codeforge-dev 1.11.0 → 1.13.0

package/.devcontainer/features/lsp-servers/devcontainer-feature.json

@@ -1,45 +1,45 @@
 {
-  "id": "lsp-servers",
-  "version": "1.0.0",
-  "name": "LSP Servers for Claude Code",
-  "description": "Installs language server binaries for Python (pyright), TypeScript (typescript-language-server), and Go (gopls)",
-  "maintainer": "AnExiledDev",
-  "documentationURL": "https://code.claude.com/docs/en/discover-plugins#code-intelligence",
-  "options": {
-    "version": {
-      "type": "string",
-      "description": "Set to 'none' to skip installation of all LSP servers",
-      "default": "latest"
-    },
-    "pyrightVersion": {
-      "type": "string",
-      "description": "Pyright npm package version (e.g., 'latest', '1.1.350')",
-      "default": "latest"
-    },
-    "typescriptLspVersion": {
-      "type": "string",
-      "description": "typescript-language-server npm package version (e.g., 'latest', '4.3.0')",
-      "default": "latest"
-    },
-    "typescriptVersion": {
-      "type": "string",
-      "description": "TypeScript npm package version (e.g., 'latest', '5.3.0')",
-      "default": "latest"
-    },
-    "goplsVersion": {
-      "type": "string",
-      "description": "gopls version (e.g., 'latest', 'v0.16.0')",
-      "default": "latest"
-    },
-    "username": {
-      "type": "string",
-      "description": "Container user to install for",
-      "default": "automatic"
-    }
-  },
-  "installsAfter": [
-    "ghcr.io/devcontainers/features/common-utils:2",
-    "ghcr.io/devcontainers/features/node:1",
-    "ghcr.io/devcontainers/features/go:1"
-  ]
+	"id": "lsp-servers",
+	"version": "1.0.0",
+	"name": "LSP Servers for Claude Code",
+	"description": "Installs language server binaries for Python (pyright), TypeScript (typescript-language-server), and Go (gopls)",
+	"maintainer": "AnExiledDev",
+	"documentationURL": "https://code.claude.com/docs/en/discover-plugins#code-intelligence",
+	"options": {
+		"version": {
+			"type": "string",
+			"description": "Set to 'none' to skip installation of all LSP servers",
+			"default": "latest"
+		},
+		"pyrightVersion": {
+			"type": "string",
+			"description": "Pyright npm package version (e.g., 'latest', '1.1.350')",
+			"default": "1.1.408"
+		},
+		"typescriptLspVersion": {
+			"type": "string",
+			"description": "typescript-language-server npm package version (e.g., 'latest', '4.3.0')",
+			"default": "5.1.3"
+		},
+		"typescriptVersion": {
+			"type": "string",
+			"description": "TypeScript npm package version (e.g., 'latest', '5.3.0')",
+			"default": "5.9.3"
+		},
+		"goplsVersion": {
+			"type": "string",
+			"description": "gopls version (e.g., 'latest', 'v0.16.0')",
+			"default": "latest"
+		},
+		"username": {
+			"type": "string",
+			"description": "Container user to install for",
+			"default": "automatic"
+		}
+	},
+	"installsAfter": [
+		"ghcr.io/devcontainers/features/common-utils:2",
+		"ghcr.io/devcontainers/features/node:1",
+		"ghcr.io/devcontainers/features/go:1"
+	]
 }

package/.devcontainer/features/mcp-qdrant/poststart-hook.sh

@@ -35,7 +35,8 @@ if [ -n "${MODEL_URL}" ] && [ ! -d "${FASTEMBED_CACHE}/${MODEL_DIR}" ]; then
         tar -xzf "${TEMP_TAR}" -C "${FASTEMBED_CACHE}/" 2>/dev/null || true
         find "${FASTEMBED_CACHE}" -name "._*" -delete 2>/dev/null || true
         rm -f "${TEMP_TAR}"
-        chmod -R 777 "${FASTEMBED_CACHE}" 2>/dev/null || true
+        chown -R "vscode:vscode" "${FASTEMBED_CACHE}" 2>/dev/null || true
+        chmod -R 755 "${FASTEMBED_CACHE}" 2>/dev/null || true
         echo "[mcp-qdrant] ✓ Embedding model downloaded to ${FASTEMBED_CACHE}/${MODEL_DIR}"
     else
         echo "[mcp-qdrant] WARNING: Failed to download embedding model"

package/.devcontainer/features/ruff/devcontainer-feature.json

@@ -1,21 +1,19 @@
 {
-  "id": "ruff",
-  "version": "1.0.0",
-  "name": "Ruff",
-  "description": "Fast Python linter and formatter (replaces Black + Flake8)",
-  "options": {
-    "version": {
-      "type": "string",
-      "default": "latest",
-      "description": "Ruff version to install"
-    },
-    "username": {
-      "type": "string",
-      "default": "automatic",
-      "description": "Container user to install for"
-    }
-  },
-  "installsAfter": [
-    "ghcr.io/devcontainers-extra/features/uv"
-  ]
+	"id": "ruff",
+	"version": "1.0.0",
+	"name": "Ruff",
+	"description": "Fast Python linter and formatter (replaces Black + Flake8)",
+	"options": {
+		"version": {
+			"type": "string",
+			"default": "0.15.1",
+			"description": "Ruff version to install"
+		},
+		"username": {
+			"type": "string",
+			"default": "automatic",
+			"description": "Container user to install for"
+		}
+	},
+	"installsAfter": ["ghcr.io/devcontainers-extra/features/uv"]
 }

package/.devcontainer/features/tmux/install.sh

@@ -11,9 +11,9 @@ fi
 
 echo "Installing tmux for Claude Code Agent Teams..."
 
-# Install tmux via apt
+# Install tmux and inotify-tools via apt
 apt-get update
-apt-get install -y tmux
+apt-get install -y tmux inotify-tools
 
 # Install Catppuccin theme (shallow clone for fast builds)
 CATPPUCCIN_DIR="/usr/share/tmux/plugins/catppuccin"

package/.devcontainer/plugins/devs-marketplace/.claude-plugin/marketplace.json

@@ -89,10 +89,31 @@
 			"category": "development"
 		},
 		{
-			"name": "code-directive",
-			"description": "17 custom agents, 28 coding skills, agent redirection, syntax validation, and skill auto-suggestion",
+			"name": "agent-system",
+			"description": "17 custom agents with built-in agent redirection, CWD injection, and read-only bash enforcement",
 			"version": "1.0.0",
-			"source": "./plugins/code-directive",
+			"source": "./plugins/agent-system",
+			"category": "development"
+		},
+		{
+			"name": "skill-engine",
+			"description": "21 coding knowledge packs with auto-suggestion for frameworks, tools, and patterns",
+			"version": "1.0.0",
+			"source": "./plugins/skill-engine",
+			"category": "development"
+		},
+		{
+			"name": "spec-workflow",
+			"description": "Specification lifecycle management: creation, refinement, building, reviewing, updating, and auditing",
+			"version": "1.0.0",
+			"source": "./plugins/spec-workflow",
+			"category": "workflow"
+		},
+		{
+			"name": "session-context",
+			"description": "Session lifecycle hooks: git state injection, TODO harvesting, and commit reminders",
+			"version": "1.0.0",
+			"source": "./plugins/session-context",
 			"category": "development"
 		},
 		{

package/.devcontainer/plugins/devs-marketplace/plugins/agent-system/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+	"name": "agent-system",
+	"description": "17 custom agents with built-in agent redirection, CWD injection, and read-only bash enforcement",
+	"version": "1.0.0",
+	"author": {
+		"name": "AnExiledDev"
+	}
+}

package/.devcontainer/plugins/devs-marketplace/plugins/{code-directive → agent-system}/AGENT-REDIRECTION.md

@@ -65,7 +65,7 @@ REDIRECT_MAP = {
 }
 ```
 
-When Claude decides to spawn an `Explore` agent, the hook rewrites it to `code-directive:explorer` — a custom agent with tailored instructions, tool restrictions, and model selection. The original prompt passes through unchanged.
+When Claude decides to spawn an `Explore` agent, the hook rewrites it to `agent-system:explorer` — a custom agent with tailored instructions, tool restrictions, and model selection. The original prompt passes through unchanged.
 
 ### Custom Agent Definitions
 
@@ -138,7 +138,7 @@ elif "refactor" in prompt.lower():
     target = "refactorer"
 else:
     target = "generalist"
-updated = {**tool_input, "subagent_type": f"code-directive:{target}"}
+updated = {**tool_input, "subagent_type": f"agent-system:{target}"}
 ```
 
 ### Block Certain Operations
@@ -197,7 +197,7 @@ This is how the auto-linter and syntax validator work — they inspect the resul
 ## File Layout
 
 ```
-code-directive/
+agent-system/
 ├── agents/                    # Agent definitions (17 .md files)
 │   ├── explorer.md
 │   ├── architect.md
@@ -205,15 +205,10 @@ code-directive/
 │   └── ...
 ├── hooks/
 │   └── hooks.json             # Hook registrations
-├── scripts/
-│   ├── redirect-builtin-agents.py   # The redirection hook
-│   ├── collect-edited-files.py      # Collects paths for Stop hooks
-│   ├── syntax-validator.py          # PostToolUse syntax checks
-│   └── skill-suggester.py           # Suggests skills on prompt
-└── skills/                    # Skill definitions (16 directories)
-    ├── fastapi/
-    ├── svelte5/
-    └── ...
+└── scripts/
+    ├── redirect-builtin-agents.py   # The redirection hook
+    ├── inject-cwd.py                # CWD injection for subagents
+    └── guard-readonly-bash.py       # Read-only bash enforcement
 ```
 
 ## Writing Your Own

package/.devcontainer/plugins/devs-marketplace/plugins/{code-directive → agent-system}/REVIEW-RUBRIC.md

@@ -1,6 +1,6 @@
 # Agent & Skill Quality Rubric
 
-> Compiled from Anthropic's official documentation, Claude Code subagent docs, skill authoring best practices, and industry research on LLM agent design patterns. This rubric drives the quality review of all agents and skills in the `code-directive` plugin.
+> Compiled from Anthropic's official documentation, Claude Code subagent docs, skill authoring best practices, and industry research on LLM agent design patterns. This rubric drives the quality review of all agents in the `agent-system` plugin and skills in the `skill-engine` / `spec-workflow` plugins.
 
 ---
 

package/.devcontainer/plugins/devs-marketplace/plugins/agent-system/hooks/hooks.json

@@ -0,0 +1,29 @@
+{
+	"description": "Agent redirection and subagent configuration hooks",
+	"hooks": {
+		"PreToolUse": [
+			{
+				"matcher": "Task",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/redirect-builtin-agents.py",
+						"timeout": 5
+					}
+				]
+			}
+		],
+		"SubagentStart": [
+			{
+				"matcher": "",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/inject-cwd.py",
+						"timeout": 3
+					}
+				]
+			}
+		]
+	}
+}

package/.devcontainer/plugins/devs-marketplace/plugins/{code-directive → agent-system}/scripts/redirect-builtin-agents.py

@@ -3,7 +3,12 @@
 Redirect built-in agents - PreToolUse hook for Task tool.
 
 Intercepts Task tool calls and transparently redirects built-in agent
-types to enhanced custom agents defined in the code-directive plugin.
+types to enhanced custom agents defined in the agent-system plugin.
+
+Handles three cases:
+- Built-in name (e.g. "claude-code-guide") → qualified custom name
+- Unqualified custom name (e.g. "claude-guide") → qualified custom name
+- Already-qualified name (e.g. "agent-system:claude-guide") → passthrough
 
 The redirect preserves the original prompt — only the subagent_type
 is changed. Model selection is left to the custom agent's YAML config.
@@ -28,7 +33,11 @@ REDIRECT_MAP = {
 }
 
 # Plugin name prefix for fully-qualified agent references
-PLUGIN_PREFIX = "code-directive"
+PLUGIN_PREFIX = "agent-system"
+
+# Unqualified custom name → fully-qualified custom name
+# Handles cases where the model uses the short name directly
+UNQUALIFIED_MAP = {v: f"{PLUGIN_PREFIX}:{v}" for v in REDIRECT_MAP.values()}
 
 LOG_FILE = os.environ.get("AGENT_REDIRECT_LOG", "/tmp/agent-redirect.log")
 
@@ -54,12 +63,14 @@ def main() -> None:
     tool_input = input_data.get("tool_input", {})
     subagent_type = tool_input.get("subagent_type", "")
 
-    if subagent_type not in REDIRECT_MAP:
+    if subagent_type in REDIRECT_MAP:
+        target = REDIRECT_MAP[subagent_type]
+        qualified_name = f"{PLUGIN_PREFIX}:{target}"
+    elif subagent_type in UNQUALIFIED_MAP:
+        qualified_name = UNQUALIFIED_MAP[subagent_type]
+    else:
         sys.exit(0)
 
-    target = REDIRECT_MAP[subagent_type]
-    qualified_name = f"{PLUGIN_PREFIX}:{target}"
-
     log(f"{subagent_type} → {qualified_name}")
 
     # Include all original fields in updatedInput — Claude Code may replace

package/.devcontainer/plugins/devs-marketplace/plugins/auto-formatter/README.md

@@ -0,0 +1,81 @@
+# auto-formatter
+
+Claude Code plugin that batch-formats edited files when Claude finishes responding. Reads file paths collected by the `code-directive` plugin's `collect-edited-files.py` hook and formats each file based on its extension.
+
+## What It Does
+
+When Claude stops responding, the plugin reads the session's list of edited files and formats each one using the appropriate tool:
+
+| Language / File Type | Formatter | Fallback |
+|----------------------|-----------|----------|
+| Python (`.py`, `.pyi`) | [ruff format](https://docs.astral.sh/ruff/) | [black](https://github.com/psf/black) |
+| Go (`.go`) | gofmt (bundled with Go) | — |
+| JS/TS/CSS/JSON/GraphQL/HTML (`.js`, `.jsx`, `.ts`, `.tsx`, `.css`, `.json`, `.jsonc`, `.graphql`, `.gql`, `.html`, `.vue`, `.svelte`, `.astro`) | [biome](https://biomejs.dev/) check --write | — |
+| Shell (`.sh`, `.bash`, `.zsh`, `.mksh`, `.bats`) | [shfmt](https://github.com/mvdan/sh) | — |
+| Markdown/YAML/TOML (`.md`, `.markdown`, `.yaml`, `.yml`, `.toml`) | [dprint](https://dprint.dev/) | — |
+| Dockerfile | dprint | — |
+| Rust (`.rs`) | rustfmt (bundled with Rust) | — |
+
+All formatting is non-blocking. Missing tools are silently skipped. The plugin always exits 0 — it will never interrupt Claude.
+
+## How It Works
+
+### Hook Lifecycle
+
+```
+code-directive's collect-edited-files.py (PostToolUse on Edit/Write)
+  │
+  └─→ Appends edited file path to /tmp/claude-edited-files-{session_id}
+       │
+       │  ... Claude keeps working ...
+       │
+Claude stops responding (Stop event)
+  │
+  └─→ format-on-stop.py reads the temp file, deduplicates paths,
+      formats each file by extension, then cleans up the temp file
+```
+
+### Dependency on code-directive
+
+This plugin does **not** collect file paths itself. It relies on the `code-directive` plugin's `collect-edited-files.py` PostToolUse hook to write edited file paths to `/tmp/claude-edited-files-{session_id}`. Both plugins must be enabled for formatting to work.
+
+### Biome Discovery
+
+Biome is resolved in this order:
+1. **Project-local**: walks up from the edited file looking for `node_modules/.bin/biome`
+2. **Global**: checks PATH via `which biome`
+
+### dprint Configuration
+
+The dprint formatter looks for a config file at `/usr/local/share/dprint/dprint.json`. If this file doesn't exist, dprint formatting is skipped.
+
+### Timeouts
+
+| Scope | Timeout |
+|-------|---------|
+| Entire Stop hook | 15s |
+| Individual tool invocation | 10-12s |
+
+## Conflict Warning
+
+Do **not** enable this plugin alongside `auto-code-quality`. That plugin bundles its own formatter with the same functionality. Enabling both won't corrupt data (different temp file prefixes: `claude-edited-files-*` vs `claude-cq-*`), but files would be formatted twice.
+
+## Plugin Structure
+
+```
+auto-formatter/
+├── .claude-plugin/
+│   └── plugin.json          # Plugin metadata
+├── hooks/
+│   └── hooks.json           # Stop hook registration
+├── scripts/
+│   └── format-on-stop.py    # Batch formatter (Stop)
+└── README.md                # This file
+```
+
+## Requirements
+
+- Python 3.11+
+- Claude Code with plugin hook support
+- `code-directive` plugin enabled (provides the file path collector)
+- Install the formatting tools for the languages you work with — everything is optional

package/.devcontainer/plugins/devs-marketplace/plugins/auto-linter/README.md

@@ -0,0 +1,92 @@
+# auto-linter
+
+Claude Code plugin that batch-lints edited files when Claude finishes responding. Reads file paths collected by the `code-directive` plugin's `collect-edited-files.py` hook and lints each file using the appropriate tool. Lint results are returned as advisory context — never blocking.
+
+## What It Does
+
+When Claude stops responding, the plugin reads the session's list of edited files, lints each one, and injects any warnings as `additionalContext` so Claude sees them on its next response.
+
+| Language / File Type | Linter(s) |
+|----------------------|-----------|
+| Python (`.py`, `.pyi`) | [pyright](https://github.com/microsoft/pyright) (type checking) + [ruff check](https://docs.astral.sh/ruff/) (style/correctness) |
+| JS/TS/CSS/GraphQL (`.js`, `.jsx`, `.ts`, `.tsx`, `.css`, `.graphql`, `.gql`) | [biome lint](https://biomejs.dev/) |
+| Shell (`.sh`, `.bash`, `.zsh`, `.mksh`, `.bats`) | [shellcheck](https://github.com/koalaman/shellcheck) |
+| Go (`.go`) | go vet (bundled with Go) |
+| Dockerfile | [hadolint](https://github.com/hadolint/hadolint) |
+| Rust (`.rs`) | [clippy](https://doc.rust-lang.org/clippy/) (via cargo) |
+
+All linting is non-blocking. Missing tools are silently skipped. The plugin always exits 0 and returns warnings as `additionalContext` — it will never interrupt Claude.
+
+## How It Works
+
+### Hook Lifecycle
+
+```
+code-directive's collect-edited-files.py (PostToolUse on Edit/Write)
+  │
+  └─→ Appends edited file path to /tmp/claude-lint-files-{session_id}
+       │
+       │  ... Claude keeps working ...
+       │
+Claude stops responding (Stop event)
+  │
+  └─→ lint-file.py reads the temp file, deduplicates paths,
+      lints each file by extension, groups results by linter,
+      injects warnings as additionalContext, then cleans up
+```
+
+### Dependency on code-directive
+
+This plugin relies on the `code-directive` plugin's `collect-edited-files.py` PostToolUse hook to write edited file paths to `/tmp/claude-lint-files-{session_id}`. Both plugins must be enabled for linting to work.
+
+### Output Format
+
+Lint results are grouped by linter and returned as `additionalContext`. Each file shows up to 5 issues with severity, line number, and message:
+
+```
+[Auto-linter] Pyright results:
+  example.py: 2 issue(s)
+  ✗ Line 15: Cannot assign type "str" to declared type "int"
+  ! Line 42: Variable "x" is not defined
+
+[Auto-linter] Ruff results:
+  example.py: 1 issue(s)
+  ! Line 8: [F401] `os` imported but unused
+```
+
+### Biome Discovery
+
+Biome is resolved in this order:
+1. **Project-local**: walks up from the edited file looking for `node_modules/.bin/biome`
+2. **Global**: checks PATH via `which biome`
+
+### Timeouts
+
+| Scope | Timeout |
+|-------|---------|
+| Entire Stop hook | 60s |
+| Individual tool invocation | 10s |
+
+## Conflict Warning
+
+Do **not** enable this plugin alongside `auto-code-quality`. That plugin bundles its own linter with the same functionality. Enabling both won't corrupt data (different temp file prefixes: `claude-lint-files-*` vs `claude-cq-*`), but files would be linted twice.
+
+## Plugin Structure
+
+```
+auto-linter/
+├── .claude-plugin/
+│   └── plugin.json        # Plugin metadata
+├── hooks/
+│   └── hooks.json         # Stop hook registration
+├── scripts/
+│   └── lint-file.py       # Batch linter (Stop)
+└── README.md              # This file
+```
+
+## Requirements
+
+- Python 3.11+
+- Claude Code with plugin hook support
+- `code-directive` plugin enabled (provides the file path collector)
+- Install the linting tools for the languages you work with — everything is optional

package/.devcontainer/plugins/devs-marketplace/plugins/codeforge-lsp/README.md

@@ -0,0 +1,41 @@
+# codeforge-lsp
+
+Purely declarative Claude Code plugin that registers Language Server Protocol (LSP) servers for Python, TypeScript/JavaScript, and Go. No hooks, no scripts — just server definitions in the plugin manifest.
+
+## What It Does
+
+Provides Claude Code with language intelligence (type checking, diagnostics, go-to-definition) by registering three LSP servers:
+
+| Server | Command | Languages | File Extensions |
+|--------|---------|-----------|-----------------|
+| [Pyright](https://github.com/microsoft/pyright) | `pyright-langserver --stdio` | Python | `.py`, `.pyi` |
+| [TypeScript Language Server](https://github.com/typescript-language-server/typescript-language-server) | `typescript-language-server --stdio` | TypeScript, JavaScript | `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.cts`, `.mjs`, `.cjs` |
+| [gopls](https://pkg.go.dev/golang.org/x/tools/gopls) | `gopls serve` | Go | `.go`, `.mod`, `.sum` |
+
+Servers activate only if their binary is available on PATH. Missing servers are silently skipped — the plugin never fails on a missing tool.
+
+## How It Works
+
+The plugin uses the `lspServers` field in `plugin.json` to declare server configurations. Claude Code reads this at startup and launches each server whose command binary exists. There is no hook logic or runtime behavior — everything is static configuration.
+
+Each server maps file extensions to language identifiers. When Claude Code opens a file matching a registered extension, it routes it to the corresponding LSP server for diagnostics, completions, and other language features.
+
+## Plugin Structure
+
+```
+codeforge-lsp/
+├── .claude-plugin/
+│   └── plugin.json    # Plugin metadata + LSP server definitions
+└── README.md          # This file
+```
+
+## Requirements
+
+- Claude Code with LSP plugin support
+- Install the language servers you need:
+
+| Server | Install |
+|--------|---------|
+| Pyright | `npm i -g pyright` |
+| TypeScript Language Server | `npm i -g typescript-language-server typescript` |
+| gopls | `go install golang.org/x/tools/gopls@latest` |

package/.devcontainer/plugins/devs-marketplace/plugins/dangerous-command-blocker/README.md

@@ -0,0 +1,72 @@
+# dangerous-command-blocker
+
+Claude Code plugin that intercepts Bash tool calls and blocks destructive commands before they execute. Acts as a safety net against accidental or misguided destructive operations.
+
+## What It Does
+
+Inspects every Bash command Claude attempts to run against a set of dangerous patterns. If a match is found, the command is blocked with an error message explaining why. Safe commands pass through untouched.
+
+### Blocked Patterns
+
+| Category | Examples |
+|----------|----------|
+| Destructive filesystem deletion | `rm -rf /`, `rm -rf ~`, `rm -rf ../` |
+| Privileged deletion | `sudo rm` |
+| World-writable permissions | `chmod 777`, `chmod -R 777` |
+| Force push to main/master | `git push --force origin main`, `git push -f origin master` |
+| Bare force push | `git push -f`, `git push --force` (no branch specified) |
+| Git history destruction | `git reset --hard origin/main`, `git clean -f` |
+| System directory writes | `> /usr/`, `> /etc/`, `> /bin/`, `> /sbin/` |
+| Disk formatting | `mkfs.*`, `dd of=/dev/` |
+| Docker container escape | `docker run --privileged`, `docker run -v /:/...` |
+| Destructive Docker operations | `docker stop`, `docker rm`, `docker kill`, `docker rmi` |
+| Dangerous find operations | `find -exec rm`, `find -delete` |
+
+## How It Works
+
+### Hook Lifecycle
+
+```
+Claude calls the Bash tool
+  │
+  └─→ PreToolUse hook fires for Bash
+       │
+       └─→ block-dangerous.py reads the command from stdin
+            │
+            ├─→ Pattern match found → exit 2 (block with error)
+            └─→ No match → exit 0 (allow)
+```
+
+### Exit Code Behavior
+
+| Exit Code | Meaning |
+|-----------|---------|
+| 0 | Command is safe — allow execution |
+| 2 | Command matches a dangerous pattern — block with error message |
+
+### Error Handling
+
+- **JSON parse failure**: Fails closed (exit 2) — if the input can't be read, the command is blocked
+- **Other exceptions**: Fails open (exit 0) — logs the error to stderr but does not block
+
+### Timeout
+
+The hook has a 5-second timeout. If the script takes longer, Claude Code proceeds with the command.
+
+## Plugin Structure
+
+```
+dangerous-command-blocker/
+├── .claude-plugin/
+│   └── plugin.json          # Plugin metadata
+├── hooks/
+│   └── hooks.json           # PreToolUse/Bash hook registration
+├── scripts/
+│   └── block-dangerous.py   # Pattern matcher (PreToolUse)
+└── README.md                # This file
+```
+
+## Requirements
+
+- Python 3.11+
+- Claude Code with plugin hook support