[DOCS] plugins/README.md still describes security-guidance v1 (wrong hook type, wrong pattern count)

Status Open

Maintainer reply None cached

Activity 4 comments · opened Aug 26, 2026

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://github.com/anthropics/claude-code/blob/main/plugins/README.md

Section/Topic

"Plugins in This Directory" table — the security-guidance row

Current Documentation

| [security-guidance](./security-guidance/) | Security reminder hook that warns about potential security issues when editing files | Hook: PreToolUse - Monitors 9 security patterns including command injection, XSS, eval usage, dangerous HTML, pickle deserialization, and os.system calls |

What's Wrong or Missing?

441892e ("Update security-guidance plugin") rewrote the plugin for v2 but
touched nothing outside plugins/security-guidance/, so the catalog row in
plugins/README.md still describes v1. Three things are wrong:

Hook type. The row says PreToolUse. hooks/hooks.json registers

SessionStart, UserPromptSubmit, PostToolUse and Stop — there is no
PreToolUse hook at all.

Pattern count. The row says 9. SECURITY_PATTERNS in hooks/patterns.py

has 25 entries.

Missing layers. v2 added two review layers the row never mentions: the

Stop-hook LLM diff review, and the agentic reviewer that runs on
git commit / git push (PostToolUse with matcher Bash, gated by
if: Bash(git commit:*) and if: Bash(git push:*)).

The plugin's own README (plugins/security-guidance/README.md) is accurate
and already documents all three layers — only the catalog summary drifted.

Suggested Improvement

Replace the row with one derived from hooks.json and patterns.py:

| [security-guidance](./security-guidance/) | Three-layer security review of Claude-generated code: regex pattern warnings on edits, an LLM review of the diff when Claude finishes a turn, and an agentic reviewer on git commit/git push | Hooks: PostToolUse - Warns on ~25 known-dangerous patterns (command injection, XSS, eval, unsafe deserialization, disabled TLS verification, weak crypto) when editing files<br>PostToolUse[Bash] - Agentic commit/push review that traces data flow across files<br>Stop - LLM review of the git diff, fed back so Claude can fix findings first<br>SessionStart - Prepares the Agent SDK environment the reviewers run in |

Notes on the wording:

The pattern categories come from the actual ruleName values in

patterns.py (child_process_exec, innerHTML_xss, eval_injection,
pickle_deserialization, tls_verification_disabled, aes_ecb_mode, ...).

"~25" matches the plugin README's own phrasing rather than pinning an

exact number that the next added pattern would invalidate.

I have this as a one-line commit on a fork, if that's easier to pull in
than retyping the table row:
https://github.com/chanmilee-fe/claude-code/commit/d82822b07cd2c66ec2f56acdb3705f3841b8a6ef

(I tried opening a PR first, but the repo restricts PR creation to
collaborators.)

Impact

Medium - Makes feature difficult to understand

Additional Context

Two related items found in the same pass — happy to file separately:

marketplace.json lists security-guidance at version 1.0.0, while

plugins/security-guidance/.claude-plugin/plugin.json says 2.0.0.

The code-review row in the same table has drifted the same way: it lists

"5 parallel Sonnet agents", but commands/code-review.md launches 4, two of
which are Opus. That plugin's own README additionally documents a 0-100
confidence scoring system with an 80 threshold — including a section on
how to adjust the threshold — that no longer exists in the command file.

View original on GitHub ↗

4 Comments

Fardin7798 · 1 month ago

I put together a fix for this — the row now matches the current hooks/hooks.json and hooks/patterns.py (SessionStart/UserPromptSubmit/PostToolUse/Stop hooks, ~25 patterns, and the three review layers).

Branch/commit here (PR creation is restricted to collaborators, so linking directly): https://github.com/Fardin7798/claude-code/commit/2e27828

Happy to open a PR if maintainer access is granted, or feel free to cherry-pick the commit.

belentani7 · 1 month ago

Verifying this is still accurate against current main (checked 2026-08-31):

1. Hook type — confirmed wrong. plugins/security-guidance/hooks/hooks.json registers exactly four hook events: SessionStart, UserPromptSubmit, PostToolUse, and Stop. There is no PreToolUse hook anywhere in the plugin.

2. Pattern count — confirmed wrong. SECURITY_PATTERNS in hooks/patterns.py has 25 entries (25 ruleName values: github_actions_workflow, child_process_exec, new_function_injection, eval_injection, react_dangerously_set_html, document_write_xss, innerHTML_xss, pickle_deserialization, os_system_injection, python_subprocess_shell, go_exec_shell_injection, unsafe_yaml_load, node_createcipher_no_iv, aes_ecb_mode, tls_verification_disabled, marshal_loads, shelve_open, xml_unsafe_parse, pickle_variants_load, outerHTML_xss, insertAdjacentHTML_xss, script_src_without_sri, torch_unsafe_load, yaml_unsafe_load_variants, pickle_wrapper_load) — not 9.

3. Missing layers — confirmed. The catalog row omits the two v2 review layers the plugin's own README documents:

the Stop-hook LLM diff review (Stop hook, asyncRewake: true), and
the agentic commit/push reviewer (PostToolUse with matcher Bash, gated by if: Bash(git commit:*) and if: Bash(git push:*), also asyncRewake).

The PostToolUse section also shows the pattern-warning hook is matcher-scoped to Edit|Write|MultiEdit|NotebookEdit, i.e. it fires on edits — so the row's "Monitors ... patterns" wording is only half the story.

One small addition to the proposed replacement row: the UserPromptSubmit hook (which also runs security_reminder_hook.py) is not mentioned in the suggested text; worth including for completeness.

Happy to re-verify once #81576 lands. Environment note: verified on Windows 11 (build 26200), Claude Code 2.1.240.

u-hashmi · 1 month ago

Confirmed against the current tree (plugins/README.md:27 still has the v1 row).

Verification:

plugins/security-guidance/hooks/hooks.json registers SessionStart, UserPromptSubmit, PostToolUse, and Stop — there is no PreToolUse hook (the row says PreToolUse).
SECURITY_PATTERNS in plugins/security-guidance/hooks/patterns.py has 25 entries (the row says 9).
The v2 review layers (Stop-hook LLM diff review; agentic reviewer on git commit / git push) aren't mentioned at all.

The plugin's own plugins/security-guidance/README.md is accurate — only the catalog summary drifted.

Suggested replacement row, derived from hooks.json and patterns.py:

| [security-guidance](./security-guidance/) | Three-layer security review of Claude-generated code: regex pattern warnings on edits, an LLM review of the diff when Claude finishes a turn, and an agentic reviewer on `git commit`/`git push` | **Hooks:** PostToolUse - Warns on ~25 known-dangerous patterns (command injection, XSS, `eval`, unsafe deserialization, disabled TLS verification, weak crypto) when editing files<br>PostToolUse[Bash] - Agentic commit/push review that traces data flow across files<br>Stop - LLM review of the git diff, fed back so Claude can fix findings first<br>SessionStart - Prepares the Agent SDK environment the reviewers run in |

Happy to open a PR if the repo can accept one from an external contributor — it currently rejects PRs from non-collaborators, so leaving the ready-to-apply row here instead.

u-hashmi · 1 month ago

One more, found while scanning the rest of the repo for the same drift: .claude-plugin/marketplace.json carries a v1-era summary too — this is the user-facing description shown in /plugin:

Current:

"description": "Security reminder hook that warns about potential security issues when editing files, including command injection, XSS, and unsafe code patterns"

It predates the three-layer redesign (no mention of the LLM diff review or the agentic commit/push reviewer). Suggested one-line replacement, consistent with the catalog row and the plugin's own README:

"description": "Three-layer security review of Claude-generated code: regex pattern warnings on edits, an LLM review of the diff at end of turn, and an agentic reviewer on git commit/push"

plugins/README.md:27 and this marketplace.json entry are the only two stale copies — a repo-wide grep for 9 security patterns / Monitors 9 / PreToolUse turns up nothing else.