claude-dev-env 1.38.1 → 1.40.0

package/docs/CODE_RULES.md

@@ -52,6 +52,16 @@ These rules are automatically enforced by `code_rules_enforcer.py`. Violations b
 | Hardcoded user paths | No string literals naming a specific user's home directory in production code (`C:/Users/jon/...`, `/Users/alice/...`, `/home/bob/...`). Use `pathlib.Path.home()` or `os.path.expanduser('~')`. **Exempt:** test files, `config/` files, workflow registry paths (`/workflow/`, `_tab.py`, `/states.py`, `/modules.py`), Django migrations (`/migrations/`), and hook infrastructure (the enforcer embeds path patterns and must not self-block). |
 | sys.path.insert dedup | `sys.path.insert(0, X)` must be guarded by `if X not in sys.path:` (or equivalent membership test) so reloads do not push the same entry repeatedly. **Test files exempt.** |
 | Unused module-level imports | Module-level imports never referenced in the file body are flagged. Skipped for files declaring `__all__` (re-exports), files using `TYPE_CHECKING` (annotation-only imports), and lines marked `# noqa`. **Test files exempt.** |
+| Banned identifiers | Single-letter or 2–4 char abbreviations in production code: `ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`. Test files exempt; loop counters `i`/`j`/`k` and exception `e` exempt. See §5 for the full list and rationale. |
+| Banned function prefixes | Function names starting with `handle_`, `process_`, `manage_`, or `do_` are flagged — these prefixes describe nothing about behavior. Name functions after the noun they produce or the verb they perform (`fetch_user`, `validate_payload`). **Test files exempt.** |
+| Type escape hatches | `from typing import Any`, `cast()`, and inline `Any` in production are flagged outside boundary files (`__init__.py`, `protocols.py`, `types.py`, `conftest.py`). Name the concrete shape instead. |
+| Bare except | `except:` and `except BaseException:` swallow KeyboardInterrupt/SystemExit; `except Exception:` hides bugs by catching nearly every error class. Name the specific exception(s) you intend to catch (tuple form `except (ValueError, KeyError):` is fine). **Test files and hook infrastructure exempt.** |
+| Boundary types — Any in signatures | `Any` appearing directly or nested inside a generic in a function signature (parameters, return type) or class attribute annotation is flagged. Local variable annotations are exempt. Files named `protocols.py` or `types.py` are interface-declaration surfaces and exempt. |
+| Stub implementations | Functions whose body is `pass`, `...`, or `raise NotImplementedError` in production code are flagged unless declared abstract (`@abstractmethod`) or part of a `Protocol`. Implement the function or remove it. |
+| TypedDict encode/decode pairs | Every `class FooPayload(TypedDict):` in production code must have companion `_encode_foo_payload(...)` and `_decode_foo_payload(...)` functions in the same module — boundary serialization should not leak to callers. |
+| Test-mode branching in production | Reading `TESTING`, `PYTEST_CURRENT_TEST`, `IS_TEST`, etc. from production code creates two parallel implementations. Use dependency injection so production stays single-path. **Test files and hook infrastructure exempt.** |
+| Thin wrapper files | A non-`__init__.py` module whose body is only imports (optionally with an `__all__` assignment) is a re-export indirection with no payload. Callers should import from the real module. `__init__.py` is the canonical re-export surface and is exempt. |
+| Docstring format (Google-style) | Public functions/methods (no leading underscore, not dunder, body > 3 lines, not `@property`/`@abstractmethod`) require Google-style `Args:` / `Returns:` (or `Yields:`) / `Raises:` sections matching the signature. **Test files exempt.** |
 
 ### Where UPPER_SNAKE is allowed
 
@@ -112,7 +122,7 @@ Full words only. No mental translation.
 
 **Exception:** `i`, `j`, `k` in loops; `e` for exception.
 
-**Extended naming rules** (from readability-review rubric):
+**Extended naming rules** :
 - Loop vars: `each_order`, `each_user` (prefix `each_`)
 - Booleans: `is_valid`, `has_permission`, `should_retry` (prefix `is_`/`has_`/`should_`/`can_`)
 - Collections: `all_orders`, `all_users` (prefix `all_`)
@@ -227,6 +237,57 @@ Parent knows: nothing about child's internals
 
 ---
 
+## 9.5 NO THIN WRAPPER MODULES
+
+A non-`__init__.py` module whose body is only imports (optionally with an `__all__` assignment) is a thin wrapper. Callers should import from the real module. The wrapper adds no payload — only an indirection layer that obscures where things live.
+
+`__init__.py` is the canonical re-export surface and is exempt; package surface aggregation is its job.
+
+---
+
+## 9.6 NO BACKWARDS-COMPATIBILITY SHIMS
+
+Removed code is removed. Do not leave behind:
+
+- Renamed functions that re-export the old name with a `# deprecated` comment
+- `_old_*` aliases pointing to the new implementation
+- Wrapper modules whose only purpose is to keep an old import path alive
+- `// removed in vX` comment markers next to deleted blocks
+
+When a symbol moves or its signature changes, update the call sites in the same commit. The git log records what changed; the codebase records what exists now.
+
+> **See also:** [`skills/code/SKILL.md`](../skills/code/SKILL.md) §5 ("No fallback paths, no back-compat shims, no legacy code") states the same principle as a session-start prompt directive. This section is the authoritative wording; the skill amplifies it for `/code` sessions.
+
+---
+
+## 9.7 NO FALLBACK / BEST-EFFORT WRAPPERS
+
+Do not wrap a call in `try/except` that swallows the failure and returns a default unless the caller has explicitly opted in to that behavior at the boundary.
+
+```python
+# BAD — silently hides every failure mode
+def fetch_user(user_id: int) -> User | None:
+    try:
+        return _registry[user_id]
+    except Exception:
+        return None
+```
+
+```python
+# GOOD — names the specific failure and propagates the rest
+def fetch_user(user_id: int) -> User | None:
+    try:
+        return _registry[user_id]
+    except KeyError:
+        return None
+```
+
+Fallback values mask programming errors (KeyError vs RuntimeError vs AttributeError all collapse to "None"), making debugging impossible. Production code names the specific failure mode it intends to handle.
+
+> **See also:** [`skills/code/SKILL.md`](../skills/code/SKILL.md) §2 ("No `try`/`except` in core logic that recovers, softens, or best-efforts a failure") states the same principle as a session-start prompt directive. The hook check `check_bare_except` enforces the narrowest case (bare/`Exception`/`BaseException` handlers); this section + the `code` skill cover the broader "any swallowing handler" intent.
+
+---
+
 ## 10. NO REDUNDANT DATA FETCHES
 
 If you already have data, don't fetch again.
@@ -243,6 +304,53 @@ const profile = await db.profile.first();
 
 ---
 
+## 11. ENFORCEMENT SURFACES
+
+Rules in this document are enforced through three distinct surfaces, each with different latency and reach. Knowing which surface owns a rule tells you what happens when you violate it.
+
+| Surface | What it catches | When it runs | Failure mode |
+|---------|-----------------|--------------|--------------|
+| **⚡ Hook** | Pattern-matchable violations: comments, magic values, banned identifiers, bare except, boundary `Any`, thin wrappers, docstring shape, etc. | PreToolUse on Write/Edit (and PostToolUse advisories) | Blocks the write — Claude must fix and retry |
+| **🤖 Prompt** | Judgment-driven principles: SRP, Right-Sized Engineering, KISS, conservative-action, BDD discovery; strict-mode standards via the `/code` skill (no `Any`/`cast`, immutable TypedDicts, DI hooks, 100% branch coverage, no fallback `try/except`) | Read into the model context at session start (CLAUDE.md, rules/*.md, skill prepends) | Influences Claude's decisions; no automatic block |
+| **👥 Audit rubric** | Cross-file architectural concerns: SOLID misapplication, abstraction leaks, multi-file coupling | Run on demand via `/check`, `/readability-review`, agent-driven audits | Surfaces in audit output; humans decide whether to act |
+
+### Prompt-enforced rules (no hook coverage)
+
+These principles cannot be reduced to a regex or AST visitor. They live in user-private `~/.claude/rules/` and `~/.claude/CLAUDE.md`, and are read into context every session:
+
+- **Right-Sized Engineering** — concrete classes for single concretions, functions when no state, no DI frameworks for solo-scale code
+- **SRP / SOLID misapplication signals** — see §7.5
+- **conservative-action** — when intent is ambiguous, ask before acting
+- **explore-thoroughly** — investigate before committing to an approach
+- **agent-spawn-protocol** — verify context before delegating to a subagent
+- **`code` skill ([`skills/code/SKILL.md`](../skills/code/SKILL.md))** — invoked via `/code`, prepends strict-mode standards for the entire session: no `Any`/`cast()`/`# type: ignore`, immutable TypedDicts with manual `_encode_*`/`_decode_*` and `require_*` validation, per-module `_test_hooks.py` for DI, 100% statement + branch coverage, zero mocks. Several criteria overlap with §9.6/§9.7 and the ⚡ B-series checks; the skill is the canonical entry point when the user explicitly opts into strict mode for an implementation task.
+
+### Audit-rubric reference
+
+For multi-file architectural reviews see [`packages/claude-dev-env/audit-rubrics/`](../audit-rubrics/). Categories A–F, I, K stay as agent rubrics rather than ⚡ blocking rules because they require multi-file reasoning that single-file hooks cannot perform.
+
+---
+
+## 12. DEFERRED RULES (P1 — TRACKED, NOT ENFORCED)
+
+The following rules are documented in `~/.claude/rules/` and applied by Claude through prompt context, but have no hook coverage in `code_rules_enforcer.py`. Promotion to ⚡ blocking enforcement is on the backlog and will land as separate hardening commits.
+
+| Rule | Source | Promotion path |
+|------|--------|----------------|
+| Context7 before web search for library/SDK questions | [`rules/context7.md`](../rules/context7.md) | New PreToolUse hook on WebSearch when query mentions a library name |
+| Verify-before-asking checklist | [`rules/verify-before-asking.md`](../rules/verify-before-asking.md) | Stop hook scanning AskUserQuestion calls for "where is", "what file", etc. |
+| BDD naming (`should_…` / `describe…it…`) | [`rules/bdd.md`](../rules/bdd.md) | `code_rules_enforcer.py::check_test_naming` (new) — flag test functions starting with `test_` lacking corresponding `should_…` form |
+| `gh` pagination requires `--paginate --slurp` plus external `jq` | [`rules/gh-paginate.md`](../rules/gh-paginate.md) | PreToolUse Bash hook matching `gh api .*/(reviews\|comments)` without `--paginate --slurp` |
+| Self-contained documentation (no "as discussed", "Option A", session refs) | [`rules/self-contained-docs.md`](../rules/self-contained-docs.md) | PostToolUse Write hook scanning new `.md` content for conversational refs |
+| Temp file cleanup at end of task | [`rules/cleanup-temp-files.md`](../rules/cleanup-temp-files.md) | Stop hook scanning for files Claude created and did not delete |
+| No credentials committed to git | [`rules/git-workflow.md`](../rules/git-workflow.md) | PreToolUse Bash hook on `git commit` scanning staged diff for high-entropy strings, `.env` patterns, and known credential file extensions |
+| Per-module DI hooks (`_test_hooks.py` sibling) instead of `if TESTING:` branching | [`skills/code/SKILL.md`](../skills/code/SKILL.md) §4 | New `check_test_hooks_sibling()` — when a module imports a side-effect dependency and a test exists, require a `<module>_test_hooks.py` sibling exposing the injection points |
+| 100% statement + branch coverage with zero mocks | [`skills/code/SKILL.md`](../skills/code/SKILL.md) §3 | CI check (not write-time) — `pytest --cov-branch --cov-fail-under=100` on touched packages; covers only what the diff added |
+| `TypedDict` `_decode_*` calls `require_*` on every field | [`skills/code/SKILL.md`](../skills/code/SKILL.md) §6 | Extend `check_typed_dict_encode_decode` (B2) — when the decoder is present, AST-verify every TypedDict field appears as a `require_*` call before the return |
+| `Protocol` signatures match the real implementation exactly | [`skills/code/SKILL.md`](../skills/code/SKILL.md) Gotchas | mypy `--strict` over the protocol module catches this; promotion = add `[tool.mypy] strict = true` per-module override in `pyproject.toml` for files declaring `Protocol` subclasses |
+
+---
+
 ## QUICK CHECKLIST
 
 ```
@@ -257,6 +365,16 @@ Hook will enforce:
 [⚡] Logging format args
 [ ] File length reasonable (advisory at 400, strong nudge at 1000 — see §6.5)
 [⚡] Constants in config/
+[⚡] No banned identifiers (ctx, cfg, msg, btn, idx, cnt, tmp, elem, val)
+[⚡] No banned function prefixes (handle_, process_, manage_, do_)
+[⚡] No type escape hatches (Any imports, cast(), inline Any)
+[⚡] No bare except / except Exception / except BaseException
+[⚡] No Any in function signatures or class attributes (boundary types)
+[⚡] No stub bodies (pass / ... / raise NotImplementedError) outside abstract methods
+[⚡] TypedDict has companion _encode_*/_decode_* in same module
+[⚡] No test-mode branching in production (TESTING / PYTEST_CURRENT_TEST)
+[⚡] No thin wrapper modules (imports only, optionally with __all__, outside __init__.py)
+[⚡] Public functions have Google-style Args:/Returns:/Raises: when warranted
 
 Manual check:
 [ ] No abbreviations?
@@ -264,5 +382,7 @@ Manual check:
 [ ] Self-contained components?
 [ ] SRP holds (one reason to change per function/class/module)?
 [ ] OCP/LSP/ISP/DIP only applied where abstractions already earn their keep (see §7.5)?
-[ ] Readability: /check or /readability-review
+[ ] No backwards-compatibility shims (§9.6)?
+[ ] No fallback/best-effort wrappers (§9.7)?
+[ ] Readability: /check
 ```

package/docs/PR_DESCRIPTION_GUIDE.md

@@ -1,95 +1,158 @@
-# GitHub PR Summary Writing Guide for AI
+# PR Description Guide
 
-Use this guide when writing pull request descriptions. Follow these best practices to create clear, professional, and reviewable PR summaries.
+This guide describes the PR-body shape that the `pr-description-writer` agent produces and that the `pr_description_enforcer` PreToolUse hook validates against. The style mirrors merged pull requests in `anthropics/claude-code`, `anthropics/claude-code-action`, and `anthropics/claude-cli-internal`.
 
-## Required Sections
+## Three shapes, picked from the diff
 
-### What (Changes)
+Pick the shape from the size and risk of the change, not from a template.
 
-- Concise statement of what was changed
-- What files or systems were modified
-- What functionality was added, removed, or improved
-- Keep to 2-3 sentences maximum
+| Signal | Shape |
+|---|---|
+| 1-3 files, mechanical change (pin bump, link fix, typo, single-line config), no behavior change | **Trivial** -- one declarative sentence, no headers |
+| Behavior change, bug fix, small feature; under ~15 files | **Standard** -- intro paragraph + `## Changes` + `## Test plan` (or `## Validation`) |
+| New subsystem, refactor across many files, schema or contract change, anything with a caveat | **Heavy** -- intro + `## Problem` + `## Fix` (or `## Changes`) + `## Verification` + extra sections as needed |
 
-### Why (Problem/Context)
+Prefer the smaller shape when in doubt.
 
-- Explain the problem this PR solves
-- Provide business or technical context
-- Reference related issue numbers using `#123` or `Fixes #123`, `Closes #456`
-- If no issue exists, briefly explain the motivation
+## Shape 1: Trivial
 
-### How (Approach/Solution)
+One sentence. No Markdown headers. Optional `Fixes #N` line.
 
-- Describe your implementation approach
-- Explain any design decisions or trade-offs
-- Include architectural changes if applicable
-- Note any breaking changes prominently
+```
+Pin third-party GitHub Actions references to immutable commit SHAs.
+```
 
-## Supporting Details
+```
+Bump pinned Bun from 1.3.6 to 1.3.14.
 
-### Testing and Quality
+Fixes #1311.
+```
 
-- What tests were added/modified
-- How to manually verify the changes (if applicable)
-- Any areas of concern or limitations
-- Performance impact (if relevant)
+## Shape 2: Standard
 
-### Dependencies and Risk
+```
+<One short intro paragraph stating the change and why it matters.
+ Reference the failure mode or user-visible symptom when there is one.>
 
-- New dependencies introduced (if any)
-- Backward compatibility status
-- Potential side effects
-- Migration steps (if needed)
+Fixes #<n>.
 
-## Optional but Valuable
+## Changes
 
-### Related Issues/PRs
+- `path/to/file.ext`: short clause describing the change
+- `path/to/other.ext`: short clause
+- `tests/foo.test.ts`: 2 new cases for X
 
-- Link to dependent PRs or issues
-- Note any follow-up work needed
+## Test plan
 
-### Screenshots/Examples (for UI changes)
+- `bun test test/foo.test.ts`
+- `bun run typecheck`
+- Manual: reproduce on a branch named `feature/a,b`; confirm no rejection
+```
 
-- Before/after comparisons when visual changes are involved
+The intro paragraph carries the Why -- no `## Why` header needed when one paragraph is enough.
 
-### Reviewer Guidance
+## Shape 3: Heavy
 
-- Specific areas to focus on
-- Questions for reviewers
-- Deployment considerations
+```
+<Two- to four-sentence intro: scope, motivation, user-visible effect.
+ Link to the prior PR or issue that motivates this one if applicable.>
 
-## Tone and Style Guidelines
+Fixes #<n>.
 
-- Be clear and concise -- reviewers scan quickly
-- Use second person sparingly -- focus on what the code does, not what the reviewer should do
-- Avoid jargon -- explain technical terms if non-obvious
-- Use markdown formatting -- bullets, code blocks, headers for readability
-- Be honest about limitations -- acknowledge trade-offs and known issues
-- Assume reviewers are unfamiliar -- provide sufficient context
+## Problem
 
-## What to Avoid
+<Concrete description of the failure mode or gap. Include the actual
+ error text, a reproduction, or the symptomatic log line in a fenced
+ code block when it helps.>
 
-- Vague statements like "fix bug" or "update code"
-- AI-generated summaries without human verification
-- Large walls of text -- break into sections
-- Repeating information from commit messages
-- References to temporary branch names or internal jargon without context
+```
+<example error or reproduction>
+```
+
+## Fix
 
-## Example Structure
+<What the change does at the level a reviewer needs to evaluate it.
+ Reference the file or function by path/name. Don't restate the diff
+ line-by-line -- the reviewer can read the code.>
 
-```markdown
-## Description
-Brief 1-2 sentence overview of the change.
+- `src/path/file.ts`: brief description
+- `src/path/other.ts`: brief description
 
-## Why
-Problem/context and reference to related issue (#123).
+## Verification
 
-## How
-Implementation approach and design decisions.
+- Command 1
+- Command 2 (with output count when useful: "666 pass, 0 fail")
+- Manual scenarios walked through
 
-## Testing
-How this was tested and verified.
+## Caveat
 
-## Risk Assessment
-Any breaking changes, dependencies, or concerns.
+<Anything a reviewer or downstream user needs to know that isn't in
+ the diff. Omit this section when there is no caveat.>
 ```
+
+Optional heavy-shape sections, used when they earn their place:
+
+- `## Runtime behavior` -- when the change preserves behavior but moves it.
+- `## Components` -- a small table when the PR introduces multiple named artifacts.
+- `## Backward compatibility` -- when an older consumer might still hit this code path.
+- `## Context` -- background a reviewer outside the area would need.
+
+## Section vocabulary
+
+Pick from these. Don't invent new ones, and don't use synonyms within one PR:
+
+| Intent | Header (pick one) |
+|---|---|
+| What this PR is and why | `## Summary` -- or no header (preferred when 1-3 sentences) |
+| The failure being fixed | `## Problem` -- or no header when the intro paragraph carries it |
+| The change itself | `## Changes` or `## Fix` |
+| How it was verified | `## Test plan`, `## Validation`, `## Verification`, or `## Testing` |
+| Things to know | `## Caveat`, `## Runtime behavior`, `## Backward compatibility`, `## Context` |
+
+## File reference style
+
+- Always backtick file paths: `` `src/github/operations/branch.ts` ``.
+- Use the full path from repo root, not just the basename, unless the basename is unambiguous within the PR.
+- Bullet lists describing per-file changes lead with the backticked path and a colon:
+  - `` `src/foo.ts`: whitelists `,` in branch names ``
+  - `` `test/foo.test.ts`: 3 new cases for comma-bearing branches ``
+- Prose calling out a single primary file bolds the backticked filename plus a colon: `` **`branch.ts`**: ... ``.
+
+## Cross-references
+
+- Issue/PR shorthand: `#1311` (same repo), `anthropics/claude-code#40576` (cross-repo).
+- `Fixes #N` and `Closes #N` close the linked issue on merge -- use them deliberately.
+- `Linear: CC-1723` -- one line, no Markdown, after the intro paragraph or at the bottom.
+- "Same change as <repo>#<n>" / "Follow-up to #<n>" -- one-liners that orient a reviewer.
+
+## Markers and footers
+
+- `<!-- NO CHANGELOG -->` on its own line, at the very end, for docs-only or CI-only PRs in repos that auto-generate changelogs from PR titles.
+- Don't add a "Generated with Claude Code" footer -- merged Anthropic PRs don't use one consistently, and the repo's commit trailer covers attribution.
+
+## What the hook checks
+
+`pr_description_enforcer.py` runs on `gh pr create` and `gh pr edit` invocations that include a body. It blocks when any of the following are true:
+
+- The body, after stripping Markdown ceremony (headers, code fences, bullet markers, bold/emphasis, link text), contains fewer than 40 characters of prose. A skeleton of `## Summary` + `## Changes` + bullets with no Why paragraph fails here.
+- The body contains vague phrases like `fix bug`, `update code`, `minor changes`, or `various fixes`.
+
+The hook does not require any specific section headers -- `## Summary`, `## Problem`, `## Fix`, `## Changes`, `## Test plan` are all optional, including any combination of them. A single substantive sentence ("Pin third-party GitHub Actions references to immutable commit SHAs.") satisfies the check.
+
+When the hook blocks, it points the caller at the `pr-description-writer` agent and at this guide.
+
+## Tone
+
+- Plain language. "The pull engine would blindly overwrite any record marked as 'synced'" -- not "PullEngine.run() exhibited non-idempotent behavior".
+- Active voice. "Add `,` to the whitelist" -- not "`,` was added to the whitelist".
+- No filler. Start with the content, not "This PR..." or "In this change...".
+- No restating the diff. Trust the reviewer to read the code; explain the parts they can't infer.
+- No hedging ("should", "might", "I think") unless the uncertainty is real -- in which case say "not yet verified" and call it out.
+
+## What to avoid
+
+- Code snippets that simply repeat the diff. Code blocks are for error reproductions, failing commands, or before/after when the contrast is the point.
+- Technical jargon for non-obvious internals ("Dexie transaction" -> "database transaction").
+- Multi-line preamble. The PR title already says what the change is.
+- Section headers over empty content. If `## Caveat` would be empty, drop the header.
+- Second-person commentary directed at the reviewer ("please review carefully"). The reviewer knows their job.

package/hooks/blocking/bot_mention_comment_blocker.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: block @cursor or @copilot mentions in add_issue_comment body.
+
+Bugbot trigger requires exactly ``bugbot run`` with no other text. Copilot review
+requires the GitHub REST API endpoint, not an issue comment mention. This hook
+catches both mistakes and returns the correct procedure for each.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+
+def _insert_hooks_tree_for_imports() -> None:
+    hooks_tree = Path(__file__).resolve().parent.parent
+    hooks_tree_string = str(hooks_tree)
+    if hooks_tree_string not in sys.path:
+        sys.path.insert(0, hooks_tree_string)
+
+
+_insert_hooks_tree_for_imports()
+
+from config.bot_mention_comment_blocker_constants import (
+    COPILOT_MENTION_TOKEN,
+    CORRECTIVE_MESSAGE_COPILOT,
+    CORRECTIVE_MESSAGE_CURSOR,
+    CURSOR_MENTION_TOKEN,
+    TOOL_NAME,
+)
+
+
+def _body_contains_token(body: str, token: str) -> bool:
+    return token.lower() in body.lower()
+
+
+def _detect_bot_mention(body: str) -> str | None:
+    """Return corrective message if body contains a blocked mention, else None."""
+    if _body_contains_token(body, COPILOT_MENTION_TOKEN):
+        return CORRECTIVE_MESSAGE_COPILOT
+    if _body_contains_token(body, CURSOR_MENTION_TOKEN):
+        return CORRECTIVE_MESSAGE_CURSOR
+    return None
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    if hook_input.get("tool_name", "") != TOOL_NAME:
+        sys.exit(0)
+
+    body = hook_input.get("tool_input", {}).get("body", "")
+    if not body:
+        sys.exit(0)
+
+    corrective_message = _detect_bot_mention(body)
+    if corrective_message is None:
+        sys.exit(0)
+
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": corrective_message,
+        }
+    }
+    print(json.dumps(deny_payload))
+    sys.stdout.flush()
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()