Agent-type hooks error on all event types (SessionStart, UserPromptSubmit, PostToolUse)

Bug Description

Agent-type hooks (as opposed to command-type hooks) fail with a generic "hook error" on every event type tested. Command-type hooks in the same position work correctly.

Environment

• Claude Code version: v2.1.84
• OS: macOS Darwin 25.3.0
• Model: Opus 4.6 (1M context)

Steps to Reproduce

Add an agent-type hook to settings.local.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Run TaskList and report any pending tasks.",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Start a new session.

Expected Behavior

The agent hook spawns a subagent that executes the prompt (using tools like TaskList, Bash, etc.) and returns additionalContext to the main session.

Actual Behavior

SessionStart:startup hook error

No subagent is spawned. No output. The error message provides no detail about what failed.

Events Tested

| Event | type: "command" | type: "agent" |
|-------|----------------|---------------|
| SessionStart | ✅ Works | ❌ "hook error" |
| UserPromptSubmit | ✅ Works | ❌ "hook error" |
| PostToolUse | ✅ Works | ❌ Not confirmed (silent failure suspected) |

Variations Attempted

All produce the same "hook error":

1. Minimal prompt (30 chars) — error
2. Long prompt (1500 chars) — error
3. With "model": "haiku" — error
4. Without model parameter — error
5. Single hook group — error
6. Separate hook groups — error
7. Same group as a working command hook — error
8. Agent hook alone (no command hook) — error

Impact

Agent hooks are documented as a way to run intelligent checks using Claude's tools (TaskList, Bash, Read, etc.) at lifecycle events. With agent hooks broken, the only option is command hooks that output text instructions — which the model may or may not follow. This makes automated coordination between multi-session workflows unreliable.

Workaround

Using command-type hooks that output text instructions telling the model to manually invoke an agent via the Agent tool. This is unreliable as the model can ignore the instructions.

References

• Hooks documentation
• Agent hook type is documented alongside command hooks but does not function