# Support additional\_context in subagentStart hooks

**URL:** <https://forum.cursor.com/t/support-additional-context-in-subagentstart-hooks/170918>\
**Category:** Feature Requests\
**Tags:** context, hooks, subagents\
**Created:** [September 7, 2026, 3:39pm UTC](https://forum.cursor.com/t/support-additional-context-in-subagentstart-hooks/170918 "2026-09-07T15:39:56Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![simon-bauer-sonar](https://avatars.discourse-cdn.com/v4/letter/s/a87d85/32.png) [@simon-bauer-sonar](https://forum.cursor.com/u/simon-bauer-sonar)\
**Post date:** [September 7, 2026, 3:39pm UTC](https://forum.cursor.com/t/support-additional-context-in-subagentstart-hooks/170918/1 "2026-09-07T15:39:56Z")

</div>

### Feature request for product/service

Cursor IDE

### Describe the request

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:

1. A `sessionStart` hook returned `additional_context` to the root agent.
2. I spawned a direct subagent.
3. The child did not appear to receive that context.
4. `sessionStart` did not run for the child.
5. `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:

```json
{
  "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.

### Operating System (if it applies)

Windows 10/11  
MacOS  
Linux

---

<div class="post-metadata">

**Author:** ![Colin](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/colin/32/90452_2.png) [@Colin](https://forum.cursor.com/u/Colin)\
**Post date:** [September 8, 2026, 10:29am UTC](https://forum.cursor.com/t/support-additional-context-in-subagentstart-hooks/170918/11 "2026-09-08T10:29:11Z")

</div>

Hey @simon-bauer-sonar, thanks for the detailed write-up!

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`.

`~/.cursor/hooks.json`:

```auto
{
  "version": 1,
  "hooks": {
    "preToolUse": [
      { "command": "hooks/subagent-context.sh", "matcher": "^Task$" }
    ]
  }
}

```

`~/.cursor/hooks/subagent-context.sh` (`chmod +x`):

```auto
#!/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:

```auto
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:

```auto
<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.

Hope this helps! 🐳

---

<div class="post-metadata">

**Author:** ![simon-bauer-sonar](https://avatars.discourse-cdn.com/v4/letter/s/a87d85/32.png) [@simon-bauer-sonar](https://forum.cursor.com/u/simon-bauer-sonar)\
**Post date:** [September 9, 2026, 11:56am UTC](https://forum.cursor.com/t/support-additional-context-in-subagentstart-hooks/170918/12 "2026-09-09T11:56:54Z")

</div>

Thanks Colin,  
`preToolUse(Task)` with `updated_input` could work for context delivery.

However, before adopting it as our default, we found four concerns:

1. 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.

2. 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?

3. 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?

4. 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.

Would the team consider supporting that?

---

<div class="post-metadata">

**Author:** ![Colin](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/colin/32/90452_2.png) [@Colin](https://forum.cursor.com/u/Colin)\
**Post date:** [September 18, 2026, 3:48pm UTC](https://forum.cursor.com/t/support-additional-context-in-subagentstart-hooks/170918/21 "2026-09-18T15:48:41Z")

</div>

Hey @simon-bauer-sonar, fair questions!

> [@simon-bauer-sonar](#):
>
> 1. 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.
> 
> 2. 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?

`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.

> [@simon-bauer-sonar](#):
>
> 1. 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?

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.

> [@simon-bauer-sonar](#):
>
> 1. 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.

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!