feat(cascade-tools): spec 014 — agent ergonomics (truthful prompts, structured envelope, --comment alias)

[zbigniewsobiecki]

Summary

• Root cause fix for prod run 5d993b04-6e05-4ae1-b7de-8c274cf3496b where a review agent wasted ~2½ min of a 7m42s run fighting cascade-tools scm create-pr-review and ultimately dropped an inline PR comment. The agent-facing system prompt literally told it to use --comment <string> (repeatable) when reality is --comments '<json array>'; error messages and --help gave nothing to self-correct from.
• Shared-infra fix (plan 1): prompt renderer stops s-stripping array names and stops claiming "<string> (repeatable)" for every array; array-of-object params now render --<flag> '<json>' with aliases via | and a one-line runnable example inlined from the tool definition. Every CLI failure — flag parse, JSON parse, missing-required, enum-mismatch, unknown-flag, auth, runtime — emits a single structured envelope on stdout ({success:false, error:{type, flag?, message, got?, expected?, hint?, example?}}) plus a readable prose summary on stderr. Mistyped flags get a "did you mean" suggestion via fastest-levenshtein. --help renders def.examples as copy-pasteable invocations under an EXAMPLES section.
• Per-gadget opt-in (plan 2): createPRReviewDef gains cliAliases: ['comment'] + fileInputAlternatives for --comments-file <path> (and - for stdin). Two declarative fields. Zero edits to shared infrastructure — proves the single-entrypoint invariant that a new gadget should never need to touch shared machinery.
• Authoring guide lives at src/gadgets/README.md (new). Full spec at docs/specs/014-cascade-tools-agent-ergonomics.md.done.

Highlights

Before: agent system prompt declared [--comment <string> (repeatable)]. Agent sent --comment (singular). Got Nonexistent flag: comment. Tried --comments + single-quoted-keys JSON. Got --comments must be valid JSON. Reverse-engineered source. Gave up. Posted body-only review. 2½ min lost.

After: agent prompt declares [--comments|--comment '<json>'] with an example line showing --comments '[{"path":"src/x.ts","line":1,"body":"nit"}]'. If the agent still mistypes, the envelope hint says did you mean --comments?. If JSON is malformed, the envelope surfaces got: "[{'path'...", expected: "[{\"path\":...}]", hint: "Use double-quoted JSON keys... or pass --comments-file <path>". Self-correction is one retry away.

Test plan

• npm run build — clean
• npm run lint — clean (biome)
• npm run typecheck — clean
• npm test — 8440 passing, 0 failing, 23 skipped (458 files)
• 57 new unit tests across errorEnvelope.test.ts, shared-nativeToolPrompts.test.ts, factories.test.ts, definitions.test.ts
• 7 legacy pre-014 test assertions updated in-place (prose this.error() / flat envelope / s-stripped array names)
• [manual] 6 binary-level scenarios run against ./bin/cascade-tools.js after npm run build:
  1. canonical --comments '[...]' → exit 1, type:"runtime" (parse succeeded)
  2. --comment '[...]' alias → exit 1, type:"runtime" (alias resolved)
  3. --comment "[{'path':..}]" (single-quoted JSON) → exit 1, type:"json-parse", flag:"comments", hint mentions --comments-file
  4. --comments-file /tmp/x.json → exit 1, type:"runtime" (file parsed)
  5. --comments-file - (stdin) → exit 1, type:"runtime" (stdin parsed)
  6. --help → exit 0, contains EXAMPLES + "path":"src/utils.ts"
• [manual] stderr prose readable: runtime — No GitHub client in scope... (123 chars, single line, no ANSI, no Node stack dump)

Notes

• vitest fork-pool workers deterministically fail to capture stdout/stderr from spawned binaries that do top-level await import() — reproduced with spawn/execa/sh -c/execSync, exit 2 with zero output. Unit tests cover every code path at the Command class level; the binary-level scenarios are documented as a manual-verification protocol in plan 2. Chasing the vitest/tinypool root cause is a separate concern and out of scope here.
• This PR closes out spec 014. Both plans .done; spec .done. CLAUDE.md untouched (audit clean).

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 87.46269% with 42 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/gadgets/shared/cliCommandFactory.ts	87.05%	29 Missing and 4 partials ⚠️
src/gadgets/shared/errorEnvelope.ts	81.48%	5 Missing ⚠️
src/backends/shared/nativeToolPrompts.ts	77.77%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!