enh(plan-checker): let gsd-plan-checker write its stall-watch return receipt on hosts that run it read-only (#767 Group B) #5245

GSD Version

1.16.0 (next @ 663acba1f)

Follow-up for Finding 3 of the #5192 review (the fix for #5182), filed as the contributor proposed there. The maintainer has not yet ruled on "Group B in #5192" versus "follow-up issue"; this issue is the follow-up option, and it needs its own approved-enhancement before code.

User impact

On a host that runs gsd-plan-checker read-only, such as Codex, a plan-phase run that has stall detection on can wait out the full stall threshold after a checker pass and then report the checker as stalled, even though it finished. That happens unless the runtime's own completion result reaches the orchestrator first, which #5192 also accepts. This is inferred from the sandbox derivation and has not been measured on Codex. With this change, the checker's return ends the wait on every host, the same as it already does for the planner.

Pre-submission checklist

• I have confirmed this improves existing behavior — it does not add a new command, workflow, or concept
• I have searched existing issues and this enhancement has not already been proposed
• I have read CONTRIBUTING.md and understand I must wait for approved-enhancement before writing any code
• I can clearly describe the concrete benefit — not just "it would be nicer"

What existing feature or behavior does this improve?

The plan-phase stall watch for the plan checker (step 10), after #5192. #5192 has every spawned agent end with a one-line return receipt that GSD owns, and the watch reads that receipt instead of the host's transcript. The planner writes its receipt with Write. The checker has no Write, so it writes the receipt through Bash (printf).

Current behavior

gsd-plan-checker is in #767's Group A, the pure read-only agents: tools: Read, Bash, Glob, Grep, Skill, and READONLY_AGENT_DISALLOWED_TOOLS denies Write, Edit, MultiEdit (src/runtime-artifact-conversion.cts:3930-3938). Codex derives sandbox_mode from tools:: workspace-write iff Write or Edit is declared, otherwise read-only (src/codex-agent-toml.cts:694-745; CODEX_SANDBOX_HOLDS at :492 is empty, so nothing else widens it). So on Codex the checker's sandbox refuses the receipt write. A checker that passes also touches no *-PLAN.md, so the watch sees no progress either and ends stalled at the threshold.

#5192 states this as a known limit. It is no worse than next on hosts that have no output file, where the checker watch can only end stalled. On Claude Code, next read the host transcript and ended at its first check, because the transcript quotes the markers (the #5182 defect itself). It is the one host and agent pair where #5182's AC5 ("identical on every host") does not hold.

Proposed behavior

Move gsd-plan-checker to #767's Group B, the report-writers: add Write to its tools:, and change its READONLY_AGENT_DISALLOWED_TOOLS entry to Edit, MultiEdit. That is how gsd-verifier, gsd-doc-verifier, gsd-eval-auditor and gsd-ui-auditor are configured. The checker then writes its receipt on every host, and its agent definition states that the receipt is its only write.

Reason and benefit

• AC5 of bug(plan-phase): the stall watch never observes real completion: it matches markers in the agent's own prompt and definition, and a revision can only end as stalled #5182 holds for the checker as well. Today, on a host that runs it read-only, a finished checker costs the user the whole stall threshold and a misleading "stalled" prompt.
• The change uses an existing, reviewed posture (Group B) rather than a new mechanism.

Scope of changes

• agents/gsd-plan-checker.md: tools: gains Write. Its receipt rule moves from Bash printf to Write, and states that this is the agent's only write.
• src/runtime-artifact-conversion.cts: the gsd-plan-checker entry changes from Write, Edit, MultiEdit to Edit, MultiEdit.
• Tests: the installed Codex agent TOML has sandbox_mode = "workspace-write" for the checker; the Claude disallowedTools value; the stall watch ends marker_received for a checker on a host with only Write. Tests that pin the old value: tests/codex-config.test.cjs:1029, :1134 and :1970-1975 (the last compares the pre-enhance(#3473): §8.3 rungs 2-4 — runtime marker, Codex sandbox contract, shortFormToId #3897 baseline map with the live derivation, so it needs a rewrite, not a value change), tests/install.test.cjs:1695, tests/agent-descriptor-parity.install.test.cjs:509.
• Lands after fix(#5182): watch a GSD-owned return receipt instead of the host transcript in the plan-phase stall watch #5192.

Breaking changes

None for users. The security posture is the open point. On Codex, workspace-write lets the checker write anywhere in the workspace, not only its receipt file. On Claude Code, disallowedTools stops denying Write; it still denies Edit and MultiEdit. That widening is the reason this is a separate decision rather than part of the bug fix.

Alternatives considered

• Keep Group A and accept the limit. Leaves AC5 unmet for the checker on read-only hosts. This is the state fix(#5182): watch a GSD-owned return receipt instead of the host transcript in the plan-phase stall watch #5192 ships.
• Fold the move into fix(#5182): watch a GSD-owned return receipt instead of the host transcript in the plan-phase stall watch #5192. Declined in fix(#5182): watch a GSD-owned return receipt instead of the host transcript in the plan-phase stall watch #5192: a security-posture change should not ride on a bug fix.
• Let the watch use the host's completion result as the only signal on read-only hosts. fix(#5182): watch a GSD-owned return receipt instead of the host transcript in the plan-phase stall watch #5192 already ends the wait when the runtime's completion result arrives first. This option would drop the receipt for the checker on those hosts, but a per-host special case is what the receipt was introduced to avoid.

Area affected

Agents (gsd-plan-checker tool grants); plan-phase stall detection

Additional context

• bug(plan-phase): the stall watch never observes real completion: it matches markers in the agent's own prompt and definition, and a revision can only end as stalled #5182 (bug), fix(#5182): watch a GSD-owned return receipt instead of the host transcript in the plan-phase stall watch #5192 (fix PR, Finding 3 of review 5436473886), enh(agents): add disallowedTools to read-only verifier/auditor agents (Claude Code) #767 (Group A/B, closed).
• Governing: enh(agents): add disallowedTools to read-only verifier/auditor agents (Claude Code) #767's Group A/B split, src/codex-agent-toml.cts:694-745 (the single owner of sandbox_mode derivation).

Generated by AI during contribution; reviewed and posted by a human maintainer (@davesienkowski).