Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(codex-doctor): accept [features] hooks = true in modern Codex (#4634) (#4635)

Xinmin Zeng9c31b110766a
diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
index fa4a80025..e43589824 100644
--- a/.github/workflows/pr.yml
+++ b/.github/workflows/pr.yml
@@ -38,6 +38,7 @@ jobs:
examples/codex-memory-plugin/scripts/capture-utils.test.mjs \
examples/codex-memory-plugin/scripts/marketplace.test.mjs \
examples/codex-memory-plugin/scripts/ov-credentials.test.mjs \
+ examples/codex-memory-plugin/scripts/ov-memory-doctor.test.mjs \
examples/codex-memory-plugin/scripts/recall-compressor-profile.test.mjs \
examples/codex-memory-plugin/scripts/auto-recall.test.mjs \
examples/codex-memory-plugin/scripts/session-start-commit.test.mjs \
diff --git a/examples/codex-memory-plugin/README.md b/examples/codex-memory-plugin/README.md
index 4e02cdd32..c024a13f6 100644
--- a/examples/codex-memory-plugin/README.md
+++ b/examples/codex-memory-plugin/README.md
@@ -69,7 +69,8 @@ Then enable plugin hooks (if your Codex build doesn't already) by adding to `~/.
```toml
[features]
-plugin_hooks = true
+hooks = true
+# plugin_hooks = true # for older Codex releases
```
Finally start Codex and trust the plugin hooks once:
diff --git a/examples/codex-memory-plugin/scripts/ov-memory-doctor.mjs b/examples/codex-memory-plugin/scripts/ov-memory-doctor.mjs
index 08c4011f8..c44ff35f7 100644
--- a/examples/codex-memory-plugin/scripts/ov-memory-doctor.mjs
+++ b/examples/codex-memory-plugin/scripts/ov-memory-doctor.mjs
@@ -17,7 +17,7 @@
* Exit code 1 when any check fails, 0 otherwise. Never prints a full api key.
*/
-import { readFileSync, readdirSync, statSync } from "node:fs";
+import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
import { homedir } from "node:os";
import { dirname, join, resolve as resolvePath } from "node:path";
import { fileURLToPath } from "node:url";
@@ -142,6 +142,81 @@ function checkEnvironment(report) {
return { codexOnPath: codex.ok };
}
+export function parseFeaturesList(stdout) {
+ const map = new Map();
+ if (typeof stdout !== "string") return map;
+ for (const line of stdout.split(/\r?\n/)) {
+ const trimmed = line.trim();
+ if (!trimmed) continue;
+ const parts = trimmed.split(/\s+/);
+ if (parts.length >= 3) {
+ const key = parts[0];
+ const stateStr = parts[parts.length - 1].toLowerCase();
+ const stage = parts.slice(1, -1).join(" ");
+ map.set(key, {
+ stage,
+ enabled: stateStr === "true",
+ });
+ }
+ }
+ return map;
+}
+
+export function assessHooksFeature(features, cliFeatures = null) {
+ const hooks = features?.hooks;
+ const pluginHooks = features?.plugin_hooks;
+
+ if (hooks === true) {
+ return { status: "ok", message: "[features] hooks = true" };
+ }
+ if (hooks === false) {
+ return {
+ status: "fail",
+ message: `hooks disabled in [features] (hooks=${hooks ?? "unset"}, plugin_hooks=${pluginHooks ?? "unset"})`,
+ detail: "no plugin hook fires when hooks feature is disabled",
+ fix: "set hooks = true under [features] in ~/.codex/config.toml",
+ };
+ }
+
+ if (cliFeatures instanceof Map) {
+ const liveHooks = cliFeatures.get("hooks");
+ if (liveHooks?.enabled === true) {
+ return {
+ status: "ok",
+ message: `[features] hooks enabled by default (Codex stage: ${liveHooks.stage || "stable"})`,
+ };
+ }
+ if (liveHooks?.enabled === false) {
+ return {
+ status: "fail",
+ message: "hooks feature is disabled in Codex",
+ detail: "Codex reports hooks feature effective state is false",
+ fix: "set hooks = true under [features] in ~/.codex/config.toml",
+ };
+ }
+ }
+
+ // Legacy config only applies when the modern feature cannot be determined.
+ if (pluginHooks === true) {
+ return { status: "ok", message: "[features] plugin_hooks = true (legacy; modern Codex uses hooks = true)" };
+ }
+ if (pluginHooks === false) {
+ return {
+ status: "fail",
+ message: "hooks disabled in [features] (plugin_hooks=false)",
+ detail: "legacy plugin hooks are explicitly disabled",
+ fix: "set plugin_hooks = true for older Codex, or hooks = true for modern Codex under [features] in ~/.codex/config.toml",
+ };
+ }
+
+ return {
+ status: "info",
+ message: "[features] hooks is not set (modern Codex enables hooks by default; older Codex needs plugin_hooks = true)",
+ detail: "if hooks do not fire, verify with `codex features list` or add hooks = true",
+ fix: "add hooks = true under [features] in ~/.codex/config.toml (or plugin_hooks = true for older Codex)",
+ };
+}
+
function checkInstall(report, { codexOnPath }) {
report.section("Plugin install");
const manifest = tryJson(join(PLUGIN_ROOT, ".codex-plugin", "plugin.json"));
@@ -210,9 +285,26 @@ function checkInstall(report, { codexOnPath }) {
if (!toml) {
report.warn(`${homeShort(CODEX_CONFIG)} not found`, "Codex has never been configured on this machine");
} else {
- const hooksOn = toml.features?.plugin_hooks;
- if (hooksOn === true) report.ok("[features] plugin_hooks = true");
- else report.fail(`[features] plugin_hooks is ${hooksOn === undefined ? "not set" : hooksOn}`, "no plugin hook fires at all", `add plugin_hooks = true under [features] in ${homeShort(CODEX_CONFIG)}`);
+ let cliFeatures = null;
+ if (codexOnPath) {
+ const featRes = runCommand("codex", ["features", "list"], { timeoutMs: 5000 });
+ if (featRes.ok) cliFeatures = parseFeaturesList(featRes.stdout);
+ }
+
+ const hooksAssessment = assessHooksFeature(toml.features, cliFeatures);
+ if (hooksAssessment.status === "ok") {
+ report.ok(hooksAssessment.message);
+ } else if (hooksAssessment.status === "warn") {
+ report.warn(hooksAssessment.message, hooksAssessment.detail, hooksAssessment.fix?.replace("~/.codex/config.toml", homeShort(CODEX_CONFIG)));
+ } else if (hooksAssessment.status === "info") {
+ report.info(hooksAssessment.message);
+ } else {
+ report.fail(
+ hooksAssessment.message,
+ hooksAssessment.detail,
+ hooksAssessment.fix?.replace("~/.codex/config.toml", homeShort(CODEX_CONFIG)),
+ );
+ }
const pluginSection = toml[`plugins."${PLUGIN_ID}"`];
if (!pluginSection) report.warn(`no [plugins."${PLUGIN_ID}"] section`, "the installer normally writes enabled = true here");
else if (pluginSection.enabled === false) report.fail(`[plugins."${PLUGIN_ID}"] enabled = false`, "", "set enabled = true");
@@ -432,7 +524,7 @@ function checkActivity(report, cfg, connection) {
const log = scanDebugLog(cfg.debugLogPath);
if (!log.exists) {
- report.info(`no hook log at ${homeShort(cfg.debugLogPath)}${cfg.debug ? " — debug is on but no hook has run since; if a Codex turn ran, hooks are not being spawned (plugin_hooks, trust, node)" : ""}`);
+ report.info(`no hook log at ${homeShort(cfg.debugLogPath)}${cfg.debug ? " — debug is on but no hook has run since; if a Codex turn ran, hooks are not being spawned (hooks, trust, node)" : ""}`);
} else {
report.info(`hook log ${homeShort(log.path)} — ${fmtBytes(log.size)}, last write ${fmtAge(log.mtimeMs)}, hooks seen: ${log.hooks.join(", ") || "(none)"}`);
if (log.proxyStart?.data?.mcpUrl) {
@@ -487,7 +579,18 @@ async function main() {
process.exitCode = report.exitCode();
}
-main().catch((err) => {
- console.error("ov-memory-doctor failed:", err?.stack || err?.message || err);
- process.exit(2);
-});
+function isDirectRun() {
+ if (!process.argv[1]) return false;
+ try {
+ return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+ } catch {
+ return resolvePath(process.argv[1]) === fileURLToPath(import.meta.url);
+ }
+}
+
+if (isDirectRun()) {
+ main().catch((err) => {
+ console.error("ov-memory-doctor failed:", err?.stack || err?.message || err);
+ process.exit(2);
+ });
+}
diff --git a/examples/codex-memory-plugin/scripts/ov-memory-doctor.test.mjs b/examples/codex-memory-plugin/scripts/ov-memory-doctor.test.mjs
new file mode 100644
index 000000000..524f752dd
--- /dev/null
+++ b/examples/codex-memory-plugin/scripts/ov-memory-doctor.test.mjs
@@ -0,0 +1,102 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { assessHooksFeature, parseFeaturesList } from "./ov-memory-doctor.mjs";
+
+test("parseFeaturesList: parses standard codex features list output", () => {
+ const sample = `
+hooks stable true
+plugin_hooks removed false
+plugins stable true
+apply_patch_preserve_line_endings under development false
+`;
+ const map = parseFeaturesList(sample);
+ assert.equal(map.size, 4);
+ assert.deepEqual(map.get("hooks"), { stage: "stable", enabled: true });
+ assert.deepEqual(map.get("plugin_hooks"), { stage: "removed", enabled: false });
+ assert.deepEqual(map.get("plugins"), { stage: "stable", enabled: true });
+ assert.deepEqual(map.get("apply_patch_preserve_line_endings"), { stage: "under development", enabled: false });
+});
+
+test("assessHooksFeature: modern Codex with explicit hooks = true in toml", () => {
+ const res = assessHooksFeature({ hooks: true });
+ assert.equal(res.status, "ok");
+ assert.equal(res.message, "[features] hooks = true");
+});
+
+test("assessHooksFeature: legacy Codex with explicit plugin_hooks = true in toml", () => {
+ const res = assessHooksFeature({ plugin_hooks: true });
+ assert.equal(res.status, "ok");
+ assert.match(res.message, /\[features\] plugin_hooks = true \(legacy/);
+});
+
+test("assessHooksFeature: both hooks = true and plugin_hooks = true in toml", () => {
+ const res = assessHooksFeature({ hooks: true, plugin_hooks: true });
+ assert.equal(res.status, "ok");
+ assert.equal(res.message, "[features] hooks = true");
+});
+
+test("assessHooksFeature: hooks explicitly false in toml", () => {
+ const res = assessHooksFeature({ hooks: false });
+ assert.equal(res.status, "fail");
+ assert.match(res.message, /hooks disabled in \[features\]/);
+ assert.match(res.fix, /set hooks = true/);
+});
+
+test("assessHooksFeature: explicit hooks overrides legacy config and live state", () => {
+ for (const hooks of [true, false]) {
+ const cliFeatures = new Map([["hooks", { stage: "stable", enabled: !hooks }]]);
+ const res = assessHooksFeature({ hooks, plugin_hooks: !hooks }, cliFeatures);
+ assert.equal(res.status, hooks ? "ok" : "fail");
+ assert.match(res.message, hooks ? /\[features\] hooks = true/ : /hooks disabled in \[features\]/);
+ }
+});
+
+test("assessHooksFeature: live hooks overrides conflicting legacy config", () => {
+ for (const enabled of [true, false]) {
+ const cliFeatures = new Map([["hooks", { stage: "stable", enabled }]]);
+ const res = assessHooksFeature({ plugin_hooks: !enabled }, cliFeatures);
+ assert.equal(res.status, enabled ? "ok" : "fail");
+ assert.match(res.message, enabled ? /hooks enabled by default/ : /hooks feature is disabled in Codex/);
+ }
+});
+
+test("assessHooksFeature: legacy config applies when CLI has no modern hooks entry", () => {
+ for (const enabled of [true, false]) {
+ const cliFeatures = new Map([["plugin_hooks", { stage: "experimental", enabled }]]);
+ const res = assessHooksFeature({ plugin_hooks: enabled }, cliFeatures);
+ assert.equal(res.status, enabled ? "ok" : "fail");
+ assert.match(res.message, /plugin_hooks/);
+ }
+});
+
+test("assessHooksFeature: plugin_hooks explicitly false in toml", () => {
+ const res = assessHooksFeature({ plugin_hooks: false });
+ assert.equal(res.status, "fail");
+ assert.match(res.message, /hooks disabled in \[features\]/);
+});
+
+test("assessHooksFeature: unset in toml, but CLI probe reports hooks enabled (stable default)", () => {
+ const cliFeatures = new Map([["hooks", { stage: "stable", enabled: true }]]);
+ const res = assessHooksFeature({}, cliFeatures);
+ assert.equal(res.status, "ok");
+ assert.match(res.message, /hooks enabled by default \(Codex stage: stable\)/);
+});
+
+test("assessHooksFeature: unset in toml, but CLI probe reports hooks disabled", () => {
+ const cliFeatures = new Map([["hooks", { stage: "under development", enabled: false }]]);
+ const res = assessHooksFeature({}, cliFeatures);
+ assert.equal(res.status, "fail");
+ assert.match(res.message, /hooks feature is disabled in Codex/);
+});
+
+test("assessHooksFeature: unset in toml and CLI probe unavailable (fallback to info)", () => {
+ const resEmpty = assessHooksFeature({}, null);
+ assert.equal(resEmpty.status, "info");
+ assert.match(resEmpty.message, /\[features\] hooks is not set/);
+ assert.match(resEmpty.fix, /hooks = true/);
+
+ const resUndef = assessHooksFeature(undefined, null);
+ assert.equal(resUndef.status, "info");
+ assert.match(resUndef.message, /\[features\] hooks is not set/);
+});
diff --git a/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.md b/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.md
index 156a5cd95..a6ebb537a 100644
--- a/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.md
+++ b/examples/codex-memory-plugin/skills/ov-memory-doctor/SKILL.md
@@ -19,7 +19,7 @@ Troubleshooting for the OpenViking memory plugin. Three things go
wrong on a user's machine, each silently:
- **Install** — marketplace registration, `[plugins."openviking-memory@openviking"]`
- and `[features] plugin_hooks` in `~/.codex/config.toml`, per-hook trust
+ and `[features] hooks` (or legacy `plugin_hooks`) in `~/.codex/config.toml`, per-hook trust
records, the stdio MCP proxy. When these are wrong, hooks never run and
nothing is logged anywhere.
- **Configuration** — `~/.openviking/ovcli.conf`, `~/.openviking/ov.conf` and
@@ -75,7 +75,9 @@ Work top-down; fix the first ✗ and rerun before chasing the next.
|---|---|---|
| `ovcli.conf cannot be parsed` / `no usable config` | Trailing comma/comment; the plugin treats the file as absent and uses the localhost default | Fix the JSON. Fresh machine: create `~/.openviking/ovcli.conf` with `url` + `api_key`, `chmod 600`. |
| `codex plugin list does not show …` | Plugin never installed, or installed under an old id | Re-run the one-line installer (`bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) --harness codex`; add `--dist tos` where GitHub is blocked). |
-| `[features] plugin_hooks is not set/false` | Codex never runs plugin hooks | Add `plugin_hooks = true` under `[features]` in `~/.codex/config.toml`, restart Codex. |
+| `hooks disabled in [features]` / `hooks feature is disabled in Codex` | The applicable hooks feature is disabled | Set `hooks = true` under `[features]` in `~/.codex/config.toml` (or `plugin_hooks = true` for older Codex), restart Codex. |
+| `[features] hooks enabled by default` | The live CLI reports hooks enabled; legacy `plugin_hooks` has no effect | Continue with the remaining checks. |
+| `[features] hooks is not set` (info) | The CLI probe could not determine the modern feature state and no legacy flag decides it | Verify with `codex features list`; an unset key alone does not prove hooks are disabled. |
| `[plugins."…"] enabled = false` / `installed but disabled` | Plugin switched off in config.toml | Set `enabled = true`, restart Codex. |
| `hooks disabled in [hooks.state]` | A hook was declined at the trust prompt | Remove `enabled = false` from that `[hooks.state."openviking-memory@openviking:hooks/hooks.json:<event>:0:0"]` section; approve the hook again. |
| `hooks without a trust record yet` | Codex has not yet approved those hooks (fresh install or `hooks.json` changed on update) | Start a Codex session and accept the hook prompt; nothing is wrong. |
@@ -110,7 +112,7 @@ More symptoms, exact error strings and log stage names: [reference.md](reference
Prove hooks run at all: put `OPENVIKING_DEBUG=1` in the environment that
launches Codex, run one turn, then read `~/.openviking/logs/codex-hooks.log`
(JSONL; grep `"error"`). An absent or unchanged log after a full turn means the
-hooks were not spawned — a `plugin_hooks` / trust / node problem, not a server
+hooks were not spawned — a hooks / trust / node problem, not a server
problem. `~/.openviking/logs/cc-hooks.log` belongs to the Claude Code plugin.
Prove the key and identity by hand (`Bearer` is case-sensitive with exactly one
diff --git a/examples/codex-memory-plugin/skills/ov-memory-doctor/reference.md b/examples/codex-memory-plugin/skills/ov-memory-doctor/reference.md
index 2fa9288a4..d972be84d 100644
--- a/examples/codex-memory-plugin/skills/ov-memory-doctor/reference.md
+++ b/examples/codex-memory-plugin/skills/ov-memory-doctor/reference.md
@@ -14,7 +14,7 @@ and `CODEX_CONFIG_FILE` relocate individual pieces.
| `~/.openviking/ovcli.conf.<name>` | Saved CLI profiles (`ov config switch` copies one over `ovcli.conf`). `ovcli.conf.bak.<epoch>` are installer backups. |
| `<repo root>/.openviking/config.json` / `config.local.json` | Workspace config layers, `version: 1` required: `peer.source`, `peer.id`, `recall.*`, `capture.*`, `bypass.session_patterns`, `labels`. `config.json` is committed and shared; `config.local.json` is private and gitignored. Trusted without a prompt, but connection and credential keys (`url`, `api_key`, `account`, `user`, `extra_headers`, …) are stripped with a warning and `${VAR}` is never expanded. A blanket `.openviking/` rule in `.gitignore` stops `config.json` from ever being committed — narrow it to `.openviking/media/` and `.openviking/downloads/`. |
| `~/.openviking/workspaces/<slot>.json` | Per-machine workspace registry, one file per workspace (`<dir name>-<hash>.json`, mode 0600). Outranks both workspace files, and nothing writes it — a user creates the file by hand. An entry recorded for a different repository is ignored, not inherited. |
-| `~/.codex/config.toml` | `[features] plugin_hooks`, `[plugins."openviking-memory@openviking"] enabled`, `[marketplaces.openviking]` (source, ref), `[hooks.state."openviking-memory@openviking:hooks/hooks.json:<event>:0:0"] trusted_hash` for `session_start`, `user_prompt_submit`, `stop`, `session_end`, `pre_compact`. |
+| `~/.codex/config.toml` | `[features] hooks` (or legacy `plugin_hooks`), `[plugins."openviking-memory@openviking"] enabled`, `[marketplaces.openviking]` (source, ref), `[hooks.state."openviking-memory@openviking:hooks/hooks.json:<event>:0:0"] trusted_hash` for `session_start`, `user_prompt_submit`, `stop`, `session_end`, `pre_compact`. |
| `~/.codex/plugins/cache/openviking/openviking-memory/<version>/` | The copy Codex runs hooks from. Keyed by `plugin.json` version. |
| `~/.codex/.tmp/marketplaces/openviking/` | Git clone of the marketplace (GitHub/TOS dist); `examples/codex-memory-plugin` inside it is what `codex plugin list` reports as the source path. |
| `~/.openviking/codex-plugin-state/<session_id>.json` | Per-session state: `ovSessionId` (`cx-<session_id>`, null once committed), `transcriptPath` (last rollout seen, used by the SessionStart sweep to catch up unsent turns), `capturedTurnCount`, `lastUpdatedAt`. |
@@ -59,6 +59,11 @@ mode only), `X-OpenViking-Actor-Peer`, `User-Agent: openviking-memory-codex/<ver
The open-source server also accepts `X-API-Key` (and prefers it when both are
sent); the Volcengine-hosted OpenViking Service (`https://api.vikingdb.cn-beijing.volces.com/openviking`) accepts Bearer only.
+The doctor checks explicit `features.hooks` first, then the live `hooks` entry
+from `codex features list`. Legacy `plugin_hooks` only decides the result when
+neither supplies a modern feature state. An unavailable probe with no configured
+flag is informational; a live enabled result needs no configuration change.
+
## Peer: giving a directory its own memory
```json
@@ -178,7 +183,7 @@ reports `unknown command`.
| Symptom | Likely cause | Detect | Fix |
|---|---|---|---|
-| Plugin listed and enabled, but no `<openviking-context>` ever, no log | `plugin_hooks` off, hooks never trusted, or no parseable config | doctor Plugin install + Configuration sections | Enable hooks / approve the prompt / fix config |
+| Plugin listed and enabled, but no `<openviking-context>` ever, no log | `hooks` / `plugin_hooks` off, hooks never trusted, or no parseable config | doctor Plugin install + Configuration sections | Enable hooks / approve the prompt / fix config |
| Worked until an edit to `ovcli.conf` | JSON broken by the edit | doctor "cannot be parsed" | Fix JSON |
| Edits to `ovcli.conf` or `ov config switch` have no effect | Env var or rc-file export wins (`credential source: env`) | doctor "← env"; `env \| grep OPENVIKING_` | Remove the export |
| Recall empty on a healthy server | Wrong key (401 reads as no results), wrong user space, peer scope, threshold | `/health` with key; `/api/v1/system/status` → `result.user` | Fix key; `OPENVIKING_PEER_ID`; lower `OPENVIKING_SCORE_THRESHOLD` |