doc: document parallel execution, background interrupts, and dispatch flags

README.md

@@ -58,6 +58,7 @@ Everything lives under `$XDG_CONFIG_HOME/ollie/` (default: `~/.config/ollie/`)
 | **One-shot LLM** | `o generate "explain monads"` or `echo "prompt" \| o generate` |
 | **Run an agent** | Create a session + agent via 9P — then connect with any frontend ([ellie](doc/ellie.md), KDE (GUI/KRunner/Kate), `o tui`) |
 | **Remote execution** | Set `remote=user@host` in session config |
+| **Background processes** | Pass `"background": true` to any tool — output auto-injected into context |
 | **Agents** | Write a JSON config in `data/agents/` with agent prompt in `data/prompts/` |
 | **Tools** | Drop an executable + `.meta` in `~/.config/ollie/tools/` — load at runtime via `/tool_load` |
 | **Domain skills** | Load markdown skill modules at runtime |

doc/architecture.md

@@ -146,6 +146,25 @@ The loop is the heart of the system. On each turn:
 2. **Dispatch** — if the model returns tool calls, execute them via `toolsrv.Server`
 3. **Update** — append assistant message + tool results to session history
 4. **Repeat** — loop until the model produces a final text response (no tool calls)
+
+#### Parallel Tool Execution
+Tool calls within a single turn are dispatched in parallel using resource-based conflict scheduling. Each tool declares a **scope** in its `.meta`:
+- `"read"` — never conflicts (always parallel with everything)
+- `"write"` — conflicts only on the same file path (different files run in parallel)
+- `"global"` (or unset) — full serialization barrier (runs alone)
+
+This means N file edits on different paths complete in one round-trip instead of N sequential calls. Shell is always a barrier (global scope) since its effects are opaque.
+
+#### Background Processes
+Any tool call can include `"background": true` to execute asynchronously. The result is an immediate PID; the tool runs in toolsrv's `proc/new.bg`. Background process output is automatically injected into the model's context as `<system-proc-interrupt>` blocks at safe points (alongside subsequent tool results). The model can react to build failures, log events, etc. without polling.
+
+#### Dispatch Flags
+All tools automatically receive four optional parameters (injected into schemas at runtime):
+- `bypass` — run outside sandbox via bypass broker
+- `timeout` — execution timeout in seconds
+- `sandbox` — sandbox profile name
+- `background` — run asynchronously, auto-inject output
+
 Safety mechanisms:
 - **Consecutive error limits**: soft nudge at 5, hard abort at 10
 - **Replan gate**: after 8 rounds without a PLAN: block, inject a replan nudge

doc/resources/evolution.md

@@ -1166,6 +1166,52 @@ toolsrv uses `log/slog` (Go stdlib) with a `"svc": "toolsrv"` attribute.
 This is intentionally separate from olliesrv's `ollie/log` package — they
 are different programs with different lifecycles.
 
+### Parallel Tool Execution
+
+Replaced binary ReadOnly/not batching with resource-based conflict scheduling.
+Tool calls within a single turn are grouped into parallel batches based on
+a three-class scope system declared in `.meta`:
+
+- **scope "read"** — never conflicts (always parallel)
+- **scope "write"** — conflicts only on same file path
+- **scope "global"** (or unset, default) — full serialization barrier
+
+The model's read-before-write pattern (enforced by the turn-based protocol)
+guarantees that parallel writes are safe: each file_edit carries its own
+`old_string` context from a prior read, and edits on different paths are
+provably independent.
+
+Shell and tools with opaque effects (like `lsp_rename`) declare scope "global"
+and always run alone. Unknown/unset scope defaults to global — tools must
+opt in to parallelism.
+
+### Background Process Interrupts
+
+Any tool call can include `"background": true` to execute asynchronously
+via `proc/new.bg`. The model receives a PID immediately and continues working.
+Background process output is automatically injected into the model's context
+as `<system-proc-interrupt>` blocks alongside subsequent tool results:
+
+```xml
+<system-proc-interrupt pid="42" cmd="go test ./..." status="exited" exit="1">
+--- FAIL: TestFoo (0.00s)
+    foo_test.go:12: expected 3, got 2
+FAIL
+</system-proc-interrupt>
+```
+
+The model sees these naturally — no polling, no explicit `process_output` calls.
+It can react to failures or kill processes by PID when done.
+
+### Universal Dispatch Flags
+
+All tools receive four optional parameters injected into their schemas at
+runtime (not declared per-tool):
+- `bypass` — sandbox escape via bypass broker
+- `timeout` — execution timeout in seconds
+- `sandbox` — sandbox profile override
+- `background` — async execution with auto-injected output
+
 ### Open Problem: Concurrency
 
 Tool execution in toolsrv is capable of running in the background (`proc/new.bg`),