feat: skills pinning — supply chain & update drift defense (AST 02 + AST 07)

[Xaik89]

Summary

• Extends the existing MCP tool pinning primitive (PR feat: MCP tool pinning — rug pull defense #81 / v1.5.0) to agent skill files — ~/.claude/skills/, ~/.claude/CLAUDE.md, ~/.claude/rules/, project .claude/CLAUDE.md, .claude/CLAUDE.local.md, .claude/rules/, .cursor/rules/, AGENTS.md, CLAUDE.md. On the first tool call of a session the hook records SHA-256 hashes of every skill file; subsequent sessions re-hash and compare. Any drift quarantines the session and blocks every tool call until a human reviews with node9 skill pin update <rootKey>.
• One feature, two threats covered: AST 02 Supply Chain Compromise and AST 07 Update Drift.
• Moat: first/only runtime defense at the skills layer — competitors (Keycard / Microsoft AGT / Invariant) have no equivalent today.
• Slim by design: ~1,150 LOC total. Mirrors src/mcp-pin.ts 1:1; no new dependencies.

(Re-opened from personal fork; supersedes closed #88.)

What's new

• src/skill-pin.ts (~300 lines) — SHA-256 content hashing (files or recursive directories, symlink-safe, 5000 files / 50 MB caps), atomic writes to ~/.node9/skill-pins.json (mode 0o600), per-root exists flag so "appeared" and "vanished" both count as drift, batched verifyAndPinRoots().
• src/cli/commands/skill-pin.ts (~100 lines) — node9 skill pin list | update <rootKey> | reset, mirroring node9 mcp pin. update removes the named pin so the next session re-pins; reset clears all pins and wipes session verification flags.
• Hook integration in src/cli/commands/check.ts (+117 lines) — first tool call of a session verifies; result memoised in ~/.node9/skill-sessions/<session_id>.json so hashing runs once per session, not per tool call. Session IDs restricted to /^[A-Za-z0-9_-]{1,128}$/ to defeat path traversal. Corrupt pin file → fail-closed. Unexpected errors → fail-open (debug-logged) so a bug here cannot brick Claude Code.
• policy.skillRoots: string[] config field — user-extensible list of extra skill paths.

Security properties

• Fail-closed on corrupt skill-pins.json (recovery: node9 skill pin reset)
• Symlink-safe (lstat + explicit isSymbolicLink(); never follows out of the tree)
• Size-bounded (5000 files / 50 MB per root)
• Path-traversal-safe session IDs
• Atomic writes, mode 0o600

Test plan

• 30 new tests across 4 files — all pass:
  • skill-pin.unit.test.ts (16): hash contract, order-invariance, add/remove/modify sensitivity, symlink skip, pin round-trip, exists-flip detection, mode 0o600, fail-closed
  • skill-pin-cli.integration.test.ts (6, spawnSync): list empty/populated/corrupt, update unknown/known, reset clears + wipes session flags
  • check-skill-pin.integration.test.ts (4, spawnSync): first-call pins + allows, new-session drift blocks with JSON-RPC payload + quarantines, corrupt fails closed, missing session_id skips
  • skill-roots-config.spec.ts (4): default empty, merge, dedup, defensive filter
• Full suite: npm test → 1170 / 1171 pass (the one failure is a pre-existing environmental flake in hud.spec.ts — fails whenever ~/.claude/CLAUDE.md exists on the test machine; passes under isolated HOME)
• npm run typecheck, npm run lint, npm run format:check, npm run build — all clean

End-to-end verified against a realistic scenario

Simulated a developer's real setup (global ~/.claude/CLAUDE.md + skill, project CLAUDE.md + .cursor/rules/) across two days of Claude Code sessions:

1. Monday 9am, fresh session → exit 0, 9 roots pinned, verified flag written with mode 0o600 ✅
2. Same session, subsequent calls → short-circuit via verified flag (~150ms incl. Node startup) ✅
3. Overnight, attacker rewrites my-project/CLAUDE.md with a prompt-injection backdoor
4. Tuesday 9am, new session → exit 2, JSON decision: "block", reason names the exact node9 skill pin update b73aad6c0b08ef42 recovery command, session flag persists as {state: "quarantined", detail: "changed: .../my-project/CLAUDE.md"} ✅
5. Developer restores file + runs skill pin update <key> → fresh session allows again ✅
6. skill pin reset → clears all pins + wipes skill-sessions/ ✅

🤖 Generated with Claude Code

[node9ai]

Really solid engineering on this — the security properties (symlink-safe, atomic writes, path-traversal-safe session IDs, fail-closed on corrupt state, session memoization) are all correct, and the test coverage is thorough. You clearly read the MCP pinning code carefully and mirrored the pattern well.

That said, I'm going to close this for now because of a fundamental design issue that I don't think can be fixed with small tweaks.

The quarantine-on-change model doesn't fit skill files.

MCP tool pinning works because you didn't write those tool definitions — a third-party server did. When they change without your knowledge, that's suspicious by definition. Skill files are different: ~/.claude/CLAUDE.md, roject/.claude/CLAUDE.md, .claude/rules/ are files you edit constantly as part of normal workflow. The feature as designed would quarantine your next Claude Code session every time you update your own CLAUDE.md. That trains users to either disable it or treat every alert as noise — which defeats the
purpose entirely.

The threat model is also narrower than it looks. The realistic attack here is a compromised package or CI script silently modifying your CLAUDE.md. That's a real threat, but it's rare. The false positive rate (you edited your own file) would overwhelm real signals in practice.

What I'd want to see instead:

• enabled: false by default — opt-in only, for users who specifically want this
• A notification/review model rather than hard quarantine — show a warning and let the user decide, don't block all tool calls
• Targets dev, not main

If you want to rework it along those lines, I'd be happy to look at a v2. The core hashing and session memoization logic is genuinely good work and worth reusing.

Help me with could agent see this
https://github.com/node9-ai/node9-pr-agent