PreToolUse hook with matcher 'Agent' does not block background Agent tool calls

Resolved 💬 4 comments Opened Mar 14, 2026 by blairlaird Closed Apr 12, 2026

Bug Description

A PreToolUse hook configured to block Agent tool calls via exit 1 does not fire (or does not enforce) when the Agent tool is invoked with run_in_background: true.

Reproduction

Hook configuration (~/.claude/settings.json)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Agent",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'BLOCK: Do NOT use sub-agents.' && exit 1"
          }
        ]
      }
    ]
  }
}

Expected behavior

All Agent tool calls should be blocked by the hook's exit 1, regardless of whether run_in_background is true or false.

Actual behavior

Three Agent tool calls with run_in_background: true launched successfully and ran to completion. The hook did not block them.

Foreground Agent calls (without run_in_background) were not tested in this session, so it's unclear whether the issue is specific to background agents or affects all Agent calls.

Environment

  • Platform: Windows 11 (win32)
  • Shell: bash (Git Bash)
  • Model: claude-opus-4-6 (1M context)
  • Permission mode: bypassPermissions

Additional context

The hook configuration is valid JSON and correctly placed in ~/.claude/settings.json under hooks.PreToolUse. Other hooks in the same config file appear to function normally.

View original on GitHub ↗

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