codeforge-dev 1.10.0 → 1.12.0

package/.devcontainer/plugins/devs-marketplace/plugins/dangerous-command-blocker/scripts/block-dangerous.py

@@ -13,54 +13,82 @@ import sys
 
 DANGEROUS_PATTERNS = [
     # Destructive filesystem deletion
-    (r'\brm\s+.*-[^\s]*r[^\s]*f[^\s]*\s+[/~](?:\s|$)',
-     "Blocked: rm -rf on root or home directory"),
-    (r'\brm\s+.*-[^\s]*f[^\s]*r[^\s]*\s+[/~](?:\s|$)',
-     "Blocked: rm -rf on root or home directory"),
-    (r'\brm\s+-rf\s+/(?:\s|$)',
-     "Blocked: rm -rf /"),
-    (r'\brm\s+-rf\s+~(?:\s|$)',
-     "Blocked: rm -rf ~"),
-
+    (
+        r"\brm\s+.*-[^\s]*r[^\s]*f[^\s]*\s+[/~](?:\s|$)",
+        "Blocked: rm -rf on root or home directory",
+    ),
+    (
+        r"\brm\s+.*-[^\s]*f[^\s]*r[^\s]*\s+[/~](?:\s|$)",
+        "Blocked: rm -rf on root or home directory",
+    ),
+    (r"\brm\s+-rf\s+/(?:\s|$)", "Blocked: rm -rf /"),
+    (r"\brm\s+-rf\s+~(?:\s|$)", "Blocked: rm -rf ~"),
     # Root-level file removal
-    (r'\bsudo\s+rm\b',
-     "Blocked: sudo rm - use caution with privileged deletion"),
-
+    (r"\bsudo\s+rm\b", "Blocked: sudo rm - use caution with privileged deletion"),
     # World-writable permissions
-    (r'\bchmod\s+777\b',
-     "Blocked: chmod 777 creates security vulnerability"),
-    (r'\bchmod\s+-R\s+777\b',
-     "Blocked: recursive chmod 777 creates security vulnerability"),
-
+    (r"\bchmod\s+777\b", "Blocked: chmod 777 creates security vulnerability"),
+    (
+        r"\bchmod\s+-R\s+777\b",
+        "Blocked: recursive chmod 777 creates security vulnerability",
+    ),
     # Force push to main/master
-    (r'\bgit\s+push\s+.*--force.*\s+(origin\s+)?(main|master)\b',
-     "Blocked: force push to main/master destroys history"),
-    (r'\bgit\s+push\s+.*-f\s+.*\s+(origin\s+)?(main|master)\b',
-     "Blocked: force push to main/master destroys history"),
-    (r'\bgit\s+push\s+-f\s+(origin\s+)?(main|master)\b',
-     "Blocked: force push to main/master destroys history"),
-    (r'\bgit\s+push\s+--force\s+(origin\s+)?(main|master)\b',
-     "Blocked: force push to main/master destroys history"),
-
+    (
+        r"\bgit\s+push\s+.*--force.*\s+(origin\s+)?(main|master)\b",
+        "Blocked: force push to main/master destroys history",
+    ),
+    (
+        r"\bgit\s+push\s+.*-f\s+.*\s+(origin\s+)?(main|master)\b",
+        "Blocked: force push to main/master destroys history",
+    ),
+    (
+        r"\bgit\s+push\s+-f\s+(origin\s+)?(main|master)\b",
+        "Blocked: force push to main/master destroys history",
+    ),
+    (
+        r"\bgit\s+push\s+--force\s+(origin\s+)?(main|master)\b",
+        "Blocked: force push to main/master destroys history",
+    ),
     # System directory modification
-    (r'>\s*/usr/',
-     "Blocked: writing to /usr system directory"),
-    (r'>\s*/etc/',
-     "Blocked: writing to /etc system directory"),
-    (r'>\s*/bin/',
-     "Blocked: writing to /bin system directory"),
-    (r'>\s*/sbin/',
-     "Blocked: writing to /sbin system directory"),
-
+    (r">\s*/usr/", "Blocked: writing to /usr system directory"),
+    (r">\s*/etc/", "Blocked: writing to /etc system directory"),
+    (r">\s*/bin/", "Blocked: writing to /bin system directory"),
+    (r">\s*/sbin/", "Blocked: writing to /sbin system directory"),
     # Disk formatting
-    (r'\bmkfs\.\w+',
-     "Blocked: disk formatting command"),
-    (r'\bdd\s+.*of=/dev/',
-     "Blocked: dd writing to device"),
-
+    (r"\bmkfs\.\w+", "Blocked: disk formatting command"),
+    (r"\bdd\s+.*of=/dev/", "Blocked: dd writing to device"),
     # History manipulation
-    (r'\bgit\s+reset\s+--hard\s+origin/(main|master)\b',
-     "Blocked: hard reset to remote main/master - destructive operation"),
+    (
+        r"\bgit\s+reset\s+--hard\s+origin/(main|master)\b",
+        "Blocked: hard reset to remote main/master - destructive operation",
+    ),
+    # Docker container escape
+    (
+        r"\bdocker\s+run\s+.*--privileged",
+        "Blocked: docker run --privileged allows container escape",
+    ),
+    (
+        r"\bdocker\s+run\s+.*-v\s+/:/\w",
+        "Blocked: docker run mounting host root filesystem",
+    ),
+    # Destructive Docker operations
+    (
+        r"\bdocker\s+(stop|rm|kill|rmi)\s+",
+        "Blocked: destructive docker operation - use with caution",
+    ),
+    # Additional rm patterns
+    (r"\brm\s+.*-[^\s]*r[^\s]*f[^\s]*\s+\.\./", "Blocked: rm -rf on parent directory"),
+    (r"\bfind\s+.*-exec\s+rm\b", "Blocked: find -exec rm is dangerous"),
+    (r"\bfind\s+.*-delete\b", "Blocked: find -delete is dangerous"),
+    # Git history destruction
+    (r"\bgit\s+push\s+-f\b", "Blocked: bare force push - specify remote and branch"),
+    (
+        r"\bgit\s+push\s+--force\b",
+        "Blocked: bare force push - specify remote and branch",
+    ),
+    (
+        r"\bgit\s+clean\s+-[^\s]*f",
+        "Blocked: git clean -f removes untracked files permanently",
+    ),
 ]
 
 
@@ -89,17 +117,15 @@ def main():
 
         if is_dangerous:
             # Output error message and exit 2 to block
-            print(json.dumps({
-                "error": message
-            }))
+            print(json.dumps({"error": message}))
             sys.exit(2)
 
         # Allow command to proceed
         sys.exit(0)
 
     except json.JSONDecodeError:
-        # If we can't parse input, allow by default
-        sys.exit(0)
+        # Fail closed: can't parse means can't verify safety
+        sys.exit(2)
     except Exception as e:
         # Log error but don't block on hook failure
         print(f"Hook error: {e}", file=sys.stderr)

package/.devcontainer/plugins/devs-marketplace/plugins/notify-hook/README.md

@@ -0,0 +1,42 @@
+# notify-hook
+
+Ultra-lightweight Claude Code plugin that sends a desktop notification and audio chime when Claude finishes responding. No scripts — just a single hook definition that calls the `claude-notify` binary.
+
+## What It Does
+
+When Claude stops responding (Stop hook), it runs the `claude-notify` command to:
+1. Send a desktop notification
+2. Play an audio chime
+
+This lets you switch to other tasks while Claude works and get alerted when it needs your attention.
+
+## How It Works
+
+### Hook Lifecycle
+
+```
+Claude stops responding (Stop event)
+  │
+  └─→ claude-notify command fires
+       │
+       ├─→ Desktop notification sent
+       └─→ Audio chime played
+```
+
+The hook has a 5-second timeout. The plugin contains no scripts of its own — it delegates entirely to the `claude-notify` binary.
+
+## Plugin Structure
+
+```
+notify-hook/
+├── .claude-plugin/
+│   └── plugin.json    # Plugin metadata
+├── hooks/
+│   └── hooks.json     # Stop hook registration
+└── README.md          # This file
+```
+
+## Requirements
+
+- Claude Code with plugin hook support
+- The `notify-hook` devcontainer feature must be installed (provides the `claude-notify` binary)

package/.devcontainer/plugins/devs-marketplace/plugins/protected-files-guard/README.md

@@ -0,0 +1,86 @@
+# protected-files-guard
+
+Claude Code plugin that blocks modifications to sensitive files — environment secrets, lock files, git internals, certificates, and credentials. Covers both direct file edits (Edit/Write tools) and indirect writes through Bash commands.
+
+## What It Does
+
+Intercepts file operations and checks target paths against a set of protected patterns. If a match is found, the operation is blocked with an error message explaining why and suggesting the correct approach (e.g., "use npm install instead" for package-lock.json).
+
+### Protected File Categories
+
+| Category | Patterns | Reason |
+|----------|----------|--------|
+| Environment secrets | `.env`, `.env.*` | Contains secrets |
+| Git internals | `.git/` | Managed by git |
+| Lock files | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Gemfile.lock`, `poetry.lock`, `Cargo.lock`, `composer.lock`, `uv.lock` | Must be modified via package manager |
+| Certificates & keys | `.pem`, `.key`, `.crt`, `.p12`, `.pfx` | Sensitive cryptographic material |
+| Credential files | `credentials.json`, `secrets.yaml`, `secrets.yml`, `secrets.json`, `.secrets` | Contains secrets |
+| Auth directories | `.ssh/`, `.aws/` | Contains authentication data |
+| Auth config files | `.netrc`, `.npmrc`, `.pypirc` | Contains authentication credentials |
+| SSH private keys | `id_rsa`, `id_ed25519`, `id_ecdsa` | SSH private key files |
+
+## How It Works
+
+### Two-Hook Architecture
+
+The plugin registers two PreToolUse hooks to cover different attack vectors:
+
+```
+Claude calls Edit or Write tool
+  │
+  └─→ guard-protected.py checks file_path against protected patterns
+       │
+       ├─→ Match → exit 2 (block)
+       └─→ No match → exit 0 (allow)
+
+Claude calls Bash tool
+  │
+  └─→ guard-protected-bash.py extracts write targets from the command
+       │
+       ├─→ Detects: > redirect, >> append, tee, cp, mv, sed -i, cat heredoc
+       ├─→ Checks each target against protected patterns
+       ├─→ Any match → exit 2 (block)
+       └─→ No match → exit 0 (allow)
+```
+
+### Bash Write Detection
+
+The Bash guard parses commands for write-indicating patterns and extracts the target file path:
+
+| Pattern | Example |
+|---------|---------|
+| Redirect (`>`, `>>`) | `echo "key=val" > .env` |
+| `tee` / `tee -a` | `cat data \| tee .env` |
+| `cp` / `mv` | `cp template .env` |
+| `sed -i` | `sed -i 's/old/new/' .env` |
+| `cat` heredoc | `cat <<EOF > .env` |
+
+### Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| JSON parse failure | Fails closed (exit 2) — blocks the operation |
+| Other exceptions | Fails open (exit 0) — logs error, allows the operation |
+
+### Timeout
+
+Both hooks have a 5-second timeout.
+
+## Plugin Structure
+
+```
+protected-files-guard/
+├── .claude-plugin/
+│   └── plugin.json              # Plugin metadata
+├── hooks/
+│   └── hooks.json               # PreToolUse hook registrations (Edit|Write + Bash)
+├── scripts/
+│   ├── guard-protected.py       # Edit/Write file path checker
+│   └── guard-protected-bash.py  # Bash command write target checker
+└── README.md                    # This file
+```
+
+## Requirements
+
+- Python 3.11+
+- Claude Code with plugin hook support

package/.devcontainer/plugins/devs-marketplace/plugins/protected-files-guard/hooks/hooks.json

@@ -1,17 +1,27 @@
 {
-  "description": "Block modifications to protected files",
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/guard-protected.py",
-            "timeout": 5
-          }
-        ]
-      }
-    ]
-  }
+	"description": "Block modifications to protected files",
+	"hooks": {
+		"PreToolUse": [
+			{
+				"matcher": "Edit|Write",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/guard-protected.py",
+						"timeout": 5
+					}
+				]
+			},
+			{
+				"matcher": "Bash",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/guard-protected-bash.py",
+						"timeout": 5
+					}
+				]
+			}
+		]
+	}
 }

package/.devcontainer/plugins/devs-marketplace/plugins/protected-files-guard/scripts/guard-protected-bash.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""
+Block bash commands that write to protected files.
+
+Reads tool input from stdin, checks the command field for write operations
+targeting protected file patterns.
+Exit code 2 blocks the command with error message.
+Exit code 0 allows the command to proceed.
+"""
+
+import json
+import re
+import sys
+
+# Same patterns as guard-protected.py
+PROTECTED_PATTERNS = [
+    (r"(^|/)\.env$", "Blocked: .env contains secrets - edit manually if needed"),
+    (
+        r"(^|/)\.env\.[^/]+$",
+        "Blocked: .env.* files contain secrets - edit manually if needed",
+    ),
+    (r"(^|/)\.git(/|$)", "Blocked: .git is managed by git"),
+    (
+        r"(^|/)package-lock\.json$",
+        "Blocked: package-lock.json - use npm install instead",
+    ),
+    (r"(^|/)yarn\.lock$", "Blocked: yarn.lock - use yarn install instead"),
+    (r"(^|/)pnpm-lock\.yaml$", "Blocked: pnpm-lock.yaml - use pnpm install instead"),
+    (r"(^|/)Gemfile\.lock$", "Blocked: Gemfile.lock - use bundle install instead"),
+    (r"(^|/)poetry\.lock$", "Blocked: poetry.lock - use poetry install instead"),
+    (r"(^|/)Cargo\.lock$", "Blocked: Cargo.lock - use cargo build instead"),
+    (r"(^|/)composer\.lock$", "Blocked: composer.lock - use composer install instead"),
+    (r"(^|/)uv\.lock$", "Blocked: uv.lock - use uv sync instead"),
+    (r"\.pem$", "Blocked: .pem files contain sensitive cryptographic material"),
+    (r"\.key$", "Blocked: .key files contain sensitive cryptographic material"),
+    (r"\.crt$", "Blocked: .crt certificate files should not be edited directly"),
+    (r"\.p12$", "Blocked: .p12 files contain sensitive cryptographic material"),
+    (r"\.pfx$", "Blocked: .pfx files contain sensitive cryptographic material"),
+    (r"(^|/)credentials\.json$", "Blocked: credentials.json contains secrets"),
+    (r"(^|/)secrets\.yaml$", "Blocked: secrets.yaml contains secrets"),
+    (r"(^|/)secrets\.yml$", "Blocked: secrets.yml contains secrets"),
+    (r"(^|/)secrets\.json$", "Blocked: secrets.json contains secrets"),
+    (r"(^|/)\.secrets$", "Blocked: .secrets file contains secrets"),
+    (r"(^|/)\.ssh/", "Blocked: .ssh/ contains sensitive authentication data"),
+    (r"(^|/)\.aws/", "Blocked: .aws/ contains AWS credentials"),
+    (r"(^|/)\.netrc$", "Blocked: .netrc contains authentication credentials"),
+    (
+        r"(^|/)\.npmrc$",
+        "Blocked: .npmrc may contain auth tokens - edit manually if needed",
+    ),
+    (r"(^|/)\.pypirc$", "Blocked: .pypirc contains PyPI credentials"),
+    (r"(^|/|-)id_rsa($|\.)", "Blocked: SSH private key file"),
+    (r"(^|/)id_ed25519", "Blocked: SSH private key file"),
+    (r"(^|/)id_ecdsa", "Blocked: SSH private key file"),
+]
+
+# Patterns that indicate a bash command is writing to a file
+# Each captures the target file path for checking against PROTECTED_PATTERNS
+WRITE_PATTERNS = [
+    # Redirect: > file, >> file
+    r"(?:>|>>)\s*([^\s;&|]+)",
+    # tee: tee file, tee -a file
+    r"\btee\s+(?:-a\s+)?([^\s;&|]+)",
+    # cp/mv: cp src dest, mv src dest
+    r"\b(?:cp|mv)\s+(?:-[^\s]+\s+)*[^\s]+\s+([^\s;&|]+)",
+    # sed -i: sed -i '' file
+    r'\bsed\s+-i[^\s]*\s+(?:\'[^\']*\'\s+|"[^"]*"\s+|[^\s]+\s+)*([^\s;&|]+)',
+    # cat > file (heredoc style)
+    r"\bcat\s+(?:<<[^\s]*\s+)?>\s*([^\s;&|]+)",
+]
+
+
+def extract_write_targets(command: str) -> list[str]:
+    """Extract file paths that the command writes to."""
+    targets = []
+    for pattern in WRITE_PATTERNS:
+        for match in re.finditer(pattern, command):
+            target = match.group(1).strip("'\"")
+            if target:
+                targets.append(target)
+    return targets
+
+
+def check_path(file_path: str) -> tuple[bool, str]:
+    """Check if file path matches any protected pattern."""
+    normalized = file_path.replace("\\", "/")
+    for pattern, message in PROTECTED_PATTERNS:
+        if re.search(pattern, normalized, re.IGNORECASE):
+            return True, message
+    return False, ""
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+        tool_input = input_data.get("tool_input", {})
+        command = tool_input.get("command", "")
+
+        if not command:
+            sys.exit(0)
+
+        targets = extract_write_targets(command)
+
+        for target in targets:
+            is_protected, message = check_path(target)
+            if is_protected:
+                print(json.dumps({"error": f"{message} (via bash command)"}))
+                sys.exit(2)
+
+        sys.exit(0)
+
+    except json.JSONDecodeError:
+        # Fail closed: can't parse means can't verify safety
+        sys.exit(2)
+    except Exception as e:
+        # Log error but don't block on hook failure
+        print(f"Hook error: {e}", file=sys.stderr)
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.devcontainer/plugins/devs-marketplace/plugins/protected-files-guard/scripts/guard-protected.py

@@ -20,7 +20,7 @@ PROTECTED_PATTERNS = [
         "Blocked: .env.* files contain secrets - edit manually if needed",
     ),
     # Git internals
-    (r"(^|/)\.git/", "Blocked: .git/ directory is managed by git"),
+    (r"(^|/)\.git(/|$)", "Blocked: .git is managed by git"),
     # Lock files (should be modified via package manager)
     (
         r"(^|/)package-lock\.json$",
@@ -97,8 +97,8 @@ def main():
         sys.exit(0)
 
     except json.JSONDecodeError:
-        # If we can't parse input, allow by default
-        sys.exit(0)
+        # Fail closed: can't parse means can't verify safety
+        sys.exit(2)
     except Exception as e:
         # Log error but don't block on hook failure
         print(f"Hook error: {e}", file=sys.stderr)

package/.devcontainer/plugins/devs-marketplace/plugins/ticket-workflow/README.md

@@ -0,0 +1,96 @@
+# ticket-workflow
+
+Claude Code plugin that provides an EARS-based ticket workflow with GitHub issues as the single source of truth. Command-driven — no hooks or scripts, just a custom system prompt and four slash commands.
+
+## What It Does
+
+Provides a structured workflow for creating, planning, reviewing, and shipping work through GitHub issues. All major decisions, plans, and progress are posted as issue comments to maintain an audit trail.
+
+### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/ticket:new` | Transform requirements into a structured GitHub issue with EARS-formatted business requirements |
+| `/ticket:work` | Retrieve a ticket, create a technical implementation plan, and post it to the GitHub issue |
+| `/ticket:review-commit` | Conduct a thorough code review, verify requirements are met, and commit with a detailed message |
+| `/ticket:create-pr` | Create a pull request with aggressive security and architecture review |
+
+### EARS Requirement Format
+
+Every requirement uses one of these patterns:
+
+| Type | Template |
+|------|----------|
+| Ubiquitous | The `<system>` shall `<response>`. |
+| Event-Driven | WHEN `<trigger>`, the `<system>` shall `<response>`. |
+| State-Driven | WHILE `<state>`, the `<system>` shall `<response>`. |
+| Unwanted Behavior | IF `<condition>`, THEN the `<system>` shall `<response>`. |
+| Optional Feature | WHERE `<feature>`, the `<system>` shall `<response>`. |
+
+## How It Works
+
+### Workflow Lifecycle
+
+```
+/ticket:new [requirements]
+  │
+  └─→ Gather requirements → Create EARS-formatted GitHub issue
+       │
+       └─→ /ticket:work #123
+            │
+            └─→ Fetch issue → Create technical plan → Post plan as issue comment
+                 │
+                 │  ... implementation work ...
+                 │
+                 └─→ /ticket:review-commit
+                      │
+                      └─→ Review changes → Verify requirements → Commit
+                           │
+                           └─→ /ticket:create-pr
+                                │
+                                └─→ Create PR → Security/architecture review → Post findings
+```
+
+### Ticket Structure
+
+Each ticket created by `/ticket:new` includes:
+- **Overview**: Plain language description
+- **Requirements**: EARS-formatted business requirements
+- **Technical Questions**: Open questions for implementation
+- **Acceptance Criteria**: Verifiable conditions for completion
+
+### Audit Trail
+
+| Action | Destination |
+|--------|-------------|
+| Plans | Issue comment |
+| Decisions | Issue comment |
+| Requirement changes | Issue comment |
+| Commit summaries | Issue comment |
+| Review findings | PR + issue comment |
+| Created sub-issues | Linked to source ticket |
+
+### Custom System Prompt
+
+The plugin injects a system prompt that defines the assistant persona, coding standards (SOLID, DRY, KISS, YAGNI), testing standards, and the ticket workflow rules. This ensures consistent behavior across all four commands.
+
+## Plugin Structure
+
+```
+ticket-workflow/
+├── .claude-plugin/
+│   ├── plugin.json                  # Plugin metadata
+│   ├── system-prompt.md             # Custom system prompt (persona + workflow rules)
+│   └── commands/
+│       ├── ticket:new.md            # Create EARS-formatted issue
+│       ├── ticket:work.md           # Implementation planning
+│       ├── ticket:review-commit.md  # Review and commit
+│       └── ticket:create-pr.md      # PR creation with review
+└── README.md                        # This file
+```
+
+## Requirements
+
+- Claude Code with plugin command support
+- [GitHub CLI](https://cli.github.com/) (`gh`) installed and authenticated
+- A GitHub repository as the working context

package/.devcontainer/plugins/devs-marketplace/plugins/workspace-scope-guard/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+	"name": "workspace-scope-guard",
+	"description": "Enforces working directory scope — blocks writes and warns on reads outside the project",
+	"author": {
+		"name": "AnExiledDev"
+	}
+}

package/.devcontainer/plugins/devs-marketplace/plugins/workspace-scope-guard/README.md

@@ -0,0 +1,94 @@
+# workspace-scope-guard
+
+Claude Code plugin that enforces working directory scope for all file operations. Blocks writes outside the current project directory and warns on reads outside it. Prevents accidental cross-project modifications in multi-project workspaces.
+
+## What It Does
+
+Intercepts file operations (Read, Write, Edit, NotebookEdit, Glob, Grep) and checks whether the target path is within the current working directory:
+
+| Operation | Out-of-scope behavior |
+|-----------|-----------------------|
+| Write, Edit, NotebookEdit | **Blocked** (exit 2) with error message |
+| Read, Glob, Grep | **Warned** (exit 0) with advisory context |
+
+When the current working directory is `/workspaces` (the workspace root), all operations are unrestricted.
+
+### Allowed Prefixes
+
+These paths are always permitted regardless of working directory:
+
+| Path | Reason |
+|------|--------|
+| `/workspaces/.claude/` | Claude Code configuration |
+| `/workspaces/.tmp/` | Temporary files |
+| `/workspaces/.devcontainer/` | Container configuration |
+| `/tmp/` | System temp directory |
+| `/home/vscode/` | User home directory |
+
+## How It Works
+
+### Hook Lifecycle
+
+```
+Claude calls Read, Write, Edit, NotebookEdit, Glob, or Grep
+  │
+  └─→ PreToolUse hook fires
+       │
+       └─→ guard-workspace-scope.py
+            │
+            ├─→ cwd is /workspaces? → allow (unrestricted)
+            ├─→ No target path? → allow (tool defaults to cwd)
+            ├─→ Resolve path via os.path.realpath() (handles symlinks/worktrees)
+            ├─→ Path is within cwd? → allow
+            ├─→ Path matches allowed prefix? → allow
+            ├─→ Write tool + out of scope → exit 2 (block)
+            └─→ Read tool + out of scope → exit 0 (warn via additionalContext)
+```
+
+### Symlink and Worktree Handling
+
+Target paths are resolved with `os.path.realpath()` before scope checking. This correctly handles:
+- Symbolic links that point outside the working directory
+- Git worktree paths (`.git` file containing `gitdir:`)
+
+### Path Field Mapping
+
+The script extracts the target path from different tool input fields:
+
+| Tool | Input Field |
+|------|-------------|
+| Read | `file_path` |
+| Write | `file_path` |
+| Edit | `file_path` |
+| NotebookEdit | `notebook_path` |
+| Glob | `path` |
+| Grep | `path` |
+
+### Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| JSON parse failure | Fails open (exit 0) |
+| Other exceptions | Fails open (exit 0) — logs error to stderr |
+
+### Timeout
+
+The hook has a 5-second timeout.
+
+## Plugin Structure
+
+```
+workspace-scope-guard/
+├── .claude-plugin/
+│   └── plugin.json                # Plugin metadata
+├── hooks/
+│   └── hooks.json                 # PreToolUse hook registration
+├── scripts/
+│   └── guard-workspace-scope.py   # Scope enforcement (PreToolUse)
+└── README.md                      # This file
+```
+
+## Requirements
+
+- Python 3.11+
+- Claude Code with plugin hook support