Repository navigation
Description
Problem
On two genuine subagent_type: discovery:explorer dispatches (2026-09-28 and 2026-09-29, same machine), the explorer behaved as if it had neither its own agent definition nor the /discovery:explore skill body:
- First run: it returned findings as prose with no YAML payload block at all (no
preload_token,preload:,scope_as_received,artifact:,persistence:), wrote noEXPLORE.md, and said "I skipped the requested skills". A SendMessage resume produced a flat single-fileEXPLORE.mdwith no sidecars, no sidecar headers, no index table, and still no payload. Only on its own after that second return did it rewriteEXPLORE.mdas a proper index with 6 sidecars and return a full payload (preload: fallback). It then claimed "I was not dispatched as discovery:explorer, so the skill body never reached me", which contradicts the parent's actual Agent call. - Recurrence: the explorer wrote a gate-passing index plus 3 sidecars but returned
preload_token: none("my brief carried no preload token") and said it followed the brief by hand without reading the skill. It expected the token to arrive in the dispatch prompt.
Separately, in run 1 the explorer spawned one nested child, received the child's hand-back, and then idled saying it was "waiting on the grid-internals subagent's report" that it already held, until the parent nudged it.
The parent's acceptance gate (check-dispatch-artifact.sh) correctly returned unusable both times, so nothing bad was accepted. The cost was two to three dispatches per exploration and a degraded stage.
Evidence
Verified this pass (origin/main 4ed0fcf5a, discovery 0.25.18):
plugins/discovery/agents/explorer.mdalready makes preload liveness the first action, names the disk fallback (Read ${CLAUDE_PLUGIN_ROOT}/skills/explore/SKILL.md), carries the full YAML return block, and definespreload_token: MISSING+status: truncatedfor the case where no skill content reached the agent ("Preload liveness: the first thing you do", "Return exactly this").- The same text was already present at
423f2ebee(discovery 0.24.5, the cache version the reporter named).git diff 423f2ebee origin/main -- plugins/discovery/agents/explorer.mdshows only small wording changes. So the item's suggestion "make the return contract live in the agent definition" was already true when the failure happened. An agent that had its own definition body in context would have known the payload shape and that the token lives in the skill file. That makes "the agent definition body did not reach the agent, or reached it and was ignored" the first thing to establish, ahead of theskills:preload. - The plugins reference (code.claude.com/docs/en/plugins-reference.md, "Where each variable resolves") states
${CLAUDE_PLUGIN_ROOT}is substituted "anywhere in the Markdown body" of skill, command, and agent content. So the fallback path in the agent body should be a real path; a literal unsubstituted token is not the likely cause here (unlike spoke files, skills: spoke files under context/, reference/ and references/ still carry a literal ${CLAUDE_PLUGIN_ROOT} that the Read tool never substitutes #5273). - The same reference states a plugin from a marketplace added as a local directory is loaded in place and is not pinned by
version. On the reporting machine the melodic marketplace is a directory source, so what ran was the working tree of the localclaude-code-pluginscheckout at the time, not necessarily cache 0.24.5. The exact definition text that ran is unknown. c43a68afa(feat(discovery,implementation,plugin-quality): ship return-contract copies and preload checks #4704, 2026-09-27) addeddiscovery:report(a shared return-contract skill) to the explorer'sskills:list;031e18864(fix(discovery): close the audit findings in research, agents and the parent contract #5301, 2026-09-29) removed it again. Whether either was in the running checkout is unknown.- Prior fix for the preload-miss case: discovery/explorer: a dispatched explorer has no disk fallback on a preload miss and its payload carries no preload provenance #4074 (closed), which added the disk fallback and
preload:provenance. Write-early and turn reserve: fix(discovery): agents write early, reserve their last turns, and mark the primary source #4501. - No text on main addresses consuming a nested child's hand-back:
git grep -i "handback\|hand-back\|waiting on"overagents/explorer.md,reference/parent-contract.md, andskills/explore/finds nothing relevant. - Issue search (
explorer preload,nested child handback) finds only closed discovery/explorer: a dispatched explorer has no disk fallback on a preload miss and its payload carries no preload provenance #4074, fix(discovery): explorer dispatch accepts an empty payload as a completed exploration #1986, fix(discovery): no echo-back of the received scope/topic, so a corrupted input passes every gate #2205, fix(discovery): three acceptance-gate obligations have no mechanism, and the gate scripts carry no grant #2267, docs(discovery): the $ARGUMENTS-on-preload claim is unsupported at five sites, and three files state three different write boundaries #2270. No open issue covers this.
Not verified (reported by a work-domain session; its transcripts are not reachable from this domain): the two runs' exact dispatch prompts, the debug log, and which files the agent read.
Proposed approach
- Reproduce on a directory-source marketplace with a named
discovery:explorerdispatch and amodel:override, with debug logging on. Record: (a) whether the agent's system prompt contains the explorer definition body, (b) whether theskills:preload resolved or logged a skip warning, (c) whether the agent ReadSKILL.mdbefore its first exploration call. Also run once without themodel:override and once withoutname:, to separate those variables. - Branch on the result:
- Definition body missing: that is a harness or resolution defect. Record it as a dated harness fact in
reference/parent-contract.md"Harness facts the dispatch design rests on", and make the parent detect it (for example, the parent includes a one-line "your first action is preload liveness; return the YAML block in agents/explorer.md" reminder in the envelope, since the envelope is the one channel that did arrive). - Definition present but ignored: move the liveness check and the return-block skeleton to the very top of the body, and add an eval where the preload is absent that asserts
preload: fallbackorpreload_token: MISSINGon the first return.
- Definition body missing: that is a harness or resolution defect. Record it as a dated harness fact in
- Nested-child hand-back: add one rule to
agents/explorer.md(near "You are already the fresh pair of eyes") that a child's delivered hand-back is its final report, and the explorer proceeds instead of waiting.
Alternatives considered: adding more contract text to the agent body (rejected until step 1 shows the body loads; the text was already there); raising maxTurns (not the failure shape here).
Files: plugins/discovery/agents/explorer.md, plugins/discovery/reference/parent-contract.md, plugins/discovery/skills/explore/reference/dispatch.md (if the parent envelope changes), plugins/discovery/skills/explore/evals/evals.json.
Acceptance criteria
- A reproduction record states, for a directory-source dispatch, whether the explorer definition body and the
skills:preload each reached the agent, with the harness version. - The fix matches the branch that record supports, and the record is cited in
reference/parent-contract.mdwith a recheck trigger. - An eval covers a dispatch where the skill body is absent and asserts the first return carries the YAML block with
preload: fallbackorpreload_token: MISSING, never bare prose. -
agents/explorer.mdstates that a nested child's delivered hand-back is final, and an eval or test covers it. - discovery version bumped with a CHANGELOG entry.
Constraints and gotchas
- The parent's gate (
check-dispatch-artifact.sh) worked; do not weaken it. - Directory-source marketplaces load in place and ignore
version, so any reproduction must record the checkout's commit, not the plugin version. - Do not reintroduce a second copy of the return contract that can drift from
agents/explorer.md; fix(discovery): close the audit findings in research, agents and the parent contract #5301 removed thediscovery:reportpreload from this agent. - A related report from the same machine (gate scripts under a directory-source plugin root blocked for a work-domain session by a machine-local guard) is user-scope configuration and is out of scope here.
Context
Source: local handoff item 20260928-175500-discovery-explorer-no-payload-block-no-sidecars.md (retired into this issue). Related: #4074 (preload fallback, closed), #4501 (write early, reserve turns), #4704, #5301, #5273 (literal ${CLAUDE_PLUGIN_ROOT} in spoke files).
Activity
kyle-sexton commentedon Oct 1, 2026
Owner decision (2026-10-01): approved the recommendation ("go with recommended", the owner's reply to the batch decision page that listed this question and its recommendation).
Question: how to handle the explorer that dropped its YAML return block and idled on a nested child's report it already held.
Chosen option A: an agent works the whole issue in a fresh worktree. It runs the step-1 reproduction on the directory-source marketplace (named dispatch with
model:, withoutmodel:, withoutname:, debug logging, recording checkout commit and harness version), applies the step-2 fix the result supports, adds the nested-child hand-back rule toagents/explorer.md, adds evals, bumps discovery with a CHANGELOG entry, and opens a draft PR that closes this issue. It does not weakencheck-dispatch-artifact.shand does not add a second copy of the return contract.Next: labels switch to
agent-ready; an agent picks it up.docs(discovery): tell the explorer a delivered child hand-back is final
fix(discovery): record the explorer dispatch reproduction and add the…
test(discovery): grade the scout caller read in the trace, not the EX…
test(discovery): drop the nested-trace Read grader from the hand-back…
docs(discovery): drop the removed caller grader from the eval changel…
test(discovery): add a plugin eval for the explorer's nested hand-bac…
kyle-sexton commentedon Oct 1, 2026
Owner decision (2026-10-01): accepted the recommendation ("accept all recommendations" and "I want you to do all of this for me", the owner's reply to the list that named this item).
Criterion 3 is waived: the absent-preload explorer dispatch cannot be built with the documented
claude plugin evalkeys (casepluginsresolve to real plugin dirs;scaffold_scriptsupplies files and git state only). #5687 (reproduction record, nested hand-back rule, parent-skill evals) and #5720 (plugin-level eval for criterion 4) cover the rest.