claude-dev-env 2.20.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/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/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()