fix(gh-cli): fall back to well-known install paths for shim PATH walk (closes #145)

[voidborne-d]

Summary

Closes #145.

The gh-cli plugin's PATH shim (hooks/shims/gh) fails to find the real gh binary when Homebrew forks an attestation verify subprocess under its build-isolation superenv. Homebrew's ensure_executable! resolves gh against ORIGINAL_PATHS, picks our shim (first match), then system_command! forks under the parent's stripped PATH (/opt/homebrew/Library/Homebrew/shims/shared:/usr/bin:/bin:/usr/sbin:/sbin). The shim's PATH walk doesn't include /opt/homebrew/bin, finds nothing, and exits 127.

User impact: brew install / brew reinstall / brew bundle fails for any formula with HOMEBREW_VERIFY_ATTESTATIONS=true set, the moment a Claude Code session is the parent context. Reporter pinned the cause with brew ruby and 6 captured shim invocations.

Fix

Add a fallback after the PATH walk covering the well-known install paths. The Homebrew Cellar opt symlinks (.../opt/gh/bin/gh) are stable across upgrades, the prefix bin entries cover manual installs, and /usr/bin/gh covers system package managers (apt/dnf/pacman):

fallbacks=(
  /opt/homebrew/opt/gh/bin/gh           # macOS Apple Silicon Homebrew
  /opt/homebrew/bin/gh
  /usr/local/opt/gh/bin/gh              # macOS Intel Homebrew
  /usr/local/bin/gh
  /home/linuxbrew/.linuxbrew/opt/gh/bin/gh
  /home/linuxbrew/.linuxbrew/bin/gh
  /usr/bin/gh                           # System package managers
)

GH_SHIM_FALLBACKS (colon-separated) overrides the list — used by tests, also doubles as an escape hatch for non-standard installs.

The anti-pattern checks (api contents deny, non-session-scoped clone deny) still execute before the fallback, so the security/anti-pattern coverage is preserved when gh is reachable only via the fallback list — pinned by two new tests.

The reporter offered two alternatives I deliberately did not take:

• Direct-exec the shim'd binary (exec gh): re-introduces the recursion the shim already guards against; doesn't fix Homebrew's resolution, just shifts the error.
• Detect Homebrew superenv and degrade behavior: brittle (Homebrew's PATH layout varies by version), and the runtime fallback is simpler and works for any PATH-stripping parent (cron, sandbox, etc.), not just Homebrew.

Tests

plugins/gh-cli/hooks/shims/gh-shim.bats — 6 new cases under a new "Homebrew superenv fallback" section, plus an updated exits 127 when real gh not found to neutralize the new fallback list (CI runners often have /usr/bin/gh pre-installed):

1. falls back to GH_SHIM_FALLBACKS when PATH walk finds nothing — the bug-fix pin.
2. prefers PATH-found gh over fallback — regression guard for normal-PATH callers.
3. tries fallbacks in order, skipping non-executable entries — pins ordering and -x check.
4. exits 127 when neither PATH nor fallback have gh — preserves the original failure mode when nothing is reachable.
5. anti-pattern checks fire before fallback (api contents) — pins ordering with deny rules.
6. anti-pattern checks fire before fallback (clone temp path) — same, for the clone deny.

Red-baseline verified: tests #48 (falls back to GH_SHIM_FALLBACKS…) and #50 (tries fallbacks in order…) FAIL on main (stash the source change → run bats), then PASS once the source change is restored.

Local gates

• bats plugins/gh-cli/hooks/shims/gh-shim.bats → 53/53 pass.
• find plugins/gh-cli -name '*.bats' -type f -print0 | xargs -0 bats → 144/144 pass (all gh-cli bats suites).
• shellcheck -x plugins/gh-cli/hooks/shims/gh → clean.
• shfmt -i 2 -ci -d plugins/gh-cli/hooks/shims/gh plugins/gh-cli/hooks/shims/gh-shim.bats → clean.
• python3 .github/scripts/validate_codex_skills.py → 73/74 OK.
• python3 .github/scripts/validate_plugin_metadata.py → all in sync.
• python3 -c 'import json; json.load(...)' on both plugin.json files → valid.
• grep -rPn '(?<![a-zA-Z])(/home/[a-z]|/Users/[A-Z])' plugins/ --include='*.md' --include='*.py' --include='*.json' → no matches (excluded extensions cover the bash file).

Version bump

gh-cli 1.4.1 → 1.4.2 in both plugins/gh-cli/.claude-plugin/plugin.json and the root .claude-plugin/marketplace.json per CONTRIBUTING.md (substantive change to a published plugin).

Reproducer (from issue #145)

macOS 26 Tahoe, Apple Silicon, Homebrew 5.1.5, gh 2.89.0 via Homebrew, gh-cli plugin v1.4.0.
export HOMEBREW_VERIFY_ATTESTATIONS=true
rm -f "$(brew --cache <formula>)"
brew install <formula> from within Claude Code → exit 127 with attestation verification failed.
Reporter confirmed the suggested fix unblocks the install.

Out of scope

• The shim's recursion guard (skipping shim_dir in PATH walk) is unchanged. The fallback paths are absolute and do not include the shim dir, so that guard's invariant still holds.
• Other PATH-stripping parents (cron, restrictive sandboxes) benefit incidentally; if they expose a different gh location, GH_SHIM_FALLBACKS=... is the documented override.

🤖 Generated with Claude Code

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}