claude-dev-env 2.21.0 → 2.21.1

package/docs/codex-compatibility.md

@@ -6,9 +6,11 @@
 
 Run `codex-compat materialize --source-root <claude-root> --target-root <codex-root>`. The command defaults to a dry run; add `--apply` to publish files. Use `--python <command>` or `CODEX_COMPAT_PYTHON` to select Python. If no usable interpreter is found, the command reports that condition. The launcher passes an argv array, never a shell command.
 
-The Python materializer maps Claude `_shared/`, `agents/`, `hooks/`, `rules/`, and `scripts/` into the target according to the package's compatibility materialization rules. Claude agent frontmatter is converted to Codex TOML metadata. Unsupported Claude metadata is reported, rather than silently treated as equivalent.
+The Python materializer maps Claude `_shared/`, `agents/`, `hooks/`, `rules/`, and `scripts/` into the target according to the package's compatibility materialization rules. Claude agent frontmatter is converted to Codex TOML metadata. The canonical failure blast-radius rule projects its repository-instruction excerpt into a managed `AGENTS.md` file. Claude metadata reports its supported-field shape.
 
-Rules, hooks, and scripts that have no safe Codex runtime equivalent remain inert or source-only. They are preserved for inspection and are not executed as translated target tools. The capability bridge likewise emits declarative records only; it never invokes the translated surface.
+The Codex hook projection merges a managed `apply_patch` entry for `code_rules_enforcer.py` into the target `hooks.json`. Existing Codex hook entries keep their order, repeated enforcer entries collapse to one deterministic record, and the command resolves under the target root. The enforcer reads the patch command, reconstructs every file's pre-edit and projected post-edit content, and returns a blocking diagnostic for patch shapes requiring correction or code-rule violations. The existing Claude `Write`, `Edit`, and `MultiEdit` dispatcher keeps its current order and behavior.
+
+The capability bridge emits declarative records and leaves translated surfaces for their owning runtime.
 
 Materialization uses a compatibility manifest to identify generated files. Dry runs report the plan without writing. Apply mode uses safe link/copy fallback where linking is unavailable, writes atomically, removes only stale managed files, and rolls back managed changes on failure. A failed rollback reports that reconciliation is required.
 

package/hooks/blocking/plain_language_blocker.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""PreToolUse hook that checks AskUserQuestion prose when enabled."""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from blocking.config.prose_style_enforcement_constants import (  # noqa: E402
+    prose_style_enforcement_enabled_in_environment,
+)
+from hooks_constants.ask_user_question_shape_constants import (  # noqa: E402
+    ASK_USER_QUESTION_TOOL_NAME,
+)
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
+from hooks_constants.plain_language_blocker_constants import (  # noqa: E402
+    ALL_PLAIN_LANGUAGE_TERM_PATTERNS,
+    FENCED_CODE_PATTERN,
+    FILE_PATH_PATTERN,
+    INLINE_CODE_PATTERN,
+    PLAIN_LANGUAGE_BLOCK_PREFIX,
+    PLAIN_LANGUAGE_NOTICE,
+    PLAIN_LANGUAGE_TERM_SEPARATOR,
+    URL_PATTERN,
+)
+from hooks_constants.pre_tool_use_stdin import (  # noqa: E402
+    read_hook_input_dictionary_from_stdin,
+)
+
+
+def strip_non_prose_regions(text: str) -> str:
+    """Remove exact code, URL, and path regions before scanning prose."""
+    without_fenced_code = FENCED_CODE_PATTERN.sub(" ", text)
+    without_inline_code = INLINE_CODE_PATTERN.sub(" ", without_fenced_code)
+    without_urls = URL_PATTERN.sub(" ", without_inline_code)
+    return FILE_PATH_PATTERN.sub(" ", without_urls)
+
+def find_banned_terms(text: str) -> list[tuple[str, str]]:
+    """Return each detected formal term and its familiar replacement."""
+    prose_text = strip_non_prose_regions(text)
+    all_matches: list[tuple[str, str]] = []
+    seen_terms: set[str] = set()
+    for each_pattern, each_replacement in ALL_PLAIN_LANGUAGE_TERM_PATTERNS:
+        match = each_pattern.search(prose_text)
+        if match is None:
+            continue
+        matched_term = match.group(0).lower()
+        if matched_term in seen_terms:
+            continue
+        seen_terms.add(matched_term)
+        all_matches.append((matched_term, each_replacement))
+    return all_matches
+
+
+def _question_prose(payload_by_key: Mapping[str, object]) -> list[str]:
+    """Return question and option-description prose from a tool payload."""
+    raw_tool_input = payload_by_key.get("tool_input", {})
+    if not isinstance(raw_tool_input, Mapping):
+        return []
+    raw_questions = raw_tool_input.get("questions", [])
+    if not isinstance(raw_questions, Sequence) or isinstance(
+        raw_questions, (str, bytes)
+    ):
+        return []
+    all_prose: list[str] = []
+    for each_raw_question in raw_questions:
+        if not isinstance(each_raw_question, Mapping):
+            continue
+        question = each_raw_question.get("question")
+        if isinstance(question, str):
+            all_prose.append(question)
+        raw_options = each_raw_question.get("options", [])
+        if not isinstance(raw_options, Sequence) or isinstance(
+            raw_options, (str, bytes)
+        ):
+            continue
+        for each_raw_option in raw_options:
+            if not isinstance(each_raw_option, Mapping):
+                continue
+            description = each_raw_option.get("description")
+            if isinstance(description, str):
+                all_prose.append(description)
+    return all_prose
+
+
+def evaluate(payload_by_key: Mapping[str, object]) -> str | None:
+    """Return a deny reason for formal AskUserQuestion prose."""
+    if not prose_style_enforcement_enabled_in_environment():
+        return None
+    if payload_by_key.get("tool_name") != ASK_USER_QUESTION_TOOL_NAME:
+        return None
+    all_matches: list[tuple[str, str]] = []
+    for each_prose in _question_prose(payload_by_key):
+        for each_match in find_banned_terms(each_prose):
+            if each_match not in all_matches:
+                all_matches.append(each_match)
+    if not all_matches:
+        return None
+    return build_block_reason(all_matches)
+
+
+def build_block_reason(all_matches: Sequence[tuple[str, str]]) -> str:
+    """Build a concise denial reason with one replacement per detected term."""
+    swaps = PLAIN_LANGUAGE_TERM_SEPARATOR.join(
+        f"{term} -> {replacement}" for term, replacement in all_matches
+    )
+    return f"{PLAIN_LANGUAGE_BLOCK_PREFIX}{swaps}."
+
+
+def build_deny_payload(deny_reason: str) -> dict[str, object]:
+    """Build the standard PreToolUse deny response."""
+    log_hook_block(
+        calling_hook_name="plain_language_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=deny_reason,
+        tool_name=ASK_USER_QUESTION_TOOL_NAME,
+    )
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": deny_reason,
+        },
+        "systemMessage": PLAIN_LANGUAGE_NOTICE,
+        "suppressOutput": True,
+    }
+
+
+def main() -> None:
+    """Read one hook payload and emit a deny response when needed."""
+    payload_by_key = read_hook_input_dictionary_from_stdin()
+    if payload_by_key is None:
+        return
+    deny_reason = evaluate(payload_by_key)
+    if deny_reason is None:
+        return
+    sys.stdout.write(json.dumps(build_deny_payload(deny_reason)) + "\n")
+    sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/test_code_rules_enforcer_codex_apply_patch.py

@@ -143,6 +143,31 @@ def test_codex_payload_blocks_malformed_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"]
+def test_codex_payload_blocks_a_nul_containing_patch_path(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """A path containing NUL is converted into the standard JSON deny response."""
+    production_directory = _production_directory(tmp_path)
+    payload = {
+        "tool_name": "apply_patch",
+        "cwd": str(production_directory),
+        "tool_input": {
+            "command": (
+                "*** Begin Patch\n"
+                "*** Add File: unsafe\x00.py\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 "payload requires accepted patch markers" in deny_payload["hookSpecificOutput"]["permissionDecisionReason"]

package/hooks/blocking/test_plain_language_blocker.py

@@ -0,0 +1,119 @@
+"""Production-path tests for the AskUserQuestion plain-language blocker."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+HOOK_PATH = Path(__file__).with_name("plain_language_blocker.py")
+
+
+def _run_hook(
+    payload: dict[str, object], *, enabled: bool
+) -> subprocess.CompletedProcess[str]:
+    environment = os.environ.copy()
+    if enabled:
+        environment["CLAUDE_PROSE_STYLE_ENFORCEMENT"] = "1"
+    else:
+        environment.pop("CLAUDE_PROSE_STYLE_ENFORCEMENT", None)
+    return subprocess.run(
+        [sys.executable, str(HOOK_PATH)],
+        input=json.dumps(payload),
+        capture_output=True,
+        check=False,
+        env=environment,
+        text=True,
+    )
+
+
+def _decision(result: subprocess.CompletedProcess[str]) -> str | None:
+    if not result.stdout:
+        return None
+    parsed_payload = json.loads(result.stdout)
+    return parsed_payload.get("hookSpecificOutput", {}).get("permissionDecision")
+
+
+def test_default_off_allows_formal_question_word() -> None:
+    result = _run_hook(
+        {
+            "tool_name": "AskUserQuestion",
+            "tool_input": {
+                "questions": [{"question": "Should we utilize this path?"}]
+            },
+        },
+        enabled=False,
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""
+
+
+def test_enabled_blocks_formal_question_word() -> None:
+    result = _run_hook(
+        {
+            "tool_name": "AskUserQuestion",
+            "tool_input": {
+                "questions": [
+                    {
+                        "question": "Should we utilize this path?",
+                        "options": [{"description": "Initiate the migration."}],
+                    }
+                ]
+            },
+        },
+        enabled=True,
+    )
+    assert result.returncode == 0
+    assert _decision(result) == "deny"
+    assert "utilize -> use" in result.stdout
+    assert "initiate -> start" in result.stdout
+
+
+def test_exact_code_url_and_path_text_is_exempt() -> None:
+    result = _run_hook(
+        {
+            "tool_name": "AskUserQuestion",
+            "tool_input": {
+                "questions": [
+                    {
+                        "question": (
+                            "Use `utilize` in src/initiate.py or "
+                            "https://example.test/utilize."
+                        )
+                    }
+                ]
+            },
+        },
+        enabled=True,
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""
+
+
+def test_other_tools_are_ignored() -> None:
+    result = _run_hook(
+        {
+            "tool_name": "Write",
+            "tool_input": {"content": "Utilize the existing helper."},
+        },
+        enabled=True,
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""
+
+
+@pytest.mark.parametrize("raw_input", ["", "[]", "not json"])
+def test_invalid_input_is_fail_open(raw_input: str) -> None:
+    result = subprocess.run(
+        [sys.executable, str(HOOK_PATH)],
+        input=raw_input,
+        capture_output=True,
+        check=False,
+        text=True,
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""

package/hooks/hooks.json

@@ -22,6 +22,16 @@
           }
         ]
       },
+      {
+        "matcher": "apply_patch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/code_rules_enforcer.py",
+            "timeout": 60
+          }
+        ]
+      },
       {
         "matcher": "Bash|PowerShell",
         "hooks": [
@@ -80,6 +90,11 @@
       {
         "matcher": "AskUserQuestion",
         "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/plain_language_blocker.py",
+            "timeout": 10
+          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/ask_user_question_shape_blocker.py",

package/hooks/hooks_constants/plain_language_blocker_constants.py

@@ -0,0 +1,26 @@
+"""Configuration for the AskUserQuestion plain-language blocker."""
+
+from __future__ import annotations
+
+import re
+
+ALL_PLAIN_LANGUAGE_TERM_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = (
+    (re.compile(r"\butilize\b", re.IGNORECASE), "use"),
+    (re.compile(r"\binitiate\b", re.IGNORECASE), "start"),
+    (re.compile(r"\bsufficient\b", re.IGNORECASE), "enough"),
+    (re.compile(r"\bprior to\b", re.IGNORECASE), "before"),
+    (re.compile(r"\bin order to\b", re.IGNORECASE), "to"),
+)
+
+FENCED_CODE_PATTERN = re.compile(r"```[\s\S]*?```")
+INLINE_CODE_PATTERN = re.compile(r"`[^`\n]+`")
+URL_PATTERN = re.compile(r"https?://\S+", re.IGNORECASE)
+FILE_PATH_PATTERN = re.compile(
+    r"(?<!\w)(?:[A-Za-z]:[\\/]|\.\.?[\\/])?[\w.-]+(?:[\\/][\w.-]+)+"
+)
+
+PLAIN_LANGUAGE_BLOCK_PREFIX = "BLOCKED: [PLAIN_LANGUAGE] Use familiar words: "
+PLAIN_LANGUAGE_TERM_SEPARATOR = "; "
+PLAIN_LANGUAGE_NOTICE = (
+    "Plain-language check: use familiar words in the question and its options."
+)

package/package.json

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

package/scripts/codex_compat_materializer.py

@@ -520,8 +520,9 @@ def render_codex_failure_blast_radius(rule_content: str) -> str:
 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():
+    if not source_path.exists() and not _is_reparse_point(source_path):
         return None
+    source_path = _validated_source_file(config, failure_blast_radius_rule_relative_path, "failure blast-radius rule")
     rule_content = source_path.read_text(encoding="utf-8")
     projected_content = render_codex_failure_blast_radius(rule_content)
     return PlannedFile(
@@ -545,6 +546,24 @@ def _read_json_object(file_path: Path, description: str) -> dict[str, object]:
     return {each_key: each_record for each_key, each_record in parsed_json.items()}
 
 
+def _validated_source_file(
+    config: MaterializerConfig, relative_path: str, description: str
+) -> Path:
+    """Resolve one source file while rejecting reparse points and escapes."""
+    source_path = config.source_root.joinpath(*relative_path.split(path_separator))
+    current_path = config.source_root
+    for each_part in relative_path.split(path_separator):
+        current_path /= each_part
+        if current_path.exists() and _is_reparse_point(current_path):
+            raise MaterializerRunFatal(
+                f"{description} source reparse point is not allowed: {relative_path}"
+            )
+    resolved_path = _validate_containment(config.source_root, source_path)
+    if not resolved_path.is_file():
+        raise MaterializerError(f"{description} source file is missing: {relative_path}")
+    return resolved_path
+
+
 def _validated_agent_iterable(candidate: object) -> tuple[ClaudeAgent, ...]:
     """Validate the optional agent iterable used by the legacy call form."""
     if not isinstance(candidate, Iterable):
@@ -571,7 +590,11 @@ def _find_codex_hook_source(config: MaterializerConfig) -> Path | None:
         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)
+    for each_path in all_candidates:
+        if each_path.exists() or _is_reparse_point(each_path):
+            relative_path = each_path.relative_to(config.source_root).as_posix()
+            return _validated_source_file(config, relative_path, "Codex hook manifest")
+    return None
 
 
 def _resolved_codex_enforcer_command(config: MaterializerConfig) -> str:
@@ -635,6 +658,41 @@ def _is_code_rules_enforcer_hook(all_hook_record: dict[str, object]) -> bool:
     )
 
 
+def _codex_enforcer_hooks(all_manifest: object) -> tuple[dict[str, object], ...]:
+    """Return enforcer records from the target apply-patch matcher."""
+    if not isinstance(all_manifest, dict):
+        return ()
+    all_events = all_manifest.get("hooks")
+    if not isinstance(all_events, dict):
+        return ()
+    all_pre_tool_use = all_events.get(codex_hook_event_name)
+    if not isinstance(all_pre_tool_use, list):
+        return ()
+    all_enforcer_hooks: list[dict[str, object]] = []
+    for each_entry in all_pre_tool_use:
+        if not isinstance(each_entry, dict) or each_entry.get("matcher") != codex_hook_matcher:
+            continue
+        for each_hook in _hook_records(each_entry.get("hooks", [])):
+            if _is_code_rules_enforcer_hook(each_hook):
+                all_enforcer_hooks.append(each_hook)
+    return tuple(all_enforcer_hooks)
+
+
+def _has_modified_codex_enforcer_hook(
+    current_bytes: bytes, planned_content: ManagedContent
+) -> bool:
+    """Report whether an existing enforcer record differs from the plan."""
+    try:
+        current_manifest = json.loads(current_bytes.decode("utf-8"))
+        planned_manifest = json.loads(content_to_bytes(planned_content).decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return True
+    current_hooks = _codex_enforcer_hooks(current_manifest)
+    if not current_hooks:
+        return False
+    return current_hooks != _codex_enforcer_hooks(planned_manifest)
+
+
 def _merge_codex_hook_manifest(
     all_target_manifest: dict[str, object], all_focused_hook: dict[str, object]
 ) -> dict[str, object]:
@@ -710,11 +768,9 @@ def _build_codex_hook_dependency_projection(
     """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}"
-            )
+        source_path = _validated_source_file(
+            config, each_relative_path, "reviewed Codex hook dependency"
+        )
         try:
             dependency_content = source_path.read_bytes()
         except OSError as error:
@@ -1119,6 +1175,7 @@ def _record_target_state(config: MaterializerConfig, planned_file: PlannedFile,
 
         target absent                    -> ok:   publish
         on-disk bytes == planned bytes   -> ok:   unchanged, no write
+        _has_modified_codex_enforcer_hook -> flag: conflicted, preserved untouched
         on-disk hash == manifest hash    -> ok:   publish, the tool owns these bytes
         on-disk hash != manifest hash    -> flag: conflicted, preserved untouched
 
@@ -1140,6 +1197,9 @@ def _record_target_state(config: MaterializerConfig, planned_file: PlannedFile,
         _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:
+        if _has_modified_codex_enforcer_hook(current_bytes, planned_file.content):
+            _record_target_conflict(report, planned_file.target_relative_path, previous_record)
+            return target_path, current_bytes, False
         return target_path, current_bytes, True
     if _is_pristine_managed(previous_record, current_bytes):
         return target_path, current_bytes, True

package/scripts/tests/test_codex_compat_materializer.py

@@ -1,6 +1,8 @@
 import json
+import subprocess
 import sys
 from pathlib import Path
+from typing import Any
 
 import pytest
 import tomllib
@@ -442,6 +444,69 @@ def _apply_source_agent(source_root: Path, target_root: Path, description: str)
     return target_root / "Luna.toml"
 
 
+def _write_codex_hook_source(source_root: Path) -> None:
+    package_root = Path(__file__).parents[2]
+    source_hooks = source_root / "hooks"
+    source_hooks.mkdir(parents=True, exist_ok=True)
+    (source_hooks / "hooks.json").write_bytes(
+        (package_root / "hooks" / "hooks.json").read_bytes()
+    )
+    for each_relative_path in materializer.codex_hook_dependency_manifest:
+        source_path = source_root / each_relative_path
+        source_path.parent.mkdir(parents=True, exist_ok=True)
+        source_path.write_bytes((package_root / each_relative_path).read_bytes())
+
+
+def test_build_plan_rejects_reparse_hook_dependencies(
+    tmp_path: Path,
+) -> None:
+    source = tmp_path / "source"
+    _write_codex_hook_source(source)
+    dependency_path = source / materializer.codex_enforcer_script_relative_path
+    outside_path = tmp_path / "outside.py"
+    outside_path.write_text("secret", encoding="utf-8")
+    try:
+        dependency_path.unlink()
+        dependency_path.symlink_to(outside_path)
+    except OSError as error:
+        pytest.skip(f"symlinks unavailable: {error}")
+
+    with pytest.raises(MaterializerError, match="reparse point"):
+        build_plan(MaterializerConfig(source, tmp_path / "target"))
+
+
+def test_publish_plan_preserves_modified_enforcer_hook_as_conflict(
+    tmp_path: Path,
+) -> None:
+    source = tmp_path / "source"
+    target = tmp_path / "target"
+    _write_codex_hook_source(source)
+    target.mkdir()
+    modified_command = f'python3 "{target / materializer.codex_enforcer_script_relative_path}" --custom'
+    existing_manifest = {
+        "hooks": {
+            "PreToolUse": [
+                {
+                    "matcher": materializer.codex_hook_matcher,
+                    "hooks": [
+                        {"type": "command", "command": modified_command, "timeout": 5}
+                    ],
+                }
+            ]
+        }
+    }
+    hooks_path = target / materializer.codex_hook_manifest_target_path
+    hooks_path.write_text(json.dumps(existing_manifest), encoding="utf-8")
+    config = MaterializerConfig(source, target, should_apply=True)
+
+    planned, report = build_plan(config)
+    publication = publish_plan(config, planned, report)
+
+    assert publication.conflicted == 1
+    assert publication.details["conflicted"] == ["hooks.json"]
+    assert json.loads(hooks_path.read_text(encoding="utf-8")) == existing_manifest
+
+
 def test_apply_with_a_missing_source_root_keeps_managed_files_and_fails(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:
@@ -712,3 +777,249 @@ def test_frontmatter_rejects_non_string_name() -> None:
             "---\nname: 1\ndescription: y\n---\n",
             "bad.md",
         )
+
+
+def test_failure_blast_radius_projection_uses_the_canonical_excerpt() -> None:
+    canonical_rule_path = Path(__file__).parents[2] / "rules" / "failure-blast-radius.md"
+    canonical_rule = canonical_rule_path.read_text(encoding="utf-8")
+
+    projected_instruction = materializer.render_codex_failure_blast_radius(canonical_rule)
+
+    assert projected_instruction.startswith("Failure handling for this run")
+    assert "Three real attempts, then park." in projected_instruction
+    assert "Report as: N of M complete" in projected_instruction
+
+
+def test_build_plan_publishes_owned_agents_projection_and_tracks_drift(
+    tmp_path: Path,
+) -> None:
+    canonical_rule_path = Path(__file__).parents[2] / "rules" / "failure-blast-radius.md"
+    source = tmp_path / "source"
+    target = tmp_path / "target"
+    rule_path = source / "rules" / "failure-blast-radius.md"
+    rule_path.parent.mkdir(parents=True)
+    rule_path.write_text(canonical_rule_path.read_text(encoding="utf-8"), encoding="utf-8")
+    config = MaterializerConfig(source, target, should_apply=True)
+
+    planned, report = build_plan(config, all_agents=[])
+    publish_plan(config, planned, report)
+
+    projected_path = target / "AGENTS.md"
+    first_projection = projected_path.read_text(encoding="utf-8")
+    manifest_record = load_manifest(config.manifest_path)["files"]["AGENTS.md"]
+    assert manifest_record["ownership"] == "codex-compat"
+    assert manifest_record["source"] == "rules/failure-blast-radius.md"
+
+    rule_path.write_text(
+        rule_path.read_text(encoding="utf-8").replace("Three real attempts, then park.", "Three tested attempts, then park."),
+        encoding="utf-8",
+    )
+    drifted_plan, _ = build_plan(config, all_agents=[])
+
+    drifted_projection = next(
+        each_file.content
+        for each_file in drifted_plan
+        if each_file.target_relative_path == "AGENTS.md"
+    )
+    assert drifted_projection != first_projection
+
+
+def test_codex_hook_manifest_keeps_dispatcher_order_and_adds_enforcer() -> None:
+    hooks_path = Path(__file__).parents[2] / "hooks" / "hooks.json"
+    hooks_configuration = json.loads(hooks_path.read_text(encoding="utf-8"))
+    pre_tool_use_entries = hooks_configuration["hooks"]["PreToolUse"]
+    matcher_names = [each_entry.get("matcher") for each_entry in pre_tool_use_entries]
+
+    dispatcher_index = matcher_names.index("Write|Edit|MultiEdit")
+    enforcer_entries = [
+        each_entry
+        for each_entry in pre_tool_use_entries
+        if each_entry.get("matcher") == "apply_patch"
+    ]
+    assert len(enforcer_entries) == 1
+    assert matcher_names.index("apply_patch") > dispatcher_index
+    assert enforcer_entries[0]["hooks"][0]["command"].endswith(
+        "/hooks/blocking/code_rules_enforcer.py"
+    )
+
+
+def _prepare_projection_fixture(
+    tmp_path: Path,
+) -> tuple[Path, Path, dict[str, Any], Path]:
+    source = tmp_path / "source"
+    target = tmp_path.parent / "codex-prod-target"
+    source_rule = source / "rules" / "failure-blast-radius.md"
+    source_hooks = source / "hooks" / "hooks.json"
+    source_rule.parent.mkdir(parents=True)
+    source_hooks.parent.mkdir(parents=True)
+    source_rule.write_text(
+        (Path(__file__).parents[2] / "rules" / "failure-blast-radius.md").read_text(
+            encoding="utf-8"
+        ),
+        encoding="utf-8",
+    )
+    source_hooks.write_text(
+        (Path(__file__).parents[2] / "hooks" / "hooks.json").read_text(encoding="utf-8"),
+        encoding="utf-8",
+    )
+    package_root = Path(__file__).parents[2]
+    for each_relative_path in materializer.codex_hook_dependency_manifest:
+        target_dependency = source / each_relative_path
+        target_dependency.parent.mkdir(parents=True, exist_ok=True)
+        target_dependency.write_bytes((package_root / each_relative_path).read_bytes())
+    target.mkdir()
+    existing_hooks = {
+        "hooks": {
+            "PreToolUse": [
+                {
+                    "matcher": "Write|Edit",
+                    "hooks": [{"type": "command", "command": "python existing.py"}],
+                },
+                {
+                    "matcher": "apply_patch",
+                    "hooks": [
+                        {
+                            "type": "command",
+                            "command": (
+                                f'python3 "{target / "hooks" / "blocking" / "code_rules_enforcer.py"}"'
+                            ),
+                            "timeout": 60,
+                        }
+                    ],
+                },
+                {
+                    "matcher": "apply_patch",
+                    "hooks": [
+                        {"type": "command", "command": "python not_code_rules_enforcer.py"}
+                    ],
+                },
+            ],
+            "Bash": [{"matcher": "", "hooks": []}],
+        }
+    }
+    (target / "hooks.json").write_text(json.dumps(existing_hooks), encoding="utf-8")
+    retired_owned_path = target / "hooks" / "obsolete.py"
+    retired_owned_path.parent.mkdir(parents=True)
+    retired_owned_path.write_text("retired owned hook\n", encoding="utf-8")
+    retired_manifest = {
+        "version": 1,
+        "files": {
+            "hooks/obsolete.py": {
+                "source": "hooks/obsolete.py",
+                "hash": materializer.hash_content(retired_owned_path.read_bytes()),
+                "ownership": "codex-compat",
+            }
+        },
+    }
+    (target / ".codex-compat-manifest.json").write_text(
+        json.dumps(retired_manifest), encoding="utf-8"
+    )
+    return source, target, existing_hooks, retired_owned_path
+
+
+def _run_materializer_and_read_report(
+    source: Path,
+    target: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> dict[str, Any]:
+    exit_code = materializer.main([str(source), str(target), "--apply"])
+    report = json.loads(capsys.readouterr().out)
+    assert exit_code == 0, report
+    assert report["errors"] == 0, report
+    return report
+
+
+def _assert_projection_and_manifest(
+    target: Path,
+    existing_hooks: dict[str, Any],
+    retired_owned_path: Path,
+) -> None:
+    assert not retired_owned_path.exists()
+    projected_instruction = (target / "AGENTS.md").read_text(encoding="utf-8")
+    assert "Three real attempts, then park." in projected_instruction
+    manifest = json.loads((target / "hooks.json").read_text(encoding="utf-8"))
+    assert manifest["hooks"]["PreToolUse"][0] == existing_hooks["hooks"]["PreToolUse"][0]
+    apply_patch_entries = [
+        each_entry
+        for each_entry in manifest["hooks"]["PreToolUse"]
+        if each_entry["matcher"] == "apply_patch"
+    ]
+    assert len(apply_patch_entries) == 1
+    apply_patch_commands = [
+        each_hook["command"] for each_hook in apply_patch_entries[0]["hooks"]
+    ]
+    assert apply_patch_commands[0] == "python not_code_rules_enforcer.py"
+    managed_command = (
+        f'python3 "{target / "hooks" / "blocking" / "code_rules_enforcer.py"}"'
+    )
+    assert managed_command in apply_patch_commands
+    manifest_record = load_manifest(target / ".codex-compat-manifest.json")["files"]
+    assert manifest_record["AGENTS.md"]["ownership"] == "codex-compat"
+    assert manifest_record["hooks.json"]["source"] == "hooks/hooks.json"
+
+
+def _assert_detached_enforcer_behavior(target: Path) -> None:
+    target_entrypoint = target / materializer.codex_enforcer_script_relative_path
+    allow_payload = {
+        "tool_name": "apply_patch",
+        "cwd": str(target),
+        "tool_input": {
+            "command": (
+                "*** Begin Patch\n"
+                "*** Add File: module.py\n"
+                "+for each_member in all_members:\n"
+                "+    raise AssetItemBlocked()\n"
+                "*** End Patch"
+            )
+        },
+    }
+    allow_run = subprocess.run(
+        [sys.executable, str(target_entrypoint)],
+        cwd=target,
+        input=json.dumps(allow_payload),
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert allow_run.returncode == 0
+    assert allow_run.stdout == ""
+
+    deny_payload = {
+        **allow_payload,
+        "tool_input": {
+            "command": allow_payload["tool_input"]["command"].replace(
+                "AssetItemBlocked", "RuntimeError"
+            )
+        },
+    }
+    deny_run = subprocess.run(
+        [sys.executable, str(target_entrypoint)],
+        cwd=target,
+        input=json.dumps(deny_payload),
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert deny_run.returncode == 0
+    assert json.loads(deny_run.stdout)["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert target_entrypoint.is_file()
+
+
+def test_exact_cli_publishes_instruction_and_additive_hook_projection(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    source, target, existing_hooks, retired_owned_path = _prepare_projection_fixture(
+        tmp_path
+    )
+
+    first_report = _run_materializer_and_read_report(source, target, capsys)
+    assert first_report["written"] > 0
+    _assert_projection_and_manifest(target, existing_hooks, retired_owned_path)
+
+    hooks_before_second_run = (target / "hooks.json").read_bytes()
+    second_report = _run_materializer_and_read_report(source, target, capsys)
+    assert second_report["written"] == 0
+    assert (target / "hooks.json").read_bytes() == hooks_before_second_run
+
+    source.rename(tmp_path / "source-detached")
+    _assert_detached_enforcer_behavior(target)