[FEATURE] Include task prompt in SubagentStart hook payload

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

The SubagentStart hook payload currently includes agent_id, agent_type, session_id, transcript_path, cwd, and permission_mode — but it does not include the prompt (or description) from the Agent/Task tool call that spawned the subagent.

This makes it impossible to identify what task a subagent was spawned to do at the time it starts. The prompt and description fields are available in PreToolUse for the Agent tool, but there is no native way to correlate a PreToolUse(Agent) event to the resulting SubagentStart event — especially under parallel execution where multiple subagents may be spawned simultaneously.

Current SubagentStart payload:

{
  "hook_event_name": "SubagentStart",
  "session_id": "abc123",
  "transcript_path": "...",
  "cwd": "...",
  "permission_mode": "default",
  "agent_id": "agent-abc123",
  "agent_type": "general-purpose"
}

No prompt, description, or tool_use_id linking back to the parent Agent tool call.

Why existing workarounds fall short

Filesystem relay via PreToolUse(Agent): Write prompt to .state/pending/<tool_use_id>.json, claim it in SubagentStart. Breaks under parallelism — multiple SubagentStart events fire concurrently with no reliable way to match them to pending files.

Embed correlation ID in task prompt: Works if you control the orchestrator, but requires prompt engineering overhead and pollutes the task prompt with metadata. Not viable for general-purpose hooks or third-party tooling.

Read transcript_path in SubagentStart: The transcript may not yet contain the initial user message at the moment SubagentStart fires, making this unreliable.

Proposed Solution

Add prompt, description, and optionally parent_tool_use_id to the SubagentStart payload:

{
  "hook_event_name": "SubagentStart",
  "session_id": "abc123",
  "transcript_path": "...",
  "cwd": "...",
  "permission_mode": "default",
  "agent_id": "agent-abc123",
  "agent_type": "general-purpose",
  "prompt": "Process the email thread at jobs/thread-xyz and schedule a meeting...",
  "description": "Schedule meeting for thread-xyz",
  "parent_tool_use_id": "toolu_01ABC..."
}

Related Issues

• #14859 — Proposes parent_agent_id + description in SubagentStart (does not include prompt)
• #7881 — SubagentStop cannot identify which subagent finished (shared session_id)
• #29068 — agent_id added to PreToolUse/PostToolUse (closed/fixed in SDK v0.1.46)

Alternative Solutions

_No response_

Priority

High - Significant impact on productivity

Feature Category

API and model interactions

Use Case Example

Building an orchestrator (Blockit) where a parent agent spawns per-thread subagents in parallel. Each subagent handles a specific email thread job. The SubagentStart hook needs to map agent_id → job_id immediately at spawn time — to register the agent with a job queue, apply per-job policies, and route PreToolUse decisions to the correct job context.

Without prompt in SubagentStart, there is no reliable way to perform this mapping when agents start in parallel.

Additional Context

_No response_