SessionStart hook fails with agent type: ToolUseContext is required

Resolved 💬 3 comments Opened Apr 10, 2026 by matsumoto-dev Closed Apr 10, 2026

Bug Description

When using "type": "agent" in a SessionStart hook, the hook fails with:

SessionStart:startup hook error
Failed to run: ToolUseContext is required for agent hooks. This is a bug.

The error message itself acknowledges this is a bug.

Steps to Reproduce

  1. Add the following to .claude/settings.json:
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "agent",
            "prompt": "Read project files and summarize status",
            "timeout": 120
          }
        ]
      }
    ]
  }
}
  1. Start a new Claude Code session in the project directory.

Expected Behavior

The agent hook should execute at session start, running the specified prompt.

Actual Behavior

The hook fails immediately with:

Failed to run: ToolUseContext is required for agent hooks. This is a bug.

Analysis

SessionStart fires before any tool call context exists. Agent hooks require ToolUseContext, which is only available during PreToolUse / PostToolUse events. This means "type": "agent" is currently incompatible with SessionStart (and likely Stop as well).

Environment

  • OS: Windows 11 Home 10.0.26200
  • Claude Code: latest
  • Shell: bash

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗