Child Sessions

Normally you start every session yourself. With child sessions turned on, a hosted agent — claude, codex, kimi, Grok, OpenCode, or Muse — can start its own agent tiles through vord and hand them work: claude can spin up a kimi tile to run a focused build task while it keeps orchestrating, then read back what kimi did. Each child is a normal, visible tile in the cockpit, just flagged as “started by session X” and linked to its parent. Both you and the parent agent can steer a child; only you can approve its permission and plan prompts.

Programmatic starting (spawn_agent) and resuming (resume_agent) leave the currently visible session and the window focus unchanged — even when the child lands in another project that isn’t currently displayed. Only your own selection (clicking a tile or choosing Resume in the history) switches the view.

Child sessions and workflows are enabled by default as long as you haven’t saved a choice yet. A saved opt-out is preserved even across an update. The switch allows the agent to delegate suitable subtasks; enabling it alone starts no session. Child sessions use real agent processes and their quota.

link_project is available only to top-level hosted sessions because it changes the calling workspace’s project link. Managed child sessions do not receive it; ask the parent to link the workspace when needed.

Claude child sessions compact early by design: by default they auto-compact at 300,000 tokens, while sessions you start yourself stay on Automatic (Claude uses the model’s full context window). You can change both values under Settings → Agents → Models → Context budget — see Usage & Quota.

The Workflows button

The connected-nodes button in the main toolbar opens the Workflows panel: its templates, active runs, and graph editor. It remains available even when starting workflows is disabled, so you can inspect or abort an existing run. Starting and advancing work is controlled separately under Settings → Agents → Helpers & Workflows.

The seven tools

vord injects seven MCP tools into every hosted session (through the built-in vord-mcp server). The tools are available by default; with child sessions turned off, vord refuses the corresponding actions with a clear message. Six of them steer children (parent → child); send_to_parent runs the other way (child → parent).

Tool	What it does
spawn_agent	Start a child tile running a chosen agent, in the same project as the parent, with an initial task. Returns with the child’s id once vord has started the process — not once the child has finished the task. Under a busy cockpit that start can take longer than a fast tool like update_focus; if the local connection drops during that window, vord retries once instead of claiming the app isn’t running. Takes an optional short tile title, an optional model and thinking_level — see Choosing the model — an optional workdir to put the child into a different checkout, see Where the child works, optional worktree: true to start the child in a fresh managed git worktree (mutually exclusive with workdir), see Start a child in its own worktree, an optional request_id idempotency key, see Cost and loop protection, and optional workflow_run_id / workflow_stage_id to bind the child to a workflow blueprint stage. Omit those last two and the spawn is an ordinary child. Pass skills (up to 3 slugs) or task (a label bound with lead_memory) to require skills: vord adds one line per skill to the task, and a missing skill fails the spawn with skill_missing unless allow_missing_skills is true.
send_to_agent	Send text to one of the caller’s own children — as its next task (mode: "prompt", the default) or as a free-text reply into an open question box (mode: "answer"). It cannot answer a permission or plan box.
get_agent_status	Report a child’s live state — including starting for a child that hasn’t run a single turn yet, plus where its initial instruction stands — any open box (type, prompt text, options), its report file (path plus whether it has been written), and a short tail of its recent output (~40 lines). Pass a child_id, or omit it to list all of the caller’s children.
stop_agent	End one of the caller’s own children — e.g. a runaway. Its tile stays visible as exited.
complete_agent	Tidy away one of the caller’s own children that has finished — the gentler sibling of stop_agent. It ends the child’s process just the same, but only hides the tile instead of archiving it, exactly like your own “Mark as done”. This cascades: any children the child itself spawned are marked done right along with it, recursively — see Marking a child done takes its whole line with it. The child stays fully reversible: bring it back from the project’s history any time, or see Resuming a finished child for doing that from the parent agent itself. Calling it on a child that’s already done reports an honest error rather than silently doing nothing.
resume_agent	Restart one of the caller’s own children whose process has already exited — finished, marked done, stopped, crashed, or usage-limited into exit. It is the exact same restore vord’s own history “Continue” action performs, not a custom MCP-only path — see Resuming a finished child.
send_to_parent	The only tool a child calls: send a message up to the agent that started it — a finished result, a mid-task question, or a blocker it can’t resolve alone. The message is delivered into the parent box-safely, framed as untrusted data. From a session that isn’t a child (no parent), the call is refused with not_a_child_session.

The tool list itself is always advertised (it has to stay static — codex freezes its tool set at start), so the on/off decision happens per call, not by hiding the tools.

Starting an OpenCode child

vord treats an OpenCode child as started only after the first task is stored on the OpenCode server — a busy event or a persisted user message, not merely an HTTP acknowledgement. If that evidence never arrives, vord aborts the in-flight turn and reports the spawn as failed, so a retry cannot start a second child for the same package. If the per-tile vord tools are not visible in the OpenCode configuration yet, vord keeps checking at growing intervals until the startup deadline instead of giving up after a single retry. When the Mac is under heavy load (CPU at 85 % or more, or a serious thermal state), that deadline is doubled, up to three minutes, because OpenCode then needs noticeably longer to start.

When an OpenCode child stops responding

An OpenCode 1.x server can keep running but stop answering requests, a known issue during long reasoning responses. vord first reconnects to the server; if it still gets no events, it checks whether the server responds. For a child session that an agent started, vord stops the hung server and automatically resumes the same session, asking the agent to continue the interrupted task. The parent is notified. The interrupted answer is lost. vord allows at most one automatic restart for a session in any 30-minute period. If the server hangs again during that period, vord does not restart it and tells both you and the parent.

If the server still answers and only its event stream disconnected, vord quietly reconnects the stream.

OpenCode permission requests

vord starts OpenCode with permission requests switched on and answers them itself according to the session’s permission mode, so OpenCode asks before every shell command and file edit. In Auto mode — and for file edits in Edit mode — vord answers each request the moment it arrives on OpenCode’s event stream, even while the Mac is busy, so an OpenCode child no longer waits at a permission prompt. In Read-only mode vord rejects the request just as quickly. This works with OpenCode 1.x and 2.x.

If a permission prompt stays open — in Ask mode, or when an automatic answer fails — vord shows it like any other agent’s permission box: the tile turns 🟡 waiting for permission, and the parent of a child session receives a permission-box report instead of a “finished” report. vord counts the prompt only once it is still visible on the next status check, about 0.4 seconds later, so a prompt that vord answers right away never makes the tile flicker.

A child session itself only sees the few tools it needs: send_to_parent, show_to_user, send_to_mesh, and update_focus. Job, board, workflow, and child-spawning tools stay reserved for sessions you start yourself — vord fixes this tool profile when the session starts (codex freezes its tool list at startup, so the role must be known by then) and refuses any call outside the profile with a clear message. This also keeps every child’s context small: the full tool list is dozens of kilobytes, the child’s set is a fraction of that. Children also get the vord Brain tools (notes, skills, learnings, search) through vord, just like the lead.

If the project has skill bindings, the child sees the same binding line as every other session (Project skill bindings: … in the operating manual at start and after compaction). When spawn_agent passes skills or a bound task, the child also gets the required-skill line in its assignment (“Required skills: use skill …; read it before you start”).

A parent that runs a workflow blueprint also gets workflow_list, workflow_start, workflow_gate, and workflow_status. Those tools do not replace spawn_agent — they sequence it.

Turning it on

All related controls live together under Settings → Agents → Helpers & Workflows. Old saved selections and deep links for Child Permissions open this combined page.

• Agents may spawn child sessions — the master switch, on by default. A saved opt-out is preserved. When it is off, spawn_agent is refused with child_spawn_disabled.
• Parent sessions may start sessions on paired hosts — on by default. It controls spawn_agent calls with a host, including calls from Host sessions. The Host’s own device permission still applies. You can change it on the iPhone under Mac settings.
• The project lead may start sessions on paired hosts — on by default; next to the parent switch above, it allows lead_start_session with a host and workdir, and you can change it on the iPhone under Mac settings.
• Most child sessions per agent — how many children one parent may run concurrently (1–20, default 3). Past 8, the stepper shows a note: a high cap can spread work across provider quotas, but it also raises coordination overhead, local system load, and the parked-session backlog — information, not a lock. Only children whose process is still running count: a child that has finished and exited — by itself, via stop_agent/complete_agent, via your “Mark as done”/close, or through an app restart — never holds a slot, whether or not its tile is still visible. Past the cap, further spawn requests are refused with child_limit_reached (the error says how many are still running) until a running child exits or is stopped.
• Allowed child agents — a row per agent (claude, codex, kimi, Grok, OpenCode, Muse) with its detection state (installed / not found, using the same binary lookup that greys out the native spawn menus) and a switch for whether it may run as a child. An agent that isn’t installed is greyed out. By default all six are allowed; a spawn for an agent you’ve switched off is refused with agent_not_allowed. The switch also covers sessions that a project lead starts (lead_start_session is refused with agent_not_allowed, and lead_list_accounts no longer lists the agent) and automations (the run fails with “ is not allowed for child sessions and automations in Settings.”; for a project-lead automation the message follows “The project lead could not start the session:”).
• Enable workflows — a separate hard gate, on by default. A workflow is usable only while both this switch and Agents may spawn child sessions are on. Turning child sessions off does not erase this workflow preference.
• How independently child sessions work — a row per agent choosing what a child of that kind may do without asking. See below.

The cap, allowlist, workflow switch, autonomy choices, and their warnings are dimmed and inert until the child-session master toggle is on. Their stored values are preserved, so turning child sessions back on restores the same choices.

How independently a child works

A child that stops at its very first approval prompt isn’t much use to the parent that started it — it just sits there waiting for you. So each agent kind gets its own autonomy level, picked once in settings and applied to every child of that kind from the moment it starts:

Level	What the child may do
Ask before every action	Nothing without your approval — exactly like a session you start yourself.
Work independently	Edits files and runs commands inside its own project folder without asking, but still checks with you before anything risky outside that folder (for claude and grok that is their auto mode: a classifier decides, and what it doesn’t clear becomes an approval box only you can answer — a public web fetch, for example).
Allow everything (default)	Anything on this Mac without asking first, including outside the project folder. This is the default because a child that an agent started is meant to work through its task — an approval box on a child stalls both the child and the parent until you click. Pick a lower level per agent kind if you’d rather be asked.

Two things are deliberately not possible here:

• The agent can’t choose its own level. The level comes only from these settings. spawn_agent has no parameter for it, so a parent can never grant its child more freedom than you allowed.
• A parent in plan mode can’t hand out more than it has. If the parent’s own terminal is in plan mode — you told it to plan, not to act — its children drop back to “Ask before every action”, whatever the setting says.

For kimi, “Allow everything” behaves the same as “Work independently”: kimi has no higher level than its own auto mode, and vord doesn’t invent a flag that doesn’t exist.

Host children on a paired host get the same level. An older host that does not know it yet starts them with full access. See Running sessions on a Mac host.

What a codex child can and cannot do

Which files, network connections, and build tools a codex child may use depends on the autonomy level chosen in vord and the sandbox actually launched. “Work independently” uses workspace-write; “Allow everything” has different access rights. The parent agent must not derive a blanket restriction for all codex children from this. Checking and acceptance remain its responsibility.

vord’s own MCP tools do not add a Codex approval box

Codex children started by vord automatically trust the MCP tools provided by vord’s own session-scoped server, including send_to_parent and the child-management tools. The old “Allow the vord MCP server …” prompt therefore no longer appears once per child. This trust is limited to vord’s own server: shell and file approvals, the Codex sandbox, and approval prompts from other MCP servers are unchanged.

Muse children trust the folder for this run only

When vord starts a Muse child, Muse trusts the folder for that run only. The trust is not saved. A Muse session you start yourself in a new folder still shows Muse’s own trust question as a 🟡 box.

No first-run trust dialog for Claude, Grok and Kimi children inside your projects

A CLI’s first-run question — do you trust the contents of this directory? — is about the folder, and for a folder you added to vord as a project you already answered it by adding the project. vord therefore records that folder in the agent’s own trusted-folders list before launching the CLI, so the dialog never appears — for the project folder itself and everything inside it. Today that covers Grok (~/.grok/trusted_folders.toml) and Kimi (~/.kimi-code/workspace-trust/, or $KIMI_CODE_HOME/workspace-trust on a named Kimi account).

Claude children are covered too, through Claude’s own file. After the account choice, vord enters the folder into that account’s .claude.json — including after an account switch, a failover to another account, a move by the usage brake, and a resume. It writes an entry Claude reads for that folder (for a Git worktree, the project’s main folder), under Claude’s own file lock and as a minimal change. If the file is locked, a symlink or a hardlink, or the profile folder is missing, vord leaves it untouched and the dialog appears as before.

A Git worktree of a vord project counts as part of that project, even when it lives outside the project folder — the usual setup when several children work in parallel. vord only accepts a worktree that Git itself has registered: the project’s own .git metadata must point to the worktree, and the worktree must point back. A folder cannot declare itself a worktree. Two limits apply. A worktree is never pre-trusted if it is your home folder, a folder containing it, or a folder containing the project. And nobody else may be able to swap the folder out from under the child: every folder on the path to the worktree must belong to you or to the system, must not be writable by other users — neither through its permissions nor through an access-control list — and must sit on a local disk that enforces ownership (not a network share or an external drive with “Ignore ownership on this volume”). A shared sticky folder such as /tmp is fine as a parent, but not as the worktree itself. If any check fails, nothing breaks — the dialog simply appears as before.

Any other workdir outside every vord project is a genuinely new question and keeps the dialog. Codex children still show their own first-run prompt: their trust lives inside a larger live config file (~/.codex/config.toml) that vord deliberately never edits. OpenCode has no such dialog.

vord also pre-approves its own homework across all permission modes: writing the child’s report file and calling send_to_parent, send_to_mesh and show_to_user never raise a permission box, for Claude and Grok children alike. Your own deny rules still win.

Orchestrator models

Under Settings → Agents → Models, each provider card lists its models in a table with two toggle columns. Allowed controls whether agents may choose the model themselves, for example for child sessions and automations; it does not affect your own model choice. Disabled models appear dimmed. The Orchestrator column marks orchestrator models. They plan work and review results; child sessions use them only as a fallback. By default, these are Opus and Fable for Claude, and GPT Astra and GPT Sol for Codex, including newer versions of the same families. Pools that include such models — an account, or with OpenCode one access path — are used for child sessions only as overflow: while a pool without orchestrator models has headroom, an explicit start on a fallback pool is refused with FALLBACK_POOL, unless the agent passes a one-sentence load_override_reason. A provider is only marked FALLBACK when all of its pools are fallback pools. See How vord spreads child sessions across accounts. An orchestrator model starts as a child only after an acceptance gate fails and with a brief reason. You can override the family rule for individual models; changes apply to new starts immediately.

Orchestrator models always run in their newest version. When a Claude session starts or resumes with an older version of an orchestrator family, for example claude-opus-4-6, or with an alias such as opus, vord starts the newest version of that family instead, today claude-opus-5-5. A project lead or an external client that explicitly asks for an older version gets an error instead.

Choosing the model and thinking level

Every spawn says which model the child runs on and how much reasoning effort it spends, so a child can never silently inherit an expensive top-tier configuration:

• model — which model the child runs. Required, unless you set a default child model for that agent in Settings; then the agent may omit it and vord fills in your choice. Your default is checked against the model release you granted agents, so it cannot become a back door.
• thinking_level — how much reasoning effort it spends. Required for claude, codex, kimi, grok and muse; OpenCode has no such axis and rejects the field rather than ignoring it, so an agent can’t believe it set an effort that never applied.

The list the agent reads is live, not a hardcoded one. When an agent session starts, vord asks the installed CLI which models the signed-in account actually has — codex via its app-server, claude via its handshake, kimi, OpenCode, and Muse via their own listings — and puts that list into the tool description, each model with the exact thinking levels it supports. If a probe fails (agent not installed, not signed in, timeout), the description falls back to a built-in list and says so plainly, so the agent knows the CLI is the authority.

This matters because model names drift in both directions. A hardcoded list goes stale: it keeps naming models an account can no longer use, and it silently hides new ones the account could use. Worse, an agent that doesn’t find a usable list falls back on its own training data and invents a plausible-looking id.

The rule vord gives every hosted agent — in its always-visible instructions, in get_delegation_context and in the spawn_agent description — is: within the chosen provider, start at the lowest model tier and thinking level that can plausibly pass the acceptance gate. Search, triage, summaries, test runs and changes that follow an existing pattern rarely need a top tier. A top tier is for root-cause debugging, work on invariants or cross-cutting design, and review or skeptic roles, and the agent states its reason in one sentence. If a child fails its gate, the parent retries once with the failure output and then moves up one tier.

To make that rule usable, get_delegation_context lists each provider’s models as modelLines, ordered from lowest to highest quota use, each with a capability and a quota rank within that provider — for example gpt-5.6-luna — capability low-mid · quota low. Ranks never compare providers with each other, and a model shown as “not assessed” is simply one this vord build has no ranking for — not a bad choice.

The same instructions ask orchestrators to keep their own context small: delegate bulk reading and ask for conclusions with file:line references, filter build and test output to failures, keep plans in files, and give each child a short brief with the goal, exact paths, the acceptance command, a stop-and-report rule and a maximum report length.

The built-in fallback list:

Agent	model	thinking_level
claude	haiku / sonnet / opus / fable (lowest to highest tier); full ids like claude-opus-4-8 also work	low / medium / high / xhigh / max
codex	gpt-5.4-mini / gpt-5.3-codex-spark / gpt-5.6-luna / gpt-5.4 + gpt-5.5 (previous generations) / gpt-5.6-terra / gpt-5.6-sol / gpt-6-astra (lowest to highest quota use)	Per model, not per agent: gpt-6-astra, gpt-5.6-sol and gpt-5.6-terra go up to ultra, gpt-5.6-luna up to max, the rest up to xhigh. The live list states each model’s own set.
kimi	kimi-code/kimi-for-coding (everyday default) / …/kimi-for-coding-highspeed (6× faster output, 3× quota) / …/k3-256k (K3 flagship, 256k context, half of k3’s quota) / …/k3 (K3 flagship, 1M context, priciest)	low / high / max — graduated on the K3-class models; the K2.7 models just toggle thinking on
OpenCode	The provider-supplied model IDs reported by the installed OpenCode CLI; the list is dynamic	No thinking_level: OpenCode has no common effort field, so the model is the choice
Grok	The IDs from grok models (live 1.0.4: grok-4.6 default, grok-4.5)	Per model: grok-4.5 supports low / medium / high; grok-4.6 and grok-4.7 also support xhigh. Grok has no max.
Muse	The IDs Muse currently reports (live catalog; names such as muse-wonder-1.0 or muse-spark-1.3-contributor are examples, not a fixed list)	The thinking levels Muse reports for that model, from minimal through max

This is separate from the autonomy level above: the model is a cost-and-capability choice the parent is allowed to make, whereas the autonomy level is yours alone and has no tool parameter.

Automatic model selection (experimental)

Instead of letting the parent pick, you can let vord choose the provider, model and thinking level for every child. Turn on Settings → Agents → Helpers & Workflows → Automatic model selection (experimental). Switching it on checks that you are signed in with a vord account that has Basic, Pro or valid beta access; if that check fails, the switch stays off and the card says why. It is off by default. Switching it on or off takes effect immediately, including in sessions that are already running.

What leaves your Mac. To assess a task, vord sends a short structured task description — a summary, the goal, the relevant scope, how the result will be checked, known risks and whether the child only reads — through the vord server to TypeSafe in the USA. The list of your allowed models goes to the vord server only; TypeSafe never sees it. vord’s shared provider connection is used, so you don’t need your own TypeSafe account or API key. The full chat, terminal output, files, account tokens and local paths are not attached automatically. TypeSafe does not promise a fixed deletion period, so don’t expect local-only processing.

How a child is chosen. The parent describes the work in prompt and adds a short routing_task summary, a goal (the expected result in one sentence) and an acceptance check (for example tests that must pass); when known it also names the scope, the kind of work (role: research, implement, debug or review), risks (such as security, data, billing or production) and read_only. vord builds the list of candidates itself from the live catalogs of your signed-in accounts: only agents allowed for children, installed and signed in, only models you allowed for agents, only catalogs that are still current (fetched in the last five minutes; Muse’s catalog, which vord refreshes every six hours, stays current for six hours), and no provider that is currently usage-limited. The same rules as before still apply — for example a child still runs a different agent than its parent, and workflow stages that require a different provider keep that separation: when a build stage starts, the choice already reserves a suitable provider for the later review stage, and the build start fails immediately instead of only at the review gate when no provider is left.

The choice then happens in two steps. First, TypeSafe assesses only the task: what kind of work it is, how demanding it is (levels 0–3), how costly a mistake would be and whether the description is enough to judge. Second, the vord server — not TypeSafe — derives the requirement from that assessment and checks every allowed model at each of its thinking levels against a shared model registry: technical data from the providers, public independent benchmark measurements and provisional ratings derived from those measurements. A rating holds for the thinking level it was measured at and above. Below it, only two provisional rules apply, and neither covers reviews or critical work: the lowest thinking level counts for the simplest tasks only, and a middle thinking level counts one level lower than the next rated level above it. Models without suitability data are listed but never count as suitable, and provisional ratings are not enough for critical work. On launch, vord measures every discovered account through the measurement paths permitted by the current account settings, then follows the normal five-minute refresh cycle. Before sending candidates for a route, vord refreshes a missing or stale account measurement and waits up to three seconds; if the refresh fails or takes longer, that account remains unknown for quota purposes. Among qualifying accounts from the same provider with measured headroom, the account with fewer busy or working sessions is favored. An account at or above the three-session load cap is lower priority while another account from that provider has measured headroom below the cap. Equal load keeps the existing quota, cost and tie-break rules. The vord server still picks among the remaining qualifying configurations economically: accounts with measured headroom first, then the configuration with lower documented quota use on its account. A neutral lot only breaks a remaining tie. Separate subscriptions reached through the same agent count as separate accounts — for example the MiniMax Token Plan in OpenCode is measured apart from OpenCode Go. A subscription whose overflow is billed (MiniMax draws purchased credits) is only used with a fresh measurement showing headroom, never from 90 % of a window on, and a pay-as-you-go key is never chosen automatically. Each routing log records the candidate account slots, measurement age, headroom, busy sessions and the selected slot; it omits account emails and local paths. vord checks the answer against exactly the list it sent and checks the catalog, account and login once more right before it starts the child. That final check no longer applies soft load avoidance: a choice made while the Mac was quiet stays valid when load spikes in between; a genuinely stale choice fails with the concrete reason (for example which catalog or account changed). Models without a thinking level (for example Claude Haiku) start without one.

Load avoidance for CPU-heavy clients. While your Mac is busy (CPU at least 60 % or thermal pressure), automatic selection avoids OpenCode, whose own client uses noticeable local CPU, as long as another suitable model is available. Steering only: a choice already made is not retroactively voided when load rises afterwards.

Sign-in failures. When a running session reports that its sign-in failed — an expired or invalid key, or a subscription without access — automatic selection skips that account for six hours. For OpenCode only the models of the affected model provider are skipped (for example only opencode-go/…). You get one notice per account, and a parent agent is told that its child cannot continue, so starting the package again picks another provider. The account becomes eligible again after six hours or when vord restarts; your own manual choice is not affected. Codex sign-in losses keep their own handling: the account stays marked until you sign in again.

Per-account limit memory. An unknown quota state does not restrict an account. When a session reports a real usage limit, vord records the provider and account slot. That account stays excluded from automatic model selection even after the child session ends or the app restarts. The restriction ends at the confirmed reset time, or earlier if a newer official measurement shows available capacity. If the provider gives no time, the restriction expires after the applicable wait. Other slots from the same provider remain available. If the limited session used a separately measured pool — such as the MiniMax Token Plan in OpenCode — the restriction applies only to models in that pool: minimax-coding-plan/* is restricted, while opencode-go/* remains available on the same account. vord starts no child on an OpenCode Go or MiniMax Token Plan model while that pool’s measured quota is exhausted. The delegation context then marks the pool as exhausted and leaves that pool’s models out of its model list, so agents do not pick them.

Plan-following packages and open questions. A parent marks each child task as execute (a plan-following package with named paths and a mechanical acceptance check) or think (a judgement the parent cannot make itself). execute tasks are capped at level 1 and go to small models. If the server finds a package too demanding, it refuses with ROUTING_SPLIT_REQUIRED and the parent has to split it; resending the same task as think or without a mode within 30 minutes is refused as well. think tasks are capped at level 2. Only critical work and reviews reach level 3, the level that only the largest models qualify for.

Lean children. An OpenCode child starts with vord’s own tools only. The MCP servers from your global OpenCode configuration (for example a ticket system or a knowledge base) stay switched off for it, because their tool descriptions alone can fill most of a small model’s context: measured on 28 September 2026, two such servers added about 140,000 tokens to every request. If a task needs one of them, the parent names it in spawn_agent with mcp_servers, for example ["machbar"]. Your own sessions keep every server.

Beyond that, a child gets the servers selected in its project — the same selection every other session of that project uses. mcp_servers adds to that selection, and for an OpenCode child it is still the way to get a server at all. See MCP servers per session.

Managed OpenCode children disable update checks and settle after three minutes of server-reported idleness without SSE activity.

Compaction loops are reported. When a child compacts its context three times within ten minutes, it is still working but keeps losing track. vord then sends the parent one notice, so it can stop the child and split the task. An OpenCode child’s tile shows the running child session instead of OpenCode’s start screen.

Never more expensive than the parent. A child never runs on a model that costs more than the parent’s own model. vord sends the parent session’s current model along with the request, but only to vord servers that announce support for it. Within the same subscription the server compares the documented usage order; for Claude, Opus 5.5 counts as cheaper than Opus 5 because of its lower list price. Across providers it compares the independent benchmark cost tier. If only more expensive configurations would fit, vord starts nothing and tells the parent to split the package into smaller steps or do that part itself (ROUTING_SPLIT_REQUIRED). The fallback below also only considers configurations that are not more expensive than the parent. An escalation after two failed checks (escalation_reason) lifts this limit. When the escalation names the stalled or failed child (escalation_child_id), its model configuration is excluded from the new choice; with no candidate left, the spawn fails instead of silently choosing it again.

When nothing qualifies. If no configuration is documented as suitable — typically a demanding or critical review — or every suitable account is out of quota, vord does not refuse the task. It starts the strongest independently measured configuration instead: ranked by the overall score of the same independent measurement (agent, model and thinking level), taken from an account that still has headroom. Accounts at or near their limit (from 90 % of a window), subscriptions with billed overflow but no fresh measurement, and paths with extra costs stay excluded. Such a child is marked as unverified — its evidence reads unverified:strongest_measured in the tooltip and in the parent’s answer — so the parent checks the result itself. Risk rules, permissions, workflow gates and acceptance checks apply unchanged. Only when no measured configuration has headroom either does the selection fail with ROUTING_NO_QUALIFIED_CANDIDATE.

What the parent may not do. With the automation on, spawn_agent rejects agent, model and thinking_level with ROUTING_OVERRIDE_FORBIDDEN — also for sessions that were started before you switched it on. Naming a provider or model inside the task text is fine (“fix the Claude effort bug”) and has no effect, because TypeSafe never sees the candidates. Jobs created by agents and custom workflows follow the same rule. A saved template that pins a model — a workflow role, for example — is never rewritten behind your back: the start reports ROUTING_PIN_CONFLICT until you remove the pin or turn the automation off.

Switching the automation off. The spawn_agent schema always lists agent, model and thinking_level together with routing_task, goal, scope, acceptance, role, risks and read_only. After you switch the automation off, vord no longer chooses them. A spawn_agent call that omits agent is refused and tells the parent to pass agent, model and thinking_level and to try again with a new request_id. It is not reported as a missing agent command. With the switch off, the routing fields are ignored.

What you see. A routed child shows an Auto · ‹model› badge in its header; the tooltip names the provider, thinking level, the assessed requirement (kind of work, level and risk) and the evidence the choice rests on. The parent’s answer contains the same information, a decision id and the request_id. The requirement is an assessment of the task, not a measured success rate. Children started before this version keep their old tooltip with the router’s confidence.

Public benchmarks only. Model suitability is based solely on public, independent benchmarks (currently the Coding Agent Index by Artificial Analysis) and provider documentation; our own test runs are not included.

Derived only, no public measurement. If a model has no public measurement of its own, the registry temporarily derives its rating from a measured related model. get_delegation_context then shows derived only, no public measurement. When the model is selected, the notice appears in the vord auto badge and persists after a restart. Acceptance checks and workflow gates are unchanged.

Variants that share your data are never chosen automatically. Some providers offer a cheaper variant of a model whose inputs and outputs the provider may use to improve its products — for Muse these are the -contributor variants such as muse-wonder-1.0-contributor, muse-wonder-full-1.0-contributor, muse-spark-1.3-contributor and muse-spark-1.2-contributor. Automatic selection never picks them, however cheap they are: they carry no suitability data and appear as unrated in get_delegation_context. You and your agents can still choose them explicitly.

Cost class. For measured models, get_delegation_context also reports a rough cost class: very low, low, medium, high, or very high. It is based on Artificial Analysis’s measured cost per benchmark task at API list prices, grouped into under $0.50, under $2, under $5, under $10, and above. The class does not describe actual subscription usage. Within one provider, it reliably indicates which model costs less; between providers, it is a rough guide. Automatic selection uses it only to choose between equally suitable models on an account without documented usage figures.

Restarts and automations. A finished child is not started again with an earlier selection: with the automation on, resume_agent answers ROUTING_SELECTION_STALE, and follow-up work goes through a new spawn_agent. For a workflow stage, vord adds the stage and role to the scope and, if the parent names no acceptance check, derives one from the stage’s gate. An automation created by an agent is routed each time it runs, with the goal and acceptance check stored when it was created; without them the run is refused with ROUTING_CONTEXT_INSUFFICIENT. If an automation carries a permission mode, only providers that can apply exactly that mode are candidates (a plan automation, for example, only goes to Claude or Grok) — it never runs in a provider’s default mode instead.

When it fails. Nothing starts, and vord never falls back to a default model or to the previous selection method. The parent gets a stable error code with the reason: ROUTING_CONTEXT_INSUFFICIENT (goal or acceptance missing, or the description too vague to judge), ROUTING_UNCERTAIN (the task could be routine or very demanding — describe it more precisely), ROUTING_OUT_OF_SCOPE (not something a coding agent can do) or ROUTING_NO_QUALIFIED_CANDIDATE (no allowed model is documented as suitable, and no independently measured model has headroom left for the fallback described above). Sending the identical request again returns the same answer for 15 minutes; a changed description counts as a new request. Temporary problems (not signed in, timeout, rate limit) can be retried with the same request. The settings card shows the last failure. At most 255 allowed models and about 24 KB of model information fit into one selection — if you allow more, restrict the models agents may use. The automation needs a vord server that supports this selection method; otherwise switching it on reports that the server doesn’t support it yet.

Advice for manual choices. With the automation off, get_delegation_context lists every model with the same registry data: the resolved model, its documented suitability per kind of work and thinking level, its documented quota use and, where a public measurement exists, a coarse cost tier. “No suitability data” means unknown, not weak.

Tool limits per request. A provider can cap how many tools a single request may carry — xAI (Grok) accepts at most 350, so a session with many MCP servers can exceed it. Every modelLines entry for such a model carries max <L> tools per request (provider limit). Once vord has seen a real provider rejection from an OpenCode session in a working directory, it remembers how many tools that session exposed and adds unusable here: OpenCode sessions exposed <N> tools to the affected models; the automatic selection then skips them, and a manual spawn_agent on such a model is refused before any process starts, with the message Model <id> accepts at most <L> tools per request, but this OpenCode session exposes <N> tools. … (learned from a provider error at <time>). The number is learned, not measured up front: vord does not read the tool list from OpenCode (its API does not expose the MCP tools) and never changes your configured MCP servers. The learned tool count and model limit stay in memory for up to 24 hours. Until a rejection has been seen, the model is simply listed with its documented limit; an alias without a documented limit is covered as soon as a rejection has taught vord that model’s limit. A tool-limit failure is deterministic, so vord never auto-retries it. The same refusal guards resume_agent and the plan-time validation of a scheduled start, which reads the explicit workdir first.

Native subagents. While the automation is on, vord also switches off Claude’s and Codex’s own subagent tools in the sessions it launches, so delegation goes through spawn_agent. Kimi, OpenCode and Grok have no documented switch for this, so their internal subagents stay outside vord’s control. Programs an agent starts on its own in the shell are not vord children either.

Where the child works

By default a child works in the parent’s own project directory. That covers most delegation — but not the case where the work simply is somewhere else: a second repository, an existing git worktree, a platform port you keep in sync. For that, spawn_agent takes an optional workdir. To let vord create a fresh managed worktree for the child, pass worktree: true instead — see Start a child in its own worktree. worktree and workdir cannot be combined.

• Omit it and nothing changes: the child starts in the parent’s project directory, exactly as before.
• Pass an absolute path and the child’s process starts there instead. Its tile still belongs to the parent’s project and stays linked to the parent — only its working directory moves.

The path must already exist and be a directory. A relative path, a typo, or a file instead of a folder fails the spawn loudly and starts nothing; vord never quietly falls back to the project directory, because a child working in the wrong place is the more expensive mistake. The confirmation the parent gets back names the working directory it actually got. An unknown argument such as cwd is refused with unknown_argument (did you mean workdir?) and starts nothing.

This matters most for codex, whose sandbox is anchored to its working root. A codex child pointed at the project while the work lives elsewhere can’t even run git pull in the other checkout — it fails with “Operation not permitted”. With workdir, vord passes the directory to codex as its working root (--cd) as well as the process directory, so the sandbox moves with it. claude and kimi have no such flag and simply take the process directory.

The child’s report file moves along too: it is created under <working directory>/.vord/child-reports/, so it is always inside what the child is allowed to write. The path vord reports to the parent is the real one.

Start a child in its own worktree

Pass worktree: true on spawn_agent and vord creates a fresh managed git worktree and branch for that child. The spawn answer names the path and the branch. worktree: true together with workdir is refused with worktree_conflict.

vord runs an executable .vord/prepare (or .agents/prepare) first, with a 15-second limit for children. Longer setup belongs in a worktree you create yourself, then pass as workdir. .vord/linked (or .agents/linked) links git-ignored files such as .env from the main checkout.

Four errors start nothing and remove the worktree:

• worktree_conflict — workdir was also set.
• worktree_unavailable — the project is not a git repository, has no commit, git failed, or the app is in Cowork mode (the flag is unavailable there too).
• prepare_needs_trust — the repository’s prepare script is not trusted yet. vord shows the trust sheet; after you approve it, the agent can try again.
• prepare_failed — the prepare script timed out, exited non-zero, was not executable, or could not start. The reply includes the log path.

Wherever it works, the child stays directly below its parent in the sidebar — the parent’s group is the anchor, even when the child’s own directory would sort it into another worktree group. If the child runs outside the parent’s own checkout, a small target badge says where: Worktree: ‹branch› for another worktree of the same repo, ‹project› · ‹branch› for another project vord knows, or ‹directory› · external for anything else. The badge never shows an absolute path — only a branch, a project name, or a plain directory name.

Cross-provider only — no same-model children

A child must run a different agent than its parent. The value here is cross-provider orchestration — claude delegating to kimi, kimi delegating to codex — not running more of your own kind. A spawn_agent whose agent matches the parent’s is refused with same_agent_not_allowed, and the agent is pointed back at its own native subagent or task mechanism (see Subagents & the Hierarchy Tree) for parallelizing work with its own model.

Note

For sessions vord started itself (a claude, codex, or kimi tile — including children), the parent’s identity is pinned to what vord launched: the process in that tile is the agent, so screen content can never change its identity. In particular, an orchestrator that quotes its child’s output — a kimi banner or status footer inside a claude tile — stays claude, and its spawn_agent("kimi") goes through. Only for plain shell sessions does vord read the agent from the terminal output (that’s where you might have typed claude or codex yourself); a shell with no detected agent has no identity, so the same-model check simply doesn’t apply to it.

What a child is

A child is a full, first-class session — its own tile, its own capability token, its own process — that happens to be linked to a parent. Two limits define it:

• Depth 1. A child cannot spawn children of its own. The tool refuses with depth_limit_exceeded. This keeps a delegation chain from turning into an unbounded tree.
• Same project. A child’s tile always belongs to the parent’s project, and by default it also works there. A parent that needs work done in a different checkout can say so per spawn — see Where the child works.

A freshly spawned child appears inside its parent’s tile, as a new strip in the tile’s family bar — it needs no grid slot of its own, so it can never displace a tile you put there, and it can never be pushed into the pool while its parent is on screen. A child only takes its own tile when its parent isn’t visible at all (parked, marked done, or filtered out by the project scope).

Marking a child done takes its whole line with it

Agents routinely forget to tidy up after themselves — a child that spawned children of its own leaves them running even after the child itself is done. So marking a session done — the hover-header checkmark, the sidebar/context-menu “Mark as done”, and complete_agent — cascades by default: every descendant of that session (its children, their children, and so on) is marked done right along with it, whether each one is still running or has already exited but is still visible as a tile. Nothing outside that one line is touched.

The one interactive exception is the hover-header checkmark on a tile: hold ⌥ Option while clicking it to mark only that session, leaving its own children running. Option is macOS’s usual “narrower variant of this action” modifier (the same idea as Finder’s “Secure Empty Trash”); every other path — the sidebar, the context menu, and complete_agent — always cascades, since there is no keyboard modifier to attach to a menu click or an MCP call.

Resuming a finished child

A child whose process has exited — it finished, you or the parent marked it done, it was stopped, it crashed, or it ran out of usage and exited — doesn’t have to stay that way. The parent agent can bring it back itself with resume_agent, without you doing anything in the UI. That restore stays in the background: it does not jump the cockpit to the child. Clicking Continue in the project history still focuses the resumed session, because that is your choice.

This is not a special MCP-only shortcut: it is the exact same restore vord’s own history “Continue” action performs (see Ended members stay put below and the project history view) — for a claude child it re-invokes the CLI with --resume against its real conversation id, so it picks up where it left off; codex and kimi children re-attach the same way when vord has learned their prior session id. It does not send a new instruction on the parent’s behalf — the child just wakes back up with whatever its own CLI restores, and the parent follows up with send_to_agent if it needs to give it something new. A prompt sent right after resume_agent waits until the resumed child is ready; vord reports a delay instead of losing it. The child’s parent link and its report file path are untouched by having been hidden or archived, so reporting keeps working exactly as before.

After a successful stop_agent, every view of the child agrees on the same terminal truth: the process is gone, the session sits in the history as exited, get_agent_status reports exited, and a second stop_agent honestly answers “already exited” instead of claiming another kill. There is no settling delay and no ghost state — the stop marks the session exited at the same moment it ends the process.

resume_agent is refused if the child isn’t the caller’s own, doesn’t exist, or — the common mistake — is still running: there’s nothing to resume, and send_to_agent is the right tool for a live child. It also respects the same concurrent cap as spawn_agent, since resuming genuinely starts a new process; free a slot with complete_agent/stop_agent first if you’re at the limit. If the restart itself fails — its working directory is gone, its pinned account is no longer available — the child simply stays exited, the same as a failed restore from the history view.

Families in the cockpit and the Team view

A family is one unit — you choose how it uses the grid. Settings ▸ Cockpit & Behavior ▸ Parent and child sessions offers two layouts. Either way the family stays together; the setting only decides how many cells it occupies:

• Folded (default) — the family holds a single slot and the children fold into the parent’s card.
• Grouped — every member gets its own card, and the whole family sits inside one tinted, outlined frame with a slim group header.

Folded: the family is one tile

The tile shows one member’s terminal at a time; every member sits below it as a narrow, clickable strip with its own status dot and title — parent first, children marked with ↳. Click a strip and the tile switches to that member’s terminal; click the parent strip to come back. The currently shown strip is highlighted, and the tile header (title, ↳ pill, hover actions, double-click into focus) always describes what you’re looking at.

Nothing pauses while it’s out of sight: every member keeps running, keeps writing its scrollback, and keeps its status live. Switching is instant — the full history is already there, no replay.

Parked children stay in the parent’s family strip — and since parking always applies to the whole family, the strip simply reflects the family state; in the Team view you page through a family’s children with the pager row instead of opening compact rows.

A waiting member lights up the whole tile. The tile’s status rail and border carry the most urgent status in the family, so a child asking a question is impossible to miss even when the parent’s terminal is the one on screen. The same applies to the grid’s auto-fill: a family counts as urgent as its most urgent member.

From five members on the bar scrolls instead of growing. So that the rail never says “someone is waiting” without saying who, the bar scrolls the first waiting member into view by itself as soon as it starts waiting. The family order stays as it is — nothing is re-sorted.

The family bar takes its room from inside the card: the grid works out how many rows fit from the window size, card density and the card cap alone, so the number of visible cards never changes when subagents appear or finish. A card with a family bar simply gives its terminal a little less height.

In Focus the same strip sits under the full terminal. Each row there also shows the agent and model, a status word, and the running time, and up to five rows stay on screen. Clicking a row switches the focused terminal; the strip stays put. A session without children shows no strip.

Grouped: every member gets a card, in a shared frame

Switch Parent and child sessions to Grouped and the family spreads across as many neighbouring cells as it has members, wrapped in one tinted frame. A slim header above the cards names the parent, counts the members and carries the family’s collective status — so all terminals are readable at once, and it is still obvious at a glance which cards belong together. Each card keeps its own status dot and its own ↳ ‹parent› pill.

A group never breaks across a row. If the family no longer fits in the row being filled, the whole family moves to the next one and the started row simply stays partly empty. Holding the family together outranks packing a row tightly — cards are never re-ordered to fill the gap, because that would break the sort order you picked.

A family wider than the whole row (more members than the grid has columns) still keeps to one row: the first members get their own cards, and the last card collects the remaining ones as strips in its foot — exactly like the folded layout. Nothing is hidden; every member is one click away.

Grouped cards need more room, so fewer families fit on screen at once; the rest wait in the pool button as usual. Switching the setting never loses a session and never restarts a terminal — the running agents just get re-arranged.

Both layouts: parent and children are never separated

In the Team view, the parent stays above the horizontally scrolling child area, so it remains visible while you browse a wide team. Child cards use the full scrollable width instead of being clipped at the window edge; narrow windows therefore scroll rather than hiding children.

Large families don’t turn into a wall of terminals: the Team view shows six live child tiles per page. Beyond the sixth child, the children simply continue on further pages — a pager row above the tiles flips between pages (no wrap-around), and a status dot next to the page label warns you when a child on another page is waiting. No child is ever parked automatically, and focusing a child never parks another one: the pager just jumps to the page that holds it. Parking stays available as a manual action and always applies to the whole family.

One unit means no pin, no filter, and no full row can pull them apart. That also shapes the tile’s actions:

• Pin and dragging belong to the grid place, so they always move or fix the whole family — in Grouped mode you can grab any member’s header and the entire frame travels with it.
• Park always applies to the whole family, no matter where you trigger it — the parent’s card, a child’s card, or the tile button in the Team view — because parking only one member would strand the rest. The hover button and the right-click menu say so (“Park family”, “Bring family back”). Mark as done follows what the card shows: on the parent’s card it acts on the whole family (“Mark family as done”), on a child’s card on that child alone. Marking a session done also cascades independently of the grid grouping — see Marking a child done takes its whole line with it.
• ⌘⇧←/⌘⇧→ steps through the members of the family the selection is in — in Folded it swaps the tile’s terminal, in Grouped it moves the selection to the neighbouring card (in the Team view the same keys switch families). ⌘←/⌘→ walk from card to card, so in Folded mode they step past a family in one go; ⌘⇧←/⌘⇧→ is the way into it.

Ended members stay put. A child that has finished keeps its strip, marked ended, and clicking it shows its final screen with a Resume button. If the parent ends while its children keep working, the family stays whole — the parent’s tile just shows its last screen, and it stays in the sidebar too. vord normally tidies a finished agent session away immediately; as long as one of its children is still running it waits, and moves the parent into the history only once the last child is gone. Only marking the parent done from the sidebar (that row addresses one session) drops its children back to tiles of their own, flagged ↳ detached.

The Team view (third density, ⌃⌘4 or the people icon in the toolbar’s density control) is the dedicated family perspective: the parent session large on the left, its children on the right — six live tiles per page, flipped through with the pager row — and a chip bar on top to switch families. Only real families appear there — sessions without children get no chip, just a small “N more sessions without a team” note that links back to the cockpit. Finished children remain visible as replay tiles with a Resume button until you mark them done, and ⌘⇧←/⌘⇧→ flip through families from the keyboard. See View Densities.

Schedule child sessions for later

An agent can schedule a child session for later with spawn_agent and start_at. start_at is an ISO-8601 timestamp with a time zone. This can be useful, for example, when another provider’s usage limit resets at a known time. A time more than 60 seconds in the past is rejected; a time within the next 60 seconds starts the child immediately.

In vord, find these settings under Settings → Agents → Helpers & Workflows. Allow scheduled child starts is on by default. Up to … hours ahead ranges from 1 to 24 hours and defaults to 12. Both settings are disabled while child sessions are turned off. Scheduled starts are not available for workflow stages.

The scheduled start does not occupy a child slot until its start time. vord then checks the model, account, quota, and available capacity again, as it would for a normal start. If all child slots are occupied, vord retries every 30 seconds. If another check fails, the parent agent receives the reason; vord does not silently start a different model.

The start expires at the later of these times: the scheduled time plus the configured limit, or the start time plus 30 minutes. If the app is closed or the Mac sleeps past the deadline, the start also expires and the parent agent is notified. Scheduled starts survive an app restart.

After the child starts, the plan id stays valid for every child tool (send_to_agent, get_agent_status, stop_agent, complete_agent, and in vord resume_agent); get_agent_status reports it as scheduled_as.

In the parent’s sidebar row, a clock icon with a count shows scheduled starts. Click it to see the start time, agent, model, task, and Cancel. A start that waits at the usage brake shows waits for usage brake instead of a time. The parent agent can cancel a scheduled start with stop_agent and its ID. Closing the parent session discards its scheduled starts. Turning off the setting also discards all scheduled starts and notifies the parent agents.

For runs scheduled further ahead or on a recurring basis, use Jobwerk.

Heavy load holds back new child sessions

When Hold back new child sessions while this Mac is under heavy load is on (the default, under Settings → Agents → Helpers & Workflows), vord holds back starts when memory pressure is critical, the one-minute load average reaches 12 per CPU core, or the Mac is in serious thermal state or hotter—the same thresholds as the build queue. Instead the request is parked: it uses no child slot, and vord starts it automatically as soon as the load drops, at the latest after 20 minutes even if the load stays high. The parent agent gets a deferred reply first and a report when the child actually starts. Parking also applies when scheduled starts are turned off and to workflow stage spawns; a workflow stage counts such a child once it actually starts. Held-back sessions start one at a time, about every 30 seconds, once load drops. Held-back children appear under their parent in lead_list_sessions as up to three status lines in scheduled_children; scheduled_child_count gives the total. They also appear in get_agent_status, and do not count as a stall.

Waiting for child results

vord delivers substantive feedback automatically: questions back, blockers, errors, revoked work, and completion reports. A successful queued or accepted acknowledgement is only diagnostic information (get_agent_status, diagnostics log) and does not start a turn in the parent; a failed delivery does. Meanwhile the lead agent can do independent work. When it is only waiting for child results, it ends its turn; the automatic delivery continues the conversation. It neither polls status and report files repeatedly nor stays active with wait loops.

The agent instructions shipped by vord and the tool descriptions explicitly prescribe this behaviour. A targeted status check remains available for a concrete diagnosis or on your request. After a completion report, the lead agent reads the full report file, checks the result, and frees the child slot.

With Hold until released selected, child starts and reports for an account at its own limit wait at the usage brake until the limit releases. A running child session follows the selected setting. You can switch it to another connected account yourself from its account menu.

Every child writes a report file

Without a report file, the report a parent receives carries only the last lines of the child’s screen — at most 8 lines or 800 characters. A child that writes a long answer into its chat loses the beginning of it before the parent ever sees it, and the reasoning and evidence go with it.

vord closes that gap without anyone having to remember it:

• At spawn, vord assigns the child a report file at <working directory>/.vord/child-reports/<child-id>.md and creates the folder — that’s the project directory unless the spawn set a workdir. .vord/ is already excluded from git, so the file never lands in your repository.
• vord appends the instruction to write that file to the child’s task itself — the child gets it whether or not the parent thought to ask.
• vord tells the parent the same path: in the spawn_agent answer, in every settled report, and in get_agent_status.
• Every report also states whether the file has actually been written and how large it is. A child that ignored the instruction is visible immediately instead of quietly leaving a truncated screen behind, and the parent is told to have it write the file rather than retype everything into chat.
• Finishing a turn and writing the file are two separate moments, so a “finished” report waits a few seconds for the file before it judges. Without that pause a child that was still writing got reported as having skipped its report — along with the advice to go tell it to write the file it was writing. The wait happens once and is short: a child that genuinely wrote nothing still gets reported as such, and it only applies to finished — a question or permission box reaches you immediately, since a child asking something owes no report yet.
• If the file is there but has not been touched in a while, the report says so. It stays linked either way; you just get told it may be left over from an earlier run rather than being this task’s answer.
• A “finished” report can go out while the child is in fact still working, with the file still missing. When that child really finishes and has written its file, the parent gets the result anyway: vord sends one follow-up report that points to the file and says it replaces the earlier one. Any other repeat of the same “finished” stays suppressed, so the parent is not woken twice for nothing.

When the full report file has been written, the report to the parent is the state plus the file path — no additional screen tail. Only when the file is missing or empty does the screen tail stay as a quick “where does it stand” glance, explicitly labelled as not the result.

Reports back to the parent

When a child reaches a settled state, vord pushes a compact report into the parent, so the parent agent can react without you relaying anything. The reported states are: finished, a question, a permission or plan box, an error, a clean exit, and hitting a usage limit.

If a child’s turn ends as idle or finished but its report did not reach the parent, vord sends the normal child report again about 90 seconds later, at most once per turn.

If none of a parent’s children has been working for three minutes and the parent has also been idle for three minutes without taking a turn since the last child stopped, vord sends one wake-up message for that idle phase. It lists each child, its status, when it entered that status, and its report file (or says none written). vord holds the wake-up while the parent is waiting on its own build-queue entry, its own open board question, or a scheduled child start.

The report reaches the parent agent compactly: the lead-in, the state, and — for output states — the state and path of the child’s report file; the parent reads the file for the full result. The screen excerpt is at most 8 lines or 800 characters, or 4 lines or 400 characters when the report file has been written. The remaining output is available through get_agent_status. If the report file is missing or empty, for example because the child crashed before writing it, the report says so plainly instead of implying that the excerpt is the whole result. In the rare case where vord could not create the report folder at all, the child was never told to write one — the report says that instead of blaming the child for a file it never knew about.

In your Mac tile, that same report shows up as one collapsed line — ▸ vord: Child report: Fold-Fork (finished) — 24 lines — which you click to open and click again to close. The ▸ / ▾ marker shows whether the report is closed or open. The folding is done by vord’s terminal, not by the agent, so it behaves identically in Claude, Codex, Kimi, Grok, OpenCode and Muse, and it leaves the text untouched: search still finds matches inside a collapsed report, and copying still yields the full wording. The iPhone companion shows the same collapsed line — ▸ vord: Child report: Fold-Fork (finished) — 24 lines — but as plain text: it mirrors the Mac’s picture rather than running its own terminal, so the header cannot be opened there.

• The report is pasted into the parent box-safely — the same mechanism vord uses for incoming mesh messages. If the parent is mid-turn and its compose frame is visible and empty (claude shows Press up to edit queued messages), vord pastes and presses Enter so claude queues the report for after the current turn. Muse queues a follow-up the same way — it appears after the current turn. Grok queues an Enter into an empty compose box the same way — unless a message is already queued there (its screen then shows Queued · Enter to send now / Enter:send now), because a second Enter would push the queue into the running turn; in that case vord waits until the turn ends. An unreadable composer — including the old case where folded reports hid the live screen — is not treated as a queue: vord holds and only escalates after a few uninterrupted minutes. If the parent’s compose field holds half-typed text, vord does not paste into the middle of it and does not make the report wait either: once your text has been untouched for a few seconds, vord saves the draft, clears the field, delivers the report, and then puts your text back unsent — even while the parent agent is mid-turn. Your words are never sent along with the report and never lost: if any step fails, the report stays queued and the saved draft is preserved in your inbox. (One exception: for a working kimi parent vord keeps waiting, because kimi’s only clear shortcut would abort its running turn.) An unsent [Pasted text #N] chip that vord itself wrote is not treated as your draft: vord retries Enter on that chip instead of holding later reports behind it. Claude Code’s grey prompt suggestion — the dimmed follow-up it offers under ❯ after each answer, accepted with Tab — is not your text either: vord reads the cell styling of the screen and treats a fully dimmed field as empty, so reports are delivered right away instead of waiting for Enter or Esc.
• Once vord’s terminal harness has accepted that paste, the report is recorded as delivered immediately and will not be pasted again after a restart, wake-up, or missing parent turn. A later screen check can still press Return to rescue visibly stuck text, but it never reopens the report for retry.
• Waiting is never silent or endless. vord double-checks a “user is typing” suspicion against the parent’s actual input field — a suspicion left over from earlier keystrokes whose submit vord never saw is dropped when the field is provably empty, and the report goes straight through. If a blockage keeps the report held for about a minute — unsent text, or a composer vord cannot prove empty — you get an inbox notification naming the session and what unblocks it (press Enter or Esc in that tile, or click into its terminal so the screen can be read again). The notice comes once per blockage episode, and the report itself stays queued and is delivered automatically the moment the way is clear — nothing is lost.
• A composer vord cannot prove empty does not hold the report forever. “Unreadable” mostly means the screen was caught mid-redraw or the CLI draws an input frame vord’s recognizer does not know yet — not that you are typing. So when that unprovable state persists for a few minutes without interruption — the clock restarts the moment vord sees anything to protect (unsent text, an open box, a readable composer) — while the parent’s process channel is alive, nothing vord can recognize as an open box is on screen, and the tile is not showing a full-screen program (less, vim, an alternate-screen view), vord delivers anyway. Proven unsent text and open permission/plan/question boxes still hold for as long as they exist — this escalation only ends the unprovable stall that used to leave a parent waiting for its children forever. Mesh messages addressed to a session (and reports a child posts through the project chat) follow the same uninterrupted-stall rule with its own clock per tile.
• A paste whose submit was never confirmed also survives an app restart — but vord never presses Enter on its own after one. The pending delivery is recorded next to the report queues; when the session comes back, vord cannot know anymore whose text sits in the compose field, so instead of a blind submit you get one inbox notice carrying the full message content. Nothing is lost silently, and nothing of yours can ever be sent by a leftover rescue. Typing in the tile clears the pending record immediately — the field is yours from that moment.
• A child that ends naturally — its process exits after a finished turn — keeps its queued reports deliverable: the report describing its end is the most valuable one it has, so it is still pasted to the parent. Marking a child done (complete_agent, or your own “Mark as done”) does the same: the parent asked for the slot, not to throw the work away, so undelivered reports stay in the parent’s queue and vord keeps trying to deliver them. Only a hard stop (stop_agent or closing the tile) redirects undelivered reports to your inbox as a terminal notice that will not be retried, so a deliberately aborted sender can never paste into the parent later.
• What counts as “box-safely” is decided from the parent’s input frame, not from searching its screen for box-shaped text. A real box replaces that frame; a box merely quoted in the transcript cannot draw one. Without this distinction the channel poisoned itself: the first delivered report quoted the child’s box into the parent’s screen, every later report was held for a minute and then redirected to your inbox while the parent sat there working perfectly fine.
• The child’s output is wrapped as an untrusted data block in the report. It comes from a different agent and must never act as an instruction to the parent — the framing says so explicitly, code fences and role-looking lines inside it are defused, and the length is capped.
• A usage-limit report is written so the parent can actually decide what to do: it names the exhausted account and which quota ran out, and gives the reset time only when it is backed — “The provider states the reset at …”, or, when the time comes from the account’s quota data, “The account’s quota data puts the reset at …”. Several limits have neither, and then the report says the provider does not state a reset time rather than guessing. It also says whether vord will retry the child by itself and when. When no retry is scheduled at all — the provider gave no reset time, so there is nothing to aim at — the report says exactly that and names the options (restart later, or a child on a different provider or pool) instead of inventing a date. With Auto-Continue off it says outright that nothing will resume the child on its own. For an OpenCode child whose Go quota arrived as OpenCode’s own retry status, the report says instead that OpenCode retries by itself at the stated time and that vord sends nothing on top. get_agent_status answers with the same facts, so a parent that asks actively sees exactly what the pushed report said.
• The provider name is only stated when it is confirmed. vord reads it from the wording of the agent’s own limit message, and some limit screens carry no provider signature at all. When that reading contradicts the agent vord actually started for that child, the report names the child’s own account (Claude, Codex or Kimi) and says plainly that the provider could not be confirmed — it never claims a foreign account.
• Repeated identical edges are de-duplicated, so a flapping detection can’t spam the parent with the same report twice. De-duplication works per settled episode, and an episode is anchored on the child’s proven turn: the turn its agent actually started, read from the agent’s own record (Claude’s prompt hook, Kimi’s wire log, Codex’s rollout, Grok’s transcript). A retry of the same event stays silent even when the child’s output has grown in the meantime, and so does a settled state that merely flickers back to green and settles again without a new task. A real new turn — the parent gives the child something to do and it settles again — is always reportable. For a session with no turn record of its own (a plain shell, an agent vord could not identify), the episode still turns over whenever the tile goes green again, because there is nothing better to anchor on. Episodes never repeat across app restarts either: vord restores which reports a parent has already received, so a child that finishes its first turn after a restart is still reported rather than mistaken for one that was already delivered. A usage limit reports per limit state, not per episode: as long as the child sits in the same state (same provider or pool, same backed reset time — or both unknown), only the first report goes to the parent and identical follow-ups are just logged, even when the limit episode ends and reopens in between — for example while OpenCode retries on its own every minute. A state change reports again: a different backed reset time, a different pool, or a genuinely new limit after the child worked again.
• While the parent itself is usage-limited, reports to it wait: pasting them would only be rejected. They are delivered as one batch once the parent’s limit has ended; a held report saying that a child is limited is dropped if that child is working again by then.
• When a child finishes its turn (its stop hook fires), the parent gets a reliable, deduplicated “finished” report through this same channel — unless the child has no report file and is still waiting on its own working or scheduled children, or on a build-queue slot. That notice is withheld while the child has such pending work, so its later report can describe the completed work.

A child can also speak up on its own, without waiting to reach a settled state, by calling send_to_parent — to report a result, ask a mid-task question, or flag a blocker. That message rides the exact same box-safe channel (and for a working kimi parent, the same steering that submits it correctly). If the parent’s personal weekly limit holds it, the tool returns held_by_usage_brake with the account and usage details; the report remains queued until the limit releases or the parent moves accounts. A retry can reuse its optional message_id; vord then treats it as the same logical message. Without message_id, vord deduplicates messages from the same child with the same text. A child that deliberately needs to send identical text again must supply a new message_id of its own; otherwise vord treats it as a retry. And if a child both sends its own send_to_parent message and then finishes its turn, vord doesn’t repeat the content: the automatic “finished” report shrinks to a compact turn-end notice — the turn ended, the substance already arrived via send_to_parent, plus the state of the child’s report file, without the screen excerpt. The notice is withheld during that wait; if the child later reports its completed work, the substantive report can still reach the parent.

To answer a child’s question, the parent calls send_to_agent with mode: "answer" — vord types the reply into the child’s live question box. A task (mode: "prompt") is only delivered when the child isn’t sitting in a box at all; otherwise the call is refused with child_busy_in_box rather than risking a stray keystroke confirming a selection.

Permission and plan boxes always wait for you

A permission request or a plan approval can only ever be granted by a human. The parent agent cannot approve one through send_to_agent — such a call is hard-refused with child_awaiting_user_permission, and not a single byte is written to the child’s terminal.

This check reads the child’s live box from the grid content, not its status, on purpose: a session’s status can briefly misread as “working” while a permission box is actually open, and trusting the status there could fire a confirmation onto the pre-selected option. The box itself is the source of truth, so permission and plan boxes are blocked regardless of what the status claims. get_agent_status reports the box type from the same source, so the parent can see it’s blocked and tell you.

Question boxes stay answerable by the parent — that’s the intended shortcut. Permission and plan boxes are yours alone.

Cost and loop protection

Beyond the concurrent cap in settings, three limits keep an autonomous parent from burning through tokens or looping:

• A spawn rate budget per parent (8 spawns per allowed concurrent slot in a rolling 30-minute window — 24 with the default of 3, capped at 96 for the highest concurrency settings) blocks serial respawn loops even when the parent stops old children in between. Over budget returns spawn_budget_exhausted.
• Duplicate spawns are de-duplicated. Every spawn_agent call carries a stable request id — the agent can pass its own request_id, otherwise vord derives one from the full task content (agent, prompt, title, model, thinking level, workdir and, with automatic model selection, the routing summary and task fields). A second call with the same key never starts a second child: while the first spawn is still being set up it waits for that same spawn, and once finished the original answer is replayed for 15 minutes after success or a final ROUTING_* rejection. This protects against a host retry or a double-delivered instruction turning into two identical children. An agent that intentionally wants two children with identical task text passes two distinct request_id values; an agent retrying a call it is unsure about reuses the same one. The dedup is keyed per parent and lives in memory only — an app restart starts it fresh. With automatic model selection on, a request that failed before anything started for a temporary reason (not signed in, timeout, rate limit, a changed catalog or a template pin) is not remembered as finished, so the same request can be retried; two identical calls at the same time still share one attempt. Other rejections, such as child_limit_reached or an exhausted spawn budget, are not kept: repeating the request checks the current state again, so it can succeed after a slot frees or a budget changes. Retryable routing failures also remain fresh; repeated final ROUTING_* rejections are marked as replayed, with their age, because nothing was re-checked.
• An exchange cap per parent–child pair (25 messages) stops the report channel once a pair keeps reporting and answering each other in circles — automatic reports and a child’s own send_to_parent messages both count toward it. The compact turn-end notice that follows a child’s own send_to_parent does not count: it carries no new content, and charging it would halve the pair’s budget. At the cap vord pauses the channel and raises it to you instead.
• The normal license gate applies in this path too: a child won’t start without a valid license or an active trial, the same as any session you start yourself.

Credential protection for child sessions

Child sessions must not search for or read credentials. vord blocks a child’s tool call when it would:

• run keychain commands (e.g. security find-generic-password, security dump-keychain, security export)
• read .env files — templates such as .env.example, .env.sample, .env.template and .env.dist stay readable
• read other sessions’ transcripts
• read agent login or config files (Claude, Codex, OpenCode, Muse, Grok, Kimi)
• read vord’s per-session configuration folders and temporary MCP/hook files
• read common credential files in the home folder: SSH keys, .netrc, AWS credentials, GitHub CLI hosts, .git-credentials, Docker and Kubernetes config, .npmrc, .pypirc, .pgpass

The agent receives Blocked by vord: child sessions must not search for or read credentials …. Every child’s task also tells it to stop and report missing access to its parent instead of looking for another way in.

How it is enforced:

• for Claude, Codex, Grok, Kimi and Muse children by vord’s PreToolUse hook
• for Claude and OpenCode children additionally by static deny rules that apply even with full access

Main sessions (sessions you start yourself) are not affected.

Caution

Limits:

• The check is pattern-based and not a sandbox.
• A command that only mentions a blocked file or keychain command as text, for example in a commit message, is blocked as well.

The badges

Three small pills make the parent–child relationship readable at a glance, in the cockpit tile header and the focus header:

• When a tile shows a child: a ↳ ‹parent› pill — the unmistakable sign that you’re not looking at the parent. Clicking it brings the parent back into the same tile when it’s part of that family; elsewhere (Team view, detached child) it jumps to the parent in focus. If the parent has been closed while the child lives on, the pill turns into a neutral, non-clickable ↳ detached marker — the origin stays visible, with nothing to click into.
• When a child runs outside its parent’s checkout: a target badge saying where it actually works — Worktree: ‹branch›, ‹project› · ‹branch›, or ‹directory› · external. Where the ↳ pill says who started the child, this badge says where it runs. Like the ↳ pill it shrinks to just its icon in the tightest header stage instead of disappearing, and it never carries an absolute path.
• When a tile shows a parent: a ⑂ N counter of its live children. Hover it (not click — it sits under the header’s double-click detector) to open a popover listing each child with its status dot and a jump button; in the cockpit that button switches the tile to the child instead of leaving the grid.

Families in the sidebar

The sidebar keeps a family together: every visible child sits directly below its parent, indented one extra level, with a subtle ↳ marker between its status dot and its title. Siblings keep their usual status/activity order among themselves. The parent’s group is the anchor — a child working in another worktree or directory is shown with its parent there (carrying its target badge), not as a stray second entry in its own group. This also holds in the collapsed project preview.

If the parent is missing or filtered out — closed, hidden by search, or simply not in the same group — the child stays visible in its own group, exactly once, and the ↳ marker still flags it as a child, with the target badge keeping its location readable. Nothing is duplicated and nothing disappears — and the “no sessions” hint only appears when a project truly renders no session row at all.

Families on the iPhone companion

The companion app folds a family into a single card, in both the session list and the cockpit grid: a visible child never gets a card of its own — it disappears into its parent’s, and the parent’s card carries a fixed-height family badge (a branch icon, the live child count, and up to five status dots) instead. The badge uses the child summaries already present on the phone first and the Mac’s aggregate counters as a fallback, so it still signals a family when an older or partial sender omits those optional counters. VoiceOver reads the badge as one full sentence — “3 child sessions, 1 running, 1 waiting for you” — never just the icon and a number.

• Session list, either mode (project or activity): a folded child never gets its own row. Only a detached child — its parent isn’t loaded in the same section, closed, or filtered out — still gets its own row, with a small ↳ ‹parent› caption naming the origin (or ↳ detached if the parent can’t be found at all) on its own line, so it never crowds out the waiting reason, limit countdown, or subagent status. In activity mode the parent is looked up across both sections, so the caption can still name it even when it landed in the other one.
• Cockpit grid: the same folding applies — a family is one tile, carrying the family badge. A detached child keeps its own tile with the same compact origin line as before.
• Session detail header, on a parent: the expanded status header shows one compact family chip with the count and status dots. Tap it to open a native bottom sheet with the full scrollable list, title, status, runtime, and a jump action for each child. The chat keeps its full height.
• Session detail header, on a child: unchanged — the parent relationship shows in the expanded status header, and tapping it jumps to the parent if it’s loaded, or reads a neutral detached otherwise.
• Target tag: a child running outside its parent’s checkout carries the same semantic target as the Mac badge — Worktree: ‹branch›, ‹project› · ‹branch›, or ‹directory› · external — as a small caption in the session list and on cockpit tiles. The Mac sends only those safe building blocks (kind, branch, project name, directory name) in the session list; no absolute host path ever reaches the phone.

A waiting child always reaches the phone

Marking a child “done” from the parent normally hides its tile everywhere, including the phone. The one exception: a child that still has a genuine open question, permission request, or plan approval waiting for you keeps reaching the phone — as its own row and counted in the family badge — even while marked done. A child that has merely finished its turn (no action needed from you) does not get this exception; it stays hidden like any other “done” tile. Once you’ve cleared the open box, the normal hidden rule applies again.

A running child on an otherwise idle or “done and waiting” parent also counts toward the parent’s own status on the phone — the same “a live child keeps its parent looking busy” rule the Mac cockpit already applies — so a family with real activity never reads as quiet just because the parent’s own turn hasn’t started yet.

Notifications while the parent is alive

A supervised child session reports its finish and its errors to its parent agent, not to you. By default those moments create no entry in your notification inbox, no banner, no sound, and no phone push — the parent agent is watching and looks after them. Permission requests and plan approvals from a child always reach you, because only a human can approve them. A question stays with the parent as long as the parent can answer it itself; when the parent cannot, the question comes to you.

The child’s first-run trust prompt is a permission box like any other: it is always loud, for every role, and the child-notification switch never touches it. Each waiting child gets exactly one first-run card in the bell; the card disappears after you approve the dialog or the child ends.

With Notify me about child sessions too (off by default) in the notification settings, the child’s finish reaches you as well, clearly marked as a child notification. Its errors then land in the notification inbox like every session failure — visible, but without a banner, sound, or push unless you turn on Show system notices as banners. Explicit notify_user messages follow the same switch. A child without a living parent reaches you regardless.

The rules that decide what reaches you are on Notifications & the Menu Bar.

Edge: codex’s first-run trust box

The first time codex runs in a project, it shows a one-time trust prompt in its own interface that only a human can clear. Codex 0.166 and later ask Trust this folder? with Trust and continue and Back to Agent Command Center; older versions ask Do you trust the contents of this directory?. vord recognizes both. A codex child spawned in a project that hasn’t been trusted yet will sit on that box until you approve it. This also happens after you move a project to a new folder, because Codex stores trust per folder path.

• The parent is told right away. Its report says the child is blocked by the folder-trust dialog, that you have been notified, and that it must not stop or restart the child, because that would discard the dialog. get_agent_status shows the same state as blocked by its folder trust dialog.
• You get a card you can answer. The two choices appear as an answer card on the child’s tile, in Mac chat (Code and Cowork, including the project-lead column) and in the iPhone command zone. The project board lists the child under the sessions waiting for you. The prompt also reaches you as a loud notification. vord answers Codex’s box with Enter or the arrow keys, because Codex ignores a typed number there.
• vord never answers it for you. Choosing Trust and continue is your decision; Codex then saves the folder as trusted for the account the child runs on.

Projects you’ve already trusted aren’t affected, and this is specific to codex.

Trust a project folder for Codex accounts

On Mac, open a project’s context menu in vord Code or vord Cowork and choose Codex folder access…. The sheet shows the trust state for each Codex account and selects accounts that are not trusted or are marked untrusted. Already trusted accounts and accounts without a config.toml cannot be selected. Review the selection, then click Trust folder to update only those accounts. vord writes nothing automatically. If multiple account slots share a config.toml through a symlink, the sheet identifies the shared settings because a change applies to that same file. Trust is tied to the folder path, so a moved project needs its new path trusted separately.

On iPhone, open the project section menu and choose Codex folder access. The sheet shows each account’s status and lets you choose the accounts to trust. The iPhone sends the request; the Mac writes the setting only after you tap Trust folder. This option requires a current Mac version that supports Codex folder access.

Delivery is confirmed, not assumed

Writing text into a child’s terminal is not the same as the child accepting it. Agent terminals can swallow a submit — most visibly kimi, whose Ctrl-S “steer” key only works while a turn is actually running and does nothing at all in a session that hasn’t run one yet. vord therefore treats delivery as a two-step affair:

• send_to_agent answers honestly. A successful call reports that the text was written into the child’s composer, with the submit not yet confirmed — not “delivered”. vord then verifies and reports back to the parent either way: a confirmation once the child starts a turn on the text, or an explicit failure if it stays stuck.
• “Confirmed” means a turn started, taken from the child’s own transcript (kimi’s wire log, claude’s prompt hook, codex’s rollout) — not from how its screen looks. A composer that merely looks empty is no longer accepted as proof.
• A child that hasn’t run a turn yet reads starting, never working. get_agent_status also states where the initial instruction stands: not delivered yet, written but no turn started, or accepted. A parent can no longer mistake “the terminal launched” for “the task is running”.
• Failures arrive in about a minute. Deliveries to children run on their own short retry cadence (roughly 60 seconds) instead of the four-minute ladder used for phone pastes, because an orchestrator that hears nothing keeps planning as if the child were working. If the child accepts the text but never starts a turn — a provider error right after the prompt, for instance — a separate watchdog tells the parent that too.

A fresh agent terminal is also not ready for input the moment its first screen appears, so vord delivers a child’s initial prompt only once the child’s screen is input-ready and stable. If delivery still can’t be confirmed, the parent gets an explicit report instead of the prompt sitting unsent in the child’s composer — the task never silently “starts”. Before that first prompt, vord also removes a leftover terminal reply in the child’s composer (for example a color-query answer that arrived after the TUI had already started reading the keyboard) when the field contains only a complete, known reply pattern. Anything else, including a remnant mixed with text you typed, is left untouched. The delay report to the parent names the concrete reason: a remnant vord could not clear, a first-run trust dialog, a login only you can complete, or a composer that is not ready yet.

Related

• Workflow Blueprints — gated multi-agent runs over these children: list/start/gate/status tools, four gate types, and a per-run spawn-and-time budget.
• Subagents & the Hierarchy Tree — the native way an agent parallelizes work with its own model, and the tree/counter that visualizes it.
• MCP Servers — the vord-mcp server that carries these tools, plus show_to_user and send_to_mesh.
• Responding to a Waiting Session — the box types (permission, finished, question, plan) a child can land in.
• Project Lead Session — one level up: a session that coordinates a whole project’s parent sessions for you, while those parents keep delegating to children as described here.
• Settings Reference — where the child-session and workflow controls live among the other agent options.
• Claude vs. Codex vs. Kimi — What Differs — the broader per-agent differences, including the codex trust step above.

Current models and account load

Parent agents can call get_delegation_context immediately before choosing to fetch a summary of the current models, supported thinking levels, model grants, and selected account slot; pass detail: "full" for the full text. Successful catalogs are refreshed after five minutes. After a failed refresh, the last successful state is kept with its original timestamp and an error marker. After errors a short retry pause applies; “Reload models” triggers an explicit refresh.

The status shows running and working sessions of this app as well as observed limits. Official quota values from the local CLI appear with a measurement timestamp, windows, and a marker for stale measurements. Without a measurement the quota remains unknown. The number of running sessions is not converted into a supposedly free percentage; model-bound limits remain distinguishable from account limits. The internal Claude utilization function is not needed for this.

The selection hints treat all allowed providers including Grok as candidates. Task requirements, observed load, cost, and expected rework determine the choice; the parent agent’s provider is not an automatic favorite. A not-yet-assessed model is not ranked lower. The new tool definition is available after the hosted agent session restarts.