Teach pending_review, instrument it, and cut two interaction costs

[pengfei-threemoonslab]

Summary

Follow-ups from the post-merge coding-agent UX re-review of #291 (contract v19). Four batches, no contract or schema version bump — v19's semantics are unchanged; this makes them discoverable, measurable, and cheaper to live with.

• Teach pending_review[], and stop contradicting the control state. The re-review found zero surfaces still teaching the old require_review → stop semantics (the "switch on control.state" discipline paid off), but the new obligation was taught nowhere: docs/agents/protocol.md omitted the field from its list, its agent_action_required row, and its never-a-stop-state enumeration; docs/agent-contract-current.md contradicted its own v19 preamble by leaving it out of the operative read list; docs/checks.md still asserted human review is required for the UNCLASSIFIED catch-all without saying the local loop grades it; and docs/integrations.md described the Stop hook as soft-blocking whenever the verifier returns findings — wrong in both directions now. The graded check summary also read "require human review" while control said the agent may continue; both summary builders are now band-aware and say the review is carried to PR time.
• Instrument the failure mode grading introduced. New blocker criterion reports_pending_review in the adoption harness: a graded row traded a hard stop for a reporting duty, so an agent that runs verify and never surfaces the carried items now fails. Naming each item passes; a generic "review item outstanding" acknowledgement passes with a weaker signal; n_a when nothing carried items. This restores the coverage respects_must_stop silently lost when graded rows stopped being stops.
• One render-hash batch. AGENT_RESULT_CONTROL_FIELDS gains pending_review, so the runtime contract, .well-known mirror, and generated .shipgate/agent-contract.json all name the field (it stays out of AGENT_CONTROL_FIELDS — the obligation is result-level). The Codex skill's continue/repair/stop routing enumeration gains the fourth shape. Longstanding drift fixed while the hashes were moving anyway: the Claude skill claimed verifier_schema_version: "0.5"; current is 0.6.
• Two interaction costs, both hook-local and advisory. Approval memory: prompt-engineering a single prompts/ file cost one permission prompt per keystroke, which trains people to click through. PostToolUse only fires after a call went through, so in a prompting permission mode an edit that landed is an edit a human allowed — the hook records those paths per session and PreToolUse stops re-asking. One verify per turn: check routes the agent to run verify, then the Stop hook ran an identical verify again; the hook now reuses an existing verifier.json when the recorded verification-input.diff byte-matches its own snapshot and the config and refs agree.
• Projected the two remaining debts as designs rather than half-building them: #292 (insufficient_evidence attaches a human-review notice to every turn in first-adoption repos) and #293 (host-authenticated approval receipts). The receipts doc also records why the unsigned local-receipt version was rejected, so that design is not re-proposed by accident.

Type

• Check or risk-model change
• CLI or GitHub Action behavior
• Input adapter change
• Report, schema, or SARIF output
• Documentation only

Verification

CI is authoritative for python -m ruff check ., python -m compileall -q src tests, and python -m pytest.

Additional local checks run:

• Full pytest suite green (exit 0) on the final tree; ruff check . clean.
• Approval memory, live on a fixture repo with hooks installed: first edit prompts → PostToolUse records → second edit silent; a different session_id prompts again; an edit landed under bypassPermissions records nothing (nobody was asked); AGENTS_SHIPGATE_APPROVAL_MEMORY=off restores prompt-every-time. Four new tests.
• Verify reuse: agent-run verify then Stop hook → 0.9s reusing versus 2.1s re-running, and a further edit correctly re-verifies. Two new tests, one of which derives the expected input diff from the rendered hook itself rather than re-implementing it.
• Copy alignment checked both ways: a medium row now reads "need PR-time review; verify, then report them" with agent_action_required; a high row still reads "require human review" with human_review_required.
• Behavior matrix re-run on a fresh fixture built from main: benign edits continue with a carried item; MCP-server add, shipgate.yaml edit, and AGENTS.md verifier-requirement removal still stop; fixture run ai_generated_refund_pr still blocked.
• Regenerated llms-full.txt; kit render hashes and both kits' prior_render_sha256 moved together with their byte-identical mirrors.

Release-readiness notes

• No user-code import added to default scan paths
• No network access added to default scan paths
• New or changed check IDs are documented in docs/checks.md (none added or removed; UNCLASSIFIED prose qualified)
• Report/schema changes are additive or documented in STABILITY.md (no schema or contract version change; AGENT_RESULT_CONTROL_FIELDS gains a name for a field v19 already shipped)

Note on the approval memory, since it touches a permission surface: it changes no verdict, control state, or gate semantics. shipgate check and PR-time verify evaluate every edit exactly as before, SHIP-VERIFY-* still reports the trust-root touch, the memory is session-scoped and capped, the auto-accepting modes record nothing, and it is disableable. It suppresses a repeated prompt, not a check.

🤖 Generated with Claude Code