[FEATURE] Add agent context information to hook environments

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Problem Statement

Currently, hooks don't provide information about which agent (main agent vs subagent) is invoking a tool. This makes it impossible to implement agent-specific logic, access controls, or validation rules that need to differentiate between agent contexts.

Use Case

There are several scenarios where knowing the agent context would be valuable:

• Implementing different access controls for main vs subagents
• Content isolation strategies
• Agent-specific logging and monitoring
• Different validation rules based on agent hierarchy
• Resource usage tracking per agent type

Example: PreToolUse hooks for file access controls where main agents should be restricted from certain files while subagents need access to prevent context pollution.

Current Workaround

Currently requires complex state management:

1. Detect subagent lifecycle using Task tool detection in PreToolUse hooks
2. Maintain file-based flags to track agent state
3. Clean up state with PostToolUse/SubagentStop hooks
4. Handle race conditions with parallel subagents using counters

This approach is error-prone and doesn't scale well.

Expected Behavior

All hooks should have access to agent context information, enabling:

• Agent-specific validation logic
• Hierarchical access controls
• Context-aware monitoring and logging
• Cleaner, more maintainable hook implementations

Benefits

• Enables sophisticated agent-aware workflows
• Improves security and access control capabilities
• Reduces need for complex workarounds
• Better debugging and monitoring capabilities

Proposed Solution

Add agent context information to all hook environments via environment variables:

• CLAUDE_AGENT_NAME: The name/identifier of the current agent (e.g., "main", "subagent-1", etc.)

This would apply to all hook types (PreToolUse, PostToolUse, SubagentStart, SubagentStop, etc.)

Priority

High - Significant impact on productivity

Feature Category

Developer tools/SDK