octet

Documentation Extensions

Subagents

Delegate bounded work and collect its results.

Manual for v0.9.5. Stable release: v0.9.5.

Source candidate distribution: 0.9.5. This bundle needs exactly octet 0.9.5. Use the version-matched installation and the 0.9.5 candidate record for availability and remaining qualification. 0.9.5 assets are not published; use the reviewed source-checkout route below until publication is approved.

Hand a bounded task to a background worker while the main session carries on. octet owns the child conversations, permissions, saving, limits and shutdown. It isn't an agent team, a swarm or a second model loop.

Try a read-only investigation#

After installing and enabling the bundle, a subagent_spawn call can limit a worker to the hard read-only read tool:

json
{
  "name": "explore-auth",
  "task": "Trace authentication ownership and report relevant files and invariants.",
  "profile": "explore",
  "provider": "inherit",
  "model": "inherit",
  "reasoning": "inherit",
  "tools": ["read"],
  "timeout_seconds": 300,
  "max_turns": 8,
  "max_output_bytes": 8192,
  "max_cost_microdollars": 200000,
  "background": true,
  "idempotency_key": "auth-audit-v1"
}

The acknowledgement is not completion. Keep doing independent work. octet delivers the final output through its durable parent mailbox. Reusing an identical spawn key is safe to retry. Using it with different input fails.

Tool Use
subagent_models Discover configured, credential-available worker models. Optional query and limit (default 50, max 100).
subagent_spawn Start a named worker. background: false waits in the foreground, within limits.
subagent_status Resync one target, or list all workers you own.
subagent_wait Wait 1–60 seconds. Cancelling or timing out the wait doesn't stop workers.
subagent_stop Give exactly one of {"target":"explore-auth"} or {"all":true}. The acknowledgement isn't terminal completion.
subagent_continue Give target and message to steer an active worker, or resume a settled one with its conversation. Workers that are stopping, awaiting_approval or detached are rejected with stable errors.

provider, model and reasoning default to inherit. Use subagent_models to discover exact configured routes and supported reasoning before picking one. Explicit routing needs the negotiated agent_model_selection_v1. The host alone validates and normalizes it, and unknown routes never fall back to the parent. The requested and host-confirmed effective selections show in the inspector and are kept across restoration and continuation. Credentials are never returned.

Install and enable#

With octet 0.9.5 and verified matching published assets, install the bundle, then explicitly enable it:

console
octet extension install octet-subagents
octet --enable-extension octet-subagents

For local testing with the 0.9.5 source tree, run from the repository root:

console
octet --extension-dir ./extensions --enable-extension octet-subagents

Don't install a 0.8.1 bundle into the 0.9.5 host. You need Python 3.9+. Installing has no hook or third-party dependency and starts nothing, and the bundle stays disabled until explicitly enabled. Default full access (unsafe_host) implicitly trusts it without saving a grant. Optional --trust-extension or source-bound trusted_extensions grants never enable it. --safe-mode removes implicit trust and keeps executable processes stopped even with explicit grants: startup still needs unsafe_host. Neither mode supplies an OS sandbox. /extensions status shows the selected source, trust, API, generation and negotiated features. The packaged skill is opt-in too: /skills load octet-subagents.

Bound the work#

  • At most 8 active children and 32 retained workers per parent owner, one level deep.
  • Profiles are explore, review, test-analysis and research. The provider, model and reasoning selection defaults to inherited. There's no separate max_tokens argument.
  • The default tool grant is read, edit, write and bash, not read-only. A requested list must be a non-empty, duplicate-free subset. No browser, network-specific, collaboration or recursive agent tools are admitted.
  • Workers inherit the working directory, environment, sandbox, approval policy and extension policy. A shared filesystem is not isolation, so scope changes to owned paths. Task text can't relax host policy.
  • Omitted time, turn and cost ceilings inherit the parent's limits, including unlimited. The explicit limits and output bounds are in the safety reference.

Inspect the work#

Open /subagents (also /subagents list or /subagents status) to see the host-owned live roster, including while a turn runs. Up and Down select, Enter opens a scrollable, read-only transcript, Ctrl+X stops the selected worker, and Escape or Left goes back. /subagents stop <name-or-id|all> requests interruption without waiting for the parent turn to end. /subagents inspect <name-or-id>, /subagents wait [name-or-id] and /subagents reattach [name-or-id] run at idle, or queue until idle during a turn. /extensions only enables, disables and configures the extension; runtime worker controls are not in its options menu.

A bounded, tool-like Subagents transcript block updates in place while workers are active, including between root turns. Its heading counts worker states, and up to four active child lines show the task and input and output tokens. Ctrl+O keeps disclosure. Once the block settles, the worker list shows all retained workers (up to 32), exact outcomes, models, tool-call counts (not model turns), cost and reasons. Prompts, tool arguments and results, and running model prose stay out of the roster.

What doesn't produce notices

Worker state and reason transitions, and raw first-party orchestration results (including errors), add no automatic per-worker transcript or semantic-copy notices, live or on replay. Actual failed, stopped or approval-parked states, model-visible errors, durable results and accounting are unchanged, and ordinary tool and run failures and approval prompts stay visible.

Serve inspection is also owner-bound and read-only, and can't send a prompt. In both frontends, /subagents inspect <name-or-id> gives cached detail, and /extensions inspect agent-session:<digest> is the fallback for an explicit reference.

Open the fleet in panes#

Partial: pane execution is blocked. /subagents open-all tmux or /subagents open-all herdr refreshes the owner-bound agent/list and reports bounded plans using opaque agent-session:<sha256> handles. No pane is created and no command is submitted, including on repeated calls. See /subagents open-all.

Why it's blocked

The host can resolve the opaque handles, but even launchable: true with live_task: false is only a snapshot, not exclusive ownership. Every worker stays blocked with an explicit reason, and otherwise-ready workers report atomic host writer claim/settlement unavailable. The current parent stays blocked because its calling process still owns it. Execution can't be enabled until the host supplies atomic writer claim and settlement, and operator coordination is no substitute. The command never installs a multiplexer and keeps the eight-worker plan cap. The low-level tmux and herdr adapters keep preflight, partial-failure reporting and direct stub tests, and those tests aren't product ownership or live-handover qualification.

Session-scoped delegation#

A worker is owned by the parent session, not just the turn that spawned it. Ending the parent turn doesn't stop its workers. After owner reconstruction, the extension treats retained records as detached, not dead: summaries, errors, usage and the sibling roster stay recoverable. An owner-bound reattach pass restores available workers as idle until an explicit follow-up, and never invents a new task. A worker parked at the approval boundary shows as awaiting approval and can't be given unattended work.

Ownership and restoration

Host rebuilds restore extension ownership from the persisted principal and resource-owner fences. Each root session has its own roster alongside its lease, even when sessions share a delegation directory. Releasing an owner keeps settled output, error, terminal status and completion time independent of attachment.

Reference#

This bundle has distribution version 0.9.5 and uses API 0.4, with an exact runtime requirement of octet 0.9.5. The detailed contract is a bundled-runtime reference, not a general extension SDK tutorial.