feat: add forked subagent context

docs/concepts/context-engine.md

@@ -78,13 +78,15 @@ four lifecycle points:
 
 ### Subagent lifecycle (optional)
 
-OpenClaw currently calls one subagent lifecycle hook:
+OpenClaw calls two optional subagent lifecycle hooks:
 
+- **prepareSubagentSpawn** — prepare shared context state before a child run
+  starts. The hook receives parent/child session keys, `contextMode`
+  (`isolated` or `fork`), available transcript ids/files, and optional TTL.
+  If it returns a rollback handle, OpenClaw calls it when spawn fails after
+  preparation succeeds.
 - **onSubagentEnded** — clean up when a subagent session completes or is swept.
 
-The `prepareSubagentSpawn` hook is part of the interface for future use, but
-the runtime does not invoke it yet.
-
 ### System prompt addition
 
 The `assemble` method can return a `systemPromptAddition` string. OpenClaw
@@ -191,7 +193,7 @@ Optional members:
 | `bootstrap(params)`            | Method | Initialize engine state for a session. Called once when the engine first sees a session (e.g., import history). |
 | `ingestBatch(params)`          | Method | Ingest a completed turn as a batch. Called after a run completes, with all messages from that turn at once.     |
 | `afterTurn(params)`            | Method | Post-run lifecycle work (persist state, trigger background compaction).                                         |
-| `prepareSubagentSpawn(params)` | Method | Set up shared state for a child session.                                                                        |
+| `prepareSubagentSpawn(params)` | Method | Set up shared state for a child session before it starts.                                                       |
 | `onSubagentEnded(params)`      | Method | Clean up after a subagent ends.                                                                                 |
 | `dispose()`                    | Method | Release resources. Called during gateway shutdown or plugin reload — not per-session.                           |
 

docs/concepts/session-tool.md

@@ -98,8 +98,9 @@ sub-agents. It supports:
 
 ## Spawning sub-agents
 
-`sessions_spawn` creates an isolated session for a background task. It is always
-non-blocking -- it returns immediately with a `runId` and `childSessionKey`.
+`sessions_spawn` creates an isolated session for a background task by default.
+It is always non-blocking -- it returns immediately with a `runId` and
+`childSessionKey`.
 
 Key options:
 
@@ -107,6 +108,8 @@ Key options:
 - `model` and `thinking` overrides for the child session.
 - `thread: true` to bind the spawn to a chat thread (Discord, Slack, etc.).
 - `sandbox: "require"` to enforce sandboxing on the child.
+- `context: "fork"` for native sub-agents when the child needs the current
+  requester transcript; omit it or use `context: "isolated"` for a clean child.
 
 Default leaf sub-agents do not get session tools. When
 `maxSpawnDepth >= 2`, depth-1 orchestrator sub-agents additionally receive

docs/tools/subagents.md

@@ -69,9 +69,11 @@ Primary goals:
 - Keep the tool surface hard to misuse: sub-agents do **not** get session tools by default.
 - Support configurable nesting depth for orchestrator patterns.
 
-Cost note: each sub-agent has its **own** context and token usage. For heavy or repetitive
-tasks, set a cheaper model for sub-agents and keep your main agent on a higher-quality model.
-You can configure this via `agents.defaults.subagents.model` or per-agent overrides.
+Cost note: each sub-agent has its **own** context and token usage by default. For heavy or
+repetitive tasks, set a cheaper model for sub-agents and keep your main agent on a
+higher-quality model. You can configure this via `agents.defaults.subagents.model` or per-agent
+overrides. When a child genuinely needs the requester's current transcript, the agent can request
+`context: "fork"` on that one spawn.
 
 ## Tool
 
@@ -98,6 +100,10 @@ Tool params:
   - `mode: "session"` requires `thread: true`
 - `cleanup?` (`delete|keep`, default `keep`)
 - `sandbox?` (`inherit|require`, default `inherit`; `require` rejects spawn unless target child runtime is sandboxed)
+- `context?` (`isolated|fork`, default `isolated`; native sub-agents only)
+  - `isolated` creates a clean child transcript and is the default.
+  - `fork` branches the requester's current transcript into the child session so the child starts with the same conversation context.
+  - Use `fork` only when the child needs the current transcript. For scoped work, omit `context`.
 - `sessions_spawn` does **not** accept channel-delivery params (`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`). For delivery, use `message`/`sessions_send` from the spawned run.
 
 ## Thread-bound sessions