@te-river/opencode-team-mode 1.7.7 → 1.7.8

package/docs/research/host-subagent-injection.md

@@ -1,187 +1,187 @@
-# OpenCode 2.x — how a background sub-agent is dispatched, acknowledged, and answered
-
-**Scope:** one exported desktop session (`e-f.json`, provided by the user on 2026-09-26),
-read as evidence. Nothing in the host was modified and nothing here was inferred from the
-v1 behaviour: every claim below is either quoted from that export or measured against it.
-The session's workspace path is deliberately not reproduced.
-
-**Why this page exists.** On v2 a plugin cannot create an agent and cannot create a
-session it is allowed to read, so delegation goes through the host's own `subagent` tool.
-`tm_join` — the collect side — therefore needed to know what that tool gives a plugin at
-each of three moments: when the call is made, when the host acknowledges it, and when the
-child's answer comes back. Getting the second one wrong is what made the feature look
-impossible: the ack is small and the answer is not a tool result at all.
-
-## 1. The dispatch, as the plugin sees it
-
-`[L]`+`[B]` `execute.before` carries the model's own arguments under **`input`** — the host's
-trigger is `{tool, sessionID, agent, messageID, id, input}`, where `sessionID`/`agent` are the
-CALLER's and `input` is the argument object:
-
-```
-{ tool: "subagent",
-  sessionID: "ses_…",                       // the lead's own session
-  agent: "team",
-  input: { agent: "architect", background: true,
-           description: "注入形状取证", prompt: "…" } }
-```
-
-`description` is a task name, `prompt` is the work. Only `description` is worth keeping
-and only for the lead's own table: `prompt` is free text and never enters the trajectory
-(the R6 rule binds a diagnostic as much as a guard).
-
-## 2. The ack — this is the seam that makes claiming a child possible
-
-`[L]` The synchronous result of a background dispatch is small (98 tokens measured on an
-earlier host build) and carries the child's identity twice:
-
-```
-content[0].text = "The subagent is working in the background (sessionID: ses_f2417df8…).
-                   You will be notified automatically when it finishes.
-                   DO NOT sleep, poll for progress, ask the subagent for status, or
-                   duplicate this subagent's work; …"
-metadata        = { sessionID: "ses_f2417df8…", status: "running", truncated: false }
-```
-
-Two consequences that changed the design:
-
-1. **`execute.after` on tool `subagent` yields the child session id.** No `session.get`,
-   no `session.children`, no guessing: the host hands it over. Our `ctx.session.get`
-   bridge never resolved a shape on a live host, so a tree walk was not an option, and
-   this made the question moot.
-2. **`status:"running"` is the host telling us the work is open.** A synchronous child is
-   NOT distinguished by a missing id — read out of 2.0.18, the `subagent` result always
-   carries `metadata:{sessionID,status}`, and the completed case wraps the body itself:
-
-   ```js
-   content: G.status==="completed"
-     ? `<subagent sessionID="${G.sessionID}" state="completed">.${G.output}.</subagent>`
-     : G.output,
-   metadata:{ sessionID: G.sessionID, status: G.status }
-   ```
-
-   So what makes a synchronous child un-collectable is `status:"completed"` (the reply is
-   already in hand), not an absent id. Counting it as `settledAtOnce` rather than
-   `noChildId` is what keeps the two cases from being conflated in `tm_stats`.
-3. **The `execute.before` field is `input`, not `args`.** Also from the host's own trigger:
-
-   ```js
-   e.trigger("tool","execute.before",{tool,sessionID,agent,messageID,id,input:m})
-   ```
-
-   Reading `event.args` was the first live round's failure: the stash stayed empty, every
-   ack arrived unpaired, and each child was registered under a generic label instead of the
-   role and task it was dispatched for — `tm_stats` said "登记 1 个（1 个没配到派发行）" and
-   the unit test that now pins the paired label would have been red. A fake ctx that mirrors
-   the guessed shape passes a bug like this; the host's code does not.
-
-The id is read from `metadata` first and from the ack sentence second, because a field
-shape is exactly what a host upgrade changes.
-
-## 3. The answer is a message, not a tool result
-
-`[L]` When the child finishes, the parent receives a synthetic message. From the export,
-the message's own fields:
-
-```
-type: "synthetic"
-description: "注入形状取证"
-metadata: { source: "subagent", childID: "ses_f2417df8…", agent: "architect", state: "completed" }
-text:     <subagent sessionID="ses_f2417df8…" state="completed" description="注入形状取证">
-          PROBE-OK
-          </subagent>
-```
-
-Note the key names differ between the two moments: the ack says `sessionID`, the
-injection says `childID` (and adds `source`, `agent`, `state`). A matcher that assumes one
-spelling for both is the bug class this page exists to record — `parseHostEnvelope` in
-`src/task-offload.ts` accepts both the v1 `<task id=` and the v2 `<subagent sessionID=`
-wrapper for exactly this reason, and rewrites only the body, because the session id inside
-the envelope is the pointer the lead uses to fetch the reply back.
-
-What the plugin does NOT get on v2: a hook that hands us this message BEFORE the host
-persists it. v1 was given `chat.message` at exactly that moment; the v2 plugin surface has no
-equivalent. What we DO get is the message one step later, inside the parent's assembled
-history at `session.hook("context")` — measured, because `applyV2CompletionWatch` settles the
-child from it (§7). The distinction is the whole difference between the two claims we can
-make: we can OBSERVE that the host wrote a completion (so `tm_join` may say 已完成 and name
-where it read that), and we cannot REWRITE the body the model is about to receive. `tm_join`
-therefore reports the child's state and provenance and says where the text is, rather than
-printing a reply it never read.
-
-## 4. Ordering, measured, and the one inference it licenses
-
-`[L]` From the export's timestamps (same session, milliseconds):
-
-| moment | ts |
-|---|---|
-| child injected into the parent | …824730 |
-| parent's next assistant message streamed | …824763 → …829026 |
-| parent session `idle` | …829038 |
-
-So the injection precedes the parent's idle by construction — the parent cannot go idle
-with an undelivered notification. That single ordering fact is what licenses the fallback
-in `src/tm/dispatch.ts`: a host-dispatched child still marked running when ITS PARENT goes
-idle is settled as `settleSource: "parent-idle"` and printed as 推定已结算, with the reason
-in the same line. The child's own `session.idle` on the event feed is the measured path for a
-child THIS process dispatched (`settleSource: "event"`) — for a host `subagent` child it does
-not arrive at all, which §7 records; the two are never printed the same way, because one is an
-observation and the other is an inference from a host ordering we happened to see once.
-
-## 6. Live verification, 2026-09-26 (host 2.0.18, `lxns-uni/zai-org/GLM-5.3#max`)
-
-Run against a sandbox config dir (`OPENCODE_CONFIG_DIR`, plugin loaded from
-`vendor/team-mode`) with the user's real profile supplying credentials, so nothing was
-written to the live global config. Same three-step prompt twice, before and after the
-`input` fix:
-
-| | acks seen | registered | unpaired | audit line's `agent` | the row `tm_join` printed |
-|---|---|---|---|---|---|
-| before | 1 | 1 | **1** | `subagent` (generic) | child id + （宿主 subagent 派发）, role lost |
-| after | 1 | 1 | **0** | `architect` | `ses_f237aec68ffe… · architect · "认领复验2" · 运行中 22s ·（宿主 subagent 派发）` |
-
-So the claiming and the pairing are both observed on a live host, and the settle path was
-observed in its honest state: the child was still `运行中` when the snapshot ran (its own
-`session.idle` had not arrived and the parent had not gone idle yet), which is the row
-saying what it knows rather than guessing.
-
-**One observability caveat, measured in the same runs:** a single CLI invocation boots more
-than one server process, each writing its own `v2-surface` row with ITS OWN counters. The
-model pasted `确认 0 次 → 登记 0 个` from the sibling process while the process that
-registered the child reported `1 → 1`. `tm_stats` therefore prints the run id beside those
-counters — a bare 0 in a multi-process host is otherwise readable as "nothing was
-dispatched", which is exactly the silence this feature removes.
-
-
-## 7. What is settled, and what is still open
-
-`[L]` **The host does NOT forward a child session's `session.idle` to a plugin subscriber.**
-Measured on 2.0.18 (round 5, 2026-09-26): a background child finished, its
-`<subagent … state="completed">` injection reached the parent with the full report, and the
-plugin feed produced neither an `idle` nor an `idle_presumed` line for that child — `tm_join`
-kept showing it 运行中. So neither of the two paths this module originally offered works for a
-host child mid-turn: the event never arrives, and the parent-idle presumption cannot fire
-while the parent is still working. That is what `applyV2CompletionWatch` exists to fix: the
-envelope the host itself writes, read out of the parent's assembled message history.
-
-`[L]` **The seam that carries it is `session.hook("context")`, and settle-by-injection is
-live-verified.** Getting there took two wrong answers, and both are counted so a wrong seam is
-visible rather than silent:
-
-| round | what was watched | what the host did |
-|---|---|---|
-| 6 | `session.prompt` + `session.model.request` | `prompt` fired **0** times; `model.request` fired **6** and carried no message list at all (the history is assembled separately from that payload) |
-| 8 | `session.context` (+ `prompt` kept, counted, still 0) | fired 6, `completion_settled=1`, audit line `{"event":"idle_injection","child":"ses_f23386a7…","agent":"researcher","ms":53102}` |
-
-The line is the third source of truth in `src/tm/dispatch.ts` (`settleSource: "injection"`,
-printed as 已完成 with its provenance), and the `ms` is the child's own elapsed time, not our
-wait. `completion_skipped` grows on every later round (4, then 5) because the scan is skipped
-while nothing is open — which is the point of counting the skip: "did not look" and "looked and
-saw nothing" stay distinguishable, and a hook that exists but is the WRONG one is exactly the
-failure round 6 nearly hid.
-
-`[U]` The full `status` vocabulary: 2.0.18's own code applies the `<subagent …>` wrapper only
-when `G.status === "completed"`, so anything else is treated as open by
-`hostChildIsOpen()` — whether `error` reaches a plugin-visible ack has not been seen.
-`[U]` Whether a child of a child is ever dispatched: the config gives nesting depth one, and
-the T3 rule says only the lead dispatches, so this page describes one level.
+# OpenCode 2.x — how a background sub-agent is dispatched, acknowledged, and answered
+
+**Scope:** one exported desktop session (`e-f.json`, provided by the user on 2026-09-26),
+read as evidence. Nothing in the host was modified and nothing here was inferred from the
+v1 behaviour: every claim below is either quoted from that export or measured against it.
+The session's workspace path is deliberately not reproduced.
+
+**Why this page exists.** On v2 a plugin cannot create an agent and cannot create a
+session it is allowed to read, so delegation goes through the host's own `subagent` tool.
+`tm_join` — the collect side — therefore needed to know what that tool gives a plugin at
+each of three moments: when the call is made, when the host acknowledges it, and when the
+child's answer comes back. Getting the second one wrong is what made the feature look
+impossible: the ack is small and the answer is not a tool result at all.
+
+## 1. The dispatch, as the plugin sees it
+
+`[L]`+`[B]` `execute.before` carries the model's own arguments under **`input`** — the host's
+trigger is `{tool, sessionID, agent, messageID, id, input}`, where `sessionID`/`agent` are the
+CALLER's and `input` is the argument object:
+
+```
+{ tool: "subagent",
+  sessionID: "ses_…",                       // the lead's own session
+  agent: "team",
+  input: { agent: "architect", background: true,
+           description: "注入形状取证", prompt: "…" } }
+```
+
+`description` is a task name, `prompt` is the work. Only `description` is worth keeping
+and only for the lead's own table: `prompt` is free text and never enters the trajectory
+(the R6 rule binds a diagnostic as much as a guard).
+
+## 2. The ack — this is the seam that makes claiming a child possible
+
+`[L]` The synchronous result of a background dispatch is small (98 tokens measured on an
+earlier host build) and carries the child's identity twice:
+
+```
+content[0].text = "The subagent is working in the background (sessionID: ses_f2417df8…).
+                   You will be notified automatically when it finishes.
+                   DO NOT sleep, poll for progress, ask the subagent for status, or
+                   duplicate this subagent's work; …"
+metadata        = { sessionID: "ses_f2417df8…", status: "running", truncated: false }
+```
+
+Two consequences that changed the design:
+
+1. **`execute.after` on tool `subagent` yields the child session id.** No `session.get`,
+   no `session.children`, no guessing: the host hands it over. Our `ctx.session.get`
+   bridge never resolved a shape on a live host, so a tree walk was not an option, and
+   this made the question moot.
+2. **`status:"running"` is the host telling us the work is open.** A synchronous child is
+   NOT distinguished by a missing id — read out of 2.0.18, the `subagent` result always
+   carries `metadata:{sessionID,status}`, and the completed case wraps the body itself:
+
+   ```js
+   content: G.status==="completed"
+     ? `<subagent sessionID="${G.sessionID}" state="completed">.${G.output}.</subagent>`
+     : G.output,
+   metadata:{ sessionID: G.sessionID, status: G.status }
+   ```
+
+   So what makes a synchronous child un-collectable is `status:"completed"` (the reply is
+   already in hand), not an absent id. Counting it as `settledAtOnce` rather than
+   `noChildId` is what keeps the two cases from being conflated in `tm_stats`.
+3. **The `execute.before` field is `input`, not `args`.** Also from the host's own trigger:
+
+   ```js
+   e.trigger("tool","execute.before",{tool,sessionID,agent,messageID,id,input:m})
+   ```
+
+   Reading `event.args` was the first live round's failure: the stash stayed empty, every
+   ack arrived unpaired, and each child was registered under a generic label instead of the
+   role and task it was dispatched for — `tm_stats` said "登记 1 个（1 个没配到派发行）" and
+   the unit test that now pins the paired label would have been red. A fake ctx that mirrors
+   the guessed shape passes a bug like this; the host's code does not.
+
+The id is read from `metadata` first and from the ack sentence second, because a field
+shape is exactly what a host upgrade changes.
+
+## 3. The answer is a message, not a tool result
+
+`[L]` When the child finishes, the parent receives a synthetic message. From the export,
+the message's own fields:
+
+```
+type: "synthetic"
+description: "注入形状取证"
+metadata: { source: "subagent", childID: "ses_f2417df8…", agent: "architect", state: "completed" }
+text:     <subagent sessionID="ses_f2417df8…" state="completed" description="注入形状取证">
+          PROBE-OK
+          </subagent>
+```
+
+Note the key names differ between the two moments: the ack says `sessionID`, the
+injection says `childID` (and adds `source`, `agent`, `state`). A matcher that assumes one
+spelling for both is the bug class this page exists to record — `parseHostEnvelope` in
+`src/task-offload.ts` accepts both the v1 `<task id=` and the v2 `<subagent sessionID=`
+wrapper for exactly this reason, and rewrites only the body, because the session id inside
+the envelope is the pointer the lead uses to fetch the reply back.
+
+What the plugin does NOT get on v2: a hook that hands us this message BEFORE the host
+persists it. v1 was given `chat.message` at exactly that moment; the v2 plugin surface has no
+equivalent. What we DO get is the message one step later, inside the parent's assembled
+history at `session.hook("context")` — measured, because `applyV2CompletionWatch` settles the
+child from it (§7). The distinction is the whole difference between the two claims we can
+make: we can OBSERVE that the host wrote a completion (so `tm_join` may say 已完成 and name
+where it read that), and we cannot REWRITE the body the model is about to receive. `tm_join`
+therefore reports the child's state and provenance and says where the text is, rather than
+printing a reply it never read.
+
+## 4. Ordering, measured, and the one inference it licenses
+
+`[L]` From the export's timestamps (same session, milliseconds):
+
+| moment | ts |
+|---|---|
+| child injected into the parent | …824730 |
+| parent's next assistant message streamed | …824763 → …829026 |
+| parent session `idle` | …829038 |
+
+So the injection precedes the parent's idle by construction — the parent cannot go idle
+with an undelivered notification. That single ordering fact is what licenses the fallback
+in `src/tm/dispatch.ts`: a host-dispatched child still marked running when ITS PARENT goes
+idle is settled as `settleSource: "parent-idle"` and printed as 推定已结算, with the reason
+in the same line. The child's own `session.idle` on the event feed is the measured path for a
+child THIS process dispatched (`settleSource: "event"`) — for a host `subagent` child it does
+not arrive at all, which §7 records; the two are never printed the same way, because one is an
+observation and the other is an inference from a host ordering we happened to see once.
+
+## 6. Live verification, 2026-09-26 (host 2.0.18, `lxns-uni/zai-org/GLM-5.3#max`)
+
+Run against a sandbox config dir (`OPENCODE_CONFIG_DIR`, plugin loaded from
+`vendor/team-mode`) with the user's real profile supplying credentials, so nothing was
+written to the live global config. Same three-step prompt twice, before and after the
+`input` fix:
+
+| | acks seen | registered | unpaired | audit line's `agent` | the row `tm_join` printed |
+|---|---|---|---|---|---|
+| before | 1 | 1 | **1** | `subagent` (generic) | child id + （宿主 subagent 派发）, role lost |
+| after | 1 | 1 | **0** | `architect` | `ses_f237aec68ffe… · architect · "认领复验2" · 运行中 22s ·（宿主 subagent 派发）` |
+
+So the claiming and the pairing are both observed on a live host, and the settle path was
+observed in its honest state: the child was still `运行中` when the snapshot ran (its own
+`session.idle` had not arrived and the parent had not gone idle yet), which is the row
+saying what it knows rather than guessing.
+
+**One observability caveat, measured in the same runs:** a single CLI invocation boots more
+than one server process, each writing its own `v2-surface` row with ITS OWN counters. The
+model pasted `确认 0 次 → 登记 0 个` from the sibling process while the process that
+registered the child reported `1 → 1`. `tm_stats` therefore prints the run id beside those
+counters — a bare 0 in a multi-process host is otherwise readable as "nothing was
+dispatched", which is exactly the silence this feature removes.
+
+
+## 7. What is settled, and what is still open
+
+`[L]` **The host does NOT forward a child session's `session.idle` to a plugin subscriber.**
+Measured on 2.0.18 (round 5, 2026-09-26): a background child finished, its
+`<subagent … state="completed">` injection reached the parent with the full report, and the
+plugin feed produced neither an `idle` nor an `idle_presumed` line for that child — `tm_join`
+kept showing it 运行中. So neither of the two paths this module originally offered works for a
+host child mid-turn: the event never arrives, and the parent-idle presumption cannot fire
+while the parent is still working. That is what `applyV2CompletionWatch` exists to fix: the
+envelope the host itself writes, read out of the parent's assembled message history.
+
+`[L]` **The seam that carries it is `session.hook("context")`, and settle-by-injection is
+live-verified.** Getting there took two wrong answers, and both are counted so a wrong seam is
+visible rather than silent:
+
+| round | what was watched | what the host did |
+|---|---|---|
+| 6 | `session.prompt` + `session.model.request` | `prompt` fired **0** times; `model.request` fired **6** and carried no message list at all (the history is assembled separately from that payload) |
+| 8 | `session.context` (+ `prompt` kept, counted, still 0) | fired 6, `completion_settled=1`, audit line `{"event":"idle_injection","child":"ses_f23386a7…","agent":"researcher","ms":53102}` |
+
+The line is the third source of truth in `src/tm/dispatch.ts` (`settleSource: "injection"`,
+printed as 已完成 with its provenance), and the `ms` is the child's own elapsed time, not our
+wait. `completion_skipped` grows on every later round (4, then 5) because the scan is skipped
+while nothing is open — which is the point of counting the skip: "did not look" and "looked and
+saw nothing" stay distinguishable, and a hook that exists but is the WRONG one is exactly the
+failure round 6 nearly hid.
+
+`[U]` The full `status` vocabulary: 2.0.18's own code applies the `<subagent …>` wrapper only
+when `G.status === "completed"`, so anything else is treated as open by
+`hostChildIsOpen()` — whether `error` reaches a plugin-visible ack has not been seen.
+`[U]` Whether a child of a child is ever dispatched: the config gives nesting depth one, and
+the T3 rule says only the lead dispatches, so this page describes one level.