[FEATURE] Expose teammate identity in hook input and support per-teammate hook configuration in agent teams

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

Agent teams spawn multiple independent Claude Code sessions that all inherit the lead's hook configuration uniformly.
For PreToolUse safety hooks -tools that validate commands before execution- this creates two problems:

1. No teammate identity in hook input. The PreToolUse JSON payload includes session_id, tool_name, and tool_input, but nothing that identifies which teammate triggered the hook. A safety hook that intercepts rm -rf or curl | bash cannot log, report, or apply differentiated policy based on whether the command came from a "researcher" teammate or an "implementer" teammate. The hook sees identical input regardless of the source agent.
2. No per-teammate hook configuration. All teammates inherit the lead's hooks at spawn time. You cannot attach a stricter PreToolUse hook to a read-only research teammate while allowing a different hook profile for an implementer teammate. This means safety hooks must apply the most restrictive policy globally or accept gaps for teammates that should be more constrained.

These gaps matter more for agent teams than for single sessions because:

• Multiplied attack surface. Each teammate is an independent context window that can be independently prompt-injected or led astray. Five teammates means five independent attack vectors, all hitting the same hook with no way to distinguish them.
• No hook on inter-agent messaging. A compromised teammate can instruct another teammate to execute dangerous commands via the inbox system. The safety hook only fires when the second teammate attempts the tool call — by which point the hook has no context that the command was socially engineered from another agent.
• --dangerously-skip-permissions propagates to all teammates. If the lead uses this flag, every teammate inherits it. While PreToolUse hooks still fire regardless of permission mode, the broader safety posture collapses. There is no way for a hook to detect or warn about this propagation in multi-agent contexts.

Relationship to #24316: Issue #24316 requests per-teammate agent definitions (tool restrictions, skills, memory, models). This issue focuses specifically on the hook system — what hooks receive, how they're configured per teammate, and the safety implications unique to multi-agent execution. The two are complementary: #24316 addresses capability boundaries, this issue addresses behavioral validation.

Proposed Solution

1. Add teammate metadata to hook input JSON
Extend the PreToolUse (and other hook event) input schema with an optional agent_team object:

{
  "session_id": "abc123",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf ~/Documents"
  },
  "agent_team": {
    "team_name": "auth-refactor",
    "teammate_name": "backend-implementer",
    "teammate_role": "general-purpose",
    "is_lead": false,
    "permission_mode_inherited": true
  }
}

When the session is not part of an agent team, agent_team would be null or absent (backward compatible).

Fields:

• team_name: The team identifier, as created by the lead
• teammate_name: The name assigned to this specific teammate at spawn time
• teammate_role: The agent type ("general-purpose" today, agent definition name if #24316 lands)
• is_lead: Whether this is the team lead's session
• permission_mode_inherited: Whether this teammate is using inherited permissions vs. individually changed

This allows safety hooks to:

• Log which teammate triggered a block (audit trail)
• Apply stricter policies to specific teammates by name or role
• Detect and warn when inherited permission mode includes bypassPermissions

2. Support per-teammate hook overrides
Allow hooks to be specified per teammate at spawn time, either via:
Option A - inline in the spawn prompt (lighter weight):

Spawn a "researcher" teammate with these hook overrides:
PreToolUse for Bash: deny all write commands

Option B - via agent definitions (if #24316 lands):
The .claude/agents/ file already supports hooks in frontmatter. If teammates can reference agent definitions, hooks come along automatically.

Option C - team-level hook configuration (new):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "./scripts/validate-command.sh"
        }],
        "agent_team_filter": {
          "teammate_names": ["researcher", "reviewer"],
          "teammate_roles": ["read-only-agent"]
        }
      }
    ]
  }
}

Option B is the cleanest approach if #24316 is implemented. Option A is a quick win. Option C adds complexity but doesn't depend on other features.

3. Add a TeammateSpawn hook event
A new hook event that fires when the lead spawns a teammate, allowing safety tools to:

• Validate that the teammate configuration meets security requirements
• Warn if --dangerously-skip-permissions is being propagated
• Log team composition for audit purposes

{
  "hook_event_name": "TeammateSpawn",
  "team_name": "auth-refactor",
  "teammate_name": "backend-implementer",
  "teammate_config": {
    "permission_mode": "bypassPermissions",
    "inherited_from_lead": true
  }
}

Exit code 2 would block the spawn with feedback to the lead.

Alternative Solutions

Current workaround: Safety hooks can partially infer context from session_id - different teammates have different session IDs. But there's no mapping from session ID to teammate name/role without external state management. This is fragile and doesn't work across session restarts.

Lighter alternative: Only implement proposal 1 (metadata in hook input) without per-teammate configuration. This alone would let hook authors implement differentiated logic on their side without changes to Claude Code's hook dispatch. It's the highest-value, lowest-effort change.

Subagents instead of teams: For safety-critical workflows, use subagents (which support per-agent hooks) instead of teams. This sacrifices inter-agent collaboration for per-agent safety - exactly the tradeoff this feature request aims to eliminate.

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

Use Case 1: Safety hook audit logging
A PreToolUse hook blocks rm -rf ~/Documents from a teammate. Today, the log shows:
BLOCKED: rm -rf ~/Documents [session: abc123]
With teammate metadata:
BLOCKED: rm -rf ~/Documents [team: auth-refactor, teammate: backend-implementer, role: general-purpose]
The developer can now identify which teammate went off-track and correct the spawn prompt or constraints.

Use Case 2: Differentiated safety policy
A team has three teammates: researcher (should be read-only), implementer (full access), reviewer (read-only + can run tests). Today, the safety hook must either:

Block all Bash for everyone (researcher is safe, implementer can't work)
Allow all Bash for everyone (researcher can accidentally write files)

With per-teammate hooks or teammate metadata, the hook can:

Block write commands for "researcher" and "reviewer"
Allow full Bash for "implementer"
Allow test-runner commands for "reviewer"

Use Case 3: Permission propagation warning
The lead starts with --dangerously-skip-permissions. Five teammates spawn, all inheriting bypass mode. A TeammateSpawn hook detects this and:

Logs a warning: "5 teammates spawned with bypassPermissions"
Optionally blocks the spawn with: "Cannot spawn teammates in bypass mode. Use default permission mode."

Additional Context

The hook protocol is stable. Both first-party and third-party PreToolUse hooks (PatchPilot for vulnerability checking, HardStop for command validation) use the same stdin JSON / stdout JSON / exit code protocol. Adding an optional agent_team field to the input schema is backward compatible — hooks that don't read it continue to work unchanged.
Current documentation gap. The agent teams documentation mentions TeammateIdle and TaskCompleted hooks but does not document how PreToolUse/PostToolUse hooks behave in team contexts. Specifically, it's undocumented whether:

Hooks fire per-teammate or only for the lead
The session_id in hook input is unique per teammate
Hook stderr/stdout from teammate hooks is visible to the lead or only to the teammate

Documenting this behavior (even without new features) would help safety hook developers build correct tools for multi-agent environments.
Relevant docs:

Agent teams - current team capabilities and limitations
Hooks reference - hook input/output schema
Custom subagents - per-agent hook support that teammates lack
Issue #24316 - complementary request for per-teammate agent definitions
Issue #24175 - source-level analysis showing hooks fire inconsistently between in-process and pane-based teammate spawn modes (confirms hook system wasn't designed for multi-agent)
Issue #23983 - PermissionRequest hooks not firing for subagents in agent teams (confirms hook/team integration gaps)
Issue #23447 - delegate mode cascades to teammates (bug report confirming the permission propagation problem this issue raises as a safety concern)
Issue #24307 - teammates in Delegate Mode lack file access tools despite bypassPermissions (permission propagation broken)
Issue #24052 - production coordination patterns including crash recovery and persistent backlog