Skip to content

Subagents: subagent.run tool with depth and child limits (ATO-1670) - #1733

Draft
sosidudku1 wants to merge 18 commits into
refactor/ato-1669-shared-worker-runnerfrom
feat/ato-1670-subagent-tool
Draft

sosidudku1 wants to merge 18 commits into
refactor/ato-1669-shared-worker-runnerfrom
feat/ato-1670-subagent-tool

Conversation

@sosidudku1

@sosidudku1 sosidudku1 commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Stacked on #1728 (ATO-1669, shared worker runner, itself on #1560). Also contains a merge of #1722 (ATO-1666, worker session depth). Retarget to main once those are merged.

Linear: ATO-1670. Also fixes ATO-1682 (a .. path in declared files widened the write grant to the whole disk, in Fusion too).

What changes

A new tool, subagent.run, lets the agent hand one or more tasks to subagents in normal mode (not only in Fusion), on the shared worker runner. A subagent runs on the session's current model with the worker tool policy; a profile (explore, review, research, or one from files/settings) narrows its tools and adds its prompt.

Decisions copied from precedents:

  • Children cannot start grandchildren. Max depth 1 (SUBAGENT_MAX_DEPTH, a constant, no setting yet). Precedent: Claude Code subagents cannot spawn subagents; Codex multi-agent defaults to max depth 1.
  • The real guard is session data, not hiding. The tool checks the caller's depth from the session stamp (ATO-1666) and treats any s-w- worker id as depth 1 even with a missing or broken stamp (fail closed). It is also hidden from workers (WORKER_EXCLUDED_TOOLS) and blocked by the worker tool filter at dispatch.
  • Child caps reuse existing numbers: 4 per call (DEFAULT_FUSION_CLOUD_WORKERS), 24 per turn (DEFAULT_FUSION_TASK_TREE_MAX_NODES). The limits are an extension of the task tree: a new treeLimitBreach in task-tree.ts is used by canSplitAt, both validateSplitProposal refusals (same results, same messages) and by subagent.run.
  • Name subagent.run (repo's family.verb, like verify.run; Claude Code "Task", Codex spawn_agent). Hooks written for Claude's Task also match it.
  • Model: the turn's model, including the desktop's per-project model, so ToolContext gains optional model and turnId. A profile's model or role resolves exactly as in Fusion.
  • Writes: a task may declare files; the person is asked once per call (same fan-out approval as fusion.delegate), and a yes lets the subagents write in the directories of those files and the working directory for this turn only. Without files a subagent cannot write below the trust level that would allow it anyway, and its refusal text tells the model to declare files or do the edit itself.
  • Fusion mode: the tool is hidden and refuses (Fusion already has fusion.delegate). fusion-delegate.ts is untouched.

Spend ceiling

Subagents stop on the parent turn's spend ceiling the way Fusion workers stop on its cap.

  • ToolContext gains an optional turnSpend seam (ceilingUsd, spentUsd(), add(usd)). agent-loop sets it only when the turn's costCeilingUsd > 0; add goes through recordCompactionSpend, so subagent spend lands in turn.spendUsd and the normal ceiling check stops the parent after the tool returns. step-contract, step-executor, batch-contract, batch-scheduler only pass the field through. No ceiling, no change.
  • subagent.run prices each child completion with the same resolver as fusion.delegate (resolveWorkerPricing + estimateUsageCostUsd), adds it to the turn, starts no new task once the ceiling is reached and aborts running ones when usage crosses it.
  • Already at the ceiling when called: refused up front, before the write approval prompt and before the per-turn count.
  • Output ends with a Stopped: line and an instruction not to retry only when the ceiling actually cut or held back a task; if every task finished and the last usage crossed the ceiling, a neutral "Spend budget for this turn is now reached." line instead. Rows cut by the ceiling get the cap note whatever status the runner gave them.
  • A cloud leg with no price entry gets "not priced, spend ceiling not applied to this subagent" (cloud = configured provider, not llama-server, not a local URL, same rule as the session readout). Local legs stay silent.
  • shouldStart, onWorkerUsage and onTaskFinished moved type-only from the Fusion extras into WorkerRunnerCoreOptions; Fusion behaviour unchanged.

Duplication left for ATO-1671

Profile loading, per-task leg notes and row model labels, the local-leg width rule and the ceiling wiring (ceilingStop, ceilingAbort, shouldStart, onWorkerUsage) are copied from fusion-delegate.ts; fusion.delegate's own guard still checks only the id prefix. ATO-1671 moves fusion.delegate onto this path once #605 and #1560 are merged or closed.

Known limits

  • The spend cap is soft, like Fusion's: running subagents can overshoot by up to one completion each (up to 4 per call), and a completion cut mid-stream reports no usage.
  • A cloud model behind a local gateway (LiteLLM, a proxy on 127.0.0.1) counts as local, so it gets no "not priced" note.
  • A row that fails on its own right after a sibling triggered the ceiling stop still gets the cap note (cosmetic).
  • The approval prompt is labelled with the Fusion fan-out category.
  • MintedSessionMetadata only changes outcomes once max depth goes above 1 (commented).

Tests

New src/tools/subagent/*.test.ts (refusals by depth stamp and by s-w- id with a broken stamp, run from depth 0 stamps the child depth 1 with origin subagent, caps per call and per turn by turn id, profile tools, unknown profile, Fusion refused, turn model used, declared files ask once at approval level 1 with a real gate, a grant does not carry into the next turn, string tasks key check). Plus task-tree, fanout-paths (.. normalised), worker-runner-core (depth option), agent-loop-fusion-seams (turn id and model reach tools; the seam exists only under a ceiling and spend added by a tool stops the turn with cost_ceiling), spend ceiling in subagent-run.test.ts (refused up front with no prompt and no ledger count, stop mid-run with the Stopped: line, cap note on a cut failed row, neutral line when nothing was cut, unpriced cloud vs local legs, no change without a ceiling), and deliberate pin updates: worker-tool-policy exact list, conformance (119 descriptors), catalog, filter gate, resource class, hooks, /tools listing, feed line.

Verification

Not yet checked on the second Mac.

Worker metadata now carries depth: the operator session is 0, a worker
it spawns is 1, a worker spawned by a worker is parent depth + 1.
createFusionWorkerSession stamps it (default 1), readFusionWorkerMeta
reads a missing or malformed depth as 1 without rejecting the record,
and readSessionDepth / childFusionWorkerDepth give the depth of any
session and of its next child. The s-w- id prefix is unchanged.
…ubagent-tool

# Conflicts:
#	src/tools/fusion/worker-runner.ts
… check (ATO-1670)

The core runner options take an optional depth, stamped on every worker
session; absent it stays 1, so Fusion is unchanged. The task tree's depth
and node caps become one exported check, treeLimitBreach, which the split
check and the proposal refusals now use and the subagent tool will reuse.
…1670)

Runs up to 4 tasks per call and 24 per turn as worker turns on the
session's own model, under the subagent origin, with the worker tool
policy plus a profile's allowlist. Only a depth-0 session may call it:
the depth is read from the caller's session data and a worker id counts
as depth 1 even with a broken stamp. The tool is also hidden from
workers. Caps go through the task tree's treeLimitBreach.
…og gates (ATO-1670)

Descriptor and args schema next to fusion.delegate, compact form, grammar
rule, approval_gated solo class, a live gate that hides it while Fusion
is effective, registration beside fusion.delegate with the same profile
loader, and a record of minted worker sessions so the depth check reads
their own stamp. Shared catalog tests updated deliberately.
ToolContext gains turnId, one value per agent turn, and model, the chat
model a pinned turn asks its link for (the desktop's per-project model).
Both flow from the agent loop through the step and batch contexts.
…1670)

Optional approvalRefusal on the shared runner core options. Absent, the
worker session policy keeps Fusion's texts unchanged.
…ing tasks check (ATO-1670)

- The per-turn child count keys on ToolContext.turnId, one entry per
  session and a bounded number of sessions.
- A turn that asked its link for a model runs its subagents on it and
  their rows name it.
- A task may declare files: the person is asked once per call under the
  fusion_fanout category, and a yes lets the subagents write there.
  Subagents get their own refusal texts, naming no orchestrator.
- Unknown task keys are refused also when tasks arrive as a JSON string.
…670)

resolveUserPath leaves an absolute path as written, so files: ["/a/../b"]
gave the directory "/a/..", which passed the breadth check and then
covered the whole disk. Every path is resolved before dirname, and
collapseScope resolves each directory before judging it.
…is per directory (ATO-1670)

Outside Fusion nothing clears the gate's turn grant at turn start, so
subagent.run remembers the turn each session's grant came from and
clears it before reading it in any other turn, or without a turn id.
The descriptor and README now say a yes covers the directories of the
listed files and the working directory.
…unt (ATO-1670)

ToolContext.turnSpend carries the turn's cost ceiling, the spend so far
and a way to add to it, only when a ceiling is set. What a tool adds goes
into the same turn spend the loop checks before every step.
…e options (ATO-1670)

Type-only: the runner already read them. A subagent run now passes them.
…p on its cap (ATO-1670)

Under a ceiling, each subagent completion is priced with the resolver
Fusion workers use and added to the turn's spend. No subagent starts once
the ceiling is reached, a running one is stopped through its signal, and
the rows say so with Fusion's wording. Without a ceiling nothing changes.
… Fusion (ATO-1670)

- A call made once the ceiling is reached is refused before any approval
  question and before it counts toward the per-turn cap.
- A stopped run ends its output with the stop line and what to do.
- Every row the ceiling cut gets the note, whatever status it ended in.
- A cloud leg with no price says on its rows that the ceiling was not
  applied to it.
- onTaskFinished moves into the shared runner core options (type only).
…and flag only cloud legs as unpriced (ATO-1670)

- The Stopped line and details.stoppedBy appear only when a row was cut
  or not started by the ceiling. A run whose last completion crossed it
  but finished gets a neutral line and details.ceilingReached.
- The unpriced note uses the provider's own local check (llama-server or
  a local server URL), not slot affinity.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant