Preflight Checklist

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

Problem Statement

When using subagents via the Task() tool, there's no way to enforce different permission rules for the main session vs. subagents. This makes it impossible to build orchestrator patterns where a director agent coordinates work but doesn't perform implementation itself.

Current limitations:

1. PreToolUse hooks apply to ALL tool calls in the session (both main agent and subagents)
2. Permission deny rules in .clauderc are inherited by subagents
3. The hook stdin data doesn't include which agent is making the call
4. CLAUDE.md restrictions apply to all agents equally (subagents read the same file)

Example use case:
I'm building an Agent Teams Pattern (ATP:TDD) where a director orchestrates specialized subagents. The director should only spawn agents and manage workflow, NOT edit code directly. Subagents (dev-agent, test-architect) should be allowed to edit files.

Currently impossible to enforce because:

• If I deny Write tool in PreToolUse hook → blocks both director AND subagents
• If I allow Write tool → director can edit files (defeats the purpose)
• No way to differentiate "who" is making the tool call

Proposed Solution

Add agent identity fields to the PreToolUse hook stdin JSON data.

Current hook data:
```json
{
"session_id": "abc123",
"tool_name": "Write",
"tool_input": {
"file_path": "/path/to/file.ts",
"content": "..."
},
"cwd": "/project/root"
}
```

Proposed addition:
```json
{
"session_id": "abc123",
"tool_name": "Write",
"tool_input": {...},
"cwd": "/project/root",
"agent_name": "dev-agent", // null if main session, agent name if subagent
"agent_type": "subagent", // "main" | "subagent"
"parent_session_id": "xyz789" // null if main, parent session ID if subagent
}
```

This would enable hooks to make agent-aware permission decisions:

```bash
#!/bin/bash

Example PreToolUse hook

data=$(cat)
agent_name=$(echo "$data" | jq -r '.agent_name // "main"')
tool_name=$(echo "$data" | jq -r '.tool_name')

Block main session from editing code, allow subagents

if [[ "$agent_name" == "main" && "$tool_name" == "Write" ]]; then
file_path=$(echo "$data" | jq -r '.tool_input.file_path')
if [[ "$file_path" == *.ts || "$file_path" == *.tsx ]]; then
echo "deny" # Director can't edit code
exit 0
fi
fi

echo "allow" # Subagents can edit
```

Alternative Solutions

Attempted workarounds (all failed):

1. PreToolUse hooks - Blocks ALL agents in the session, not just the director
2. Permission deny rules in .clauderc - Inherited by subagents, blocks them too
3. Child directory with different .clauderc - Subagents inherit parent cwd settings
4. CLAUDE.md restrictions - All agents read the same CLAUDE.md file
5. Agent naming conventions - No programmatic enforcement, relies on AI obedience

None provide technical enforcement of agent-specific permissions.

Alternative API design:
Could also expose this via a `--agent-name` flag when spawning subagents, but hook data feels more composable since it's already the permission enforcement point.

Priority

High - Significant impact on productivity

Feature Category

Developer tools/SDK

Use Case Example

Scenario: ATP:TDD Pipeline

1. User runs `claude --agent director-agent`
2. Director reads issue Authentication fails at Internal Server Error if I go the "Individual" way, but works if I choose "Organisation" #123 (add crafting system)
3. Director spawns: `Task(subagent_type='architect-agent', prompt='Design crafting system')`
4. Architect analyzes codebase, writes design doc → allowed (docs aren't code)
5. Director spawns: `Task(subagent_type='test-architect', prompt='Write tests from spec')`
6. Test-architect writes test files → allowed (subagent can edit)
7. Director tries to edit `server/src/systems/CraftingSystem.ts` → BLOCKED (main agent can't edit code)
8. Director spawns: `Task(subagent_type='dev-agent', prompt='Implement tests')`
9. Dev-agent edits `CraftingSystem.ts` → allowed (subagent can edit)

Without this feature:

• Step 7 isn't enforceable - director can edit code despite policy
• Relies on AI following CLAUDE.md rules (not reliable under time pressure or context limits)

With this feature:

• PreToolUse hook technically enforces the orchestrator pattern
• Director is physically blocked from editing code
• Subagents work normally
• Pattern is robust and reliable

Additional Context

This feature enables a broader pattern of "role-based tool access" for Agent Teams. Similar use cases:

• QA agent can use Chrome MCP, but dev agent cannot (avoids distraction during coding)
• Architect agent can only read files, not write
• Debugger agent can read but not modify production code

The current session-wide permission model doesn't support these patterns. Agent identity in hook data would unlock them all.

Technical note: If implementing this is complex, even just `agent_name` (without `agent_type` or `parent_session_id`) would be sufficient for most use cases.