multi-forge 0.5.0__tar.gz → 0.6.0__tar.gz

{multi_forge-0.5.0 → multi_forge-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multi-forge
-Version: 0.5.0
+Version: 0.6.0
 Summary: Multi-runtime agent toolkit: proxy routing, cost control, session management, policy enforcement, and workflow orchestration
 Project-URL: Homepage, https://github.com/hapa1i/multi-forge
 Project-URL: Repository, https://github.com/hapa1i/multi-forge
@@ -56,15 +56,18 @@ Description-Content-Type: text/markdown
 **Multi-runtime agent toolkit: proxy routing, cost control, session management, and policy enforcement for coding
 agents.**
 
-Forge sits between you and your coding agent (Claude Code today, Codex and Gemini next), adding persistent sessions,
-multi-provider model routing, cost visibility with spend caps, and autonomous verification. You run
-`forge session start` instead of `claude`, and Forge handles the rest -- routing to your chosen model provider, tracking
-state across sessions, and enforcing policies.
+Forge sits between you and your coding agent (Claude Code by default, with Codex as an alternate runtime and Gemini
+next), adding persistent sessions, multi-provider model routing, cost visibility with spend caps, and autonomous
+verification. You run `forge session start` instead of `claude`, and Forge handles the rest -- routing to your chosen
+model provider, tracking state across sessions, and enforcing policies.
 
 ```bash
 # Use Claude with session tracking (no proxy needed)
 forge session start
 
+# Or run a different runtime entirely -- Codex as an alternate frontend
+forge session start --runtime codex    # interactive TUI; hooks/policy need a one-time Codex trust enrollment
+
 # Or route through different model providers (after creating proxies -- see Quick Start)
 forge session start planner --proxy openrouter-openai    # GPT for planning
 forge session start --proxy openrouter-gemini            # Gemini for review
@@ -223,12 +226,14 @@ Run `forge <command> --help` for details on any command.
 
 ## Documentation
 
-| Audience         | Location                           | Contents                                             |
-| ---------------- | ---------------------------------- | ---------------------------------------------------- |
-| **Users**        | [docs/end-user/](docs/end-user/)   | Tour, guides for sessions, proxies, policies, ...    |
-| **Developers**   | [docs/developer/](docs/developer/) | Setup, coding standards, testing guidelines          |
-| **Architecture** | [docs/design.md](docs/design.md)   | System narrative, data flow, invariants              |
-| **Work Board**   | [docs/board/](docs/board/)         | Cards, checklists, change log, implementation memory |
+| Audience            | Location                                             | Contents                                              |
+| ------------------- | ---------------------------------------------------- | ----------------------------------------------------- |
+| **Users**           | [docs/end-user/](docs/end-user/)                     | Tour, guides for sessions, proxies, policies, ...     |
+| **Developers**      | [docs/developer/](docs/developer/)                   | Setup, coding standards, testing guidelines           |
+| **Architecture**    | [docs/design.md](docs/design.md)                     | Core system narrative, data flow, invariants          |
+| **Workflow design** | [docs/design_workflows.md](docs/design_workflows.md) | Policy, skills, workflow runners, memory architecture |
+| **CLI reference**   | [docs/cli_reference.md](docs/cli_reference.md)       | Terminal and direct-command inventory                 |
+| **Work Board**      | [docs/board/](docs/board/)                           | Cards, checklists, change log, implementation memory  |
 
 ## Contributing
 

{multi_forge-0.5.0 → multi_forge-0.6.0}/README.md

@@ -15,15 +15,18 @@
 **Multi-runtime agent toolkit: proxy routing, cost control, session management, and policy enforcement for coding
 agents.**
 
-Forge sits between you and your coding agent (Claude Code today, Codex and Gemini next), adding persistent sessions,
-multi-provider model routing, cost visibility with spend caps, and autonomous verification. You run
-`forge session start` instead of `claude`, and Forge handles the rest -- routing to your chosen model provider, tracking
-state across sessions, and enforcing policies.
+Forge sits between you and your coding agent (Claude Code by default, with Codex as an alternate runtime and Gemini
+next), adding persistent sessions, multi-provider model routing, cost visibility with spend caps, and autonomous
+verification. You run `forge session start` instead of `claude`, and Forge handles the rest -- routing to your chosen
+model provider, tracking state across sessions, and enforcing policies.
 
 ```bash
 # Use Claude with session tracking (no proxy needed)
 forge session start
 
+# Or run a different runtime entirely -- Codex as an alternate frontend
+forge session start --runtime codex    # interactive TUI; hooks/policy need a one-time Codex trust enrollment
+
 # Or route through different model providers (after creating proxies -- see Quick Start)
 forge session start planner --proxy openrouter-openai    # GPT for planning
 forge session start --proxy openrouter-gemini            # Gemini for review
@@ -182,12 +185,14 @@ Run `forge <command> --help` for details on any command.
 
 ## Documentation
 
-| Audience         | Location                           | Contents                                             |
-| ---------------- | ---------------------------------- | ---------------------------------------------------- |
-| **Users**        | [docs/end-user/](docs/end-user/)   | Tour, guides for sessions, proxies, policies, ...    |
-| **Developers**   | [docs/developer/](docs/developer/) | Setup, coding standards, testing guidelines          |
-| **Architecture** | [docs/design.md](docs/design.md)   | System narrative, data flow, invariants              |
-| **Work Board**   | [docs/board/](docs/board/)         | Cards, checklists, change log, implementation memory |
+| Audience            | Location                                             | Contents                                              |
+| ------------------- | ---------------------------------------------------- | ----------------------------------------------------- |
+| **Users**           | [docs/end-user/](docs/end-user/)                     | Tour, guides for sessions, proxies, policies, ...     |
+| **Developers**      | [docs/developer/](docs/developer/)                   | Setup, coding standards, testing guidelines           |
+| **Architecture**    | [docs/design.md](docs/design.md)                     | Core system narrative, data flow, invariants          |
+| **Workflow design** | [docs/design_workflows.md](docs/design_workflows.md) | Policy, skills, workflow runners, memory architecture |
+| **CLI reference**   | [docs/cli_reference.md](docs/cli_reference.md)       | Terminal and direct-command inventory                 |
+| **Work Board**      | [docs/board/](docs/board/)                           | Cards, checklists, change log, implementation memory  |
 
 ## Contributing
 

{multi_forge-0.5.0 → multi_forge-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "multi-forge"
-version = "0.5.0"
+version = "0.6.0"
 description = "Multi-runtime agent toolkit: proxy routing, cost control, session management, policy enforcement, and workflow orchestration"
 readme = "README.md"
 license = "Apache-2.0"

{multi_forge-0.5.0 → multi_forge-0.6.0}/src/forge/cli/activity.py

@@ -113,10 +113,16 @@ def _render(summary: SessionActivitySummary, *, days: int | None) -> None:
 
     pol = summary.policy
     if pol and pol.has_content:
-        console.print(
-            f"\n[bold]Supervisor[/bold]: {pol.supervisor_allow} allow · "
-            f"{pol.supervisor_warn} warn · {pol.supervisor_deny} block"
-        )
+        if pol.plan_check_allow or pol.plan_check_needs_review:
+            console.print(
+                f"\n[bold]Plan check (tier-1)[/bold]: {pol.plan_check_allow} allow · "
+                f"{pol.plan_check_needs_review} needs review"
+            )
+        if pol.supervisor_allow or pol.supervisor_warn or pol.supervisor_deny or pol.total_warnings:
+            console.print(
+                f"\n[bold]Supervisor[/bold]: {pol.supervisor_allow} allow · "
+                f"{pol.supervisor_warn} warn · {pol.supervisor_deny} block"
+            )
         for warning in pol.recent_warnings:
             console.print(f"  [yellow]•[/yellow] {warning}")
 

{multi_forge-0.5.0 → multi_forge-0.6.0}/src/forge/cli/extensions.py

@@ -99,15 +99,18 @@ def _parse_modules(modules_str: str | None) -> set[InstallModule] | None:
     return {InstallModule(m.strip()) for m in modules_str.split(",")}
 
 
-def _count_actions(plan: InstallPlan) -> tuple[int, int]:
+def _count_actions(plan: InstallPlan) -> tuple[int, int, int]:
     """Count non-skip actions in a plan.
 
     Returns:
-        Tuple of (file_actions, settings_actions) that are not skips.
+        Tuple of (file_actions, settings_actions, codex_actions) that
+        actually change something. A codex install/update counts as an
+        action so a codex-only change never renders "Already up to date.".
     """
     file_actions = sum(1 for f in plan.files if f.action != "skip")
     settings_actions = sum(1 for s in plan.settings if s.action != "skip")
-    return file_actions, settings_actions
+    codex_actions = 1 if plan.codex is not None and plan.codex.action in ("install", "update") else 0
+    return file_actions, settings_actions, codex_actions
 
 
 # Modules that are intentionally empty in the source tree (only .gitkeep).
@@ -165,8 +168,8 @@ def _print_completion_message(
     tracking: TrackingStore,
 ) -> None:
     """Print appropriate completion message based on what was done."""
-    file_actions, settings_actions = _count_actions(plan)
-    total_actions = file_actions + settings_actions
+    file_actions, settings_actions, codex_actions = _count_actions(plan)
+    total_actions = file_actions + settings_actions + codex_actions
 
     _warn_if_modules_have_no_files(plan, scope, project_root, tracking)
 
@@ -178,6 +181,8 @@ def _print_completion_message(
             parts.append(f"{file_actions} file{'s' if file_actions != 1 else ''}")
         if settings_actions > 0:
             parts.append(f"{settings_actions} setting{'s' if settings_actions != 1 else ''}")
+        if codex_actions > 0:
+            parts.append("Codex hooks")
         console.print(f"\n[green]Extensions enabled.[/green] ({', '.join(parts)} updated)")
 
     print_tip(
@@ -200,6 +205,30 @@ def _print_completion_message(
         required = gated[0][1].value
         print_tip(f"Additional skills available with --profile {required}: {skill_list}", console=console)
 
+    _print_codex_completion(plan, scope)
+
+
+def _print_codex_completion(plan: InstallPlan, scope: InstallScope) -> None:
+    """Print the trust-ceremony guidance (or skip notice) for the codex plan.
+
+    Registration alone is inert: Codex hooks fire only after the user's
+    one-time interactive trust ceremony, which Forge can neither perform nor
+    verify -- so a fresh registration always names the ceremony explicitly.
+    """
+    codex = plan.codex
+    if codex is None:
+        return
+    if codex.action in ("install", "update"):
+        where = "in any project" if scope == InstallScope.USER else "in this project"
+        config = display_path(codex.config_path) if codex.config_path else "config.toml"
+        console.print("\n[dim]Next steps (Codex hooks):[/dim]")
+        console.print(f"  - Forge hooks are registered in {config} but stay inert until trusted.")
+        console.print(f"  - Run 'codex' interactively {where} and grant trust when prompted (one-time).")
+    elif codex.action == "conflict":
+        console.print(f"\n[yellow]Warning:[/yellow] Codex hook registration skipped: {codex.reason}")
+    elif codex.action == "unavailable":
+        console.print(f"\n[dim]Codex hooks skipped: {codex.reason}.[/dim]")
+
 
 def _validate_anchor(anchor: Path) -> None:
     """Reject anchors that point inside a ``.claude/`` directory.
@@ -324,6 +353,23 @@ def _print_plan(plan: InstallPlan, dry_run: bool = False) -> None:
 
         console.print(table)
 
+    if plan.codex is not None:
+        console.print(f"\n{prefix}[bold]Codex hooks (config.toml):[/bold]")
+        table = Table(show_header=True, header_style="bold", box=None)
+        table.add_column("ACTION", style="dim")
+        table.add_column("TARGET")
+        table.add_column("REASON", style="dim")
+        style = {
+            "install": "green",
+            "update": "yellow",
+            "skip": "dim",
+            "conflict": "yellow",  # best-effort: degrades to skip, never blocks
+            "unavailable": "dim",
+        }.get(plan.codex.action, "")
+        target = display_path(plan.codex.config_path) if plan.codex.config_path else ""
+        table.add_row(plan.codex.action, target, plan.codex.reason or "", style=style)
+        console.print(table)
+
     if plan.has_conflicts:
         console.print(f"\n{prefix}[bold red]Conflicts detected:[/bold red]")
         for c in plan.conflicts:
@@ -467,7 +513,7 @@ def extensions() -> None:
     "--with",
     "-w",
     "with_modules",
-    help="Add modules (comma-separated: commands,agents,skills,hooks,status-line,permissions)",
+    help="Add modules (comma-separated: commands,agents,skills,hooks,status-line,permissions,codex-hooks)",
 )
 @click.option(
     "--without",
@@ -672,8 +718,8 @@ def sync_cmd(scope: str | None, force: bool) -> None:
             console.print("\n[red]Sync failed due to conflicts.[/red]")
             sys.exit(1)
         else:
-            file_actions, settings_actions = _count_actions(plan)
-            total_actions = file_actions + settings_actions
+            file_actions, settings_actions, codex_actions = _count_actions(plan)
+            total_actions = file_actions + settings_actions + codex_actions
             if total_actions == 0:
                 console.print("\n[dim]Already up to date.[/dim]")
             else:
@@ -682,8 +728,15 @@ def sync_cmd(scope: str | None, force: bool) -> None:
                     parts.append(f"{file_actions} file{'s' if file_actions != 1 else ''}")
                 if settings_actions > 0:
                     parts.append(f"{settings_actions} setting{'s' if settings_actions != 1 else ''}")
+                if codex_actions > 0:
+                    parts.append("Codex hooks")
                 console.print(f"\n[green]Sync complete.[/green] ({', '.join(parts)} updated)")
 
+            # A synced block can carry NEW entries whose trust is not yet
+            # granted (per-entry trusted_hash) -- the ceremony guidance
+            # matters most exactly here.
+            _print_codex_completion(plan, install_scope)
+
     except NoForgeInstallationError as e:
         console.print(f"[red]Error:[/red] {e}")
         sys.exit(1)
@@ -788,6 +841,10 @@ def disable_cmd(scope: str | None, uninstall_all: bool, yes: bool) -> None:
             console.print("[bold]Settings:[/bold]")
             console.print(table)
 
+        if existing.codex_config_path:
+            console.print("\n[bold]Codex hooks:[/bold]")
+            console.print(f"  [red]remove[/red] managed block in {display_path(existing.codex_config_path)}")
+
         if not yes:
             if not click.confirm("\nProceed with disable?"):
                 console.print("[dim]Cancelled.[/dim]")
@@ -926,6 +983,8 @@ def status_cmd(scope: str | None, path: str | None, show_all: bool, as_json: boo
                     "modules": list(inst.modules_enabled),
                     "files_count": len(inst.files),
                     "settings_count": len(inst.settings_entries),
+                    "codex_config_path": inst.codex_config_path,
+                    "codex_commands": list(inst.codex_commands),
                     "installed_at": inst.installed_at,
                     "updated_at": inst.updated_at,
                 }
@@ -966,6 +1025,8 @@ def status_cmd(scope: str | None, path: str | None, show_all: bool, as_json: boo
         console.print(f"  Modules:   {', '.join(installation.modules_enabled)}")
         console.print(f"  Files:     {len(installation.files)}")
         console.print(f"  Settings:  {len(installation.settings_entries)} entries")
+        if installation.codex_config_path:
+            console.print(f"  Codex:     hooks registered in {display_path(installation.codex_config_path)}")
         console.print(f"  Installed: {installation.installed_at}")
         console.print(f"  Updated:   {installation.updated_at}")
 

{multi_forge-0.5.0 → multi_forge-0.6.0}/src/forge/cli/hooks/_group.py

@@ -8,11 +8,12 @@ import click
 @click.group(name="hook", hidden=True)
 @click.pass_context
 def hooks(ctx: click.Context) -> None:
-    """Hook handlers invoked by Claude Code.
+    """Hook handlers invoked by agent runtimes.
 
-    Most subcommands are invoked automatically by Claude Code hooks
-    configured in .claude/settings.local.json. The 'enable' and
-    'disable' subcommands are user-facing.
+    Most subcommands are invoked automatically by runtime hooks: Claude Code's
+    are configured in .claude/settings.local.json; Codex's (codex-policy-check)
+    are registered in a Codex config and require trust enrollment. The 'enable'
+    and 'disable' subcommands are user-facing.
     """
     from forge.core.logging import configure_debug_logging
 

multi_forge-0.6.0/src/forge/cli/hooks/codex_patch.py

@@ -0,0 +1,129 @@
+"""Parser for Codex's apply_patch envelope (PreToolUse ``tool_input.command``).
+
+System boundary: the patch text arrives in a Codex hook payload (external data),
+so the parser is strict but the caller fails open -- ``None`` means "not a patch
+Forge can reason about", and the hook allows the action rather than guessing.
+Codex's own apply_patch rejects input outside this grammar, so failing open on
+malformed text converges with native behavior.
+
+Grammar (codex-cli 0.138.0; witness fixture in ``tests/fixtures/codex/hooks/``)::
+
+    *** Begin Patch
+    *** Add File: <path> | *** Update File: <path> | *** Delete File: <path>
+    *** Move to: <path>        (only immediately after an Update header)
+    <body lines prefixed +, -, space, or @@; blank lines are context>
+    *** End of File            (tolerated inside add/update sections)
+    *** End Patch
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from forge.policy.types import extract_added_lines
+
+PatchOpKind = Literal["add", "update", "delete"]
+
+_BEGIN = "*** Begin Patch"
+_END = "*** End Patch"
+_EOF_MARKER = "*** End of File"
+_MOVE_TO = "*** Move to: "
+_HEADERS: tuple[tuple[str, PatchOpKind], ...] = (
+    ("*** Add File: ", "add"),
+    ("*** Update File: ", "update"),
+    ("*** Delete File: ", "delete"),
+)
+
+
+@dataclass(frozen=True)
+class PatchFileOp:
+    """One file operation parsed from an apply_patch envelope.
+
+    ``path`` is the post-op path (the "Move to" target when present) -- policies
+    judge where content lands, not where it came from. The pre-move path is
+    recoverable from ``raw_section``.
+    """
+
+    kind: PatchOpKind
+    path: str
+    move_to: str | None
+    added_content: str  # introduced lines ("" for delete)
+    raw_section: str  # verbatim header + body (raw_diff source)
+
+
+@dataclass
+class _Section:
+    kind: PatchOpKind
+    path: str
+    move_to: str | None = None
+    header_lines: list[str] = field(default_factory=list)
+    body: list[str] = field(default_factory=list)
+
+    def finalize(self) -> PatchFileOp:
+        body = "\n".join(self.body)
+        return PatchFileOp(
+            kind=self.kind,
+            path=self.move_to or self.path,
+            move_to=self.move_to,
+            added_content="" if self.kind == "delete" else extract_added_lines(body),
+            raw_section="\n".join(self.header_lines + self.body),
+        )
+
+
+def parse_apply_patch(command: str) -> list[PatchFileOp] | None:
+    """Parse an apply_patch envelope into per-file operations.
+
+    Returns None for anything outside the known grammar (caller fails open);
+    an empty envelope (Begin + End only) returns [].
+    """
+    lines = [line.rstrip("\r") for line in command.split("\n")]
+    while lines and not lines[0].strip():
+        lines.pop(0)
+    while lines and not lines[-1].strip():
+        lines.pop()
+    if not lines or lines[0] != _BEGIN or lines[-1] != _END or len(lines) < 2:
+        return None
+
+    ops: list[PatchFileOp] = []
+    current: _Section | None = None
+
+    for line in lines[1:-1]:
+        header = _match_header(line)
+        if header is not None:
+            kind, path = header
+            if not path:
+                return None
+            if current is not None:
+                ops.append(current.finalize())
+            current = _Section(kind=kind, path=path, header_lines=[line])
+        elif line.startswith(_MOVE_TO):
+            # Only valid immediately after an Update header (no body yet, one move max).
+            target = line[len(_MOVE_TO) :].strip()
+            if current is None or current.kind != "update" or current.body or current.move_to or not target:
+                return None
+            current.move_to = target
+            current.header_lines.append(line)
+        elif line == _EOF_MARKER:
+            if current is None or current.kind == "delete":
+                return None
+            current.body.append(line)  # kept verbatim in raw_section; extract_added_lines ignores it
+        elif current is None:
+            return None  # body line before any section header
+        elif current.kind == "delete":
+            return None  # Delete sections are bodyless in the grammar
+        elif line == "" or line.startswith(("+", "-", " ", "@@")):
+            current.body.append(line)
+        else:
+            return None
+
+    if current is not None:
+        ops.append(current.finalize())
+    return ops
+
+
+def _match_header(line: str) -> tuple[PatchOpKind, str] | None:
+    for prefix, kind in _HEADERS:
+        if line.startswith(prefix):
+            return kind, line[len(prefix) :].strip()
+    return None

multi_forge-0.6.0/src/forge/cli/hooks/codex_policy.py

@@ -0,0 +1,197 @@
+"""Codex halves of the hook seam: payload -> ActionContexts, decision -> stdout JSON.
+
+The Codex counterparts of ``ClaudeHookAdapter``/``ClaudeHookResponder`` (policy.py),
+filling the runtime-neutral protocols in ``protocols.py``. Probe-pinned facts this
+module encodes (codex_frontend Phase 1, codex-cli 0.138.0):
+
+- Codex file writes arrive as ``tool_name="apply_patch"`` with the patch envelope in
+  ``tool_input.command``; shell commands arrive as ``tool_name="Bash"``.
+- Every Forge policy's ``applies_to`` gates on ``tool_name in ("Write", "Edit")``, so
+  the adapter normalizes patch operations to those names (Add File -> Write,
+  Update File -> Edit). The runtime truth stays in ``origin="codex"`` + ``tool_args``.
+- Codex FAILS OPEN on malformed hook output, so the responder emits only
+  ``json.dumps`` of literal dicts -- never hand-assembled wire strings.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from forge.cli.hooks.codex_patch import PatchFileOp, parse_apply_patch
+from forge.cli.hooks.policy import format_deny_text, format_needs_review_text
+from forge.policy.deterministic.base import is_under_directory
+from forge.policy.types import ActionContext, CompositeDecision
+
+_MAX_CONTENT_CHARS = 5000  # same truncation convention as ClaudeHookAdapter
+
+
+class CodexHookAdapter:
+    """Normalize a Codex PreToolUse payload into ``ActionContext``s (origin="codex").
+
+    Only ``apply_patch`` actions are evaluable (Codex's file-write tool); anything
+    else -- including ``Bash`` -- yields ``[]`` so the hook command fails open, the
+    same posture as Claude's hook skipping non-Write/Edit tools. A multi-file patch
+    yields one context per non-delete file operation, in patch order; deletions are
+    skipped (no policy evaluates them -- there is no introduced content).
+    """
+
+    ORIGIN = "codex"
+
+    def build_contexts(self, payload: dict[str, Any], tool_name: str, manifest: Any) -> list[ActionContext]:
+        """Build per-file ``ActionContext``s from a Codex PreToolUse payload ([] if unbuildable)."""
+        if tool_name != "apply_patch":
+            return []
+        tool_input = payload.get("tool_input", {})
+        if not isinstance(tool_input, dict):
+            return []
+        command = tool_input.get("command")
+        if not isinstance(command, str):
+            return []
+
+        ops = parse_apply_patch(command)
+        if ops is None:
+            return []  # malformed patch: fail open, like Claude's unbuildable payload
+
+        # Payload cwd is where Codex resolves apply_patch paths; the hook process's
+        # own CWD is unpinned, so prefer the payload's.
+        payload_cwd = payload.get("cwd")
+        cwd = Path(payload_cwd) if isinstance(payload_cwd, str) and payload_cwd else Path(os.getcwd())
+        cwd = cwd.resolve()
+
+        return [self._context_for_op(op, cwd, manifest) for op in ops if op.kind != "delete"]
+
+    def _context_for_op(self, op: PatchFileOp, cwd: Path, manifest: Any) -> ActionContext:
+        # Normalize to the tool names every policy's applies_to expects.
+        normalized_tool = "Write" if op.kind == "add" else "Edit"
+
+        target_path = op.path
+        try:
+            p = Path(target_path)
+            if p.is_absolute():
+                target_path = str(p.relative_to(cwd))
+        except (ValueError, RuntimeError):
+            pass  # Keep as-is if can't make relative
+
+        new_content: str | None = op.added_content
+        if new_content and len(new_content) > _MAX_CONTENT_CHARS:
+            new_content = new_content[:_MAX_CONTENT_CHARS] + "\n... (truncated)"
+
+        # raw_diff only for updates: an Add's full content already is new_content,
+        # while an update section genuinely is a diff (richer LLM-policy context).
+        raw_diff = op.raw_section[:_MAX_CONTENT_CHARS] if op.kind == "update" else None
+
+        return ActionContext(
+            origin=self.ORIGIN,
+            event=f"PreToolUse.{normalized_tool}",
+            tool_name=normalized_tool,
+            tool_args={
+                "codex_tool_name": "apply_patch",
+                "path": op.path,
+                "move_to": op.move_to,
+                "kind": op.kind,
+            },
+            repo_root=str(cwd),
+            session_name=manifest.name,
+            target_path=target_path,
+            new_content=new_content or None,
+            raw_diff=raw_diff,
+        )
+
+
+class CodexHookResponder:
+    """Serialize a composed policy decision into Codex's PreToolUse wire contract.
+
+    Codex blocks on a strict stdout JSON ``hookSpecificOutput`` with
+    ``permissionDecision: "deny"`` and exits 0 (probe-pinned; the exit-2 form also
+    blocks but the JSON form carries the reason in-band). Codex fails OPEN on
+    malformed output, so every wire string is ``json.dumps`` of a literal dict.
+    """
+
+    BLOCK_EXIT = 0  # deny is stdout JSON, not an exit code (contrast Claude's 2)
+    ALLOW_EXIT = 0
+
+    def format_deny(self, result: CompositeDecision) -> str:
+        """Render the deny wire JSON for a single composed decision."""
+        return self.format_deny_multi([(None, result)])
+
+    def format_needs_review(self, result: CompositeDecision) -> str:
+        """Render the deny wire JSON for a single unresolved ``needs_review``."""
+        return self.format_needs_review_multi([(None, result)])
+
+    def format_deny_multi(self, file_results: list[tuple[str | None, CompositeDecision]]) -> str:
+        """Render one deny wire JSON covering every denying file of a patch."""
+        reason = self._join_sections(file_results, format_deny_text)
+        return self._deny_wire(reason)
+
+    def format_needs_review_multi(self, file_results: list[tuple[str | None, CompositeDecision]]) -> str:
+        """Render one deny wire JSON for the unresolved-review files of a patch."""
+        reason = self._join_sections(file_results, format_needs_review_text)
+        return self._deny_wire(reason)
+
+    def format_error_deny(self, reason: str) -> str:
+        """Render the deny wire JSON for a fail-closed evaluation error (no decision)."""
+        return self._deny_wire(reason)
+
+    def allow_feedback(self, additional_context: str) -> dict[str, Any]:
+        """Build the allow JSON (protocol conformance only).
+
+        Not emitted in Phase 3: PreToolUse ``additionalContext`` delivery on allow is
+        unprobed (only SessionStart's is confirmed), so the command allows silently.
+        """
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "allow",
+                "additionalContext": additional_context,
+            }
+        }
+
+    @staticmethod
+    def _deny_wire(reason: str) -> str:
+        return json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": reason,
+                }
+            }
+        )
+
+    @staticmethod
+    def _join_sections(
+        file_results: list[tuple[str | None, CompositeDecision]],
+        format_text: Callable[[CompositeDecision], str],
+    ) -> str:
+        sections = []
+        for path, result in file_results:
+            text = format_text(result)
+            sections.append(f"{path}:\n{text}" if path else text)
+        return "\n\n".join(sections)
+
+
+def sort_contexts_tests_first(contexts: list[ActionContext]) -> list[ActionContext]:
+    """Order contexts so tests/ paths evaluate before src/ paths.
+
+    Optimistic ordering for TDD stateful evaluation: an atomic patch adding test +
+    implementation together passes tests-before-impl (the test file populates
+    ``tests_touched`` first). Uses ``is_under_directory`` -- the SAME nested-aware rule
+    the TDD policy's ``applies_to`` gates on -- so a nested ``pkg/tests`` / ``pkg/src``
+    layout is reordered too. A top-level-only prefix match would leave both nested files
+    in one bucket and false-deny an impl-first atomic patch. ``sorted`` is stable, so
+    patch order is preserved within each bucket.
+    """
+
+    def _key(ctx: ActionContext) -> int:
+        path = ctx.target_path or ""
+        if is_under_directory(path, "tests"):
+            return 0
+        if is_under_directory(path, "src"):
+            return 2
+        return 1
+
+    return sorted(contexts, key=_key)