# The Agent tool's `name` parameter silently destroys the return channel **Date:** 2026-08-17 (voyage S85) **Claude Code:** 2.1.226 · **Plugin:** voyage 5.9.1 (installed cache — verified byte-identical to the repo working tree for both reviewer agents before measuring) **Status:** Root cause MEASURED and mechanistically confirmed. The defect is in how the harness treats one Agent-tool parameter, not in voyage's agent definitions. A one-line workaround exists and is now pinned in every voyage spawn site. ## The report that triggered this `akashic-intelligence` lost `/trekplan` Phase 9 twice. S25 (2026-08-17, plan rev 5.0): four subagents spawned via the Agent tool — `voyage:plan-critic` ×2, `voyage:scope-guardian` ×2, all `model: "opus"`, not Workflow. Nine `SendMessage` reminders, zero replies. The round before had the same outcome with tighter scope and an explicit tool-call budget. Consequence: the hand-dedup step fell away (one source instead of two) and review coverage came out **narrower** than the four preceding rounds. Their own conclusion was "the channel, not the agents" — directionally right. Two details in it are wrong and matter: they attributed it to the agents having no `Write` tool, and they concluded the remedy is to abandon agents and run the review inline. `Write` is irrelevant, and the agents do not need abandoning. ## Root cause **Passing `name` to the Agent tool does not name a subagent. It changes what kind of thing gets spawned.** The spawn metadata says it outright. From `~/.claude/projects///subagents/agent-*.meta.json`, same session, same model, same `subagent_type`: | spawn | recorded `agentType` | `taskKind` | `spawnDepth` | |---|---|---|---| | without `name` | `voyage:plan-critic` | *(none — a real subagent)* | `1` | | with `name` | `pc-opus` (the name) | `in_process_teammate` | `0` | The two kinds have different return semantics: - **Subagent** (`spawnDepth: 1`) — the agent's final assistant text **is** the return value. It arrives at the parent as a task notification. - **Teammate** (`in_process_teammate`, `spawnDepth: 0`) — a peer of the main session, not a child of it. Its plain final text is **not** a return value; it is only transcript. A teammate reaches the parent **only** by calling `SendMessage(to: "main")`. Every voyage agent declares a `tools:` allowlist. `plan-critic` and `scope-guardian` declare `["Read", "Glob", "Grep"]`. **No SendMessage.** As teammates they are therefore *structurally* incapable of returning anything — no prompt, no scope tightening, and no tool-call budget can change that. This is exactly why akashic's second attempt with a stricter prompt failed identically: the prompt was never the variable. ### Why it looks like a hung agent The teammate runs. It reads the plan, reasons, and writes a complete, correct final answer to its transcript. Then it stops. From the orchestrator's side this is indistinguishable from an agent that stalled — so the natural response is to poke it with `SendMessage`, which produces more transcript that also never comes back. Nine reminders, zero replies. ### The symptom signature, exactly The teammates do eventually surface — as content-free idle notifications, delivered long after the fact. Observed in this session, all six named agents (times UTC): ``` {"type":"idle_notification","from":"ctrl-pong", "idleReason":"available"} 19:57:30 {"type":"idle_notification","from":"ctrl-read", "idleReason":"available"} 19:57:35 {"type":"idle_notification","from":"pc-nooverride", "idleReason":"available"} 19:59:19 {"type":"idle_notification","from":"pc-opus", "idleReason":"available"} 19:59:24 {"type":"idle_notification","from":"sg-opus", "idleReason":"available"} 19:59:37 {"type":"idle_notification","from":"ctrl-sendback", "idleReason":"available", "summary":"[to main] PONG-VIA-SENDMESSAGE"} 20:06:16 ``` This is akashic's "innholdsløse idle-pings", verbatim, and it is the field signature to recognise the defect by. Two things to read off it: - **`summary` is present only for the teammate that called SendMessage.** For the five tool-less ones the notification carries no content at all — not a truncated result, not an error, nothing. The presence or absence of `summary` is the fastest way to tell a delivering teammate from a mute one. - **The idle notifications lag by minutes.** `ctrl-pong` went idle 10 seconds after spawn; its notification arrived ~9 minutes later. So "no idle ping yet" is not evidence the agent is still working, and the ping, when it comes, is not a result. Judging liveness from these is how a completed run gets re-prompted nine times. **The work is not lost.** It is on disk at `~/.claude/projects///subagents/agent-a-.jsonl`. The final assistant text block in that file is the answer the orchestrator never received. This is the recovery path when a run has already been burned. ## Measurements One session, one target unless noted. Target for the reviewer cells: `docs/devils-advocate-plan.md` (66 lines) — a real plan file, small enough that runtime cannot be confused with hanging. | # | `subagent_type` | `model` | `name`? | Returned to parent? | Time | |---|---|---|---|---|---| | 1 | `general-purpose` ("reply PONG", 0 tools) | `opus` | yes | **no** | >17 min, never | | 2 | `general-purpose` (read file, count headings) | `opus` | yes | **no** | never | | 3 | `voyage:plan-critic` | `opus` | yes | **no** | never | | 4 | `voyage:scope-guardian` | `opus` | yes | **no** | never | | 5 | `voyage:plan-critic` | *(no override)* | yes | **no** | never | | 6 | `general-purpose`, told to call `SendMessage(to: "main")` | `opus` | yes | **yes** | ~30 s | | 7 | `general-purpose` ("reply PONG", 0 tools) | `opus` | **no** | **yes** | **2.19 s** | | 8 | `voyage:plan-critic` | `opus` | **no** | **yes** — full findings + JSON block | **110.3 s**, 7 tool uses | | 9 | `voyage:scope-guardian` | `opus` | **no** | **yes** — full findings + JSON block | **109.1 s**, 8 tool uses | Denominators, per varied dimension: - **`name` present, no explicit SendMessage: 0/5 returned.** `name` absent: **3/3 returned.** This is the only dimension that moved the outcome. - **`name` present *with* an explicit `SendMessage(to: "main")` instruction: 1/1 returned** (cell 6). This is the positive control for the teammate channel: it is not broken, it is merely never used by tool-less agents. - **Model override: 2/2 non-returning.** Cells 3 (`model: "opus"`) and 5 (no override) are identical in outcome — the override is not the variable, which rules out akashic's stated `model: "opus"` detail as causal. - **Agent type: 2/2 in each arm.** `plan-critic` and `scope-guardian` behave identically named (both silent) and unnamed (both complete). The agent definitions are not the variable. - **Work actually performed while named: 5/5.** All five named agents produced correct, complete final text in their transcripts within ~3 minutes — `PONG`, `8`, plan-critic's blocker list with the correct legacy-format advisory, and scope-guardian's coverage table. Nothing failed except delivery. ### Known-positive discipline (Verifiseringsloven face 4) Two negative results in this investigation were produced by broken queries and would have been consumed as facts: 1. **`ListAgents` returned no in-process subagents** while five were running. It listed 26 peer sessions and none of mine. Probing one directly with `SendMessage` proved the agents existed and had live inboxes. Had the empty listing been believed, the diagnosis would have been "the spawns silently no-op" — wrong. 2. **The first known-positive control failed.** Cell 1 (named PONG) was meant to prove the spawn mechanism works, and it did not return either. A failed control proves nothing; it only means the control shared the defect. The control that discriminates is cell 7 — same prompt, same model, same agent type, `name` removed — which returned in 2.19 s. **Unmeasured cells, stated as unmeasured:** the returning arm was only exercised against the 66-line target. Large targets (voyage's 573-line plan; akashic's 3730-line / 277 KB `features/01-sun-position/plan.md`) were **not** measured in either arm. Nothing here rules out a *separate*, size-dependent failure at akashic's scale — it only establishes that the failure they observed reproduces at 66 lines, where size cannot be the cause. **External measurement closes half of that (2026-08-17).** `akashic-intelligence` recovered its own S25 transcripts from `~/.claude/projects///subagents/` and read the last assistant text block out of each. Denominator: 4 of 4 agents, all **named**, all against the full 3730-line / 277 KB plan. Three produced valid JSON review output (17, 8 and 13 findings); the fourth was their PONG control and produced `PONG`. Their commit `e281a9d`. What that closes: **the work is performed at 3730 lines.** No size-dependent failure of the agent's *reasoning or output* exists at that scale — the named arm produces correct final text at 66 lines and at 3730 lines alike, and only delivery fails, identically at both. The 38 recovered findings were re-used instead of re-run. What it does **not** close: their four cells were all named, so the *returning* (unnamed) arm still has no measurement above 66 lines. That a plain subagent returns a 21 KB result at that scale is inferred, not observed. Stated as inferred. Their PONG control also carries the same lesson as cell 1 above, in a third repo: S25 reported that agent as having "gone idle without sending PONG". It sent PONG. Absence of *delivery* was read as absence of *work* — the same face-4 error, three times in one evening. ## Where the defect lives **Outside this repository.** Nothing in `agents/plan-critic.md` or `agents/scope-guardian.md` is wrong: correct frontmatter, a `tools:` list appropriate to a read-only reviewer, a terminating prompt, and an output format that both agents produced verbatim when spawned as real subagents. The failure is a harness behaviour — a parameter that silently changes a spawn's kind and its return contract, with no error, no warning, and no observable difference at the call site beyond the wording of the tool result. Per the standing rule, this is **not** worked around silently. It is documented here, reported to `.claude` (which owns cross-repo quality and can escalate), and guarded in voyage's own spawn instructions so no consumer re-enters it. ## In-repo fix Every voyage command that spawns agents — `trekbrief`, `trekplan`, `trekresearch`, `trekreview` — now states the rule at its spawn site, naming the mechanism (`in_process_teammate`) so it cannot be mistaken for style preference. `trekexecute` spawns nothing (Hard Rule 10) and is excluded. Pinned by `tests/lib/doc-consistency.test.mjs`: - `S85: the set of agent-spawning commands is exactly the four that carry the no-name rule` — derives the spawning set from the command files themselves, so the pin cannot go vacuous when a command starts or stops spawning. - `S85: commands/.md forbids the Agent tool's name parameter at its spawn sites` — one per command. Verified red before the prose was written, green after. ## Recommended working shape for consumers For anyone running voyage's reviewers (akashic included), grounded in the measurements above rather than in preference: **1. Use agents. Spawn them without `name`.** Cells 8 and 9 are the evidence: both reviewers returned complete, schema-conformant output — human-readable findings *and* the machine-readable JSON block the dedup helper consumes — in ~110 seconds, in parallel, from a single message. This is the intended shape and it works. Removing `name` is the entire fix. **2. Do not switch to inline review as a remedy.** akashic's fallback was rational under their diagnosis but it pays a real, measured price: with one source there is no dedup step, and their own record shows `scope-guardian` finding blockers in the rev 3.0/4.0 rounds that `plan-critic` did not see at all. The two agents are not redundant — cells 8 and 9 here returned largely *different* findings on the same 66-line plan (plan-critic led on placeholder/headless defects; scope-guardian led on the plan already having been executed and its deliverable never being written). Two independent passes with different mandates is the property worth keeping, and unnamed agents deliver it for free. Running two inline passes is the fallback if agents fail *for a different, verified reason* — not for this one. **3. If you deliberately want a named teammate, give it SendMessage and say so.** Cell 6 shows the teammate channel works when used. That means adding `SendMessage` to the agent's `tools:` list *and* instructing it in the prompt to call `SendMessage(to: "main")` with its result. voyage does not do this: its reviewers are read-only by design, and the subagent path already returns. **4. A hard tool-call budget is not the lever here.** akashic tried a tighter budget and it changed nothing, which this measurement explains: a 0-tool-call agent (cell 1) failed exactly like a 7-tool-call one. Budget caps are a cost control, not a liveness control. **5. When an agent looks hung, check its transcript before re-prompting.** The final assistant block in `~/.claude/projects///subagents/agent-*.jsonl` tells you within seconds whether the agent failed or merely could not deliver. Reading that file directly recovers a burned run's output. Extract only the last assistant text block — these transcripts run to 140 KB and reading one whole will flood the orchestrator's context. ## Open - The `--gates`-adjacent "idle-agent gap" already logged as open operator decision #3 in `STATE.md` (`/trekreview` Phase 5, `/trekplan` Phases 5/6/9, `/trekresearch` Phase 4 have no empty-return detection) now has a measured root cause for its most likely trigger. Whether to add active detection — as opposed to the prevention pinned here — remains open and is not decided by this document.