Skip to content

A self-organizing Obsidian vault that gives AI coding agents persistent memory.

docs: record that Codex takes the SessionStart envelope, and the trust its hooks need (#362)

Brenno Ferrariddfc70442aad
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 111e128..211b9a4 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -203,7 +203,7 @@ sequenceDiagram
A few specific design choices are worth calling out:
-- **`SessionStart` injects, it does not load.** It builds a briefing (filename listing, North Star excerpt, git summary, open tasks aggregated from `work/active/` and the vault root) and hands it to the agent. Full note contents never flow through this hook. Its size is bounded by `eager_layer_budget_bytes`, held under Claude Code's 10,000-character hook output cap, and reported by the meter on the last line of every injection, so the cost is visible rather than assumed. When the template's Claude Code mod delivers the same briefing as an instruction file instead, the hook stands down and the briefing is bounded by `eager_layer_instruction_budget_bytes`, since instruction files are not under the hook cap (#264). The same backstop holds there, in bytes: sections that never degrade are cut at the budget plus the meter's room, and the meter says "truncated to fit the instruction budget". On the hook path the briefing goes out as one JSON object, `{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":…}}`, for every agent (#340). Gemini parses a hook's stdout as JSON and takes context only from that field (per its hooks reference as of 2026-10-13, not observed), and Claude Code accepts the same shape, capping the `additionalContext` string rather than the raw stdout. Whether Codex and Grok take context from the envelope is unverified (TBC). So the budget and the backstop measure the JSON-encoded text (escaping counts), keeping the whole stdout under the cap for an agent whose cap is undocumented. The mod's `deliver` run stays plain text, since it becomes an instruction file. The open-tasks scan is filesystem-only so the hook never spawns the Obsidian CLI — that subprocess flashes the Electron app on macOS when no instance is running (#83).
+- **`SessionStart` injects, it does not load.** It builds a briefing (filename listing, North Star excerpt, git summary, open tasks aggregated from `work/active/` and the vault root) and hands it to the agent. Full note contents never flow through this hook. Its size is bounded by `eager_layer_budget_bytes`, held under Claude Code's 10,000-character hook output cap, and reported by the meter on the last line of every injection, so the cost is visible rather than assumed. When the template's Claude Code mod delivers the same briefing as an instruction file instead, the hook stands down and the briefing is bounded by `eager_layer_instruction_budget_bytes`, since instruction files are not under the hook cap (#264). The same backstop holds there, in bytes: sections that never degrade are cut at the budget plus the meter's room, and the meter says "truncated to fit the instruction budget". On the hook path the briefing goes out as one JSON object, `{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":…}}`, for every agent (#340). Gemini parses a hook's stdout as JSON and takes context only from that field (per its hooks reference as of 2026-10-13, not observed), and Claude Code accepts the same shape, capping the `additionalContext` string rather than the raw stdout. Codex takes context from it the same way (observed with Codex CLI 0.160.0 as of 2026-10-13, #345). Whether Grok does is unverified (TBC). So the budget and the backstop measure the JSON-encoded text (escaping counts), keeping the whole stdout under the cap for an agent whose cap is undocumented. The mod's `deliver` run stays plain text, since it becomes an instruction file. The open-tasks scan is filesystem-only so the hook never spawns the Obsidian CLI — that subprocess flashes the Electron app on macOS when no instance is running (#83).
- **`UserPromptSubmit` classifies, it does not route.** It tags the prompt with hints like `ARCHITECTURE discussion` or `DECISION`; the agent decides where to file. Keeping the hook opinion-free means the routing logic lives in `AGENTS.md`, which is editable per-user without touching scripts.
- **QMD refresh is shared, debounced, and detached.** Three hook entries fire the same refresh helper — `PostToolUse` (after `.md` writes), `PreCompact` (before transcript backup; writes tend to cluster before compaction), and `Stop` (after a response) — sharing one sentinel file so a burst of events produces at most one worker per debounce window. The actual indexing runs in `.claude/scripts/qmd-refresh-run.ts` as a detached, stdio-silent worker (`qmd update` → `qmd embed` → tail-chase `qmd update`), so the parent hook returns in milliseconds and nothing flows to the agent's context.
- **`VAULT_QMD_REFRESH=off` switches the detached refresh off** (exactly `off`, as wiki-mind's copy reads it): no `qmd-refresh-run.ts` worker, and no detached `qmd update` or bootstrap from `SessionStart`. The debounce decision and its sentinel stamps still run. The test suite sets it in every test process and every hook a test runs. The test runner also stops and fails on any surviving worker whose command line names the run's temp folder, which every trailing worker's does; an immediate-path worker carries no path, so for those the switch is the guard (#337).
diff --git a/README.ja.md b/README.ja.md
index 85cfac5..9c491b8 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -245,6 +245,12 @@ obsidian-mindはClaude Code、Codex CLI、Gemini CLIで動作します。`CLAUDE
**Codex CLI** — `AGENTS.md`をネイティブに読み込みます。`.codex/hooks.json`のフック設定がClaude Codeと同じフックスクリプトを接続 — セッションコンテキスト、メッセージ分類、書き込み検証が自動的に動作します。
+Codex がプロジェクトのフックを実行するには、2 つの信頼が必要です(Codex CLI 0.160.0 で確認、2026-10-13 時点、[#345](https://github.com/breferrari/obsidian-mind/issues/345))。
+- **ボールトのフォルダーが信頼されていること。** Codex は `~/.codex/config.toml` の `[projects.'<path>']` に記録します。Windows ではキーが `\\?\` 付きのパスになります(例: `[projects.'\\?\C:\path\to\vault']`)。
+- **各フックが承認されていること。** 対話型の `codex` セッションで承認します。Codex は各承認を `[hooks.state]` の `trusted_hash` として保存します。
+
+両方が揃うまで Codex はフックを一切実行せず、セッションにボールトのコンテキストは届きません。
+
**Gemini CLI** — `GEMINI.md`をネイティブに読み込みます。`.gemini/settings.json`のフック設定がGeminiのイベント名を共有フックスクリプトにマッピングします。
**その他のエージェント**(Cursor、Windsurf、GitHub Copilot、JetBrains AI)— `AGENTS.md`でボールト規約を読み取ります。フックサポートはエージェントにより異なります。
diff --git a/README.ko.md b/README.ko.md
index 738febb..ded6ccc 100644
--- a/README.ko.md
+++ b/README.ko.md
@@ -245,6 +245,12 @@ obsidian-mind는 Claude Code, Codex CLI, Gemini CLI에서 작동합니다. `CLAU
**Codex CLI** — `AGENTS.md`를 네이티브로 읽습니다. `.codex/hooks.json`의 훅 설정이 Claude Code와 동일한 훅 스크립트를 연결합니다 — 세션 컨텍스트, 메시지 분류, 쓰기 검증이 자동으로 작동합니다.
+Codex가 프로젝트의 훅을 실행하려면 두 가지 신뢰가 필요합니다(Codex CLI 0.160.0으로 확인, 2026-10-13 기준, [#345](https://github.com/breferrari/obsidian-mind/issues/345)).
+- **볼트 폴더가 신뢰되어 있어야 합니다.** Codex는 이를 `~/.codex/config.toml`의 `[projects.'<path>']`에 기록합니다. Windows에서는 키가 `\\?\` 접두사가 붙은 경로입니다(예: `[projects.'\\?\C:\path\to\vault']`).
+- **각 훅이 승인되어 있어야 합니다.** 대화형 `codex` 세션에서 승인하세요. Codex는 각 승인을 `[hooks.state]` 아래 `trusted_hash`로 저장합니다.
+
+둘 다 갖춰지기 전에는 Codex가 어떤 훅도 실행하지 않으며, 세션에 볼트 컨텍스트가 전달되지 않습니다.
+
**Gemini CLI** — `GEMINI.md`를 네이티브로 읽습니다. `.gemini/settings.json`의 훅 설정이 Gemini의 이벤트 이름을 공유 훅 스크립트에 매핑합니다.
**기타 에이전트** (Cursor, Windsurf, GitHub Copilot, JetBrains AI) — `AGENTS.md`로 볼트 규약을 읽습니다. 훅 지원은 에이전트마다 다릅니다.
diff --git a/README.md b/README.md
index d4d003f..d7c9a84 100644
--- a/README.md
+++ b/README.md
@@ -262,6 +262,12 @@ Observed with scratch vaults as of 2026-10-06 (Claude Code 2.1.291, Codex CLI 0.
**Codex CLI** — hook config at `.codex/hooks.json` wires the same hook scripts Claude Code uses — session context, message classification, and write validation work automatically. Commands work as regular prompts (e.g. type `om-standup` without the `/` prefix).
+Codex runs a project's hooks only once two kinds of trust are in place (observed with Codex CLI 0.160.0 as of 2026-10-13, [#345](https://github.com/breferrari/obsidian-mind/issues/345)):
+- **The vault folder is trusted.** Codex records this in `~/.codex/config.toml` under `[projects.'<path>']`. On Windows the key is the `\\?\`-prefixed path, e.g. `[projects.'\\?\C:\path\to\vault']`.
+- **Each hook is approved.** Approve them in an interactive `codex` session. Codex stores each approval as a `trusted_hash` under `[hooks.state]`.
+
+Until both are in place, Codex runs no hook, and the session gets no vault context.
+
**Gemini CLI** — hook config at `.gemini/settings.json` maps Gemini's event names to the shared hook scripts, and its `context.fileName` setting points Gemini at `AGENTS.md`.
**Antigravity** and **Grok** — read `AGENTS.md` for vault conventions. Their hook, skill and command layers are tracked in [#322](https://github.com/breferrari/obsidian-mind/issues/322) and [#323](https://github.com/breferrari/obsidian-mind/issues/323).
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 5efd772..f3c6868 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -245,6 +245,12 @@ obsidian-mind 支持 Claude Code、Codex CLI 和 Gemini CLI。`CLAUDE.md` 中的
**Codex CLI** — 原生读取 `AGENTS.md`。`.codex/hooks.json` 中的钩子配置连接了与 Claude Code 相同的钩子脚本 — 会话上下文、消息分类和写入验证自动工作。
+Codex 只有在两种信任都具备时才会运行项目的钩子(使用 Codex CLI 0.160.0 观察,截至 2026-10-13,[#345](https://github.com/breferrari/obsidian-mind/issues/345)):
+- **vault 文件夹已被信任。** Codex 将其记录在 `~/.codex/config.toml` 的 `[projects.'<path>']` 下。在 Windows 上,键是带 `\\?\` 前缀的路径,例如 `[projects.'\\?\C:\path\to\vault']`。
+- **每个钩子已被批准。** 在交互式 `codex` 会话中批准。Codex 将每次批准作为 `trusted_hash` 存储在 `[hooks.state]` 下。
+
+两者都具备之前,Codex 不会运行任何钩子,会话也得不到 vault 上下文。
+
**Gemini CLI** — 原生读取 `GEMINI.md`。`.gemini/settings.json` 中的钩子配置将 Gemini 的事件名称映射到共享钩子脚本。
**其他 Agent**(Cursor、Windsurf、GitHub Copilot、JetBrains AI)— 通过 `AGENTS.md` 读取 vault 规约。钩子支持因 Agent 而异。