Please add support additional_context in subagentStart hook responses.
I use hooks to provide dynamic startup guidance and repository context. sessionStart covers the root agent, but subagents also need this context because they can inspect files, edit code, and use tools independently.
In Cursor Desktop 3.18.25 on Windows 11:
A sessionStart hook returned additional_context to the root agent.
I spawned a direct subagent.
The child did not appear to receive that context.
sessionStart did not run for the child.
subagentStart did run and exposed child metadata, including IDs and task information.
subagentStart currently supports allow / deny and an optional user_message, but offers no documented way to add context for the child.
Requested response shape:
{
"permission": "allow",
"additional_context": "Use the repository navigation tools before searching files. Follow the project coding guidelines."
}
The context would be injected once when the subagent starts, before its initial reasoning, and not reinjected on retries, compaction, or later tool calls.
A preToolUse hook can intercept the internal Task tool and prepend guidance via updated_input, but that couples child context to an internal tool payload and requires preserving its full input schema.
Supporting additional_context on subagentStart would provide a stable, lifecycle-level way to initialize subagents with repository-specific guidance.
Although subagentStart doesn’t support additional_context today, you can get the same effect with a preToolUse hook on the Task tool that returns updated_input.
#!/bin/bash
# Prepend fixed guidance to every subagent prompt. Skips resumes of an existing subagent.
CONTEXT='<spawn_context>
Use the repository navigation tools before searching files. Follow the project coding guidelines.
</spawn_context>'
jq -c --arg ctx "$CONTEXT" \
'if .tool_input.resume then {} else {updated_input: {prompt: ($ctx + "\n\n" + .tool_input.prompt)}} end'
After configuring, you can verify it’s working with a prompt like this:
Spawn ONE `explore` subagent (thoroughness: quick) with this prompt, verbatim:
"Do not search the codebase. Quote the first user message of this conversation verbatim in a code block, from its very first character through the line 'END OF HEADER CHECK'. Then say PASS if the message begins with a <spawn_context> block, and FAIL otherwise.
END OF HEADER CHECK"
Report the subagent's verbatim quote and PASS/FAIL. Do not modify any files.
If you click into the subagent, you sould see that the context from your hook was passed through:
<spawn_context>
Use the repository navigation tools before searching files. Follow the project coding guidelines.
</spawn_context>
Do not search the codebase. Quote the first user message of this conversation verbatim in a code block, from its very first character through the line 'END OF HEADER CHECK'. Then say PASS if the message begins with a <spawn_context> block, and FAIL otherwise.
END OF HEADER CHECK
and it returns PASS.
A lifecycle-level additional_context on subagentStart might be a bit smoother, but this works now and has the advantage that the context is part of the prompt the child actually reasons over.
Thanks Colin, preToolUse(Task) with updated_input could work for context delivery.
However, before adopting it as our default, we found four concerns:
Cursor documents Task as a hook matcher, but we could not find clear lifecycle semantics or confirmation that it is intended as a stable integration point.
We could not find a public, stable Task contract for updated_input, prompt and resume. We would then need to integrate against observed behavior and risk diverging as Cursor evolves. Are these supported and stable contracts?
Multiple preToolUse(Task) hooks may conflict. In our tests, native Cursor and Claude Code-compatible hooks ran concurrently from the same original input, but only one rewritten prompt reached the child. Are ordering and merge behavior deterministic?
Prepending guidance turns integration context into additional task content. This risks overloading the Task with guidance that is not part of its actual task and reducing the impact task-specific context.
This workaround is useful in controlled setups, but it mutates the child task instruction rather than adding separate integration context.
Given these trade-offs, additional_context on subagentStart seems both simpler and cleaner: it would attach guidance once at the lifecycle boundary.
Task is a supported preToolUse matcher, and updated_input is the documented way to modify a tool’s input before it runs. The fields you can set are the Task tool’s own input fields. Your updated_input is merged over the original input and re-validated against the Task schema, so a wrong field name fails visibly rather than silently. We don’t version that schema separately from the tool, so fields can be added over time, but updated_input, prompt and resume are core to it and not something we expect to rename.
Ordering is deterministic, but the results are not combined. All matching hooks run in parallel, and each receives the original input, so one hook never sees another hook’s rewrite. Responses are then meant to be merged in a fixed source order: enterprise, team, project, user, Claude Code hooks (project-local, project, user), and plugins. That said, updated_input is taken whole from the last source in that order that returns one. That is why only one rewritten prompt reached your subagent, and why the Claude Code compatible hook was the one that won. We know this does not match the documented precedence, and it is an issue we are tracking.
Agreed. For these kinds of instructions, it would be better for them to land in a <system_reminder> block, the same way additional_context works for other hooks.
Overall, agreed that it makes sense for subagentStart to support additional_context. That said, it’s not in our short-term roadmap. I’ll keep this thread open and monitor for other users with the same use case. If there’s more demand, that’ll help us prioritize it!
