Agent Context Detention in Hook Events

Environment

• Platform (select one):
• [ ] Anthropic API
• [x] AWS Bedrock
• [ ] Google Vertex AI
• [ ] Other:
• Claude CLI version: 1.0.96
• Operating System: macOS
• Terminal: Ghostty

Feature Description

Add agent context information to hook events so that hooks can determine whether they're running within an agent workflow (e.g., when Claude is using the Task tool with subagents).

Use Case / Problem Statement

Currently, hooks receive rich context about tool usage, session information, and transcript data, but cannot determine if they're executing within an agent context. This limits the ability to:

1. Apply different security policies for agent vs. direct user interactions
2. Implement agent-specific logging or auditing
3. Adjust hook behavior based on execution context
4. Provide better debugging information for agent workflows

Example use case (git-sub agent)

It would be ideal for me to develop a hook that checks whether Bash(git:*) calls were being performed inside of a slash command kicked off to a sub-agent. To know what sub-agent(s) are being used to run it would let me determine if it's doing something outside of my instructions (such as saying "never commit to the repo without using @agent-git-expert").

Proposed Solution

Add agent context information to hook events, such as:

• IsAgentContext bool - indicates if running within an agent
• AgentName string - type of agent (e.g., "general-purpose", "code-reviewer")
• ParentSessionID string - session ID of the parent context
• AgentDepth int - nesting level for multi-agent scenarios

This could be added to existing event types (PreToolUseEvent, PostToolUseEvent, etc.) or provided through the hook context.

Expected Behavior

Using cchooks, it would work like this:

func (h *MyHook) preToolUseHandler(ctx context.Context, event *cchooks.PreToolUseEvent) {
    if event.IsAgentContext {
        // Apply agent-specific logic
        log.Printf("Agent %s executing %s", event.AgentType, event.ToolName)
    }
}

Alternative Solutions

If direct agent context isn't feasible, consider:

1. Adding metadata fields to events that agents can populate
2. Providing session hierarchy information
3. Adding agent-related information to the existing SessionID structure

Additional Context

This feature would enhance the security and observability capabilities of Claude Code hooks, particularly for users building sophisticated agent workflows that require different governance policies than direct user interactions.