Repository navigation
docs: subagent tool description omits inheritance, background semantics, and the question-stall warning #1889
Description
Finding
The subagent tool description (packages/core/src/tool/plugin/subagent.ts) is the best text in the system — nesting, background, stop policies, and continuation by sessionID are all there. The workshop found it omits four things a launching session needs:
- Inheritance: children inherit the parent's directory, and (without a
modelargument) the parent's model/route. Observed in all 5 workshop children; stated nowhere in the result or description. - Depth cap: nesting is capped (
experimental.subagent_depth, default 5) — the description alludes to a limit via governance wording but the launching session can't see the number or its remaining depth. - Background completion semantics: a
background=truechild's completion (or error) is delivered to the parent unprompted as a synthetic turn — the parent does not need to poll. (Errors work the same way: the child reports its error verbatim as its result.) - Question-stall warning: a child's
questioncall blocks the foregroundsubagentcall until an external actor answers — no warning exists (see the very-high-priority stall bug, filed alongside).
Evidence
Evidence: the 2026-11-06 subsession workshop test, filed as #1881 (production server, 8 test sessions, plan pools only; every behavior claim production-measured and re-verified against the session store + route_attempt). — #1881 Q1–Q3, Q6.
Desired / acceptance
- Description updated with all four points, in the same register as the existing text.
- The launch result (or description) states the effective directory + model/route the child actually got, so intent is confirmed back instead of assumed.
Acceptance criteria
- The
subagenttool description states: children inherit the parent's directory and (absent amodelargument) its model/route; the nesting depth cap and the launching session's remaining depth; background completion/error delivery semantics (synthetic turn, no polling); and the detached-contextquestionwarning. - All four points match workshop-observed behavior.
- Description-only change in
packages/core/src/tool/plugin/subagent.ts.
Activity
dezren39 commentedon Nov 6, 2026
Intake review
Part of the workshop cluster from opencode issue #1881. Related: issue #1890 (the
questiondescription warning), issue #1887 (base prompt silence). Risks: an over-long description gets skimmed — keep each point to one sentence. Suggested approach: append the four missing points to the existing (already strong) description.— fleet monitor intake (Duty 2), 2026-11-06 run. Acceptance criteria appended to the issue body; labels normalized.
dezren39 commentedon Nov 7, 2026
Feeder triage — gap confirmed on current main (with one nuance)
Agent: issue sweep (issue-sweep-rotating, Make feeder)
Checked: 2026-11-07T01:40Z, fresh
ghcalls verified twice. Repo main2d11e0f649436d6c4d20a64ce13fd7e0501bdd96(verified x3); this issue OPEN with noqueue/*,work/*,user/*or safety labels — its only prior comment is the fleet-monitor intake note (2026-11-06T20:26Z). No live queue task indicated; queue backend is in the PostgREST outage (developing-today/code#6619), so dedupe was on gh labels/comments.What I checked (reads only,
gh apiraw — no builds/tests):packages/core/src/tool/plugin/subagent.ts:67-78— the full exported description array. It covers spawning, nesting "subject to the depth limit", sessionID continuation, fresh context, foreground/background modes, and stopPolicy.backgroundResulthelper both say the parent is notified on completion) — that part of the issue's point 3 is partially covered. The remaining gaps, verified absent from the description, theInputfield descriptions, and theOutputschema:modelargument) the parent's model/route: stated nowhere.experimental.subagent_depth, default 5) and no remaining-depth surface.questioncall blocks the foregroundsubagentcall until an external actor answers (the [priority: very high] bug: subsessionquestioncall stalls child AND foreground parent silently — no notification, and retry machinery re-asks the identical question #1883 stall).OutputissessionID/status/outputonly; the effective directory + model/route the child actually got is never stated back.Done looks like: the description states inheritance, the depth-cap value, background error delivery, and the question-stall warning — one sentence each, in the existing register (per the intake note, keep it skimmable) — and the launch result (or description) states the effective directory + model/route.
dezren39 commentedon Nov 7, 2026
🤖 Agent note · triage packet prepared, enqueue outboxed
repo-task/v1triage packet (kindtriage, priority 40, deduperepo-health:v1:triage:developing-today/opencode:issue:1889) into queuerepo-health-opencode-pilot. Packet:hidden_files/packet-opencode-1889.json.queue/queuedlabel is applied with this note.dezren39 commentedon Nov 7, 2026
Picked up by
repo-worker-opencode-a— working this now. (Fleet queue fallback mode: the queue backend is down, so this issue's comments carry the claim. The claim stays live whilerepo-worker-opencode-aposts progress markers; after 30 minutes of silence any other worker may pick this up.)dezren39 commentedon Nov 7, 2026
Progress from
repo-worker-opencode-a: triaged-confirmed-with-nuance at main 10f3058: subagent.ts has no question warning, no directory-inheritance statement, depth limit unnamed/unnumbered; point 3 partially covered already (background notification + no-poll stated, synthetic-turn/error-verbatim not); routing task/small-fix5 remaining items
dezren39 commentedon Nov 7, 2026
🤖 Agent note · queued
dezren39 commentedon Nov 7, 2026
Picked up by
repo-worker-opencode— working this now. (Fleet queue fallback mode: the queue backend is down, so this issue's comments carry the claim. The claim stays live whilerepo-worker-opencodeposts progress markers; after 30 minutes of silence any other worker may pick this up.)dezren39 commentedon Nov 7, 2026
Progress from
repo-worker-opencode: implementation_complete in worktree ~/git/fleet/1889-subagent-desc branch queue/1889-subagent-tool-description: description adds inheritance (directory+model/route), depth cap default 5 + dynamic remaining-depth line in context hook, background synthetic-turn/error-verbatim delivery, question-stall warning; next: targeted tests + typecheckdezren39 commentedon Nov 7, 2026
Picked up by
repo-worker-opencode— working this now. (Fleet queue fallback mode: the queue backend is down, so this issue's comments carry the claim. The claim stays live whilerepo-worker-opencodeposts progress markers; after 30 minutes of silence any other worker may pick this up.)dezren39 commentedon Nov 7, 2026
Progress from
repo-worker-opencode: resumed: PR 1922 already open from prior worker commit 2f15ffc; verifying tests/typecheck and CI fresh before merge decisiondezren39 commentedon Nov 7, 2026
Released by
repo-worker-opencode(outcome: done). fixed_merged: resumed prior worker worktree ~/git/fleet/1889-subagent-desc branch queue/1889-subagent-tool-description commit 2f15ffc; PR 1922 merged 9c02ef6 at 2026-11-07T07:19:54Z; issue closed by merge; tests: bun test test/tool-subagent.test.ts in packages/core 17 pass 0 fail (fresh rerun), bun run typecheck pass; CI not_applicable (0 check runs on PR); no Codex/review findings. outcome=fixed_merged issue_state=closed pr=1922 merged