Document sub-agent context isolation

README.md

@@ -61,7 +61,7 @@ Everything lives under `$XDG_CONFIG_HOME/ollie/` (default: `~/.config/ollie/`)
 | **Remote execution** | Set `remote=user@host` in session config |
 | **Background processes** | Pass `"background": true` to any tool — runs with no timeout, output pushed to agent prompt on completion |
 | **Parallel execution** | Non-conflicting tool calls within a turn run in parallel (scope-based conflict scheduling) |
-| **Sub-agents** | `subagent_spawn` — delegate work to a transient agent, block until done, get the reply. Multiple spawns run in parallel. |
+| **Sub-agents** | `subagent_spawn` — delegate work to a transient agent with an independent context and runtime. The child receives a one-time snapshot of the parent's conversation history, then returns only its final reply; it cannot mutate the parent's context. Multiple spawns run in parallel. |
 | **Agents** | Write a JSON config in `~/.config/ollie/agents/` with agent prompt in `~/.config/ollie/prompts/` |
 | **Tools** | Drop an executable + `.meta` in `~/.config/ollie/tools/` — load at runtime via `tool_load` |
 | **Tool definitions** | Define tools with `.meta` files only — no wrapper script needed ([doc](doc/tool-definitions.md)) |

cmd/olliesrv/internal/prompts/system_prompt.md

@@ -168,7 +168,7 @@ printf 'cwd=%s\nprompt=fix the failing tests in auth/\n' "$PWD" \
   | ollie-9p rdwr session/$OLLIE_SESSION_ID/agent/new
 ```
 
-The sub-agent gets its own context window, tool access, and runs independently. Use sub-agents for:
+The sub-agent gets its own context window and tool access and runs independently. When spawned from an existing agent, it starts with a snapshot of the parent's conversation history. The snapshot is copied once at spawn time; it is not a live shared context. The child cannot append to, rewrite, or otherwise mutate the parent's history. Its final reply is returned to the parent as the tool result, and the parent decides how to use that reply. Use sub-agents for:
 - Tasks that benefit from a clean context (no history bloat)
 - Parallel work on non-overlapping files (spawn multiple via background shell)
 - Deep exploration that would clutter your own context

doc/evolution.md

@@ -1619,14 +1619,23 @@ landed as pure wiring because:
 No new abstractions. No new processes. No new protocols. Just connecting
 existing pieces with 42 lines of glue.
 
-### Context inheritance
+### Context inheritance and isolation
 
-Sub-agents inherit the parent's conversation history. When `parent=` is
-specified in the payload, the handler clones the parent agent's messages
-into the sub-agent's initial context via `RestoreHistoryFromMessages`.
-This is mechanically identical to session restore — same function, same
-data path. The sub-agent knows everything the parent knows without
-rediscovering it.
+A sub-agent gets its own context window, history object, runtime state, tool
+registry, cache, step budget, and lifecycle. When spawned from an existing
+agent, the parent conversation messages are copied into the child's initial
+history via `RestoreHistoryFromMessages`.
+
+This is a one-time snapshot, not a live shared context. The child cannot append
+to, rewrite, or otherwise mutate the parent's history. The parent does not see
+child messages while the child runs. The child reports only its final reply
+through the blocking `subagent_spawn` result; the parent decides whether and
+how to incorporate that reply into its own context.
+
+This separation is deliberate. Shared conversation mutation would create
+ordering races, prompt contamination, and unclear ownership of tool results.
+Shared workspace resources remain coordinated independently through toolsrv's
+scope and path locks.
 
 ### Future work
 

doc/resources/multi-agent.md

@@ -53,6 +53,13 @@ This creates a child session + agent atomically, writes the prompt, and returns
 the session path (e.g. `session/my-session`). Child sessions carry the parent
 session ID in their name, so the spawning tree is recoverable from session IDs alone.
 
+For transient `subagent_spawn` calls, the child gets its own context window and
+runtime state. It receives a one-time snapshot of the parent's conversation
+history, not a live shared context. The child cannot mutate the parent's
+history, and the parent receives only the child's final reply. The parent
+explicitly decides how to incorporate that reply. Workspace changes and other
+shared resources are coordinated separately through toolsrv locks.
+
 ### Explicit Two-Step Creation
 
 Session creation can be split into two phases for advanced orchestration