examples: add pkgxray-guard supply-chain hook

[adamsjack711-ux]

Summary

Adds examples/pkgxray-guard/ — a hook that runs pkgxray supply-chain triage on any package an AI coding agent tries to install, before it runs, and denies the command on a BLOCK verdict with pkgxray's cited evidence returned to the agent. hookshot supplies the cross-agent hook surface (Claude Code, Cursor, Windsurf Cascade, Factory Droid, OpenAI Codex); pkgxray supplies the detection engine.

agent runs:  npm install left-pad evil-pkg@1.2.3
                       │  OnBeforeExecution (hookshot)
                       ▼  pkgxray guard npm:evil-pkg@1.2.3 --format json
             BLOCK → DenyExecution("pkgxray blocked …: [credential-access] …")

What's included

• main.go — registers OnBeforeExecution (guard installs, worst-verdict-wins across a multi-package command) and an opt-in OnAfterFileEdit lockfile re-audit. Env config: PKGXRAY_BIN, PKGXRAY_HOOK_POLICY, PKGXRAY_HOOK_DISABLE, PKGXRAY_HOOK_AUDIT_LOCKFILES, PKGXRAY_GUARD_ARGS.
• pkgxrayguard/ — pure, stdlib-only core:
  • parse.go — shell command → package refs; handles npm/pnpm/yarn/bun install|i|add, npx/bunx/pnpm dlx runners, and claude mcp add … -- <launcher>. Conservative: unrecognized shapes and local/VCS installs are allowed through, not wrongly blocked.
  • guard.go — runs pkgxray guard <ref> --format json, maps the decision, and falls back to the process exit code (2=block/3=review/0=safe) if the JSON is unparsable, so a truncated payload still fails in the right direction.
  • policy.go — strict/balanced/permissive. Default balanced denies BLOCK, asks on REVIEW, and denies UNKNOWN so a missing/broken pkgxray fails closed.
  • Offline table tests + fake-pkgxray exec tests (no network, no real binary).
• configs/ — drop-in hook configs for Claude Code, Cursor, and Codex.
• README.md — install, config, policy matrix, layout, limits.

Design notes

• No separate go.mod — the example is part of the root module (like examples/multi-hook), so go build ./... / go test ./... build and test it in the existing go.yml CI. Every hookshot symbol and handler signature used was checked against unified.go.
• No new third-party dependencies; the pkgxrayguard core is stdlib-only and tests offline.
• Only registry installs are triaged; local/VCS installs are out of scope. Defense-in-depth, not a sandbox. pkgxray guard reaches the network (registry/OSV/GitHub); budget ~1s/package, tunable via PKGXRAY_GUARD_ARGS.

Verification

Built and tested green via go build ./... / go test ./... (the offline pkgxrayguard tests included) on my fork's CI before opening this PR.

🤖 Generated with Claude Code

[adamsjack711-ux]

For context on the other side of this integration: the pkgxray repo carries the companion reference copy of this hook plus a reusable lockfile-audit GitHub workflow — adamsjack711-ux/pkgxray#13 (merged).

• pkgxray (the detection engine this hook shells out to): https://github.com/adamsjack711-ux/pkgxray
• pkgxray guard <ref> --format json is the only interface the hook depends on, so the two can evolve independently.