Skip to content

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

docs(agent): update sub-agent orchestration docs

Steven Enamakel9cb5f28cccc0
diff --git a/crates/openhuman-core/src/agent/README.md b/crates/openhuman-core/src/agent/README.md
index 6ea1ccbb9f..7ee59736dd 100644
--- a/crates/openhuman-core/src/agent/README.md
+++ b/crates/openhuman-core/src/agent/README.md
@@ -176,11 +176,10 @@ its `AgentStores`. See [session_host/README.md](session_host/README.md).
### Sub-agents and orchestration
-A parent agent delegates by calling a tool. `spawn_subagent`
-([`orchestration/tools/spawn_subagent.rs`](./orchestration/tools/spawn_subagent.rs)) and its siblings
-(`spawn_subagent`, `continue_subagent`,
-`steer_subagent`, `wait_subagent`, `close_subagent`) look up the
-target `AgentDefinition` and call `subagent_host::run_subagent_with_parent`.
+A parent agent delegates through the always-asynchronous `spawn_subagent`
+tool ([`orchestration/tools/spawn_subagent_surface.rs`](./orchestration/tools/spawn_subagent_surface.rs)).
+The `agent_id` argument selects an allowlisted `AgentDefinition`; the same
+`task_key` resumes a clarification checkpoint or reuses a previous worker.
```text
parent harness loop
diff --git a/crates/openhuman-core/src/agent/harness/README.md b/crates/openhuman-core/src/agent/harness/README.md
index cb56f25efa..79e928cb82 100644
--- a/crates/openhuman-core/src/agent/harness/README.md
+++ b/crates/openhuman-core/src/agent/harness/README.md
@@ -99,8 +99,7 @@ turn lifecycle are in `../session_host/`; `run_subagent`,
`AgentDefinitionRegistry`/`ToolScope`.
- `agent/tinyagents/middleware/credential_scrub.rs` calls
`harness::credentials::scrub_credentials` on every tool result.
-- `agent/orchestration/tools/*` (`spawn_subagent`, `spawn_subagent`,
- `continue_subagent`, `steer_subagent`, and friends)
+- `agent/orchestration/tools/*` (`spawn_subagent`)
call into `../subagent_host/` and take this module's parent context
explicitly.
diff --git a/crates/openhuman-core/src/agent/orchestration/README.md b/crates/openhuman-core/src/agent/orchestration/README.md
index 2daff9c244..f51e302d34 100644
--- a/crates/openhuman-core/src/agent/orchestration/README.md
+++ b/crates/openhuman-core/src/agent/orchestration/README.md
@@ -1,7 +1,7 @@
# orchestration
`agent::orchestration` hosts live OpenHuman adapters for detached sub-agents:
-spawning, steering, waiting, progress, and durable
+spawning, cancellation, progress, and durable
subagent-session projections. TinyAgents owns generic task execution and
registry behavior; OpenHuman supplies product policy, execution context, RPC,
and UI-facing projections.
@@ -11,17 +11,17 @@ and UI-facing projections.
- Host adapters that dispatch work through `agent::subagent_host::run_subagent`.
- Background sub-agent task tracking, cancellation, steering, completion
delivery, and run-ledger projection.
-- Manual cancellation and steering for detached `spawn_subagent` runs.
+- Manual cancellation for detached `spawn_subagent` runs.
- The shared root `ParentExecutionContext` builder used by background tasks.
## Key files
-- `running_subagents.rs` and `running_subagents/`: detached run metadata,
- registry, steering, wait, task ledger, and boot reconciliation.
+- `running_subagents.rs` and `running_subagents/`: admission checks,
+ driver-backed cancellation, task ledger, and boot reconciliation.
- `background_completions.rs`, `completion_notice.rs`, and
`background_delivery.rs`: host delivery policy over TinyAgents completion
routing.
-- `subagent_control.rs`: manual cancel and steer RPCs.
+- `subagent_control.rs`: manual cancel RPC.
- `subagent_sessions/`: durable session reuse and deduplication.
- `parent_context/builder.rs`: construction for tasks without a parent turn.
- `tools.rs`: callable sub-agent tools.
@@ -30,15 +30,14 @@ and UI-facing projections.
| Namespace | Surface |
| --- | --- |
-| `subagent` | Cancel and steer |
+| `subagent` | Cancel |
## Tools
-The module exposes `spawn_subagent`, `spawn_subagent`,
-`steer_subagent`, `continue_subagent`,
-`close_subagent`, `wait_subagent`, and `list_subagents`.
-Archetype delegates provide focused synchronous calls over the live sub-agent host.
-Execution routes through `agent::subagent_host::run_subagent`.
+The model-facing surface is the always-asynchronous `spawn_subagent` tool.
+The parent reuses a `task_key` to continue a clarification or follow up on a
+completed worker. Execution routes through TinyAgents' shared driver; OpenHuman
+provides product policy, durable session resolution, progress, and cancellation.
## Persistence and policy