Hooks not firing in Claude Agent SDK sessions

[yashexosphere]

Problem

failproofai works when I run Claude Code directly from the shell, but the same hooks do not fire when I run the Python Claude Agent SDK in the same environment.

This happens even when hooks are installed at different Claude settings scopes. In the failing SDK runs, no Failproof AI hook activity appears in the Claude session JSONL hook_progress entries, and nothing shows in the dashboard.

The Python claude_agent_sdk was not launching the same Claude Code binary that I use manually.

In my environment:

manual CLI: /home/yashu/.local/bin/claude
manual CLI version: 2.1.100
SDK default CLI: bundled binary inside claude_agent_sdk/_bundled/claude
bundled CLI version: 2.1.81
The SDK prefers its bundled Claude binary by default. In my case, that bundled CLI did not fire the installed command hooks that failproofai depends on. Once I forced the SDK to use the system claude binary, hooks started firing again.

Why This Happens
failproofai relies on Claude Code hook execution.
The Python Agent SDK is “Claude Code underneath,” but it may invoke a different Claude executable than the one you run manually.

So the real mismatch is not:

failproof scope vs user/project/local scope
The real mismatch is:

manual claude binary that fires hooks
SDK-bundled claude binary that, in this environment, does not

Evidence

Across 5 Agent SDK sessions (Claude 2.1.81, bypassPermissions, sdk-py):

• Sessions with .claude/settings.local.json → hooks fired ✅
• Sessions with only .claude/settings.json (--scope project) → zero hooks fired ❌
• failproofai hooks never appeared in any Agent SDK session JSONL hook_progress entry

Reproduce

options = ClaudeAgentOptions(
    permission_mode="bypassPermissions",
    setting_sources=["project"],  # maps to --setting-sources project
    ...
)

failproofai policies --install all --scope project
uv run agent.py
# SessionStart, PreToolUse etc. → zero hook_progress entries in session JSONL

Workaround

Option A — Add "local" to setting_sources in your agent code:

setting_sources=["project", "local"]

Option B — Install to local scope:

failproofai policies --install all --scope local

Suggested Fix

1. Warn when installing with --scope project that Agent SDK sessions using setting_sources=["project"] will not pick up these hooks
2. Document the scope naming mismatch between failproofai and Claude Code's --setting-sources flag
3. Consider an --scope agent-sdk alias that writes to settings.local.json with clear intent

Environment

• Claude Code: 2.1.81
• Claude Agent SDK: Python claude_agent_sdk
• OS: Ubuntu (WSL2)
• failproofai: v0.0.2-beta.7