claude-dev-env 2.20.0 → 2.21.0

package/hooks/blocking/code_rules_enforcer.py

@@ -16,6 +16,7 @@ concern focused. The separate ``tdd_enforcer.py`` hook accepts any
 ``code_rules_*`` module family, so the suffix files satisfy its gate.
 """
 import json
+import os
 import sys
 from collections import Counter
 from collections.abc import Callable
@@ -29,6 +30,8 @@ if _BLOCKING_DIRECTORY not in sys.path:
 if _HOOKS_DIRECTORY not in sys.path:
     sys.path.insert(0, _HOOKS_DIRECTORY)
 
+_codex_apply_patch_tool_name = "apply_patch"
+
 from code_rules_annotations_length import (  # noqa: E402
     check_function_length,
     check_known_pytest_fixture_annotations,
@@ -203,6 +206,11 @@ from code_rules_typeddict_stub import (  # noqa: E402
 from code_rules_unused_imports import (  # noqa: E402
     check_unused_module_level_imports,
 )
+from codex_apply_patch import (  # noqa: E402
+    CodexPatchError,
+    CodexPatchFile,
+    parse_codex_apply_patch,
+)
 
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_CODE_EXTENSIONS,
@@ -211,6 +219,7 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     DENY_REASON_ISSUE_PREVIEW_COUNT,
     PRECHECK_USAGE_EXIT_CODE,
     PRECHECK_USAGE_MESSAGE,
+    VIOLATION_SEPARATOR,
 )
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.setup_project_paths_constants import (  # noqa: E402
@@ -218,6 +227,76 @@ from hooks_constants.setup_project_paths_constants import (  # noqa: E402
 )
 
 
+def _codex_patch_issues(each_patch_file: CodexPatchFile) -> list[str]:
+    """Run the existing code-rules verdict over one Codex patch view."""
+    if not each_patch_file.post_content and each_patch_file.operation == "delete":
+        return []
+    if _is_hook_infrastructure_python_target(each_patch_file.file_path):
+        all_issues = _hook_infrastructure_blocking_issues(
+            each_patch_file.post_content,
+            each_patch_file.file_path,
+            each_patch_file.post_content,
+            each_patch_file.prior_content,
+        )
+    elif _is_validated_target(each_patch_file.file_path):
+        all_issues = validate_content(
+            each_patch_file.post_content,
+            each_patch_file.file_path,
+            each_patch_file.prior_content,
+            each_patch_file.post_content,
+            each_patch_file.prior_content,
+        )
+    else:
+        return []
+    return [
+        f"{each_patch_file.file_path}: {each_issue}"
+        for each_issue in all_issues
+    ]
+
+
+def _report_codex_patch_payload(
+    all_pretooluse_payload: dict[str, object], deny_stream: TextIO
+) -> None:
+    """Validate every file view carried by a Codex apply_patch payload."""
+    tool_input = all_pretooluse_payload.get("tool_input")
+    if not isinstance(tool_input, dict):
+        _write_deny_payload(
+            "BLOCKED: [CODE_RULES] apply_patch payload requires tool input",
+            deny_stream,
+        )
+        return
+    patch_command = tool_input.get("command")
+    if not isinstance(patch_command, str):
+        _write_deny_payload(
+            "BLOCKED: [CODE_RULES] apply_patch payload requires a string command",
+            deny_stream,
+        )
+        return
+    working_directory = all_pretooluse_payload.get("cwd")
+    if not isinstance(working_directory, str):
+        working_directory = os.getcwd()
+    try:
+        all_patch_files = parse_codex_apply_patch(patch_command, working_directory)
+    except CodexPatchError as error:
+        _write_deny_payload(
+            f"BLOCKED: [CODE_RULES] apply_patch payload requires accepted patch markers: {error}",
+            deny_stream,
+        )
+        return
+    all_issues = [
+        each_issue
+        for each_patch_file in all_patch_files
+        for each_issue in _codex_patch_issues(each_patch_file)
+    ]
+    if all_issues:
+        _write_deny_payload(
+            f"BLOCKED: [CODE_RULES] {len(all_issues)} violation(s): "
+            + VIOLATION_SEPARATOR.join(all_issues[:DENY_REASON_ISSUE_PREVIEW_COUNT])
+            + _precheck_hint(),
+            deny_stream,
+        )
+
+
 def validate_content(
     content: str,
     file_path: str,
@@ -1259,6 +1338,10 @@ def main(all_arguments: list[str]) -> None:
         sys.exit(0)
 
     tool_name = pretooluse_payload.get("tool_name", "")
+    if tool_name == _codex_apply_patch_tool_name:
+        _report_codex_patch_payload(pretooluse_payload, sys.stdout)
+        sys.exit(0)
+
     tool_input = pretooluse_payload.get("tool_input", {})
     file_path = tool_input.get("file_path", "")
 

package/hooks/blocking/codex_apply_patch.py

@@ -0,0 +1,238 @@
+"""Parse Codex apply_patch commands into safe pre-edit and post-edit views."""
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+_codex_patch_begin_marker = "*** Begin Patch"
+_codex_patch_end_marker = "*** End Patch"
+_codex_update_marker = "*** Update File:"
+_codex_add_marker = "*** Add File:"
+_codex_delete_marker = "*** Delete File:"
+_codex_hunk_marker = "@@"
+_codex_end_of_file_marker = "*** End of File"
+_codex_no_newline_marker = "\"
+_codex_minimum_patch_line_count = 2
+_codex_update_operation = "update"
+_codex_add_operation = "add"
+_codex_delete_operation = "delete"
+
+
+class CodexPatchError(ValueError):
+    """Describe the accepted file views required by a Codex patch."""
+
+
+@dataclass(frozen=True)
+class CodexPatchFile:
+    """Represent one Codex path with pre-edit and projected post-edit content."""
+
+    file_path: str
+    prior_content: str
+    post_content: str
+    operation: str
+
+
+def _codex_marker_text(patch_line: str) -> str:
+    """Return one patch control line minus its line ending."""
+    return patch_line.rstrip("\r\n")
+
+
+def _codex_resolve_patch_path(relative_path: str, working_directory: Path) -> str:
+    """Resolve one relative patch path under the Codex working directory."""
+    normalized_path = relative_path.replace("\\", "/")
+    all_path_parts = tuple(
+        each_part
+        for each_part in normalized_path.split("/")
+        if each_part not in ("", ".")
+    )
+    if (
+        not all_path_parts
+        or normalized_path.startswith("/")
+        or re.match(r"^[A-Za-z]:", normalized_path)
+    ):
+        raise CodexPatchError("patch path requires a relative location")
+    if any(each_part == ".." for each_part in all_path_parts):
+        raise CodexPatchError("patch path requires a traversal-free location")
+    target_path = (working_directory / Path(*all_path_parts)).resolve()
+    resolved_working_directory = working_directory.resolve()
+    if target_path != resolved_working_directory and resolved_working_directory not in target_path.parents:
+        raise CodexPatchError("patch path requires a location under the working directory")
+    return str(target_path)
+
+
+def _codex_patch_sections(command: str) -> list[tuple[str, str, list[str]]]:
+    """Parse operation sections from a Codex apply_patch command."""
+    all_lines = command.splitlines(keepends=True)
+    if len(all_lines) < _codex_minimum_patch_line_count:
+        raise CodexPatchError("patch requires begin and end markers")
+    if _codex_marker_text(all_lines[0]) != _codex_patch_begin_marker:
+        raise CodexPatchError("patch requires a begin marker")
+    if _codex_marker_text(all_lines[-1]) != _codex_patch_end_marker:
+        raise CodexPatchError("patch requires an end marker")
+    all_sections: list[tuple[str, str, list[str]]] = []
+    current_section: tuple[str, str, list[str]] | None = None
+    for each_line in all_lines[1:-1]:
+        marker_text = _codex_marker_text(each_line)
+        operation = next(
+            (
+                each_operation
+                for each_operation, each_marker in (
+                    (_codex_update_operation, _codex_update_marker),
+                    (_codex_add_operation, _codex_add_marker),
+                    (_codex_delete_operation, _codex_delete_marker),
+                )
+                if marker_text.startswith(each_marker)
+            ),
+            None,
+        )
+        if operation is not None:
+            if current_section is not None:
+                all_sections.append(current_section)
+            marker_by_operation = {
+                _codex_update_operation: _codex_update_marker,
+                _codex_add_operation: _codex_add_marker,
+                _codex_delete_operation: _codex_delete_marker,
+            }
+            path_text = marker_text[len(marker_by_operation[operation]) :].strip()
+            if not path_text:
+                raise CodexPatchError("patch operation requires a path")
+            current_section = (operation, path_text, [])
+            continue
+        if current_section is None:
+            raise CodexPatchError("patch content requires a file operation")
+        current_section[2].append(each_line)
+    if current_section is not None:
+        all_sections.append(current_section)
+    if not all_sections:
+        raise CodexPatchError("patch requires a file operation")
+    return all_sections
+
+
+def _codex_find_patch_block(
+    all_current_lines: list[str], all_old_lines: list[str], search_start: int
+) -> int:
+    """Find one hunk's old lines at or after the prior hunk position."""
+    if not all_old_lines:
+        return search_start
+    last_start = len(all_current_lines) - len(all_old_lines)
+    for each_start in range(search_start, last_start + 1):
+        if all_current_lines[each_start : each_start + len(all_old_lines)] == all_old_lines:
+            return each_start
+    return -1
+
+
+def _codex_apply_hunk(
+    all_current_lines: list[str], all_hunk_lines: list[str], search_start: int
+) -> tuple[list[str], int]:
+    """Apply one context, deletion, and addition hunk to file lines."""
+    all_old_lines: list[str] = []
+    all_new_lines: list[str] = []
+    for each_line in all_hunk_lines:
+        marker_text = _codex_marker_text(each_line)
+        if marker_text in (_codex_end_of_file_marker, _codex_no_newline_marker):
+            continue
+        if not each_line or each_line[0] not in " +-":
+            raise CodexPatchError("patch hunk requires context, deletion, or addition lines")
+        line_content = each_line[1:]
+        if each_line[0] in " -":
+            all_old_lines.append(line_content)
+        if each_line[0] in " +":
+            all_new_lines.append(line_content)
+    block_start = _codex_find_patch_block(all_current_lines, all_old_lines, search_start)
+    if block_start < 0:
+        raise CodexPatchError("patch hunk requires matching file content")
+    all_current_lines[block_start : block_start + len(all_old_lines)] = all_new_lines
+    return all_current_lines, block_start + len(all_new_lines)
+
+
+def _codex_apply_update(prior_content: str, all_section_lines: list[str]) -> str:
+    """Apply every hunk in one Codex update section."""
+    all_current_lines = prior_content.splitlines(keepends=True)
+    all_hunk_lines: list[str] = []
+    search_start = 0
+    has_hunk = False
+    for each_line in all_section_lines:
+        marker_text = _codex_marker_text(each_line)
+        if marker_text.startswith(_codex_hunk_marker):
+            if all_hunk_lines:
+                all_current_lines, search_start = _codex_apply_hunk(
+                    all_current_lines, all_hunk_lines, search_start
+                )
+                all_hunk_lines = []
+            has_hunk = True
+            continue
+        all_hunk_lines.append(each_line)
+    if all_hunk_lines:
+        all_current_lines, _ = _codex_apply_hunk(all_current_lines, all_hunk_lines, search_start)
+    if not has_hunk:
+        raise CodexPatchError("update section requires a hunk marker")
+    return "".join(all_current_lines)
+
+
+def _codex_add_content(all_section_lines: list[str]) -> str:
+    """Build new content from an Add File section."""
+    all_content_lines: list[str] = []
+    for each_line in all_section_lines:
+        marker_text = _codex_marker_text(each_line)
+        if marker_text == _codex_end_of_file_marker:
+            continue
+        if not each_line or each_line[0] != "+":
+            raise CodexPatchError("add section requires added lines")
+        all_content_lines.append(each_line[1:])
+    return "".join(all_content_lines)
+
+
+def _codex_read_patch_file(
+    operation: str, target_path: Path, all_section_lines: list[str]
+) -> CodexPatchFile:
+    """Read one pre-edit file and project its post-edit content."""
+    try:
+        prior_content = target_path.read_text(encoding="utf-8")
+    except (FileNotFoundError, IsADirectoryError, OSError, UnicodeDecodeError, ValueError) as error:
+        if operation == _codex_add_operation and isinstance(error, FileNotFoundError):
+            prior_content = ""
+        else:
+            raise CodexPatchError("patch target requires readable UTF-8 content") from error
+    if operation == _codex_add_operation:
+        if target_path.exists():
+            raise CodexPatchError("add target requires a new path")
+        post_content = _codex_add_content(all_section_lines)
+    elif operation == _codex_update_operation:
+        post_content = _codex_apply_update(prior_content, all_section_lines)
+    else:
+        if any(
+            _codex_marker_text(each_line) != _codex_end_of_file_marker
+            for each_line in all_section_lines
+        ):
+            raise CodexPatchError("delete section requires end-of-file content")
+        post_content = ""
+    return CodexPatchFile(str(target_path), prior_content, post_content, operation)
+
+
+def parse_codex_apply_patch(
+    command: str, working_directory: str | None = None
+) -> tuple[CodexPatchFile, ...]:
+    """Return pre-edit and post-edit views for every Codex patch path."""
+    if not isinstance(command, str) or not command.strip():
+        raise CodexPatchError("patch command requires text")
+    resolved_working_directory = Path(working_directory or os.getcwd()).expanduser().resolve()
+    if not resolved_working_directory.is_dir():
+        raise CodexPatchError("patch working directory requires an existing directory")
+    all_patch_files: list[CodexPatchFile] = []
+    seen_paths: set[str] = set()
+    for each_operation, each_relative_path, each_section_lines in _codex_patch_sections(command):
+        try:
+            resolved_path = _codex_resolve_patch_path(
+                each_relative_path, resolved_working_directory
+            )
+        except (OSError, ValueError) as error:
+            raise CodexPatchError("patch path requires a resolvable location") from error
+        path_key = resolved_path.casefold()
+        if path_key in seen_paths:
+            raise CodexPatchError("patch paths require unique entries")
+        seen_paths.add(path_key)
+        all_patch_files.append(
+            _codex_read_patch_file(each_operation, Path(resolved_path), each_section_lines)
+        )
+    return tuple(all_patch_files)

package/hooks/blocking/test_code_rules_enforcer_codex_apply_patch.py

@@ -0,0 +1,148 @@
+"""Tests for the Codex apply_patch adapter."""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+_HOOK_DIRECTORY = Path(__file__).resolve().parent
+_HOOKS_PARENT = _HOOK_DIRECTORY.parent
+if str(_HOOK_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIRECTORY))
+if str(_HOOKS_PARENT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_PARENT))
+
+import code_rules_enforcer
+import codex_apply_patch
+
+
+def _run_codex_payload(
+    payload: dict[str, object],
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> str:
+    """Run the real enforcer entry point and return its stdout."""
+    monkeypatch.setattr(code_rules_enforcer.sys, "stdin", io.StringIO(json.dumps(payload)))
+    with contextlib.suppress(SystemExit):
+        code_rules_enforcer.main([])
+    return capsys.readouterr().out
+
+
+def _production_directory(tmp_path: Path) -> Path:
+    """Return a temporary directory whose path carries production semantics."""
+    production_directory = tmp_path.parent / "codex-prod"
+    production_directory.mkdir(exist_ok=True)
+    return production_directory
+
+
+def test_parse_codex_apply_patch_projects_every_multi_file_operation(
+    tmp_path: Path,
+) -> None:
+    """The parser returns pre-edit and post-edit content for update, add, and delete."""
+    updated_path = tmp_path / "updated.py"
+    deleted_path = tmp_path / "deleted.py"
+    updated_path.write_text("before\nkeep\n", encoding="utf-8")
+    deleted_path.write_text("remove\n", encoding="utf-8")
+    patch = (
+        "*** Begin Patch\n"
+        "*** Update File: updated.py\n"
+        "@@\n"
+        "-before\n"
+        "+after\n"
+        " keep\n"
+        "*** Add File: added.py\n"
+        "+new\n"
+        "*** Delete File: deleted.py\n"
+        "*** End Patch"
+    )
+
+    all_patch_files = codex_apply_patch.parse_codex_apply_patch(patch, str(tmp_path))
+
+    views_by_name = {
+        Path(each_patch.file_path).name: each_patch for each_patch in all_patch_files
+    }
+    assert views_by_name["updated.py"].prior_content == "before\nkeep\n"
+    assert views_by_name["updated.py"].post_content == "after\nkeep\n"
+    assert views_by_name["added.py"].prior_content == ""
+    assert views_by_name["added.py"].post_content == "new\n"
+    assert views_by_name["deleted.py"].prior_content == "remove\n"
+    assert views_by_name["deleted.py"].post_content == ""
+
+
+def test_codex_payload_allows_declared_blast_radius(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """A loop raise with a declared stopping scope passes the Codex hook."""
+    production_directory = _production_directory(tmp_path)
+    payload = {
+        "tool_name": "apply_patch",
+        "cwd": str(production_directory),
+        "tool_input": {
+            "command": (
+                "*** Begin Patch\n"
+                "*** Add File: module.py\n"
+                "+for each_member in all_members:\n"
+                "+    raise AssetItemBlocked()\n"
+                "*** End Patch"
+            )
+        },
+    }
+
+    stdout = _run_codex_payload(payload, monkeypatch, capsys)
+
+    assert stdout == ""
+
+
+def test_codex_payload_blocks_undeclared_blast_radius(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """A loop raise requires a stopping-scope declaration for acceptance."""
+    production_directory = _production_directory(tmp_path)
+    payload = {
+        "tool_name": "apply_patch",
+        "cwd": str(production_directory),
+        "tool_input": {
+            "command": (
+                "*** Begin Patch\n"
+                "*** Add File: module.py\n"
+                "+for each_member in all_members:\n"
+                "+    raise RuntimeError()\n"
+                "*** End Patch"
+            )
+        },
+    }
+
+    stdout = _run_codex_payload(payload, monkeypatch, capsys)
+
+    deny_payload = json.loads(stdout)
+    assert deny_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert "blast radius" in deny_payload["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+def test_codex_payload_blocks_malformed_patch(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """A malformed Codex patch returns a blocking diagnostic."""
+    production_directory = _production_directory(tmp_path)
+    payload = {
+        "tool_name": "apply_patch",
+        "cwd": str(production_directory),
+        "tool_input": {"command": "*** Begin Patch\n*** End Patch"},
+    }
+
+    stdout = _run_codex_payload(payload, monkeypatch, capsys)
+
+    deny_payload = json.loads(stdout)
+    assert deny_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert "payload requires accepted patch markers" in deny_payload["hookSpecificOutput"]["permissionDecisionReason"]

package/hooks/hooks_constants/code_rules_enforcer_constants.py

@@ -36,6 +36,7 @@ ADVISORY_LINE_THRESHOLD_SOFT = 400
 ADVISORY_LINE_THRESHOLD_HARD = 1000
 
 DENY_REASON_ISSUE_PREVIEW_COUNT = 10
+VIOLATION_SEPARATOR = "; "
 
 ALL_BOOLEAN_NAME_PREFIXES: tuple[str, ...] = ("is_", "has_", "should_", "can_", "was_", "did_")
 UPPER_SNAKE_CONSTANT_PATTERN = re.compile(r"^[A-Z][A-Z0-9_]*$")

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "2.20.0",
+    "version": "2.21.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/scripts/codex_compat_materializer.py

@@ -9,14 +9,14 @@ import os
 import re
 import stat
 import tempfile
-import tomllib
+from collections.abc import Callable, Iterable
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Callable, Iterable
+from typing import NoReturn
 
+import tomllib
 import yaml
 
-
 ManagedContent = str | bytes
 
 path_separator = "/"
@@ -27,6 +27,87 @@ publish_plan_max_positional_arguments = 3
 publish_plan_failure_injector_position = 2
 frontmatter_unsupported_fields = ("tools", "model", "color")
 instruction_alias_filenames = frozenset({"AGENTS.md", "CLAUDE.md"})
+failure_blast_radius_rule_relative_path = "rules/failure-blast-radius.md"
+codex_instruction_target_path = "AGENTS.md"
+codex_instruction_section_heading = "## Excerpt for repository-instruction sessions"
+codex_hook_manifest_source_path = "hooks/hooks.json"
+codex_hook_manifest_target_path = "hooks.json"
+codex_hook_event_name = "PreToolUse"
+codex_hook_matcher = "apply_patch"
+codex_enforcer_script_relative_path = "hooks/blocking/code_rules_enforcer.py"
+codex_enforcer_script_name = "code_rules_enforcer.py"
+codex_enforcer_path_suffix = path_separator + codex_enforcer_script_relative_path
+codex_hook_command_token_pattern = r'''(?:"[^"]*"|'[^']*'|\S+)'''
+codex_hook_merge_action = "merge"
+codex_hook_timeout_seconds = 60
+codex_hook_dependency_manifest = (
+    "hooks/blocking/__init__.py",
+    "hooks/blocking/code_rules_annotations_length.py",
+    "hooks/blocking/code_rules_banned_identifiers.py",
+    "hooks/blocking/code_rules_blast_radius.py",
+    "hooks/blocking/code_rules_boolean_mustcheck.py",
+    "hooks/blocking/code_rules_command_dispatch.py",
+    "hooks/blocking/code_rules_comments.py",
+    "hooks/blocking/code_rules_constants_config.py",
+    "hooks/blocking/codex_apply_patch.py",
+    "hooks/blocking/code_rules_dead_argparse_argument.py",
+    "hooks/blocking/code_rules_dead_config_field.py",
+    "hooks/blocking/code_rules_dead_dataclass_field.py",
+    "hooks/blocking/code_rules_dead_module_constant.py",
+    "hooks/blocking/code_rules_dead_split_branch.py",
+    "hooks/blocking/code_rules_docstrings.py",
+    "hooks/blocking/code_rules_duplicate_body.py",
+    "hooks/blocking/code_rules_enforcer.py",
+    "hooks/blocking/code_rules_imports_logging.py",
+    "hooks/blocking/code_rules_js_conventions.py",
+    "hooks/blocking/code_rules_magic_values.py",
+    "hooks/blocking/code_rules_mock_completeness.py",
+    "hooks/blocking/code_rules_naming_collection.py",
+    "hooks/blocking/code_rules_optional_params.py",
+    "hooks/blocking/code_rules_orphan_css_class.py",
+    "hooks/blocking/code_rules_paired_test.py",
+    "hooks/blocking/code_rules_path_utils.py",
+    "hooks/blocking/code_rules_paths_syspath.py",
+    "hooks/blocking/code_rules_probe_chains.py",
+    "hooks/blocking/code_rules_probe_detection.py",
+    "hooks/blocking/code_rules_probe_recording.py",
+    "hooks/blocking/code_rules_scope_binding.py",
+    "hooks/blocking/code_rules_shared.py",
+    "hooks/blocking/code_rules_string_magic.py",
+    "hooks/blocking/code_rules_test_assertions.py",
+    "hooks/blocking/code_rules_test_branching_except.py",
+    "hooks/blocking/code_rules_test_isolation.py",
+    "hooks/blocking/code_rules_test_layout.py",
+    "hooks/blocking/code_rules_type_escape.py",
+    "hooks/blocking/code_rules_typeddict_stub.py",
+    "hooks/blocking/code_rules_unused_imports.py",
+    "hooks/hooks_constants/__init__.py",
+    "hooks/hooks_constants/any_type_config.py",
+    "hooks/hooks_constants/banned_identifiers_constants.py",
+    "hooks/hooks_constants/blast_radius_constants.py",
+    "hooks/hooks_constants/blocking_check_limits.py",
+    "hooks/hooks_constants/code_rules_enforcer_constants.py",
+    "hooks/hooks_constants/code_rules_path_utils_constants.py",
+    "hooks/hooks_constants/command_dispatch_constants.py",
+    "hooks/hooks_constants/dead_argparse_argument_constants.py",
+    "hooks/hooks_constants/dead_config_field_constants.py",
+    "hooks/hooks_constants/dead_dataclass_field_constants.py",
+    "hooks/hooks_constants/dead_module_constant_constants.py",
+    "hooks/hooks_constants/duplicate_function_body_constants.py",
+    "hooks/hooks_constants/hardcoded_user_path_constants.py",
+    "hooks/hooks_constants/harness_scratchpad_constants.py",
+    "hooks/hooks_constants/hook_block_logger.py",
+    "hooks/hooks_constants/inline_tuple_string_magic_constants.py",
+    "hooks/hooks_constants/js_conventions_constants.py",
+    "hooks/hooks_constants/orphan_css_class_constants.py",
+    "hooks/hooks_constants/paired_test_coverage_constants.py",
+    "hooks/hooks_constants/setup_project_paths_constants.py",
+    "hooks/hooks_constants/stuttering_check_config.py",
+    "hooks/hooks_constants/stuttering_import_binding_constants.py",
+    "hooks/hooks_constants/sys_path_insert_constants.py",
+    "hooks/hooks_constants/test_layout_constants.py",
+    "hooks/hooks_constants/unused_module_import_constants.py",
+)
 full_prune_opt_in_flag = "--allow-prune-all"
 unreadable_source_root_message = (
     "source root is missing or is not a directory, so nothing was planned or changed; "
@@ -50,6 +131,10 @@ class MaterializerError(ValueError):
     """Raised when a materialization request cannot be safely planned."""
 
 
+class MaterializerRunFatal(MaterializerError):
+    """Raised when invalid materializer state stops the whole run."""
+
+
 class ArgumentParserError(ValueError):
     """Raised when command-line arguments cannot be parsed."""
 
@@ -57,7 +142,7 @@ class ArgumentParserError(ValueError):
 class MaterializerArgumentParser(argparse.ArgumentParser):
     """Parse materializer arguments while keeping errors in the JSON contract."""
 
-    def error(self, message: str) -> None:
+    def error(self, message: str) -> NoReturn:
         """Raise a reportable parser error instead of writing process output."""
         raise ArgumentParserError(message)
 
@@ -407,6 +492,246 @@ def convert_agent(agent: ClaudeAgent) -> str:
     return content
 
 
+def render_codex_failure_blast_radius(rule_content: str) -> str:
+    """Extract the repository-instruction contract from the canonical rule.
+
+    Args:
+        rule_content: Canonical failure blast-radius rule text.
+
+    Returns:
+        The fenced repository-instruction excerpt with a trailing newline.
+
+    Raises:
+        MaterializerError: If the canonical rule lacks the required excerpt.
+    """
+    heading_start = rule_content.find(codex_instruction_section_heading)
+    if heading_start < 0:
+        raise MaterializerError("failure blast-radius rule requires a Codex excerpt")
+    fence_start = rule_content.find("```", heading_start)
+    if fence_start < 0:
+        raise MaterializerError("failure blast-radius rule requires a Codex excerpt")
+    content_start = rule_content.find(line_separator, fence_start)
+    fence_end = rule_content.find(line_separator + "```", content_start + 1)
+    if content_start < 0 or fence_end < 0:
+        raise MaterializerError("failure blast-radius rule requires a complete Codex excerpt")
+    return rule_content[content_start + len(line_separator) : fence_end].rstrip() + line_separator
+
+
+def _build_codex_instruction_projection(config: MaterializerConfig) -> PlannedFile | None:
+    """Build the managed AGENTS.md projection when the canonical rule is present."""
+    source_path = config.source_root / failure_blast_radius_rule_relative_path
+    if not source_path.is_file():
+        return None
+    rule_content = source_path.read_text(encoding="utf-8")
+    projected_content = render_codex_failure_blast_radius(rule_content)
+    return PlannedFile(
+        failure_blast_radius_rule_relative_path,
+        codex_instruction_target_path,
+        projected_content,
+        hash_content(projected_content),
+    )
+
+
+def _read_json_object(file_path: Path, description: str) -> dict[str, object]:
+    """Read one JSON object and report the required content shape."""
+    try:
+        parsed_json = json.loads(file_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise MaterializerError(f"{description} requires readable UTF-8 content: {file_path}") from error
+    if not isinstance(parsed_json, dict):
+        raise MaterializerError(f"{description} must be a JSON object: {file_path}")
+    if not all(isinstance(each_key, str) for each_key in parsed_json):
+        raise MaterializerError(f"{description} requires string keys: {file_path}")
+    return {each_key: each_record for each_key, each_record in parsed_json.items()}
+
+
+def _validated_agent_iterable(candidate: object) -> tuple[ClaudeAgent, ...]:
+    """Validate the optional agent iterable used by the legacy call form."""
+    if not isinstance(candidate, Iterable):
+        raise TypeError("agent collection requires an iterable")
+    all_candidate_agents = tuple(candidate)
+    if not all(isinstance(each_agent, ClaudeAgent) for each_agent in all_candidate_agents):
+        raise TypeError("agent collection requires ClaudeAgent entries")
+    return all_candidate_agents
+
+
+def _validated_planned_file_iterable(candidate: object) -> tuple[PlannedFile, ...]:
+    """Validate planned files passed through the legacy publication call form."""
+    if not isinstance(candidate, Iterable):
+        raise TypeError("planned files require an iterable")
+    all_candidate_files = tuple(candidate)
+    if not all(isinstance(each_file, PlannedFile) for each_file in all_candidate_files):
+        raise TypeError("planned files require PlannedFile entries")
+    return all_candidate_files
+
+
+def _find_codex_hook_source(config: MaterializerConfig) -> Path | None:
+    """Find the source hook manifest alongside the compatibility sources."""
+    all_candidates = (
+        config.source_root / codex_hook_manifest_source_path,
+        config.source_root / Path(codex_hook_manifest_source_path).name,
+    )
+    return next((each_path for each_path in all_candidates if each_path.is_file()), None)
+
+
+def _resolved_codex_enforcer_command(config: MaterializerConfig) -> str:
+    """Build the target-root command for the focused Codex enforcer."""
+    script_path = (config.target_root / codex_enforcer_script_relative_path).resolve()
+    return f'python3 "{script_path}"'
+
+
+def _source_codex_enforcer_hook(
+    all_source_manifest: dict[str, object], command: str
+) -> dict[str, object]:
+    """Read the source enforcer hook shape and resolve its target command."""
+    all_events = all_source_manifest.get("hooks")
+    if not isinstance(all_events, dict):
+        raise MaterializerError("source Codex hook manifest requires a hooks object")
+    all_pre_tool_use = all_events.get(codex_hook_event_name)
+    if not isinstance(all_pre_tool_use, list):
+        raise MaterializerError("source Codex hook manifest requires a PreToolUse list")
+    for each_entry in all_pre_tool_use:
+        if not isinstance(each_entry, dict) or each_entry.get("matcher") != codex_hook_matcher:
+            continue
+        all_hook_records = each_entry.get("hooks")
+        if not isinstance(all_hook_records, list):
+            continue
+        for each_hook in all_hook_records:
+            if not isinstance(each_hook, dict):
+                continue
+            if not _is_code_rules_enforcer_hook(each_hook):
+                continue
+            resolved_hook = dict(each_hook)
+            resolved_hook["command"] = command
+            return resolved_hook
+    return {
+        "type": "command",
+        "command": command,
+        "timeout": codex_hook_timeout_seconds,
+    }
+
+
+def _hook_records(raw_hooks: object) -> list[dict[str, object]]:
+    """Validate and copy a Codex hook-record list."""
+    if not isinstance(raw_hooks, list):
+        raise MaterializerError("Codex hook manifest entry requires a hooks list")
+    if not all(isinstance(each_hook, dict) for each_hook in raw_hooks):
+        raise MaterializerError("Codex hook manifest requires valid hook entries")
+    return [dict(each_hook) for each_hook in raw_hooks]
+
+
+def _is_code_rules_enforcer_hook(all_hook_record: dict[str, object]) -> bool:
+    """Report whether a hook record names the focused code-rules enforcer."""
+    command = str(all_hook_record.get("command", ""))
+    normalized_command = command.replace("\\", path_separator)
+    all_command_tokens = (
+        each_token.strip("\"'")
+        for each_token in re.findall(codex_hook_command_token_pattern, normalized_command)
+    )
+    return any(
+        each_token in (codex_enforcer_script_name, codex_enforcer_script_relative_path)
+        or each_token.endswith(codex_enforcer_path_suffix)
+        for each_token in all_command_tokens
+    )
+
+
+def _merge_codex_hook_manifest(
+    all_target_manifest: dict[str, object], all_focused_hook: dict[str, object]
+) -> dict[str, object]:
+    """Preserve target hook order while merging one deterministic enforcer entry."""
+    all_events = all_target_manifest.get("hooks", {})
+    if not isinstance(all_events, dict):
+        raise MaterializerError("Codex hook manifest requires a hooks object")
+    all_pre_tool_use = all_events.get(codex_hook_event_name, [])
+    if not isinstance(all_pre_tool_use, list):
+        raise MaterializerError("Codex hook manifest requires a PreToolUse list")
+    merged_pre_tool_use: list[dict[str, object]] = []
+    merged_apply_patch_entry: dict[str, object] | None = None
+    merged_hooks: list[dict[str, object]] = []
+    for each_entry in all_pre_tool_use:
+        if not isinstance(each_entry, dict):
+            raise MaterializerRunFatal("Codex hook manifest requires valid matcher entries")
+        copied_entry = dict(each_entry)
+        if copied_entry.get("matcher") != codex_hook_matcher:
+            merged_pre_tool_use.append(copied_entry)
+            continue
+        all_hook_records = _hook_records(copied_entry.get("hooks", []))
+        if merged_apply_patch_entry is None:
+            merged_apply_patch_entry = copied_entry
+            merged_hooks = [
+                each_hook for each_hook in all_hook_records if not _is_code_rules_enforcer_hook(each_hook)
+            ]
+            merged_apply_patch_entry["hooks"] = merged_hooks
+            merged_pre_tool_use.append(merged_apply_patch_entry)
+        else:
+            merged_hooks.extend(
+                each_hook for each_hook in all_hook_records if not _is_code_rules_enforcer_hook(each_hook)
+            )
+    if merged_apply_patch_entry is None:
+        merged_apply_patch_entry = {"matcher": codex_hook_matcher, "hooks": merged_hooks}
+        merged_pre_tool_use.append(merged_apply_patch_entry)
+    merged_hooks.append(all_focused_hook)
+    merged_events = dict(all_events)
+    merged_events[codex_hook_event_name] = merged_pre_tool_use
+    merged_manifest = dict(all_target_manifest)
+    merged_manifest["hooks"] = merged_events
+    return merged_manifest
+
+
+def _build_codex_hook_projection(config: MaterializerConfig) -> PlannedFile | None:
+    """Build an additive managed hooks.json projection when its source exists."""
+    source_path = _find_codex_hook_source(config)
+    if source_path is None:
+        return None
+    source_manifest = _read_json_object(source_path, "source Codex hook manifest")
+    target_path = config.target_root / codex_hook_manifest_target_path
+    target_manifest = (
+        _read_json_object(target_path, "target Codex hook manifest")
+        if target_path.is_file()
+        else {"hooks": {}}
+    )
+    focused_hook = _source_codex_enforcer_hook(
+        source_manifest, _resolved_codex_enforcer_command(config)
+    )
+    projected_manifest = _merge_codex_hook_manifest(target_manifest, focused_hook)
+    projected_content = json.dumps(projected_manifest, ensure_ascii=False, indent=manifest_indentation_width) + line_separator
+    return PlannedFile(
+        codex_hook_manifest_source_path,
+        codex_hook_manifest_target_path,
+        projected_content,
+        hash_content(projected_content),
+        action=codex_hook_merge_action,
+    )
+
+
+def _build_codex_hook_dependency_projection(
+    config: MaterializerConfig,
+) -> list[PlannedFile]:
+    """Build the reviewed source files required by the target enforcer."""
+    all_dependencies: list[PlannedFile] = []
+    for each_relative_path in codex_hook_dependency_manifest:
+        source_path = config.source_root / each_relative_path
+        if not source_path.is_file():
+            raise MaterializerError(
+                f"source file is missing from the reviewed hook source list: {each_relative_path}"
+            )
+        try:
+            dependency_content = source_path.read_bytes()
+        except OSError as error:
+            raise MaterializerError(
+                f"reviewed Codex hook dependency has unreadable bytes: {each_relative_path}"
+            ) from error
+        all_dependencies.append(
+            PlannedFile(
+                each_relative_path,
+                each_relative_path,
+                dependency_content,
+                hash_content(dependency_content),
+            )
+        )
+    return all_dependencies
+
+
 def discover_agents(config: MaterializerConfig) -> list[ClaudeAgent]:
     """Discover and parse Markdown agents below the source root.
 
@@ -437,14 +762,17 @@ def discover_agents(config: MaterializerConfig) -> list[ClaudeAgent]:
         if _is_reparse_point(each_path):
             raise MaterializerError(f"source reparse point is not allowed: {each_path}")
         relative_source = each_path.relative_to(config.source_root).as_posix()
+        if relative_source == failure_blast_radius_rule_relative_path:
+            _validate_containment(config.source_root, each_path)
+            continue
         _validate_containment(config.source_root, each_path)
         all_agents.append(parse_frontmatter(each_path, each_path.read_text(encoding="utf-8"), relative_source))
     return all_agents
 
 
-def _case_fold_collision_error(target_relative_path: str) -> MaterializerError:
+def _case_fold_collision_error(target_relative_path: str) -> MaterializerRunFatal:
     """Build the error for two target names that differ only by letter case."""
-    return MaterializerError(f"case-fold collision: {target_relative_path}")
+    return MaterializerRunFatal(f"case-fold collision: {target_relative_path}")
 
 
 def _validate_orphan_target_is_adoptable(
@@ -479,6 +807,13 @@ def _validate_orphan_target_is_adoptable(
         raise MaterializerError(unmanaged_target_message.format(path=target_relative_path))
 
 
+def _configured_manifest_path(config: MaterializerConfig) -> Path:
+    """Return the manifest path established during configuration validation."""
+    if config.manifest_path is None:
+        raise MaterializerError("compatibility manifest path requires configuration")
+    return config.manifest_path
+
+
 def _build_plan(config: MaterializerConfig, all_agents: Iterable[ClaudeAgent]) -> tuple[list[PlannedFile], MaterializationReport]:
     """Build planned agent publications and their report.
 
@@ -495,7 +830,8 @@ def _build_plan(config: MaterializerConfig, all_agents: Iterable[ClaudeAgent]) -
     report = MaterializationReport()
     planned: list[PlannedFile] = []
     target_by_name: dict[str, str] = {}
-    previous_records = _manifest_record_by_path(load_manifest(config.manifest_path))
+    manifest_path = _configured_manifest_path(config)
+    previous_records = _manifest_record_by_path(load_manifest(manifest_path))
     existing_by_name = {
         each_path.relative_to(config.target_root).as_posix().casefold(): each_path
         for each_path in config.target_root.rglob("*")
@@ -506,16 +842,45 @@ def _build_plan(config: MaterializerConfig, all_agents: Iterable[ClaudeAgent]) -
         target_relative_path = _normalize_relative_path(each_agent.name + toml_suffix)
         folded_path = target_relative_path.casefold()
         if folded_path in target_by_name:
-            raise _case_fold_collision_error(target_relative_path)
+            raise MaterializerRunFatal(f"case-fold collision: {target_relative_path}")
         content = convert_agent(each_agent)
         _validate_orphan_target_is_adoptable(config, existing_by_name.get(folded_path), target_relative_path, content)
         target_by_name[folded_path] = target_relative_path
         target_path = validate_target_path(config.target_root, target_relative_path)
-        if _casefold_normalized_path(target_path) == _casefold_normalized_path(config.manifest_path):
-            raise MaterializerError("planned target collides with compatibility manifest")
+        if _casefold_normalized_path(target_path) == _casefold_normalized_path(manifest_path):
+            raise MaterializerRunFatal("planned target collides with compatibility manifest")
         planned.append(PlannedFile(source_identity, target_relative_path, content, hash_content(content)))
         report.unsupported += len(each_agent.unsupported)
         report.details["unsupported"].extend(f"{source_identity}:{each_key}" for each_key in each_agent.unsupported)
+    codex_instruction = _build_codex_instruction_projection(config)
+    if codex_instruction is not None:
+        folded_path = codex_instruction.target_relative_path.casefold()
+        if folded_path in target_by_name:
+            raise _case_fold_collision_error(codex_instruction.target_relative_path)
+        _validate_orphan_target_is_adoptable(
+            config,
+            existing_by_name.get(folded_path),
+            codex_instruction.target_relative_path,
+            codex_instruction.content,
+        )
+        validate_target_path(config.target_root, codex_instruction.target_relative_path)
+        planned.append(codex_instruction)
+        target_by_name[folded_path] = codex_instruction.target_relative_path
+    codex_hooks = _build_codex_hook_projection(config)
+    if codex_hooks is not None:
+        all_hook_dependencies = _build_codex_hook_dependency_projection(config)
+        for each_dependency in all_hook_dependencies:
+            folded_dependency_path = each_dependency.target_relative_path.casefold()
+            if folded_dependency_path in target_by_name:
+                raise _case_fold_collision_error(each_dependency.target_relative_path)
+            validate_target_path(config.target_root, each_dependency.target_relative_path)
+            target_by_name[folded_dependency_path] = each_dependency.target_relative_path
+            planned.append(each_dependency)
+        folded_path = codex_hooks.target_relative_path.casefold()
+        if folded_path in target_by_name:
+            raise _case_fold_collision_error(codex_hooks.target_relative_path)
+        validate_target_path(config.target_root, codex_hooks.target_relative_path)
+        planned.append(codex_hooks)
     report.planned_files = planned
     return planned, report
 
@@ -542,7 +907,11 @@ def build_plan(config: MaterializerConfig, *all_arguments: object, **all_keyword
         if supplied_agents is not None:
             raise TypeError("build_plan received duplicate all_agents")
         supplied_agents = all_arguments[0]
-    discovered_agents = discover_agents(config) if supplied_agents is None else supplied_agents
+    discovered_agents = (
+        discover_agents(config)
+        if supplied_agents is None
+        else _validated_agent_iterable(supplied_agents)
+    )
     return _build_plan(config, discovered_agents)
 
 
@@ -770,6 +1139,8 @@ def _record_target_state(config: MaterializerConfig, planned_file: PlannedFile,
     if current_bytes == content_to_bytes(planned_file.content):
         _record_matching_target(report, planned_file.target_relative_path, previous_record)
         return target_path, current_bytes, False
+    if planned_file.action == codex_hook_merge_action:
+        return target_path, current_bytes, True
     if _is_pristine_managed(previous_record, current_bytes):
         return target_path, current_bytes, True
     _record_target_conflict(report, planned_file.target_relative_path, previous_record)
@@ -845,9 +1216,10 @@ def _publish_planned_targets(
     all_backups: dict[Path, bytes | None],
     failure_injector: Callable[[str], None] | None,
 ) -> None:
+    manifest_path = _configured_manifest_path(config)
     for each_planned_file in all_planned_files:
         target_path, current_bytes, is_publishable = _record_target_state(config, each_planned_file, all_previous_records, report)
-        if _casefold_normalized_path(target_path) == _casefold_normalized_path(config.manifest_path):
+        if _casefold_normalized_path(target_path) == _casefold_normalized_path(manifest_path):
             raise MaterializerError("planned target collides with compatibility manifest")
         if not is_publishable:
             continue
@@ -950,7 +1322,8 @@ def _publish_plan(
     publication.planned_files = all_planned_files
     if not config.should_apply:
         return publication
-    previous_manifest = load_manifest(config.manifest_path)
+    manifest_path = _configured_manifest_path(config)
+    previous_manifest = load_manifest(manifest_path)
     previous_records = _manifest_record_by_path(previous_manifest)
     _validate_full_prune_consent(config, all_planned_files, previous_records)
     backups: dict[Path, bytes | None] = {}
@@ -962,10 +1335,10 @@ def _publish_plan(
             config, all_planned_files, previous_records, publication, backups, failure_injector
         )
         _remove_stale_files(config, previous_records, all_planned_files, publication, backups)
-        save_manifest(config.manifest_path, _build_manifest(all_planned_files), failure_injector)
-    except (OSError, RuntimeError, ValueError) as error:
+        save_manifest(manifest_path, _build_manifest(all_planned_files), failure_injector)
+    except (OSError, RuntimeError, ValueError):
         _rollback_publication(backups, publication, initial_written, initial_deleted)
-        raise error
+        raise
     _sort_report_details(publication)
     return publication
 
@@ -1003,7 +1376,10 @@ def publish_plan(config: MaterializerConfig, *all_arguments: object, **all_keywo
             raise TypeError("publish_plan received duplicate failure injector")
         failure_injector = all_arguments[2]
     publication = report if isinstance(report, MaterializationReport) else MaterializationReport()
-    return _publish_plan(config, planned_files, publication, failure_injector)
+    all_planned_files = _validated_planned_file_iterable(planned_files)
+    if failure_injector is not None and not callable(failure_injector):
+        raise TypeError("failure injector requires a callable")
+    return _publish_plan(config, all_planned_files, publication, failure_injector)
 
 
 def _redact_private_paths(
@@ -1086,6 +1462,8 @@ def main(*all_arguments: object) -> int:
         should_apply = options.should_apply
         source_root = options.source_root
         target_root = options.target_root
+        if source_root is None or target_root is None:
+            raise TypeError("materializer roots are required")
         config = MaterializerConfig(
             source_root,
             target_root,

package/scripts/tests/test_codex_compat_materializer.py

@@ -1,9 +1,9 @@
 import json
-from pathlib import Path
 import sys
-import tomllib
+from pathlib import Path
 
 import pytest
+import tomllib
 
 module_directory = str(Path(__file__).parents[1])
 if module_directory not in sys.path:
@@ -17,8 +17,8 @@ from codex_compat_materializer import (
     PlannedFile,
     atomic_write,
     build_plan,
-    convert_agent,
     content_to_bytes,
+    convert_agent,
     hash_content,
     load_manifest,
     parse_frontmatter,
@@ -144,6 +144,20 @@ def test_validation_rejects_overlap_and_unsafe_paths(tmp_path: Path) -> None:
             validate_target_path(config.target_root, name)
 
 
+def test_public_legacy_call_forms_validate_collection_entries(tmp_path: Path) -> None:
+    config = MaterializerConfig(tmp_path / "source", tmp_path / "target")
+
+    with pytest.raises(TypeError, match="ClaudeAgent entries"):
+        build_plan(config, all_agents=[object()])
+    with pytest.raises(TypeError, match="PlannedFile entries"):
+        publish_plan(config, all_planned_files=[object()])
+
+
+def test_render_codex_failure_blast_radius_requires_the_excerpt_heading() -> None:
+    with pytest.raises(MaterializerError, match="requires a Codex excerpt"):
+        materializer.render_codex_failure_blast_radius("# No excerpt\n")
+
+
 def test_validation_rejects_reparse_point_from_portable_attribute_seam(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None: