diff --git a/docs/CODEX.md b/docs/CODEX.md index 7a99d2674e..2defa260c3 100644 --- a/docs/CODEX.md +++ b/docs/CODEX.md @@ -27,7 +27,8 @@ adapter; alias matching alone cannot translate an edit payload. New event types appear as unmapped at startup. Unsupported handler types and failed commands report errors. The bridge does not silently claim they ran. Command-only hooks use PowerShell on Windows and `sh` elsewhere; structured -`command` and `args` avoid shell parsing. Hook chains have a 90-second outer limit. +`command` and `args` avoid shell parsing. Codex's documentation does not say +which shell runs a hook command. Only repo settings are imported. Claude's user settings, local settings, account credentials, permission grants, plugins, and status line remain Claude-owned. diff --git a/scripts/codex/bridge.py b/scripts/codex/bridge.py index 8c8b8e1fde..76a26c4658 100644 --- a/scripts/codex/bridge.py +++ b/scripts/codex/bridge.py @@ -18,6 +18,9 @@ from pathlib import Path ROOT = Path(__file__).resolve().parents[2] +# Must equal $blockExit in invoke.ps1; a mismatch leaves a block at 2, which its caller's +# pwsh -Command reports as 1. +BLOCK_EXIT = 10 EVENTS = ( "SessionStart", "SessionEnd", @@ -115,6 +118,10 @@ def sync_skills( return messages +class HookBlocked(Exception): + """A hook exited 2.""" + + def child_environment(root: Path, session_id: str) -> dict[str, str]: if not session_id: raise ValueError("Codex session id missing; pass --session-id or set CODEX_THREAD_ID") @@ -243,7 +250,7 @@ def dispatch(root: Path, payload: dict) -> dict: if completed.stderr: print(completed.stderr, file=sys.stderr, end="") if completed.returncode == 2: - raise PermissionError(completed.stderr or "Claude hook blocked this event") + raise HookBlocked(completed.stderr or "Claude hook blocked this event") completed.check_returncode() output = completed.stdout.strip() if not output: @@ -275,7 +282,14 @@ def main() -> int: parser.add_argument("--session-id", default=os.environ.get("CODEX_THREAD_ID", "")) parser.add_argument("--migrate-copies", action="store_true") parser.add_argument("--include-user-skills", action="store_true") - args, rest = parser.parse_known_args() + # A hook's exit 2 exits 2, or BLOCK_EXIT where argv is exactly `hook ... --block-exit 10`, the + # form invoke.ps1 builds; it ends its process with 2 for it. It is taken out before argparse, so + # no prefix of it is captured from a run script's own flags. Nothing inherits argv. + argv = sys.argv[1:] + block_exit = 2 + if argv[:1] == ["hook"] and argv[-2:] == ["--block-exit", str(BLOCK_EXIT)]: + argv, block_exit = argv[:-2], BLOCK_EXIT + args, rest = parser.parse_known_args(argv) if args.mode == "sync-skills": user_skills = user_skill_directory() if args.include_user_skills else None print( @@ -294,7 +308,11 @@ def main() -> int: return 0 if args.mode == "hook": payload = json.load(sys.stdin) - result = dispatch(ROOT, payload) + try: + result = dispatch(ROOT, payload) + except HookBlocked as exc: + print(f"Codex bridge: {exc}", file=sys.stderr) + return block_exit if result: print(json.dumps(result)) return 0 diff --git a/scripts/codex/invoke.ps1 b/scripts/codex/invoke.ps1 index 62f59347b4..a17468b490 100644 --- a/scripts/codex/invoke.ps1 +++ b/scripts/codex/invoke.ps1 @@ -1,6 +1,7 @@ # SPDX-License-Identifier: AGPL-3.0-or-later # Copyright (C) 2026 MessageFoundry Foundation, LLC and contributors -# No parameter block: forward native arguments, including script-specific flags, unchanged. +# No parameter block: forward native arguments, including script-specific flags, plus +# `--block-exit 10` in hook mode. $ErrorActionPreference = 'Stop' $root = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent $python = Join-Path $root '.venv/Scripts/python.exe' @@ -10,5 +11,15 @@ if (-not (Test-Path -LiteralPath $python)) { if (-not (Test-Path -LiteralPath $python)) { throw 'Create this worktree''s .venv first; see docs/WORKTREES.md.' } -& $python (Join-Path $PSScriptRoot 'bridge.py') @args +# Only where `hook` is the first argument, the bridge exits 10 for a hook's exit 2 (--block-exit in +# bridge.py), and the mapping below ends the process with 2 for it. +$hookMode = $args[0] -ceq 'hook' +$blockExit = 10 # Must equal BLOCK_EXIT in bridge.py. +# Assigned, never from an if expression, which would unroll a one-element array to a string. +$bridgeArgs = @($args) +if ($hookMode) { $bridgeArgs += '--block-exit', "$blockExit" } +& $python (Join-Path $PSScriptRoot 'bridge.py') @bridgeArgs +# Ending the process keeps the block as 2, which the caller's pwsh -Command would report as 1. +# Hook mode only, so a caller's window survives `run`. +if ($hookMode -and $LASTEXITCODE -eq $blockExit) { [Environment]::Exit(2) } exit $LASTEXITCODE diff --git a/tests/test_codex_bridge.py b/tests/test_codex_bridge.py index 49a8fd8e63..9ec7d908dc 100644 --- a/tests/test_codex_bridge.py +++ b/tests/test_codex_bridge.py @@ -7,6 +7,7 @@ import importlib.util import json import os +import shlex import shutil import subprocess import sys @@ -320,3 +321,266 @@ def test_registered_command_runs_from_a_subdirectory(tmp_path): timeout=20, ) assert json.loads(completed.stdout) == {"probe": True} + + +# --- The registered line, end to end: a hook's exit 2 reaches Codex as 2 where the outer shell +# keeps it, and every fault path is at least as strict as main's exit code (non-zero, as on main). + +_DENY = {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny"}} +_PAYLOAD = {"session_id": "x", "hook_event_name": "PreToolUse", "tool_name": "Bash"} + + +def _py(source, **extra): + return {"type": "command", "command": sys.executable, "args": ["-c", source], **extra} + + +def _outer_shells(): + shells = ["pwsh"] + if os.name == "nt": + shells.append("cmd") + if shutil.which("sh"): + shells.append("sh") + return shells + + +def _outer_argv(shell, command): + # cmd takes the line verbatim, as a string: Python's argv quoting escapes quotes in a way cmd + # does not read. + if shell == "cmd": + return f"cmd /d /c {command}" + if shell == "pwsh": + return ["pwsh", "-NoProfile", "-Command", command] + if shell == "none": + return shlex.split(command) + return [shutil.which("sh"), "-c", command] + + +def _link_python(root): + """Give the copied launcher a .venv that reaches this test's own interpreter.""" + if os.name == "nt": + if not (Path(sys.prefix) / "Scripts/python.exe").is_file(): + pytest.skip("needs a virtualenv to junction on Windows") + link = ["cmd", "/c", "mklink", "/J", str(root / ".venv"), sys.prefix] + subprocess.run(link, check=True, capture_output=True) + else: + (root / ".venv/bin").mkdir(parents=True) + (root / ".venv/bin/python").symlink_to(sys.executable) + + +def _make_repo(tmp_path, settings_text, venv=True): + root = tmp_path / "repo" + scripts = root / "scripts/codex" + scripts.mkdir(parents=True) + for name in ("invoke.ps1", "bridge.py"): + shutil.copy2(ROOT / "scripts/codex" / name, scripts / name) + (root / ".claude").mkdir() + (root / ".claude/settings.json").write_text(settings_text, encoding="utf-8") + if venv: + _link_python(root) + subprocess.run(["git", "init", "-q", str(root)], check=True, capture_output=True) + return root + + +def _launch(argv, cwd, payload=_PAYLOAD, env=None): + stdin = payload if isinstance(payload, str) else json.dumps(payload) + return subprocess.run( + argv, + cwd=cwd, + input=stdin, + text=True, + capture_output=True, + check=False, + timeout=60, + env=env, + ) + + +def _run_registered(tmp_path, shell, settings_text, payload=_PAYLOAD, venv=True): + import tomllib + + root = _make_repo(tmp_path, settings_text, venv) + config = tomllib.loads((ROOT / ".codex/config.toml").read_text()) + command = config["hooks"]["PreToolUse"][0]["hooks"][0]["command"] + return _launch(_outer_argv(shell, command), root / "scripts/codex", payload) + + +def _hooks(*handlers): + return json.dumps({"hooks": {"PreToolUse": [{"matcher": "Bash", "hooks": list(handlers)}]}}) + + +_FAULTS = { + "hook-exits-1": (_hooks(_py("import sys; sys.exit(1)")), _PAYLOAD, True), + "hook-timeout": (_hooks(_py("import time; time.sleep(5)", timeout=0.5)), _PAYLOAD, True), + "unsupported-hook": (_hooks({"type": "prompt", "prompt": "review"}), _PAYLOAD, True), + "non-object-json": (_hooks(_py("print('[1]')")), _PAYLOAD, True), + "null-json": (_hooks(_py("print('null')")), _PAYLOAD, True), + "hooks-null": ( + json.dumps({"hooks": {"PreToolUse": [{"matcher": "Bash", "hooks": None}]}}), + _PAYLOAD, + True, + ), + "unparseable-settings": ("{not json", _PAYLOAD, True), + "missing-session-id": (_hooks(_py("print('{}')")), {**_PAYLOAD, "session_id": ""}, True), + "unparseable-payload": (_hooks(_py("print('{}')")), "not json", True), + "no-venv": (_hooks(_py("print('{}')")), _PAYLOAD, False), +} + + +@pytest.mark.skipif(shutil.which("pwsh") is None, reason="requires PowerShell") +@pytest.mark.parametrize("shell", _outer_shells()) +@pytest.mark.parametrize("fault", list(_FAULTS)) +def test_every_fault_path_is_at_least_as_strict_as_mains_exit_code(tmp_path, shell, fault): + """On origin/main each of these exits non-zero through the registered line, never 0.""" + settings_text, payload, venv = _FAULTS[fault] + completed = _run_registered(tmp_path, shell, settings_text, payload, venv) + assert completed.returncode != 0, (completed.stdout, completed.stderr) + + +@pytest.mark.skipif(shutil.which("pwsh") is None, reason="requires PowerShell") +@pytest.mark.parametrize("shell", _outer_shells()) +def test_a_hooks_exit_2_reaches_codex_where_the_outer_shell_keeps_it(tmp_path, shell): + completed = _run_registered(tmp_path, shell, _hooks(_py("import sys; sys.exit(2)"))) + # pwsh -Command reports a last native program's or script's exit 2 as 1; cmd and sh pass it on. + assert completed.returncode == (1 if shell == "pwsh" else 2), completed.stderr + + +@pytest.mark.skipif(shutil.which("pwsh") is None, reason="requires PowerShell") +@pytest.mark.parametrize("shell", _outer_shells()) +def test_a_deny_and_a_clean_run_exit_0(tmp_path, shell): + deny = _run_registered(tmp_path / "deny", shell, _hooks(_py(f"print({json.dumps(_DENY)!r})"))) + assert deny.returncode == 0, deny.stderr + assert json.loads(deny.stdout)["hookSpecificOutput"]["permissionDecision"] == "deny" + clean = _run_registered(tmp_path / "clean", shell, _hooks(_py("print('{}')"))) + assert clean.returncode == 0, clean.stderr + + +# --- The block exit flag. invoke.ps1 passes `--block-exit 10` only for `hook` as its first +# argument, the condition its 10-to-2 mapping uses; without the flag a hook's exit 2 exits 2, as on +# main. The flag is argv, so neither a child nor an inherited environment carries it. + +_EXIT_2 = _hooks(_py("import sys; sys.exit(2)")) +# A variable an ancestor could set; the block exit must not depend on the environment. +_OLD_SENTINEL = {"MEFOR_CODEX_BLOCK_SENTINEL": "1"} +_needs_pwsh = pytest.mark.skipif(shutil.which("pwsh") is None, reason="requires PowerShell") + + +def _env(**extra): + env = {k: v for k, v in os.environ.items() if k not in _OLD_SENTINEL} + env.update(extra) + return env + + +def _direct(root, *args, payload=_PAYLOAD, **extra): + bridge_py = root / "scripts/codex/bridge.py" + return _launch([sys.executable, str(bridge_py), *args], root, payload, _env(**extra)) + + +def _invoke_file(root, *args, payload=_PAYLOAD, **extra): + invoke = root / "scripts/codex/invoke.ps1" + argv = ["pwsh", "-NoProfile", "-NonInteractive", "-File", str(invoke), *args] + return _launch(argv, root, payload, _env(**extra)) + + +def _assert_blocked(completed, code): + """Assert the exit code and the bridge's block line, which a silent blocking hook produces.""" + assert completed.returncode == code, completed.stderr + assert "Claude hook blocked this event" in completed.stderr + + +@_needs_pwsh +def test_the_registered_line_gives_2_for_a_hooks_exit_2(tmp_path): + _assert_blocked(_run_registered(tmp_path, "none", _EXIT_2), 2) + + +def test_a_direct_bridge_hook_gives_2_for_a_hooks_exit_2(tmp_path): + root = _make_repo(tmp_path, _EXIT_2, venv=False) + _assert_blocked(_direct(root, "hook"), 2) + _assert_blocked(_direct(root, "hook", "--block-exit", "10"), 10) + + +def test_the_retired_sentinel_variable_does_not_change_the_block_exit(tmp_path): + root = _make_repo(tmp_path, _EXIT_2, venv=False) + _assert_blocked(_direct(root, "hook", **_OLD_SENTINEL), 2) + + +@_needs_pwsh +def test_invoke_ignores_an_inherited_environment(tmp_path): + root = _make_repo(tmp_path, _EXIT_2) + _assert_blocked(_invoke_file(root, "--session-id", "x", "hook", **_OLD_SENTINEL), 2) + + +_ARGV_CHILD = "import json, sys\nprint(json.dumps(sys.argv[1:]))\n" + + +@_needs_pwsh +def test_invoke_adds_no_flag_to_a_run_childs_argv(tmp_path): + root = _make_repo(tmp_path, _hooks()) + (root / "scripts/argv.py").write_text(_ARGV_CHILD, encoding="utf-8") + completed = _invoke_file(root, "run", "scripts/argv.py", "--b", "1", CODEX_THREAD_ID="x") + assert completed.returncode == 0, completed.stderr + assert json.loads(completed.stdout) == ["--b", "1"] + + +@pytest.mark.parametrize("flags", [["--block", "1", "--block-exit", "0"], ["--block-exit", "10"]]) +def test_a_run_childs_block_exit_flags_pass_through_as_on_main(tmp_path, flags): + root = _make_repo(tmp_path, _hooks(), venv=False) + (root / "scripts/argv.py").write_text(_ARGV_CHILD, encoding="utf-8") + completed = _direct(root, "--session-id", "x", "run", "scripts/argv.py", *flags) + assert completed.returncode == 0, completed.stderr + assert json.loads(completed.stdout) == flags + + +def test_only_the_launchers_block_exit_is_honoured(tmp_path): + root = _make_repo(tmp_path, _EXIT_2, venv=False) + _assert_blocked(_direct(root, "hook", "--block-exit", "0"), 2) + + +@_needs_pwsh +def test_invoke_forwards_a_single_argument_whole(tmp_path): + root = _make_repo(tmp_path, _hooks()) + completed = _invoke_file(root, "state-dir", CODEX_THREAD_ID="x") + assert completed.returncode == 0, completed.stderr + assert ".codex" in completed.stdout + + +@_needs_pwsh +def test_invoke_with_a_flag_before_hook_gives_2(tmp_path): + root = _make_repo(tmp_path, _EXIT_2) + _assert_blocked(_invoke_file(root, "--session-id", "x", "hook"), 2) + + +@_needs_pwsh +def test_a_run_child_exiting_10_is_not_remapped(tmp_path): + root = _make_repo(tmp_path, _hooks()) + (root / "scripts/exit10.py").write_text("import sys\nsys.exit(10)\n", encoding="utf-8") + assert _invoke_file(root, "--session-id", "x", "run", "scripts/exit10.py").returncode == 10 + run_first = _invoke_file(root, "run", "scripts/exit10.py", CODEX_THREAD_ID="x") + assert run_first.returncode == 10, run_first.stderr + direct = _direct(root, "--session-id", "x", "run", "scripts/exit10.py") + assert direct.returncode == 10, direct.stderr + + +# The exit code each fault gave on origin/main, through each launch path. "registered" runs the +# .codex/config.toml line with no outer shell; its pwsh -Command reports the script's exit 2 as 1. +# With no .venv, invoke.ps1 throws before the bridge runs, which exits 1. +_MAIN_FAULT_EXIT = {"registered": 1, "direct": 2, "invoke": 2} + + +@pytest.mark.parametrize("path", list(_MAIN_FAULT_EXIT)) +@pytest.mark.parametrize("fault", list(_FAULTS)) +def test_every_fault_path_exits_as_on_main(tmp_path, path, fault): + settings_text, payload, venv = _FAULTS[fault] + if path != "direct" and shutil.which("pwsh") is None: + pytest.skip("requires PowerShell") + if path == "registered": + completed = _run_registered(tmp_path, "none", settings_text, payload, venv) + elif not venv and path == "direct": + pytest.skip("the direct path never reads a .venv") + else: + root = _make_repo(tmp_path, settings_text, venv and path != "direct") + if path == "direct": + completed = _direct(root, "hook", "--block-exit", "10", payload=payload) + else: + completed = _invoke_file(root, "hook", payload=payload) + expected = 1 if not venv else _MAIN_FAULT_EXIT[path] + assert completed.returncode == expected, (completed.stdout, completed.stderr)