SubagentStart

Runs when Claude spawns a subagent with the Agent tool, when Claude resumes a subagent, and each time an in-process agent team teammate handles a new message. Supports matchers to filter by agent type name. For built-in agents, this is the agent name like general-purpose, Explore, or Plan. For custom subagents, this is the name field from the agent's frontmatter, not the filename.

For subagents shipped by a plugin, the agent type is the plugin-scoped identifier such as my-plugin:reviewer, not the bare frontmatter name. The colon places a plugin-scoped name on the regular-expression path, so anchor the matcher with ^ and $ for an exact match: ^my-plugin:reviewer$.

SubagentStart input

In addition to the common input fields, SubagentStart hooks receive agent_id with the unique identifier for the subagent and agent_type with the agent name that the matcher filters on.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SubagentStart",
  "agent_id": "agent-abc123",
  "agent_type": "Explore"
}

SubagentStart hooks can't block subagent creation, but they can inject context into the subagent. In addition to the JSON output fields available to all hooks, you can return:

Field	Description
additionalContext	String added to the subagent's context at the start of its conversation, before its first prompt. See Add context for Claude

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "Follow security guidelines for this task"
  }
}

When the hook runs again for the same subagent, Claude Code injects the returned context only when the subagent's context doesn't already hold the copy from an earlier run. The copy injected at launch stays in place, leaving the subagent's prompt cache intact. After auto-compaction discards that copy, Claude Code injects the next run's context again.