chore(repo): resolve subagent narration + tool-registration failures#55
Merged
Conversation
Two related fixes that unblock plan-execution-housekeeper and
plan-execution-contract-author dispatches.
YAML registration: Claude Code's session-start parser handled
`tools: ["Read", ...]` flow-form inconsistently — same byte format
parsed as a real array for some agents, as a literal string for these
two, leaving zero tools registered ("No such tool available"). Switch
to block-list YAML form so the parser registers the tool array
reliably.
Narration anti-pattern: agent bodies contained literal `Tool: <Name>`
strings in failure-mode warnings and "do not output X" sections.
Opus 4.7's literal instruction following caused the model to emit
those tokens as text content instead of invoking the tool API
(totalToolUseCount: 0 across PR #36 / #42 / #45 / #51 dispatches).
Replace with positive-only action contracts; let the orchestrator's
existing validator (check #13, narration_mode_detected) and
auto-deviation fallback handle the defense-in-depth.
Housekeeper cleanup: consolidate duplicate `## First action (mandatory)`
into `## Manifest contents` so each heading has a single, distinct
purpose.
Validation: post-restart smoke tests exercise both agents end-to-end
(housekeeper edits target.md + writes manifest preserving _script_stage;
contract-author writes a Zod schema file). All 393 plan-execution skill
tests pass (including the buildHousekeeperPrompt snapshot test that
pins the orchestrator's runtime brief), all 411 package tests pass,
typecheck and lint clean.
Builds on the guardrails landed in #53.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
tools: ["Read", ...]flow-form inconsistently — same byte format parsed as a real array for some agents (plan-execution-implementer,plan-execution-spec-reviewer) but as a literal string forplan-execution-housekeeperandplan-execution-contract-author, leaving zero tools registered (No such tool availableon every Read/Edit/Write). Switched to block-list YAML form so the parser registers the array reliably.`Tool: <Name>\n{...}`strings in failure-mode warnings and "do not output X" sections. Opus 4.7's literal instruction following caused the model to emit those tokens as text content instead of invoking the tool API —totalToolUseCount: 0across the PR feat(control-plane): compose pg.Pool-backed Querier (Plan-001 T5.5) #36 / feat(sidecar-rust-pty): bootstrap crate + protocol + framing (Plan-024 P1) #42 / feat(contracts): add PtyHost interface (Plan-024 T-024-2-1) #45 / feat(daemon): NodePtyHost + PtyHostSelector (Plan-024 Phase 2) #51 dispatches. Replaced negative-example warnings with positive-only action contracts; defense-in-depth from the orchestrator's existing validator (narration_mode_detectedgap, check docs(repo): resolve Tier 1-3 plan governance audit findings #13) and auto-deviation fallback is preserved.## First action (mandatory)into## Manifest contentsso each heading has a single, distinct purpose (the "first action is Read" rule lives in## Action contractalone now).Builds on the guardrails landed in #53.
Test plan
_script_stage; contract-author wrote a Zod schema file)buildHousekeeperPromptsnapshot test that pins the orchestrator's runtime brief)pnpm typecheck8/8 successful,pnpm lint5/5 cleanfeedback_subagent_authoring_pitfallsdocumenting both rules + the unknown-root-cause caveat for the YAML parser🤖 Generated with Claude Code