Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

docs: update agent coordination docs for unified spawn_subagent

Steven Enamakel73bba6ab500d
diff --git a/crates/openhuman-core/src/agent/orchestration/tools/tools_e2e_tests.rs b/crates/openhuman-core/src/agent/orchestration/tools/tools_e2e_tests.rs
index b21f60f04a..a4ba3df120 100644
--- a/crates/openhuman-core/src/agent/orchestration/tools/tools_e2e_tests.rs
+++ b/crates/openhuman-core/src/agent/orchestration/tools/tools_e2e_tests.rs
@@ -517,3 +517,6 @@ mod profile_cancel_tests;
#[path = "tools_e2e_continuation_tests.rs"]
mod continuation_tests;
+
+#[path = "tools_e2e_paused_cancel_tests.rs"]
+mod paused_cancel_tests;
diff --git a/docs/gitbooks/en/developing/architecture/agent-harness.md b/docs/gitbooks/en/developing/architecture/agent-harness.md
index 10a95e7baf..13280b0506 100644
--- a/docs/gitbooks/en/developing/architecture/agent-harness.md
+++ b/docs/gitbooks/en/developing/architecture/agent-harness.md
@@ -437,9 +437,9 @@ neutral TinyAgents lifecycle:
`subagent_session_id` so later turns can resume or inspect it. Pause
continuation also retains its complete TinyAgents task key.
-`wait_subagent` and `steer_subagent` accept either the durable `subagent_session_id` or the transient `task_id`; durable ids are preferred across turns. `list_subagents` shows reusable children for the current parent thread, and `close_subagent` marks a worker non-reusable and cancels it if it is still running. Inline blocking is explicit via `blocking: true`.
+The model-facing orchestration surface has one child tool: `spawn_subagent`. It always returns asynchronously and accepts `agent_id` to select a specialist. A matching `task_key` reuses the compatible durable child session; when that child is paused on clarification, another spawn with the same key resumes its checkpoint and preserves the original task identity. The child result is delivered to the parent chat when a delivery thread exists. Headless callers remain asynchronous and record completion in the run log.
-The synthesized archetype delegations (`delegate_*`, `build_workflow`, and the other `delegate_name` tools) follow the same contract: they route through the durable async path by default, returning an `[async_subagent_ref]` (with `subagent_session_id` + `task_id`) immediately, and the finished result is inserted into the parent chat as a new system turn via `background_completions`/`background_delivery`. The queue behind that is the harness `tinyagents_tasks::CompletionRouter` over a per-workspace `JsonlCompletionStore` (`.openhuman/background_completions.jsonl`, keyed by chat thread): it dedupes by task id, holds the tombstones for results the parent collected inline or that a Stop/delete cancelled, counts delivery attempts and hands back the records that gave up. A record stays leased until the delivery turn lands (`mark_delivered`), so a result that finished but was never delivered is redelivered after a restart. The host keeps the `<background_agent_*>` wording (a `CompletionFormatter`), the 3s idle debounce, the system turn and its web_chat events, and the writer that persists a given-up result into the thread. The delivery turn persists its own closing message, `sender: "agent"`, id `agent:<run_id>`, `extraMetadata.requestId = run_id`, before it emits `chat_done` as `client_id: "system"`; the frontend reuses that id, so its usual `chat_done` append collapses onto the same row (the conversation store is idempotent for these deterministic `agent:`-prefixed ids; every other id is UUID-fresh and keeps the constant-time append path) instead of persisting the delivered result a second time. Interactive turns follow the same contract: `web_chat::presentation::deliver_response` stores the reply under `agent:<request_id>` before publishing `chat_done`, so an answer the core produced exists on disk whether or not a client is there to receive the announcement, a dropped socket or a reloaded webview costs a repaint, not the reply. The exception is a segmented delivery, where the client owns one row per segment and the core stores none; the frontend keeps generated ids there for exactly that reason. They fall back to inline blocking automatically when there is no parent agent turn or no chat thread to deliver into (cron/CLI), or when `blocking: true` is passed. Cross-turn continuity comes from three pieces: the per-turn `[active_subagents]` roster merges the live in-memory registry with the durable `subagent_sessions` store (so a cold-booted orchestrator still sees earlier workers); `continue_subagent` falls back from pause checkpoints to the durable store, resuming an idle worker with its persisted history; and a `workflow_proposal` payload found in a finished child's history is persisted as a parent-thread message (`extraMetadata.scope = "workflow_proposal"`) that the frontend rehydrates into the proposal card on thread load.
+Former specialist delegation aliases are represented by `agent_id` values on `spawn_subagent`, so the model sees one spawn schema. The asynchronous result path delivers child completions to a parent chat when available; otherwise it records the result in the run log. Compatible follow-ups use the durable session keyed by `task_key`, and clarification checkpoints resume through the same spawn tool.
### Spawn hierarchy and tiers
diff --git a/docs/gitbooks/en/features/native-tools/agent-coordination.md b/docs/gitbooks/en/features/native-tools/agent-coordination.md
index 095dba0c48..16b7e4ad13 100644
--- a/docs/gitbooks/en/features/native-tools/agent-coordination.md
+++ b/docs/gitbooks/en/features/native-tools/agent-coordination.md
@@ -5,24 +5,21 @@ icon: sitemap
# Agent coordination
-Besides doing the work, the agent has tools for organizing it: planning multi-step jobs, delegating to specialists, spawning sub-agents, and pausing to ask you when something is genuinely unclear.
+Besides doing the work, the agent has tools for organizing it: planning multi-step jobs, spawning sub-agents, and pausing to ask you when something is unclear.
## Tools in this family
-| Tool | What it does |
-| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `todo` | Rewrites the session to-do list across a long task. The chat shows it as a checklist that ticks off as work progresses. |
-| `spawn_subagent` | Delegates to a reusable async specialist. It creates a fresh worker only when the work is incompatible or you ask. |
-| `spawn_async_subagent` | A lower-level reusable async delegation tool with the same durable session identity. |
-| `steer_subagent`, `wait_subagent` | Message or collect a running worker by durable `subagent_session_id` or transient `task_id`. |
-| `list_subagents`, `close_subagent` | Inspect the reusable workers for the parent thread, or retire one. |
-| `use_skill` | Loads an inline skill's playbook and tools (coding, web3, system, scheduling, docs, mcp) so the agent can call them. |
-| `ask_user_clarification` | Pauses and asks you a precise question instead of guessing. |
-| `plan_exit` | Leaves the planning phase and starts executing. |
+| Tool | What it does |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `todo` | Rewrites the session to-do list across a long task. The chat shows it as a checklist that ticks off as work progresses. |
+| `spawn_subagent` | Starts an asynchronous child selected by `agent_id`; use `task_key` to resume a compatible child, including a paused one. |
+| `use_skill` | Loads an inline skill's playbook and tools (coding, web3, system, scheduling, docs, mcp) so the agent can call them. |
+| `ask_user_clarification` | Pauses and asks you a precise question instead of guessing. |
+| `plan_exit` | Leaves the planning phase and starts executing. |
-`spawn_subagent` and archetype delegation calls accept an optional `model` field to pin an exact model for one call. If you leave it out, the harness uses per-agent pins from config when present, and otherwise falls back to normal model-routing hints. Model, sandbox mode, parent thread and task key all affect whether a sub-agent can be reused, so materially different work gets its own worker. For concurrent work, start several async sub-agent tasks and collect their results with `wait_subagent`.
+`spawn_subagent` accepts an `agent_id` to choose a specialist and an optional `model` to pin that child to a model for one call. If omitted, model selection uses the configured pin or normal routing hints. Calls return an asynchronous task reference; they do not wait for the child. Reusing the same `task_key` continues a compatible child and resumes a clarification-paused child when its checkpoint is available. Without a chat delivery thread, the child still runs asynchronously and its completion is recorded in the parent run log.
-Reusable delegation returns a transient `task_id` and a durable `subagent_session_id`. Use the durable id for follow-ups in later turns. Pass `fresh: true` only when you or the task needs a clean worker. Pass `blocking: true` only when the parent must wait for the child's result.
+The returned task reference identifies the asynchronous child. Its result is delivered to the parent chat when a delivery thread is available; headless runs retain the result in the run log.
## Why these are tools