Skip to content

Convert Claude Code or Codex into the most intelligent Deep Research Agent. Collect, search, and synthesize web research into a persistent, searchable wiki that builds on itself. Hosted API + MCP: hyperresearch.ai

fix(codex): keep the Stop hook out of user-level Codex config; report a read-only .codex (#169)

Chronode9acb6dd5e966
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bbc2800..abcc740 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,8 @@
## [Unreleased]
+- **The Codex Stop hook stays in the project.** A vault at the home directory (where `install` or the first-run bootstrap was run from `~`) made `<root>/.codex/hooks.json` Codex's user-level hooks file, so the stop gate ran in every Codex session. It finds a vault by walking up from the session's directory, so a home-vault run that was mid-pipeline would force-continue unrelated sessions anywhere under `~`. The hook is now skipped, with a "NOT installed" note, whenever the project's `.codex/` is `$CODEX_HOME` (default `~/.codex`). Separately, the first-run bootstrap inside a Codex session crashed with `OSError: Read-only file system`, after writing the step files, because the workspace-write sandbox keeps `.codex/` read-only. It now reports the hook as NOT installed together with the command to run outside the sandbox, and the entry skill tells the orchestrator to re-run that command once with escalated permissions.
+
### Fixed
- **Cite-check no longer auto-passes a citation because one number matches (#150, from @jackiectl2).** The mechanical triage passed a sentence when every number in it appeared anywhere in the cited note's claims, so "Another team improves throughput by 10x" or "Async employs 10 engineers" passed on a claim about async's 10x throughput gain. A sentence with a figure of 2+ digits now passes only when it matches one of the cited note's claims or quotes in full; anything else goes to the cite-checker agent. Single-digit tokens ("Step 1", the "4" in "GPT-4") are still labels rather than figures, so those sentences keep passing on a long shared run of words. The step 14.5 skill and the cite-checker prompt describe the new rule.
diff --git a/src/hyperresearch/core/codex.py b/src/hyperresearch/core/codex.py
index 0869369..ebda6e2 100644
--- a/src/hyperresearch/core/codex.py
+++ b/src/hyperresearch/core/codex.py
@@ -24,8 +24,10 @@ on this pipeline is answering the question inline and skipping the steps.
from __future__ import annotations
+import os
import re
from datetime import UTC, datetime, timedelta
+from pathlib import Path
import yaml
@@ -286,6 +288,16 @@ policy:
STOP_GATE_SUBCOMMAND = "run stop-gate"
+def user_codex_home() -> Path:
+ """Codex's user-level config directory: $CODEX_HOME, else ~/.codex.
+
+ Hooks there run in every Codex session, so the per-project Stop hook
+ must never be written into it.
+ """
+ configured = os.environ.get("CODEX_HOME", "").strip()
+ return Path(configured).expanduser() if configured else Path.home() / ".codex"
+
+
def stop_hook_command(hpr_path: str) -> str:
"""The Stop hook command line — the resolved CLI path plus the subcommand.
diff --git a/src/hyperresearch/core/hooks.py b/src/hyperresearch/core/hooks.py
index c1291d3..795e5d8 100644
--- a/src/hyperresearch/core/hooks.py
+++ b/src/hyperresearch/core/hooks.py
@@ -3972,9 +3972,19 @@ def _install_codex_stop_hook(vault_root: Path, hpr_path: str) -> str | None:
own entry is replaced. No PreToolUse hook: `codex exec` mishandles
PreToolUse output, and the vault-check reminder is not worth that risk.
"""
- from hyperresearch.core.codex import merge_stop_hook
+ from hyperresearch.core.codex import merge_stop_hook, user_codex_home
- hooks_path = vault_root / ".codex" / "hooks.json"
+ codex_dir = vault_root / ".codex"
+ if codex_dir.resolve() == user_codex_home().resolve():
+ # A vault at the home directory: its .codex/ is Codex's user-level
+ # config, where the hook would gate every Codex session on the
+ # machine. The gate finds this vault from any directory below it.
+ return (
+ f"Codex: Stop hook NOT installed — {codex_dir} is Codex's user-level "
+ "config, where it would run in every Codex session"
+ )
+
+ hooks_path = codex_dir / "hooks.json"
settings: dict = {}
if hooks_path.exists():
# An unreadable hooks.json holds the user's hooks in a form we cannot
@@ -3993,8 +4003,18 @@ def _install_codex_stop_hook(vault_root: Path, hpr_path: str) -> str | None:
merged = merge_stop_hook(settings, hpr_path)
if merged == settings:
return None
- hooks_path.parent.mkdir(parents=True, exist_ok=True)
- hooks_path.write_text(json.dumps(merged, indent=2) + "\n", encoding="utf-8")
+ try:
+ hooks_path.parent.mkdir(parents=True, exist_ok=True)
+ hooks_path.write_text(json.dumps(merged, indent=2) + "\n", encoding="utf-8")
+ except OSError as exc:
+ # Codex's workspace-write sandbox keeps .codex/ read-only, so the
+ # first-run bootstrap inside a session cannot add the hook.
+ hpr = hpr_path.replace("\\", "/")
+ return (
+ f"Codex: .codex/hooks.json is not writable ({exc.strerror or exc}) — Stop hook "
+ f"NOT installed. Re-run `{hpr} install --steps-only . --target codex` outside "
+ "the Codex sandbox to add it"
+ )
return "Codex: .codex/hooks.json (Stop hook: run stop-gate)"
diff --git a/src/hyperresearch/skills/hyperresearch.md b/src/hyperresearch/skills/hyperresearch.md
index d158531..424be1e 100644
--- a/src/hyperresearch/skills/hyperresearch.md
+++ b/src/hyperresearch/skills/hyperresearch.md
@@ -105,7 +105,7 @@ Before you invoke any step skill, do this:
0. **Auto-init if missing.** Two checks for the first-run-after-global-install case:
- **Vault check.** If `.hyperresearch/` doesn't exist in the working directory, run `hyperresearch init . --json`. Creates the SQLite vault and `research/` directory.
-<% if platform == "codex" %> - **Step-files check.** If `.hyperresearch/codex/steps/hyperresearch-1-decompose.md` doesn't exist relative to the working directory, run `hyperresearch install --steps-only . --target codex --json`. Installs the 16 step files (and the `hyperresearch-*` custom agents) that later steps read and spawn.<% else %> - **Step-skills check.** If `.claude/skills/hyperresearch-1-decompose/SKILL.md` doesn't exist relative to the working directory, run `hyperresearch install --steps-only . --json`. Installs the 16 step skill files needed by `Skill(skill: "hyperresearch-N-...")` calls in later steps.<% endif %>
+<% if platform == "codex" %> - **Step-files check.** If `.hyperresearch/codex/steps/hyperresearch-1-decompose.md` doesn't exist relative to the working directory, run `hyperresearch install --steps-only . --target codex --json`. Installs the 16 step files (and the `hyperresearch-*` custom agents) that later steps read and spawn, plus the Stop hook in `.codex/hooks.json`. The sandbox keeps `.codex/` read-only, so if the output says the Stop hook was NOT installed because `.codex/hooks.json` is not writable, re-run that one command once with escalated permissions; if escalation is refused or unavailable (as in `codex exec`), carry on without the hook.<% else %> - **Step-skills check.** If `.claude/skills/hyperresearch-1-decompose/SKILL.md` doesn't exist relative to the working directory, run `hyperresearch install --steps-only . --json`. Installs the 16 step skill files needed by `Skill(skill: "hyperresearch-N-...")` calls in later steps.<% endif %>
If either command fails because the binary isn't on PATH, tell the user to run `pip install hyperresearch` first. If both files already exist, both commands no-op cheaply — safe to run unconditionally.
diff --git a/tests/test_core/test_codex_install.py b/tests/test_core/test_codex_install.py
index 9fcfb05..7551b7e 100644
--- a/tests/test_core/test_codex_install.py
+++ b/tests/test_core/test_codex_install.py
@@ -5,6 +5,7 @@ from __future__ import annotations
import json
import tomllib
from datetime import UTC, datetime, timedelta
+from pathlib import Path
import pytest
@@ -359,6 +360,54 @@ def test_stop_hook_leaves_unparseable_hooks_json_alone(tmp_vault):
assert hooks_path.read_text(encoding="utf-8") == "{ not json"
[email protected]("via", ["CODEX_HOME", "HOME"])
+def test_stop_hook_never_lands_in_user_codex_config(tmp_path, monkeypatch, via):
+ """A vault at the home directory must not turn the Stop gate into a user-level hook."""
+ from hyperresearch.core.hooks import _install_codex_stop_hook
+
+ def set_home(path):
+ # Path.home() reads HOME on POSIX and USERPROFILE on Windows.
+ monkeypatch.setenv("HOME", str(path))
+ monkeypatch.setenv("USERPROFILE", str(path))
+
+ home = tmp_path / "home"
+ home.mkdir()
+ if via == "CODEX_HOME":
+ monkeypatch.setenv("CODEX_HOME", str(home / ".codex"))
+ set_home(tmp_path / "elsewhere")
+ else:
+ monkeypatch.delenv("CODEX_HOME", raising=False)
+ set_home(home)
+ assert Path.home() == (tmp_path / "elsewhere" if via == "CODEX_HOME" else home)
+
+ result = _install_codex_stop_hook(home, "hyperresearch")
+
+ assert result and "NOT installed" in result
+ assert not (home / ".codex" / "hooks.json").exists()
+
+
+def test_stop_hook_reports_read_only_codex_dir(tmp_vault, monkeypatch):
+ """Codex's sandbox keeps .codex/ read-only; the bootstrap must not crash on it."""
+ import errno
+ from pathlib import Path
+
+ from hyperresearch.core.hooks import _install_codex_stop_hook
+
+ real_write_text = Path.write_text
+
+ def read_only_codex(self, *args, **kwargs):
+ if self.name == "hooks.json":
+ raise OSError(errno.EROFS, "Read-only file system")
+ return real_write_text(self, *args, **kwargs)
+
+ monkeypatch.setattr(Path, "write_text", read_only_codex)
+
+ result = _install_codex_stop_hook(tmp_vault.root, "/opt/hpr")
+
+ assert result and "NOT installed" in result
+ assert not (tmp_vault.root / ".codex" / "hooks.json").exists()
+
+
def test_stop_hook_command_quotes_only_paths_with_spaces():
assert codex.stop_hook_command("C:\\venv\\hpr.exe") == "C:/venv/hpr.exe run stop-gate"
assert codex.stop_hook_command("/a b/hpr") == '"/a b/hpr" run stop-gate'