PermissionRequest hook with type: 'agent' not triggering

Resolved 💬 3 comments Opened Feb 5, 2026 by DeanFromLondon Closed Feb 9, 2026

Bug Description

The PermissionRequest hook with type: "agent" is configured correctly but does not trigger. Instead of the agent evaluating the command, the standard Claude Code permission dialog appears.

Expected Behavior

When a Bash command needs permission and matches the hook matcher:

  1. The hook should intercept the permission request
  2. Show the configured statusMessage ("Gatekeeper review...")
  3. The agent should evaluate the command using the provided prompt
  4. Auto-approve ({"ok": true}) or auto-block ({"ok": false, "reason": "..."})

Actual Behavior

The hook is completely bypassed. The standard permission dialog appears asking "Do you want to proceed?" with Yes/No options.

Configuration

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "agent",
            "prompt": "You are a permissions gatekeeper for Claude Code Bash commands...[full prompt with classification rules]...",
            "model": "opus",
            "timeout": 30,
            "statusMessage": "Gatekeeper review..."
          }
        ]
      }
    ]
  }
}

Steps to Reproduce

  1. Add the above hook configuration to ~/.claude/settings.json
  2. Restart Claude Code
  3. Try a risky command like git reset --hard HEAD~1 or git clean -fd
  4. Observe: Standard permission dialog appears instead of gatekeeper evaluation

Additional Context

  • The agent works when invoked manually: Using the Task tool to invoke the same gatekeeper agent with the same prompt works correctly - it properly classifies commands as SAFE or RISKY
  • Other hook types work: type: "command" hooks for Stop and SessionStart events trigger correctly
  • Commands in permissions.allow bypass the hook entirely (expected behavior)
  • Commands NOT in allow list should trigger the hook but don't

Environment

  • Claude Code version: Latest
  • OS: macOS Darwin 25.2.0
  • Shell: zsh

Reference

This feature was documented by Boris in the Claude Permissions Gatekeeper pattern, which describes using an Opus agent to evaluate Bash commands for safety before auto-approval in acceptEdits or bypassPermissions modes.

Workaround Attempted

Tried using type: "command" with a shell script instead, but this requires a way to invoke the Claude agent from the shell, which isn't straightforward.

Questions

  1. Is type: "agent" actually supported for PermissionRequest hooks?
  2. If so, what is the correct configuration format?
  3. Are there any additional requirements for agent-type hooks to work with PermissionRequest?

View original on GitHub ↗

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