feat(hooks): add agent context fields to hook input

[abhibarkade]

Summary

This PR adds documentation, test utilities, and examples for four new agent-context fields in the Claude Code hook input JSON. These fields allow hook handlers to distinguish between the main agent and subagents, enabling more precise security policies, targeted messaging, and better observability in multi-agent workflows.

Fixes issue #6885

New Fields added to Hook Input:

Field	Type	Description
is_subagent	boolean	true if the tool call originates from a subagent.
agent_name	string	Name of the current subagent; empty for the main agent.
parent_session_id	string	Session ID of the parent context ("" if top-level).
agent_depth	integer	Nesting level (0 = main agent, 1 = subagent, etc.).

---

Detailed Changes

📖 Documentation & Skills

• SKILL.md: Updated the "Hook Input Format" with the new schema and added guidance on using is_subagent for targeted denial messages in the PreToolUse section.
• advanced.md: Added a new "Agent-Aware Hook Patterns" section with concrete Bash and Python examples for security logic and audit logging.
• patterns.md: Added Pattern 11: Agent-Context Branching to demonstrate tiered policies.

🧪 Test Utilities

• test-hook.sh: Updated all --create-sample payloads to include the new fields. Added a --subagent flag to generate subagent-context test data easily.

🚀 Example Hooks

• agent-aware-bash-validator.sh: Demonstrates tailored denial messages based on agent context.
• validate-git-agent.py: Enforces a policy allowing only specific subagents to run git commands, with a transcript-parsing fallback.
• bash_command_validator_example.py: Updated existing example to show context field extraction and prefixing.

---

Verification Results

Sample Payload Verification:

# Verify subagent-context sample generation
./test-hook.sh --subagent --create-sample PreToolUse | jq '{is_subagent, agent_name, agent_depth}'
# Output:
# {
#   "is_subagent": true,
#   "agent_name": "git-expert",
#   "agent_depth": 1
# }

[abhibarkade]

@claude

[abhibarkade]

Hi team 👋,

I've just marked this PR as ready for review.

To provide a bit more context, this PR directly addresses the need for agent-aware security policies and observability (resolving #6885). With the increasing use of multi-agent workflows, it's critical for hook handlers (like PreToolUse) to know which specific agent is attempting to execute a tool.

🌟 Key Capabilities Enabled:

• Granular Security Policies: Hook developers can now write logic like "Only allow the git-expert subagent to execute git push" or "Deny all subagents from running npm publish."
• Targeted Feedback: Return specific, tailored denial messages dependent on whether the caller is a subagent (is_subagent), helping the subagent course-correct without confusing the user.
• Enhanced Observability: Hooks can now accurately log tool usage by extracting the agent_name, agent_depth, and tracing back through the parent_session_id.

🧪 How to test:

I've updated the test-hook.sh utility to make testing these new fields frictionless. Reviewers can quickly verify the new subagent payload structure without needing to spin up a complex multi-agent flow:

# 1. Generate a sample payload simulating a subagent
./test-hook.sh --subagent --create-sample PreToolUse | jq '{is_subagent, agent_name, agent_depth}'

# Expected Output:
# {
#   "is_subagent": true,
#   "agent_name": "git-expert",
#   "agent_depth": 1
# }