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
Python agentsagentskillscitationsclaude-codecodexcodex-plugincodex-skilldeep-researchdeep-research-agentdeepresearchmcp-serverresearchresearch-agentresearch-tools
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.mdindex 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.pyindex 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 osimport refrom datetime import UTC, datetime, timedelta+from pathlib import Pathimport 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.pyindex 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` mishandlesPreToolUse 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.mdindex 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.pyindex 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 annotationsimport jsonimport tomllibfrom datetime import UTC, datetime, timedelta+from pathlib import Pathimport 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'