Security Guidance Plugin Before Merge

TL;DR

The official security-guidance plugin adds PreToolUse and stop-time hooks that warn when Claude edits files matching risky patterns—command injection, XSS, eval, dangerous HTML, pickle usage, and similar signals. Enable it before merge review, treat warnings as blockers until a human resolves them, and pair hooks with normal PR checks—not as the only security control.

Prerequisites & Requirements

• {"task": "Plugin installed", "description": "security-guidance is available in project or user plugin settings"}
• {"task": "Hooks enabled", "description": "PreToolUse matchers cover Edit, Write, MultiEdit, and NotebookEdit tools"}
• {"task": "Review owner", "description": "A maintainer triages hook warnings before merging PRs"}
• {"task": "Python runtime", "description": "Hook scripts can invoke Python via the plugin bootstrap shell helpers"}
• {"task": "CI complement", "description": "SAST, dependency, and secret scanning still run in CI"}

Core Concepts Explained

Pattern warnings on edit tools

The security-guidance plugin ships PreToolUse and PostToolUse hooks tied to file edit tools. When Claude proposes changes, hook scripts scan content for known dangerous patterns and surface reminders before the edit lands in the working tree.

Git-diff review on session stop

Official plugin metadata describes git-diff-based LLM review when a session stops. This gives maintainers a second pass over accumulated agent changes before opening or merging a pull request.

Guidance is not automatic enforcement

Unless your team adds hard-deny hook policies, security-guidance primarily warns. Maintainers should treat unresolved warnings like failing checks during merge review.

Complements other security guides

Pair this plugin with MCP threat modeling and client configuration audits when agents use external tools. Hooks focus on local edit patterns, not remote MCP trust.

Step-by-Step Implementation Guide

1. Install the plugin. Add security-guidance from the official Claude Code plugins directory or your approved marketplace using the plugin manager.

2. Verify hook registration. Confirm hooks.json registers SessionStart bootstrap, UserPromptSubmit reminders, PostToolUse scans on edit tools, and stop-time review.

3. Run a risky edit drill. Intentionally propose a blocked-pattern snippet in a scratch branch and confirm the hook surfaces a warning your team recognizes.

4. Document merge policy. State in CONTRIBUTING that unresolved security-guidance warnings block merge until a maintainer documents acceptance or fixes the code.

5. Use during PR prep. Run Claude Code sessions with the plugin enabled while addressing review comments so new edits inherit the same guardrails.

6. Review stop output. Before git push, read stop-time git-diff review summaries and reconcile them with your diff against main.

7. Tune with hookify if needed. For repo-specific banned APIs, add complementary hookify rules rather than disabling security-guidance defaults.

Pre-Merge Security Checklist

• {"task": "Warnings cleared", "description": "No open security-guidance alerts on the final diff"}
• {"task": "Secrets absent", "description": "No credentials introduced in edited files"}
• {"task": "Injection paths", "description": "Shell, SQL, and template injection vectors reviewed"}
• {"task": "XSS surfaces", "description": "User-controlled HTML or markdown rendering checked"}
• {"task": "CI green", "description": "Project scanners and tests pass alongside hook review"}

Troubleshooting

Hooks never fire

Confirm the plugin is enabled for the project, Python is on PATH for hook scripts, and edit tools match PostToolUse matchers in hooks.json.

Too many false positives

Document accepted patterns in team rules, narrow custom hookify additions, and keep security-guidance defaults rather than disabling hooks globally.

Stop review missing

Ensure sessions end cleanly so stop hooks run; long-running background tasks may delay diff review until the session actually stops.

Plugin install fails

Update Claude Code to a hooks-capable release and verify marketplace trust settings allow the official security-guidance source.

Source Verification Notes

Verified against official Claude Code security guidance documentation and the public anthropics/claude-code plugins directory on 2026-06-16:

• code.claude.com documents the security-guidance plugin as a PreToolUse-oriented security reminder system for Claude Code projects.
• plugins/README.md lists security-guidance with hooks monitoring command injection, XSS, eval usage, dangerous HTML, pickle deserialization, and os.system calls.
• Plugin hooks.json registers SessionStart bootstrap, UserPromptSubmit scans, PostToolUse matchers on Edit and Write family tools, and stop-time git-diff review.
• Official plugin structure places metadata under .claude-plugin/plugin.json with optional commands, agents, skills, hooks, and MCP configuration.

Duplicate Check

Checked content/guides, generated catalog text, and open pull requests for security-guidance plugin, PreToolUse merge review, and Claude Code security hooks. remote-mcp-server-security-review-checklist.mdx mentions the plugin in passing but does not teach pre-merge rollout. claude-code-security-guidance-remediator-agent covers agent prompts, not plugin installation before merge. No existing guide focuses on enabling security-guidance as a merge gate workflow.

References

• Security guidance docs - https://code.claude.com/docs/en/security-guidance
• Plugins docs - https://code.claude.com/docs/en/plugins
• security-guidance plugin - https://github.com/anthropics/claude-code/tree/main/plugins/security-guidance