fix(hook): tokenized risky-akm-command assessor — eliminate false positives on prose mentions

[itlackey]

Summary

The Claude plugin's PreToolUse Bash hook used regex against the raw bash command string (/\bakm\s+vault\s+(create|set|unset|load)\b/ and similar). That regex fires on any occurrence of the phrase in argv — including commit messages, release notes, and heredoc bodies — because the hook input is the entire concatenated command. The OpenCode plugin, by contrast, already tokenized the command and matched argv positions; it never had false positives.

This PR ports the OpenCode approach into shared/ so both plugins use the same tokenized assessor.

Why this matters

The bug was caught in a real workflow: a gh release create --notes "...the vault-set legacy form is now hardened..." was blocked because the prose mention in the notes body tripped the regex. Hyphenating phrases as a workaround was the only escape hatch. That doesn't scale.

The proof point: even the commit message for this PR (which describes the bug using subcommand phrases verbatim) was initially blocked by the existing hook in the running session. After rephrasing, the commit went through — but the next contributor writing a CHANGELOG line about an akm subcommand would hit the same wall. The fix is structural, not cosmetic.

What changed

File	Change
shared/risky-command.ts	New. splitArguments() quote-aware tokenizer (promoted from opencode/index.ts), assessRiskyAkmCommand() tokenized assessor (covers accept/reject, push-publish, remove, all vault subcommands, gated config keys, mass-update, upgrade, trust-registration), blockedCommandMessage() formatter. Allowlists the documented eval-form vault loader pattern.
claude/shared/risky-command.ts	New re-export shim — matches the existing pattern for claude/shared/{memory-candidates,memory-events,ref-extraction}.ts.
claude/hooks/akm-hook.ts	assessRiskyClaudeCommand now delegates to the shared tokenized assessor. The content-aware akm remember secret scan stays plugin-side (it needs the redactor, not just a command pattern).
opencode/index.ts	Deletes the local assessRiskyAkmCommand, blockedCommandMessage, RiskyCommandAssessment type, and splitArguments. Imports them from the shared module instead. Behaviour unchanged — the OpenCode plugin already did tokenized matching; this just deduplicates.
claude/README.md	New ### Permission and approval policy section documenting the opt-in native permissions.ask block users can paste into ~/.claude/settings.json if they prefer Claude Code's built-in approve/deny dialog over the hook stderr. Notes which checks stay plugin-side because the native matcher can't express them (flag-conditional rules, content-aware secret scanning).

Path tried but not possible: ship default permissions in plugin.json

Confirmed via the claude-code-guide: Claude Code plugins cannot ship default permissions rules. There is no plugin-level mechanism. Users must configure permissions in their own settings.json. README docs are the supported path.

The Bash(pattern:*) matcher is prefix-anchored on the actual bash invocation; it does not match substring occurrences in argv. That is why README-documented native permissions are a viable complement to the hook — once users opt in, they get false-positive-free prompting for the simple prefix-matchable subcommands.

Test plan

• bun test tests/claude-plugin.test.ts — 52 pass / 0 fail
• bun test tests/opencode-plugin.test.ts — 145 pass / 0 fail
• One pre-existing failure in tests/opencode-eval-harness.test.ts confirmed unrelated by running against baseline (fails identically without this branch's changes)
• Live behavior: blocked-message text now includes the formatted reason + approval guidance (existing test for "explicit user approval" phrase still passes)
• Manual smoke after merge: confirm Claude plugin no longer trips on a gh release create --notes containing risky-subcommand phrases in the body
• Manual smoke: confirm a real vault-mutation invocation still blocks as expected

🤖 Generated with Claude Code