docs(codex): justify the subagent wire notes from the live probe alone

The roster and disposition comments explained themselves in terms of a
provider-internal path taxonomy rather than anything this repo can observe.
Restate them from the evidence Orca actually has: the live app-server probe
saw `agentsStates` arrive empty, so nothing reads it; and `collabAgentToolCall`
stays substantive because nothing guarantees a session reports subagent work as
`subAgentActivity` at all — one that only emits the collab tool call gets no
roster row, and suppressing that too would leave its fan-out blank.

Same behaviour, same tests; comments and one test name only.
This commit is contained in:
Merge Sim
2026-09-05 05:08:02 -07:00
parent 42f21468c3
commit 47fa9bd720
4 changed files with 11 additions and 11 deletions
+2 -2
View File
@@ -6,8 +6,8 @@
// * `agentPath` is a tree path (`/root`, `/root/list_directory`); the trailing
// segment is a semantic task name and the only label available. There is no
// `thread/started` for a child, so nickname/role/depth do not exist.
// * `agentsStates` on `collabAgentToolCall` is `{}` on the MultiAgentV2 path;
// the V1 path does populate it. Nothing here reads it on either path.
// * `agentsStates` on `collabAgentToolCall` arrived empty (`{}`) throughout the
// probe, so nothing here reads it — state comes from `kind` alone.
// * `thread/tokenUsage/updated` reports a per-thread RUNNING TOTAL, so the
// latest frame replaces the previous one — it is never accumulated.
+2 -2
View File
@@ -1,7 +1,7 @@
// The Codex subagent roster: one journal row per spawn group, revised in place.
//
// There is no snapshot to read. `agentsStates` is empty on the MultiAgentV2 path
// that emits these items, and children get no `thread/started`, so the roster is
// There is no snapshot to read. `agentsStates` arrived empty in the live probe
// and children get no `thread/started`, so the roster is
// accumulated purely from `subAgentActivity` items — each of which arrives TWICE
// (`item/started` and `item/completed`). Every transition here is therefore
// idempotent, and a terminal state latches: duplicate and out-of-order delivery
@@ -127,9 +127,9 @@ describe('codex subagent item disposition', () => {
).toBe('status-chrome')
})
it("leaves collab tool calls substantive — they are a V1 turn's only subagent signal", () => {
// Only the MultiAgentV2 path emits `subAgentActivity`, so the roster row
// never exists on V1. Suppressing this too would render a V1 fan-out blank.
it('leaves collab tool calls substantive — they may be the only subagent signal', () => {
// A session that reports no `subAgentActivity` gets no roster row, so
// suppressing this too would render its fan-out blank.
expect(
classifyProviderFrame('codex', 'item:collabAgentToolCall', {
type: 'collabAgentToolCall',
@@ -204,10 +204,10 @@ const CODEX_ITEM_CLASSIFICATIONS: Record<string, ProviderFrameClassification> =
// `restoreThread` replays them straight through `items.handle`, which is where
// the classification earns its keep.
//
// `collabAgentToolCall` is deliberately NOT suppressed with it. Only the
// MultiAgentV2 path emits `subAgentActivity`; a V1 turn emits collab tool
// calls and nothing else, so suppressing them would leave a V1 fan-out
// showing nothing at all.
// `collabAgentToolCall` is deliberately NOT suppressed with it. Nothing
// guarantees a session reports subagent work as `subAgentActivity` at all; one
// that only ever emits the collab tool call gets no roster row, and suppressing
// that too would leave its fan-out showing nothing.
subAgentActivity: 'status-chrome'
}