quality-gate slash invocation dies silently in headless sessions when its gh preflight is denied

[kyle-sexton]

Found during V1 pilot fixture probes (not introduced by that branch).

claude -p "/review:quality-gate …" in a non-interactive session produces empty output, exit 0: the skill's pre-computed context line runs gh pr list, the permission is denied headlessly, and the slash invocation dies without any model output. Prose invocation ("use the quality-gate skill…") degrades gracefully instead.

Candidate fixes: guard the preflight (gh … || echo unknown already exists — investigate why denial still kills the invocation), or drop gh from pre-computed context, or document allowed-tools frontmatter for the preflight.

🤖 Generated with Claude Code

[kyle-sexton]

This was generated by AI during triage.

T2 triage planning note

Confidence: HIGH — root cause identified from official docs + two in-repo precedents + the marketplace's own permission-rule-hygiene convention. Fix is additive and low-risk. (Honest caveat: grounded in documentation and precedent, not a live headless -p repro — this does not block; the fix holds regardless of whether a denied preflight aborts the invocation or substitutes a placeholder.)

Root cause

plugins/review/skills/quality-gate/SKILL.md has a Pre-computed context block using dynamic-context injection (the !`<command>` syntax). Line 13 runs:

Open PRs (...): !`gh pr list --json number,title,headRefName,baseRefName --limit 10 2>/dev/null || echo "unknown"`

The skill declares no allowed-tools frontmatter. Per the skills docs, each !`<command>` is preprocessing that runs before the model turn — "Each !`<command>` executes immediately (before Claude sees anything) … This is preprocessing, not something Claude executes." The permission gate therefore sits above the shell, during prompt expansion.

This is why candidate fix #1 cannot work. The existing || echo "unknown" guard lives inside the shell command string. When the permission system denies the gh preflight in a headless session, the shell is never invoked, so the || fallback can never fire — the denial happens a layer above the shell. An in-command guard is structurally incapable of catching a permission denial. (The reported "empty output, exit 0" is the observed downstream symptom of that denial during preprocessing; the fix does not depend on the exact abort-vs-placeholder behavior.)

Prose invocation ("use the quality-gate skill…") degrades gracefully because there is no dynamic-context preprocessing — the model reads the skill and issues gh as a normal Bash tool call, and a denial there returns a tool result the model handles, rather than aborting prompt expansion.

Why git branch / git status on the sibling lines don't also kill it

Not verified live; most likely those read-only git commands are on Claude Code's built-in read-only allowlist while gh is not. The fix below authorizes all three lines for completeness regardless, so the entire pre-computed block is deterministically permitted headlessly.

The canonical pattern this skill is missing

The official docs' own dynamic-context example pairs !`gh pr diff` with allowed-tools: Bash(gh *) in the same skill — declaring the preflight in frontmatter is the documented mechanism to authorize dynamic-context bash. Narrow allow rules carry over into auto mode (per docs/conventions/permission-rule-hygiene/README.md, citing permission-modes).

Two in-repo precedents already do exactly this:

• plugins/planning/skills/wayfind/SKILL.md — dynamic-context !`gh api user` / !`gh issue list` with allowed-tools: ["Bash(gh api user*)", "Bash(gh issue list*)", ...].
• plugins/prototype/skills/pressure-test/SKILL.md — allowed-tools: ["Bash(git branch:*)", "Bash(git status:*)", "Bash(head:*)", "Bash(echo:*)", ...], listing head and echo precisely because its pre-computed lines use | head and || echo.

Recommended fix — candidate #3 (declare allowed-tools)

Chosen over the alternatives with justification:

• chore: initialize marketplace scaffold #1 (better in-command guard) — rejected: structurally impossible (see root cause). The || cannot run when the shell is never invoked.
• fix: correct plugin-system inaccuracies and harden references #2 (drop gh from pre-computed context) — rejected as the primary fix: it discards the pre-computed PR list (used by pr/self/slice modes and the diff-base resolution in Shared inputs), degrading the feature to avoid a denial that feat: markdown-formatter plugin (pilot migration) #3 prevents outright. Kept as the noted fallback for the one config feat: markdown-formatter plugin (pilot migration) #3 cannot cover (below).
• feat: markdown-formatter plugin (pilot migration) #3 (declare allowed-tools) — chosen: matches the documented canonical pattern and two in-repo precedents, preserves the pre-computed context, and is a purely additive frontmatter change with no behavioral risk.

Exact change — add allowed-tools to the frontmatter of plugins/review/skills/quality-gate/SKILL.md (between the existing frontmatter keys, before the closing ---):

allowed-tools: ["Bash(git branch:*)", "Bash(git status:*)", "Bash(head:*)", "Bash(echo:*)", "Bash(gh pr list:*)"]

All five entries are load-bearing — do not trim to just the gh rule. Claude Code evaluates each segment of a compound command against the rules independently. The three pre-computed lines are compound:

• git branch --show-current … || echo "unknown" → needs Bash(git branch:*) + Bash(echo:*)
• git status --porcelain … | head -20 || echo "unavailable" → needs Bash(git status:*) + Bash(head:*) + Bash(echo:*)
• gh pr list --json … --limit 10 … || echo "unknown" → needs Bash(gh pr list:*) + Bash(echo:*)

If only Bash(gh pr list:*) is added, the echo segment remains unauthorized and the line can still be denied — the fix stays broken. This mirrors pressure-test exactly.

Notes for the implementer:

• Use the :* colon form (matches pressure-test and the permissions wildcard syntax); wayfind uses the older bare-* form — prefer :*.
• Keep the existing || echo … fallbacks. They cover a different failure mode — gh missing / unauthenticated / no PRs — that allowed-tools does not touch.
• These are narrow, read-only, non-interpreter gh/git subcommand rules, so they are not the interpreter-wildcard anti-pattern flagged by docs/conventions/permission-rule-hygiene/README.md; they carry over into auto mode like Bash(npm test).

Residual limitation (scope-honest)

allowed-tools fixes the reported scenario (default headless -p) and ordinary auto mode. It does not cover a session with autoMode.classifyAllShell: true, which suspends even narrow shell allow rules (per the hygiene doc). In that specific config, only candidate #2 (dropping gh from pre-computed context) avoids the denial — at the cost of the pre-computed PR list. This is a known, narrow edge, not a reason to prefer #2 as the default.

Deferred follow-up (do NOT expand this fix)

Sibling skills with dynamic-context !`gh` / !`git` commands but no matching allowed-tools may share this latent silent-death bug. Suggested trigger for a separate item: grep skills for !` dynamic-context commands lacking corresponding allow rules, and consider extending the claude-config:audit-permission-grants skill to flag dynamic-context commands whose segments aren't covered by frontmatter allowed-tools. Keep the current fix quality-gate-only.