@inetafrica/open-claudia 2.15.0 → 3.0.0

package/test-provider-stream-decoder.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const assert = require("assert");
+const { createJsonlDecoder } = require("./core/providers/events");
+
+const unicodeEvent = { type: "fixture", text: "café 👋" };
+const unicodeLine = Buffer.from(`${JSON.stringify(unicodeEvent)}\n`, "utf8");
+const emoji = Buffer.from("👋", "utf8");
+const emojiAt = unicodeLine.indexOf(emoji);
+assert.ok(emojiAt > 0);
+
+const splitUtf8 = createJsonlDecoder();
+assert.deepStrictEqual(splitUtf8.push(unicodeLine.subarray(0, emojiAt + 1)), []);
+assert.deepStrictEqual(splitUtf8.push(unicodeLine.subarray(emojiAt + 1)), [unicodeEvent]);
+assert.strictEqual(splitUtf8.bufferedBytes, 0);
+
+const jsonSplit = createJsonlDecoder();
+assert.deepStrictEqual(jsonSplit.push(Buffer.from('{"type":"part')), []);
+assert.deepStrictEqual(jsonSplit.push(Buffer.from('ial","n":1}\n')), [{ type: "partial", n: 1 }]);
+
+const coalesced = createJsonlDecoder();
+assert.deepStrictEqual(coalesced.push(Buffer.from(
+  '{"type":"one"}\r\n\r\n  \r\n{"type":"two"}\r\n',
+)), [{ type: "one" }, { type: "two" }]);
+
+const noNewline = createJsonlDecoder();
+assert.deepStrictEqual(noNewline.push(Buffer.from('{"type":"tail","ok":true}')), []);
+assert.deepStrictEqual(noNewline.end(), [{ type: "tail", ok: true }]);
+assert.deepStrictEqual(noNewline.end(), [], "EOF flush is idempotent");
+assert.throws(
+  () => noNewline.push(Buffer.from("{}\n")),
+  (error) => error && error.code === "DECODER_CLOSED",
+);
+
+const malformed = createJsonlDecoder();
+const malformedEvents = malformed.push(Buffer.from('{"secret":"must-not-leak"\n{"type":"recovered"}\n'));
+assert.strictEqual(malformedEvents[0].type, "decoder.error");
+assert.strictEqual(malformedEvents[0].code, "MALFORMED_JSON");
+assert.ok(!JSON.stringify(malformedEvents[0]).includes("must-not-leak"));
+assert.deepStrictEqual(malformedEvents[1], { type: "recovered" });
+
+const bounded = createJsonlDecoder({ maxLineBytes: 32 });
+const overlong = bounded.push(Buffer.from(`{"value":"${"x".repeat(80)}`));
+assert.strictEqual(overlong.length, 1);
+assert.strictEqual(overlong[0].type, "decoder.error");
+assert.strictEqual(overlong[0].code, "LINE_TOO_LARGE");
+assert.ok(bounded.bufferedBytes <= 32, "tail buffering must stay bounded");
+assert.strictEqual(bounded.discarding, true);
+assert.deepStrictEqual(
+  bounded.push(Buffer.from('discarded"}\n{"type":"after-oversize"}\n')),
+  [{ type: "after-oversize" }],
+);
+assert.strictEqual(bounded.discarding, false);
+
+const lineTooLarge = createJsonlDecoder({ maxLineBytes: 16 });
+const oversizedLine = lineTooLarge.push(Buffer.from(`{"x":"${"y".repeat(40)}"}\n{"ok":1}\n`));
+assert.strictEqual(oversizedLine[0].code, "LINE_TOO_LARGE");
+assert.deepStrictEqual(oversizedLine[1], { ok: 1 });
+
+const first = createJsonlDecoder();
+const second = createJsonlDecoder();
+first.push(Buffer.from('{"id":"first"}'));
+second.push(Buffer.from('{"id":"second"}'));
+assert.deepStrictEqual(first.end(), [{ id: "first" }]);
+assert.deepStrictEqual(second.end(), [{ id: "second" }]);
+
+console.log("provider stream decoder OK");

package/test-provider-subagent.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), "open-claudia-provider-subagent-"));
+process.env.OPEN_CLAUDIA_TEST = "1";
+process.env.OPEN_CLAUDIA_CONFIG_DIR = path.join(root, "config");
+process.env.WORKSPACE = root;
+
+const fixture = path.join(__dirname, "test-fixtures", "fake-agent-cli.js");
+const { createClaudeProvider } = require("./core/providers/claude");
+const { createCodexProvider } = require("./core/providers/codex");
+const { createUtilityAgentService } = require("./core/utility-agent");
+const {
+  buildSubagentSystemPrompt,
+  concurrentCount,
+  createSubagentService,
+} = require("./core/subagent");
+const { HELP, parseAgentArgs } = require("./bin/agent");
+
+function wait(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); }
+
+async function waitForFile(file, timeoutMs = 2000) {
+  const started = Date.now();
+  while (!fs.existsSync(file)) {
+    if (Date.now() - started > timeoutMs) throw new Error(`timed out waiting for ${path.basename(file)}`);
+    await wait(5);
+  }
+}
+
+function makeProvider(kind, controls = {}) {
+  const common = {
+    hookTransport: false,
+    resolveExecutable: () => fixture,
+    defaultModel: `${kind}-high-fixture`,
+    buildEnv: () => ({
+      HOME: root,
+      PATH: process.env.PATH || path.dirname(process.execPath),
+      FAKE_AGENT_KIND: kind,
+      ...controls,
+    }),
+    getAuthStatus: () => ({ state: "authenticated", reason: null }),
+  };
+  return kind === "claude" ? createClaudeProvider(common) : createCodexProvider(common);
+}
+
+function makeRegistry(provider) {
+  return {
+    getProvider(id) {
+      if (id !== provider.id) throw Object.assign(new Error(`unknown ${id}`), { code: "UNKNOWN_PROVIDER" });
+      return provider;
+    },
+    listProviders: () => [provider],
+    providerStatus(id) {
+      assert.strictEqual(id, provider.id);
+      return {
+        id,
+        availability: { state: "available", executable: fixture, reason: null },
+        compatibility: { state: "compatible", reason: null },
+        auth: { state: "authenticated", reason: null },
+      };
+    },
+  };
+}
+
+function harness(kind, controls = {}, serviceOptions = {}) {
+  const provider = makeProvider(kind, controls);
+  const utility = createUtilityAgentService({
+    registry: makeRegistry(provider),
+    env: { UTILITY_PROVIDER: kind },
+    ...serviceOptions,
+  });
+  return {
+    provider,
+    utility,
+    subagent: createSubagentService({ spawnUtilityAgent: utility.spawnUtilityAgent }),
+  };
+}
+
+async function main() {
+  assert.strictEqual(typeof createSubagentService, "function", "subagent compatibility wrapper exposes an injectable service");
+  assert.match(buildSubagentSystemPrompt("researcher"), /spawned by Open Claudia/i);
+  assert.ok(!/another Claude assistant/i.test(buildSubagentSystemPrompt()), "sub-agent identity is provider-neutral");
+
+  const parsed = parseAgentArgs(["literal", "prompt", "--role", "researcher", "--provider", "codex", "--timeout", "12", "--json"]);
+  assert.deepStrictEqual(parsed, {
+    prompt: "literal prompt",
+    role: "researcher",
+    provider: "codex",
+    cwd: process.cwd(),
+    timeoutMs: 12000,
+    json: true,
+  });
+  assert.strictEqual(parseAgentArgs(["default policy prompt"]).provider, null,
+    "omitting --provider leaves SUBAGENT_PROVIDER eligible to select the provider");
+  assert.throws(() => parseAgentArgs(["prompt", "--provider", "cursor"]), /active, claude, or codex/i);
+  assert.throws(() => parseAgentArgs(["prompt", "--provider"]), /requires a value/i);
+  assert.match(HELP, /--provider active\|claude\|codex/);
+  assert.ok(!/Claude sub-agent/i.test(HELP));
+
+  for (const kind of ["claude", "codex"]) {
+    const capture = path.join(root, `${kind}-read-only.json`);
+    const { subagent } = harness(kind, {
+      FAKE_AGENT_CAPTURE: capture,
+      FAKE_AGENT_TEXT: `${kind} focused result`,
+    });
+    const result = await subagent.spawnSubagent("focused prompt", {
+      provider: kind,
+      role: "researcher",
+      channelId: `${kind}-channel`,
+      cwd: root,
+    });
+    assert.strictEqual(result.text, `${kind} focused result`);
+    assert.strictEqual(result.provider, kind);
+    assert.strictEqual(result.truncated, false);
+    assert.strictEqual(result.code, 0);
+    const record = JSON.parse(fs.readFileSync(capture, "utf8"));
+    assert.ok(!record.argv.includes("focused prompt"), `${kind} sub-agent prompt stays out of argv`);
+    assert.strictEqual(record.stdin.present, true);
+    if (kind === "claude") {
+      assert.deepStrictEqual(
+        record.argv.slice(record.argv.indexOf("--permission-mode"), record.argv.indexOf("--permission-mode") + 2),
+        ["--permission-mode", "plan"],
+      );
+      assert.ok(record.argv.includes("--no-session-persistence"));
+    } else {
+      assert.deepStrictEqual(
+        record.argv.slice(record.argv.indexOf("--sandbox"), record.argv.indexOf("--sandbox") + 2),
+        ["--sandbox", "read-only"],
+      );
+      assert.ok(record.argv.includes("--ephemeral"));
+    }
+    assert.strictEqual(concurrentCount(`${kind}-channel`), 0);
+  }
+
+  const claudeToolsCapture = path.join(root, "claude-tools.json");
+  const claudeTools = harness("claude", { FAKE_AGENT_CAPTURE: claudeToolsCapture });
+  await claudeTools.subagent.spawnSubagent("tool policy", {
+    provider: "claude",
+    allowedTools: ["Read", "Glob"],
+    disallowedTools: ["Write", "Edit"],
+    cwd: root,
+  });
+  const toolArgv = JSON.parse(fs.readFileSync(claudeToolsCapture, "utf8")).argv;
+  assert.deepStrictEqual(toolArgv.slice(toolArgv.indexOf("--allowedTools"), toolArgv.indexOf("--allowedTools") + 2), ["--allowedTools", "Read,Glob"]);
+  assert.deepStrictEqual(toolArgv.slice(toolArgv.indexOf("--disallowedTools"), toolArgv.indexOf("--disallowedTools") + 2), ["--disallowedTools", "Write,Edit"]);
+  await assert.rejects(
+    claudeTools.subagent.spawnSubagent("unsafe", { provider: "claude", readOnly: false, cwd: root }),
+    (error) => error.code === "UTILITY_READ_ONLY_REQUIRED",
+    "sub-agent compatibility surface cannot silently opt out of read-only policy",
+  );
+
+  const codexTools = harness("codex");
+  await assert.rejects(
+    codexTools.subagent.spawnSubagent("tool policy", {
+      provider: "codex",
+      allowedTools: ["Read"],
+      cwd: root,
+    }),
+    (error) => error.code === "UNSUPPORTED_PROVIDER_CAPABILITY" && /allow\/deny/i.test(error.message),
+    "Codex tool-list limits are surfaced accurately, never silently claimed",
+  );
+
+  for (const kind of ["claude", "codex"]) {
+    const clipped = harness(kind, { FAKE_AGENT_TEXT: "abcdefghijklmnopqrstuvwxyz" }, { maxOutputBytes: 9 });
+    const result = await clipped.subagent.spawnSubagent("clip", { provider: kind, cwd: root });
+    assert.strictEqual(result.text, "abcdefghi");
+    assert.strictEqual(result.truncated, true);
+
+    const timed = harness(kind, {
+      FAKE_AGENT_SCENARIO: "forced-termination",
+      FAKE_AGENT_IGNORE_SIGTERM: "1",
+    }, { killGraceMs: 30 });
+    await assert.rejects(
+      timed.subagent.spawnSubagent("timeout", { provider: kind, timeoutMs: 140, cwd: root }),
+      (error) => error.code === "UTILITY_TIMEOUT" && error.result?.timedOut === true,
+      `${kind} sub-agent timeout is terminal and stable`,
+    );
+    assert.strictEqual(timed.utility.stats().activeGlobal, 0);
+  }
+
+  const firstCapture = path.join(root, "concurrent-first.json");
+  const secondCapture = path.join(root, "concurrent-second.json");
+  let invocation = 0;
+  const provider = makeProvider("claude");
+  const baseBuild = provider.buildUtilityInvocation;
+  provider.buildUtilityInvocation = (context) => {
+    invocation += 1;
+    const built = baseBuild(context);
+    return {
+      ...built,
+      env: {
+        ...built.env,
+        FAKE_AGENT_CLOSE_DELAY_MS: "180",
+        FAKE_AGENT_CAPTURE: invocation === 1 ? firstCapture : secondCapture,
+      },
+    };
+  };
+  const concurrentUtility = createUtilityAgentService({
+    registry: makeRegistry(provider),
+    env: { UTILITY_PROVIDER: "claude" },
+    maxGlobalConcurrency: 2,
+    maxPurposeConcurrency: 2,
+  });
+  const concurrentSubagent = createSubagentService({ spawnUtilityAgent: concurrentUtility.spawnUtilityAgent });
+  const first = concurrentSubagent.spawnSubagent("first", { channelId: "shared-channel", cwd: root });
+  const second = concurrentSubagent.spawnSubagent("second", { channelId: "shared-channel", cwd: root });
+  await Promise.all([waitForFile(firstCapture), waitForFile(secondCapture)]);
+  assert.strictEqual(concurrentCount("shared-channel"), 2, "compatibility wrapper tracks in-flight work by channel");
+  await Promise.all([first, second]);
+  assert.strictEqual(concurrentCount("shared-channel"), 0);
+
+  const systemPromptSource = fs.readFileSync(path.join(__dirname, "core", "system-prompt.js"), "utf8");
+  assert.match(systemPromptSource, /--provider active\|claude\|codex/);
+  assert.ok(!/spawned by another Claude assistant/i.test(systemPromptSource));
+
+  console.log("provider subagent OK");
+}
+
+main().catch((error) => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+}).finally(() => fs.rmSync(root, { recursive: true, force: true }));

package/test-provider-tool-hooks.js

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), "open-claudia-provider-hooks-"));
+const configDir = path.join(root, "open-claudia-config");
+const projectDir = path.join(root, "project.with.dots");
+const guardLog = path.join(configDir, "tool-guard.jsonl");
+process.env.OPEN_CLAUDIA_CONFIG_DIR = configDir;
+process.env.TOOL_GUARD_LOG = guardLog;
+process.env.TOOLING_MODE_FILE = path.join(configDir, "tooling-mode.json");
+fs.mkdirSync(projectDir, { recursive: true });
+
+const {
+  buildClaudeHookSettings,
+  createClaudeHookTransport,
+  ensureClaudeHookSettings,
+} = require("./core/providers/claude-hook");
+const {
+  buildCodexHookOverrides,
+  clearCodexHookCompatibilityCache,
+  createCodexHookTransport,
+  prepareCodexHook,
+  probeCodexHookCompatibility,
+  verifyPreparedCodexHook,
+} = require("./core/providers/codex-hook");
+const { createClaudeProvider } = require("./core/providers/claude");
+const { createCodexProvider } = require("./core/providers/codex");
+const { validateInvocation } = require("./core/providers/contract");
+const { claudeAgentEnv, codexAgentEnv } = require("./core/providers/env");
+const { shellQuote } = require("./core/providers/hook-command");
+const { captureRunContext } = require("./core/run-context");
+
+function compatibleCodexCommand(_binary, args) {
+  if (args[0] === "--version") return { ok: true, output: "codex-cli 0.144.0", code: 0 };
+  if (args.join(" ") === "exec --help") {
+    return {
+      ok: true,
+      output: "--config --json --sandbox --image --model --skip-git-repo-check --strict-config --ignore-user-config --dangerously-bypass-hook-trust",
+      code: 0,
+    };
+  }
+  if (args.join(" ") === "exec resume --help") {
+    return {
+      ok: true,
+      output: "--config --json --image --model --skip-git-repo-check --strict-config --ignore-user-config --dangerously-bypass-hook-trust",
+      code: 0,
+    };
+  }
+  if (args[0] === "features") {
+    return {
+      ok: true,
+      output: [
+        "hooks stable true",
+        "plugins stable false",
+        "unified_exec stable false",
+      ].join("\n"),
+      code: 0,
+    };
+  }
+  return { ok: false, output: "unexpected compatibility command", code: 1 };
+}
+
+function baseContext(overrides = {}) {
+  return Object.freeze({
+    coreInstructions: "CORE POLICY",
+    dynamicContext: "",
+    userPrompt: "fixture prompt",
+    cwd: projectDir,
+    providerSettings: { budget: null, worktree: false },
+    ...overrides,
+  });
+}
+
+try {
+  const injectionMarker = path.join(root, "hook-command-injection.marker");
+  const hostileLiteral = `literal'$(touch ${injectionMarker})'value`;
+  const quoted = spawnSync(`printf '%s' ${shellQuote(hostileLiteral)}`, {
+    shell: true,
+    encoding: "utf8",
+  });
+  assert.strictEqual(quoted.status, 0);
+  assert.strictEqual(quoted.stdout, hostileLiteral, "generated hook paths are shell-quoted as literal data");
+  assert.strictEqual(fs.existsSync(injectionMarker), false, "hook path quoting cannot execute substitutions");
+
+  // Claude keeps its existing --settings transport, but the generated file is
+  // now owned and verified by the Claude adapter rather than the command policy.
+  const claudeSettingsFile = path.join(configDir, "claude-deny-gate.settings.json");
+  const claudeSettings = buildClaudeHookSettings();
+  assert.strictEqual(claudeSettings.hooks.PreToolUse[0].matcher, "Bash");
+  assert.match(claudeSettings.hooks.PreToolUse[0].hooks[0].command, /deny-gate-hook/);
+  assert.match(claudeSettings.hooks.PreToolUse[0].hooks[0].command, new RegExp(process.execPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+  assert.strictEqual(ensureClaudeHookSettings({ settingsFile: claudeSettingsFile }), claudeSettingsFile);
+  assert.deepStrictEqual(JSON.parse(fs.readFileSync(claudeSettingsFile, "utf8")), claudeSettings);
+  if (process.platform !== "win32") {
+    assert.strictEqual(fs.statSync(claudeSettingsFile).mode & 0o777, 0o600, "generated hook settings are private");
+  }
+  const before = fs.statSync(claudeSettingsFile).mtimeMs;
+  assert.strictEqual(ensureClaudeHookSettings({ settingsFile: claudeSettingsFile }), claudeSettingsFile);
+  assert.strictEqual(fs.statSync(claudeSettingsFile).mtimeMs, before, "verified settings are not churned");
+
+  if (process.platform !== "win32") {
+    const victim = path.join(root, "must-not-overwrite.json");
+    const link = path.join(configDir, "symlink.settings.json");
+    fs.writeFileSync(victim, "preserve me\n");
+    fs.symlinkSync(victim, link);
+    assert.throws(
+      () => ensureClaudeHookSettings({ settingsFile: link }),
+      (error) => error && error.code === "UNSAFE_TOOL_HOOK_PATH",
+    );
+    assert.strictEqual(fs.readFileSync(victim, "utf8"), "preserve me\n");
+  }
+
+  const claudeTransport = createClaudeHookTransport({ settingsFile: claudeSettingsFile });
+  const claudeProvider = createClaudeProvider({
+    resolveExecutable: () => "/fixture/claude",
+    defaultModel: "claude-fixture",
+    buildEnv: () => ({ PATH: "/fixture", OPEN_CLAUDIA_CONFIG_DIR: configDir }),
+    getAuthStatus: () => ({ state: "authenticated", reason: null }),
+    hookTransport: claudeTransport,
+  });
+  const claudeInvocation = claudeProvider.buildMainInvocation(baseContext());
+  assert.strictEqual(claudeInvocation.args[claudeInvocation.args.indexOf("--settings") + 1], claudeSettingsFile);
+  const defaultClaudeProvider = createClaudeProvider({
+    resolveExecutable: () => "/fixture/claude",
+    defaultModel: "claude-fixture",
+    buildEnv: () => ({ PATH: "/fixture", OPEN_CLAUDIA_CONFIG_DIR: configDir }),
+    getAuthStatus: () => ({ state: "authenticated", reason: null }),
+  });
+  const defaultClaudeInvocation = defaultClaudeProvider.buildMainInvocation(baseContext());
+  assert.ok(defaultClaudeInvocation.args.includes("--settings"), "Claude factories enforce the generated hook by default");
+
+  // Codex uses only transient, generated CLI overrides. User config is ignored,
+  // the current project is explicitly untrusted, plugin hooks and unified_exec
+  // are disabled, and hook trust is bypassed only after exact verification.
+  const overrides = buildCodexHookOverrides({ cwd: projectDir });
+  assert.strictEqual(overrides.featuresHooks, "features.hooks=true");
+  assert.strictEqual(overrides.featuresPlugins, "features.plugins=false");
+  assert.strictEqual(overrides.featuresUnifiedExec, "features.unified_exec=false");
+  assert.match(overrides.projectTrust, /^projects=\{.+trust_level="untrusted".+\}$/);
+  assert.match(overrides.preToolUse, /^hooks\.PreToolUse=/);
+  assert.match(overrides.preToolUse, /deny-gate-hook/);
+
+  const prepared = prepareCodexHook({ cwd: projectDir });
+  assert.strictEqual(verifyPreparedCodexHook(prepared), true);
+  assert.ok(Object.isFrozen(prepared));
+  assert.ok(Object.isFrozen(prepared.args));
+  assert.ok(prepared.args.includes("--ignore-user-config"));
+  assert.ok(prepared.args.includes("--strict-config"));
+  assert.ok(prepared.args.includes("--dangerously-bypass-hook-trust"));
+  assert.ok(!prepared.args.includes("--profile"), "a merging Codex profile is never trusted");
+  const tampered = Object.freeze({ ...prepared, args: Object.freeze([...prepared.args, "--profile", "project-hooks"]) });
+  assert.strictEqual(verifyPreparedCodexHook(tampered), false, "trust bypass rejects non-generated argv");
+
+  clearCodexHookCompatibilityCache();
+  const codexTransport = createCodexHookTransport({ cache: false });
+  const codexProvider = createCodexProvider({
+    resolveExecutable: () => "/fixture/codex",
+    defaultModel: "gpt-fixture",
+    buildEnv: () => ({ PATH: "/fixture", OPEN_CLAUDIA_CONFIG_DIR: configDir }),
+    getAuthStatus: () => ({ state: "authenticated", reason: null }),
+    runCommand: compatibleCodexCommand,
+    hookTransport: codexTransport,
+  });
+  assert.strictEqual(codexProvider.capabilities.preToolHook.support, "native");
+  assert.strictEqual(codexProvider.compatibilityStatus().state, "compatible");
+  const fresh = codexProvider.buildMainInvocation(baseContext({ fresh: true }));
+  const resumed = codexProvider.buildMainInvocation(baseContext({ sessionId: "thread-fixture" }));
+  for (const invocation of [fresh, resumed]) {
+    assert.ok(invocation.args.includes("--ignore-user-config"));
+    assert.ok(invocation.args.includes("--dangerously-bypass-hook-trust"));
+    assert.ok(invocation.args.some((arg) => arg === overrides.preToolUse));
+    assert.ok(invocation.args.some((arg) => arg === overrides.projectTrust));
+    assert.ok(invocation.args.indexOf("--dangerously-bypass-hook-trust") < invocation.args.indexOf(invocation.args.at(-1)));
+  }
+  assert.strictEqual(resumed.args[1], "resume");
+  const defaultCodexProvider = createCodexProvider({
+    resolveExecutable: () => "/fixture/codex",
+    defaultModel: "gpt-fixture",
+    buildEnv: () => ({ PATH: "/fixture", OPEN_CLAUDIA_CONFIG_DIR: configDir }),
+    getAuthStatus: () => ({ state: "authenticated", reason: null }),
+    runCommand: compatibleCodexCommand,
+  });
+  assert.ok(
+    defaultCodexProvider.buildMainInvocation(baseContext({ fresh: true })).args.includes("--dangerously-bypass-hook-trust"),
+    "Codex factories enforce the verified transient hook by default",
+  );
+
+  // Mandatory initialization is fail-closed before spawn. Read-only fallback
+  // exists only behind an explicit policy bit and always carries a warning.
+  const unavailableTransport = createCodexHookTransport({ cache: false });
+  const unavailableProvider = createCodexProvider({
+    resolveExecutable: () => "/fixture/codex-without-hooks",
+    defaultModel: "gpt-fixture",
+    buildEnv: () => ({ PATH: "/fixture" }),
+    getAuthStatus: () => ({ state: "authenticated", reason: null }),
+    runCommand: (_binary, args) => args[0] === "--version"
+      ? { ok: true, output: "codex-cli 0.100.0", code: 0 }
+      : { ok: true, output: "--json --sandbox", code: 0 },
+    hookTransport: unavailableTransport,
+  });
+  assert.throws(
+    () => unavailableProvider.buildMainInvocation(baseContext()),
+    (error) => error && error.code === "MANDATORY_TOOL_HOOK_UNAVAILABLE",
+  );
+  assert.throws(
+    () => unavailableProvider.buildMainInvocation(baseContext({ readOnly: true })),
+    (error) => error && error.code === "MANDATORY_TOOL_HOOK_UNAVAILABLE",
+  );
+  const warnedReadOnly = unavailableProvider.buildMainInvocation(baseContext({
+    readOnly: true,
+    allowReadOnlyWithoutToolHook: true,
+  }));
+  assert.strictEqual(validateInvocation(warnedReadOnly), warnedReadOnly);
+  assert.ok(Array.isArray(warnedReadOnly.warnings) && warnedReadOnly.warnings.length === 1);
+  assert.match(warnedReadOnly.warnings[0].message, /read-only/i);
+  assert.match(warnedReadOnly.warnings[0].message, /hook/i);
+  assert.ok(!warnedReadOnly.args.includes("--dangerously-bypass-hook-trust"));
+  assert.ok(!warnedReadOnly.args.includes("--dangerously-bypass-approvals-and-sandbox"));
+  const capturedFallbackPolicy = captureRunContext({
+    state: {
+      userId: "fixture-user",
+      currentSession: { name: "fixture-project", dir: projectDir },
+      settings: { backend: "codex", budget: null, worktree: false },
+      activeSessions: { "fixture-project": {} },
+      lastInputWasVoice: false,
+    },
+    prompt: "read-only fallback fixture",
+    cwd: projectDir,
+    opts: { readOnly: true, allowReadOnlyWithoutToolHook: true },
+  });
+  assert.strictEqual(capturedFallbackPolicy.readOnly, true);
+  assert.strictEqual(capturedFallbackPolicy.allowReadOnlyWithoutToolHook, true, "the explicit fallback policy survives admission");
+
+  // Custom Open Claudia config roots reach the provider child so the shared
+  // hook reads the correct tooling mode and writes the correct audit log.
+  const envSource = { PATH: "/fixture", HOME: "/fixture/home", OPEN_CLAUDIA_CONFIG_DIR: configDir };
+  assert.strictEqual(claudeAgentEnv(envSource).OPEN_CLAUDIA_CONFIG_DIR, configDir);
+  assert.strictEqual(codexAgentEnv(envSource).OPEN_CLAUDIA_CONFIG_DIR, configDir);
+
+  // Hermetic behavioral compatibility probe: the fake Codex CLI runs the
+  // configured PreToolUse hook against a harmless false-positive command. The
+  // deny is observed and neither the command marker nor an arbitrary project
+  // hook marker is allowed to execute.
+  const marker = path.join(root, "denied-command.marker");
+  const arbitraryMarker = path.join(root, "arbitrary-hook.marker");
+  const capture = path.join(root, "fake-codex-hook-capture.json");
+  const probe = probeCodexHookCompatibility({
+    binary: path.join(__dirname, "test-fixtures", "fake-agent-cli.js"),
+    prepared,
+    cwd: projectDir,
+    markerFile: marker,
+    auditFile: guardLog,
+    env: {
+      PATH: process.env.PATH,
+      HOME: root,
+      OPEN_CLAUDIA_CONFIG_DIR: configDir,
+      TOOL_GUARD_LOG: guardLog,
+      TOOLING_MODE_FILE: process.env.TOOLING_MODE_FILE,
+      FAKE_AGENT_KIND: "codex",
+      FAKE_AGENT_CAPTURE: capture,
+      FAKE_AGENT_ARBITRARY_HOOK_MARKER: arbitraryMarker,
+    },
+    spawnCommand: spawnSync,
+  });
+  assert.strictEqual(probe.ok, true, probe.diagnostic);
+  assert.strictEqual(probe.denyObserved, true);
+  assert.strictEqual(fs.existsSync(marker), false, "denied marker command never executes");
+  assert.strictEqual(fs.existsSync(arbitraryMarker), false, "arbitrary project hooks never inherit trust bypass");
+  const probeCapture = JSON.parse(fs.readFileSync(capture, "utf8"));
+  assert.strictEqual(probeCapture.hookProbe.hookExit, 2);
+  assert.strictEqual(probeCapture.hookProbe.generatedOnly, true);
+
+  // Doctor wiring: the live probe is strictly opt-in, only fires when codex is
+  // fully healthy, and surfaces its verdict as a doctor check. Boot, health,
+  // and setup call runDoctorChecks() bare and must never reach a model turn.
+  {
+    const { runDoctorChecks } = require("./core/doctor");
+    const fixtureStatus = (id, authState) => ({
+      id,
+      label: id === "claude" ? "Claude Code" : "OpenAI Codex",
+      availability: { state: "available", executable: `/fixture/${id}`, reason: null },
+      compatibility: { state: "compatible", version: "1.0.0", reason: null },
+      auth: { state: authState, reason: authState === "authenticated" ? null : "fixture logged out" },
+    });
+    const registryStub = (codexAuth) => ({
+      listProviders: () => [
+        { id: "claude", label: "Claude Code", authHelp: () => "log in to claude" },
+        { id: "codex", label: "OpenAI Codex", authHelp: () => "log in to codex" },
+      ],
+      providerStatus: (id) => fixtureStatus(id, id === "codex" ? codexAuth : "authenticated"),
+      selectDefaultProvider: () => ({ providerId: "claude", source: "detected", reason: null }),
+    });
+    const executableStatus = (id) => ({ state: "available", configured: true, executable: `/fixture/${id}` });
+    const enforcementCheck = (checks) => checks.find((c) => /tool-hook enforcement/.test(c.label));
+
+    const probeCalls = [];
+    const okProbe = (args) => {
+      probeCalls.push(args);
+      return { ok: true, status: 0, denyObserved: true, markerExecuted: false, diagnostic: null };
+    };
+
+    const withoutOptIn = runDoctorChecks({
+      registry: registryStub("authenticated"), executableStatus, runCodexHookProbe: okProbe,
+    });
+    assert.strictEqual(enforcementCheck(withoutOptIn), undefined, "the live probe check must be opt-in");
+    assert.strictEqual(probeCalls.length, 0, "runDoctorChecks() without opt-in must never invoke the live probe");
+
+    const optedIn = runDoctorChecks({
+      registry: registryStub("authenticated"), executableStatus, probeCodexHook: true, runCodexHookProbe: okProbe,
+    });
+    const passed = enforcementCheck(optedIn);
+    assert.ok(passed, "opting in must add the enforcement check");
+    assert.strictEqual(passed.ok, true);
+    assert.strictEqual(probeCalls.length, 1);
+    assert.strictEqual(probeCalls[0].binary, "/fixture/codex", "the probe must target the codex executable doctor verified");
+
+    const failing = runDoctorChecks({
+      registry: registryStub("authenticated"), executableStatus, probeCodexHook: true,
+      runCodexHookProbe: () => ({
+        ok: false, status: 0, denyObserved: false, markerExecuted: true,
+        diagnostic: "Codex tool-hook probe failed (status=0, denyObserved=false, markerExecuted=true)",
+      }),
+    });
+    const failed = enforcementCheck(failing);
+    assert.strictEqual(failed.ok, false, "a probe that observes no deny must fail doctor");
+    assert.ok(!failed.warn, "enforcement failure is a hard problem, not a warning");
+    assert.match(failed.detail, /markerExecuted=true/);
+    assert.match(failed.action, /Do not run Codex tasks/);
+
+    const skippedProbeCalls = [];
+    const skipped = runDoctorChecks({
+      registry: registryStub("unauthenticated"), executableStatus, probeCodexHook: true,
+      runCodexHookProbe: (args) => { skippedProbeCalls.push(args); return { ok: true }; },
+    });
+    const skippedCheck = enforcementCheck(skipped);
+    assert.strictEqual(skippedCheck.ok, true);
+    assert.strictEqual(skippedCheck.warn, true, "an unready codex skips as a warning, not a failure");
+    assert.match(skippedCheck.detail, /skipped/);
+    assert.strictEqual(skippedProbeCalls.length, 0, "an unready codex must never trigger a real exec turn");
+
+    const throwing = runDoctorChecks({
+      registry: registryStub("authenticated"), executableStatus, probeCodexHook: true,
+      runCodexHookProbe: () => { throw new Error("spawn ETIMEDOUT"); },
+    });
+    const threw = enforcementCheck(throwing);
+    assert.strictEqual(threw.ok, false, "a probe crash must fail doctor, not crash it");
+    assert.match(threw.detail, /ETIMEDOUT/);
+  }
+
+  console.log("provider tool hooks OK");
+} finally {
+  fs.rmSync(root, { recursive: true, force: true });
+}

package/test-recall-discoverer.js

@@ -17,6 +17,7 @@ process.env.TOOLS_DIR = path.join(tmp, "tools");
 
 const disc = require("./core/recall/discoverer");
 const toolsLib = require("./core/tools");
+assert.strictEqual(typeof disc.runWalker, "function", "discoverer exposes the provider-aware walker boundary");
 
 // A reusable tool whose description matches a query should seed the discoverer
 // as a first-class candidate (origin user), survive the walker-off fail-open,