agents-can-communicate 0.3.0 → 0.4.0

package/node_modules/@agents-can-communicate/adapter-codex/src/app-server-client.mjs

@@ -1,14 +1,14 @@
 import os from "node:os";
 import path from "node:path";
+import { realpath, stat } from "node:fs/promises";
 
 import { openWebSocketPeer } from "./ws-json-rpc.mjs";
 
 // The Codex App Server queue protocol, captured on codex-cli 0.152.1. Every
 // method here is official and present in the generated schema: initialize,
-// thread/loaded/list, thread/list, thread/queue/list, thread/queue/add. The
-// client never resumes, starts, steers, or reads a thread, and never reads
-// assistant transcript content. Closed safe results only; no vendor string
-// escapes to core.
+// thread/loaded/list, thread/list, metadata-only thread/read, thread/queue/list,
+// thread/queue/add. Thread history is never requested; metadata reads explicitly
+// exclude turns. Closed safe results only; no vendor string escapes to core.
 
 export const PROTOCOL_CONTRACT = "codex-app-server-thread-queue-v1";
 export const MINIMUM_VERSION = "0.152.1";
@@ -42,7 +42,7 @@ export function isMethodMissing(error) {
 }
 
 export function openCodexAppServer({ socketPath, timeoutMs = 5_000 }) {
-  return openWebSocketPeer({ socketPath, timeoutMs });
+  return openWebSocketPeer({ socketPath, timeoutMs, retainNotifications: false });
 }
 
 export async function initializeCodex(peer) {
@@ -52,7 +52,7 @@ export async function initializeCodex(peer) {
   return serverVersionOf(initialized?.userAgent);
 }
 
-export async function probeCodexQueue(peer, { threadId, minimum = MINIMUM_VERSION }) {
+export async function probeCodexQueue(peer, { threadId, minimum = MINIMUM_VERSION } = {}) {
   const serverVersion = await initializeCodex(peer);
   if (serverVersion === null || parseStableVersion(serverVersion) === null) {
     return { supported: false, serverVersion, reasonCode: "prerelease_not_captured" };
@@ -61,9 +61,16 @@ export async function probeCodexQueue(peer, { threadId, minimum = MINIMUM_VERSIO
     return { supported: false, serverVersion, reasonCode: "below_minimum_version" };
   }
   try {
-    await peer.request("thread/queue/list", { threadId });
+    if (threadId === undefined) {
+      const loaded = await pageAll(peer, "thread/loaded/list", {});
+      threadId = loaded.find(id => typeof id === "string" && id !== "");
+      if (threadId === undefined) return { supported: false, serverVersion,
+        reasonCode: "feature_probe_failed" };
+    }
+    queueEntries(await peer.request("thread/queue/list", { threadId }));
   } catch (error) {
-    if (isMethodMissing(error)) return { supported: false, serverVersion, reasonCode: "protocol_mismatch" };
+    return { supported: false, serverVersion, reasonCode: error?.code === "ETIMEDOUT"
+      ? "probe_timeout" : "protocol_mismatch" };
   }
   return { supported: true, serverVersion, reasonCode: null, modes: [...QUEUE_MODES] };
 }
@@ -71,25 +78,70 @@ export async function probeCodexQueue(peer, { threadId, minimum = MINIMUM_VERSIO
 async function pageAll(peer, method, params) {
   const items = [];
   let cursor = null;
+  const cursors = new Set();
   for (let page = 0; page < MAX_PAGES; page += 1) {
     const response = await peer.request(method, cursor === null ? params : { ...params, cursor });
-    items.push(...(response?.data ?? []));
+    if (!Array.isArray(response?.data)) throw protocolError();
+    items.push(...response.data);
     cursor = response?.nextCursor ?? null;
-    if (cursor === null) break;
+    if (cursor === null) return items;
+    if (typeof cursor !== "string" || cursor === "" || cursors.has(cursor)) throw protocolError();
+    cursors.add(cursor);
   }
+  throw protocolError();
+}
+
+const protocolError = () => Object.assign(new Error("invalid queue protocol response"),
+  { code: "EPROTOCOL" });
+
+function queueEntries(response) {
+  if (!Array.isArray(response?.data) || response.data.some(item => typeof item?.id !== "string"
+    || item.id === "" || (item.clientUserMessageId != null
+      && typeof item.clientUserMessageId !== "string"))) throw protocolError();
+  return response.data;
+}
+
+function threadEntries(items) {
+  if (items.some(item => item === null || typeof item !== "object" || Array.isArray(item)
+    || typeof item.id !== "string" || item.id === "")) throw protocolError();
   return items;
 }
 
-const listParams = cwd => ({ limit: 100, useStateDbOnly: true, ...(cwd ? { cwd } : {}) });
+export async function canonicalCwd(cwd) {
+  if (typeof cwd !== "string" || !path.isAbsolute(cwd) || cwd.includes("\0")) return null;
+  try {
+    const resolved = await realpath(cwd);
+    return (await stat(resolved)).isDirectory() ? resolved : null;
+  } catch { return null; }
+}
 
 export async function locateCodexThread(peer, { threadId, cwd }) {
   const loaded = await pageAll(peer, "thread/loaded/list", {});
   if (!loaded.includes(threadId)) return { found: false, reasonCode: "thread_not_loaded" };
-  const threads = await pageAll(peer, "thread/list", listParams(cwd));
-  const found = threads.find(item => item?.id === threadId);
+  // Filter locally after canonicalization: a server-side lexical cwd filter
+  // would hide a thread recorded through a symlink to the same directory.
+  const threads = threadEntries(await pageAll(peer, "thread/list",
+    { limit: 100, useStateDbOnly: true }));
+  const matches = threads.filter(item => item.id === threadId);
+  let found = matches.length === 1 ? matches[0] : null;
+  if (matches.length === 0) {
+    // A real first SessionStart/UserPromptSubmit runs before persistence has
+    // materialized the thread. The loaded ID still has an authoritative live
+    // metadata snapshot; includeTurns:false never asks for conversation history.
+    const response = await peer.request("thread/read", { threadId, includeTurns: false });
+    const metadata = response?.thread;
+    if (metadata?.id === threadId && Array.isArray(metadata.turns) && metadata.turns.length === 0) {
+      found = metadata;
+    }
+  }
   if (!found) return { found: false, reasonCode: "thread_not_found" };
-  if (cwd !== undefined && found.cwd !== cwd) return { found: false, reasonCode: "cwd_mismatch" };
-  return { found: true, threadId, status: found.status?.type ?? "unknown" };
+  const actualCwd = await canonicalCwd(found.cwd);
+  if (actualCwd === null || (cwd !== undefined && actualCwd !== await canonicalCwd(cwd))) {
+    return { found: false, reasonCode: "cwd_mismatch" };
+  }
+  const status = found.status?.type;
+  if (!["idle", "active"].includes(status)) return { found: false, reasonCode: "thread_not_loaded" };
+  return { found: true, threadId, cwd: actualCwd, status };
 }
 
 // thread/queue/list first, so a retried client message id is the same offer
@@ -97,14 +149,15 @@ export async function locateCodexThread(peer, { threadId, cwd }) {
 // clientUserMessageId.
 export async function addCodexQueueMessage(peer, { threadId, messageId, text }) {
   const listed = await peer.request("thread/queue/list", { threadId });
-  const existing = (listed?.data ?? []).find(item => item?.clientUserMessageId === messageId);
+  const existing = queueEntries(listed).find(item => item.clientUserMessageId === messageId);
   if (existing) {
     return { accepted: true, duplicate: true, queuedSubmissionId: existing.id };
   }
   const added = await peer.request("thread/queue/add", { threadId,
     input: [{ type: "text", text }], clientUserMessageId: messageId });
   const submission = added?.queuedSubmission;
-  if (!submission || submission.clientUserMessageId !== messageId) {
+  if (!submission || typeof submission.id !== "string" || submission.id === ""
+    || submission.clientUserMessageId !== messageId) {
     throw Object.assign(new Error("queue acknowledgement did not echo the client message id"),
       { code: "EPROTOCOL" });
   }

package/node_modules/@agents-can-communicate/adapter-codex/src/config-block.mjs

@@ -0,0 +1,231 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { BEGIN, END, renderBlock } from "@agents-can-communicate/adapter-sdk";
+import { AccError, EXIT } from "@agents-can-communicate/protocol";
+
+const unsafe = (reason = "unrecognized TOML declaration") => {
+  throw new AccError(EXIT.CONFLICT, `cannot safely edit Codex config: ${reason}; `
+    + "repair ambiguous TOML or ACC markers before retrying", { reason });
+};
+const ROOT = "# ACC sandbox writable_roots created with: ";
+export const sandboxOwnership = root => `${ROOT}${JSON.stringify(root)}`;
+
+const OWNED = new Map([
+  [JSON.stringify(["marketplaces", "acc-local"]), ["source_type", "source"]],
+  [JSON.stringify(["plugins", "agents-can-communicate@acc-local"]), ["enabled"]],
+  [JSON.stringify(["sandbox_workspace_write"]), ["writable_roots"]],
+]);
+
+// A bounded lexical scan, not a TOML value parser. Newlines inside strings,
+// arrays and inline tables cannot introduce a header or a managed marker.
+function* statements(source) {
+  let start = 0, code = "", quote = null;
+  const stack = [];
+  for (let i = 0; i < source.length;) {
+    const char = source[i];
+    if (quote) {
+      if (quote[0] === '"' && char === "\\") {
+        code += source.slice(i, i + 2); i += 2; continue;
+      }
+      if (source.startsWith(quote, i)) {
+        let count = quote.length;
+        if (quote.length === 3) {
+          while (source[i + count] === quote[0]) count++;
+          if (count > 5) unsafe("unsupported string quote delimiter");
+        }
+        code += source.slice(i, i + count); i += count; quote = null; continue;
+      }
+      if (quote.length === 1 && /[\r\n]/.test(char)) unsafe("newline in single-line string");
+      code += char; i++; continue;
+    }
+    if (char === "#") {
+      while (i < source.length && source[i] !== "\n") i++;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = source.startsWith(char.repeat(3), i) ? char.repeat(3) : char;
+      code += quote; i += quote.length; continue;
+    }
+    if (char === "[" || char === "{") stack.push(char);
+    if (char === "]" || char === "}") {
+      if (stack.pop() !== (char === "]" ? "[" : "{")) unsafe("mismatched collection delimiter");
+    }
+    code += char; i++;
+    if (char === "\n" && stack.length === 0) {
+      yield { raw: source.slice(start, i), code: code.trim() };
+      start = i; code = "";
+    }
+  }
+  if (quote || stack.length) unsafe(quote ? "unclosed string" : "unclosed collection");
+  if (start < source.length) yield { raw: source.slice(start), code: code.trim() };
+}
+
+function decodeKey(key) {
+  if (key[0] === "'") return key.slice(1, -1);
+  if (key[0] !== '"') return key;
+  return key.slice(1, -1).replace(/\\(U[\da-fA-F]{8}|u[\da-fA-F]{4}|[btnfr"\\])|\\./g,
+    (match, escape) => {
+      if (!escape) unsafe("unsupported quoted-key escape");
+      if (/^[uU]/.test(escape)) {
+        const point = Number.parseInt(escape.slice(1), 16);
+        if (point > 0x10ffff || (point >= 0xd800 && point <= 0xdfff)) {
+          unsafe("invalid quoted-key Unicode escape");
+        }
+        return String.fromCodePoint(point);
+      }
+      return ({ b: "\b", t: "\t", n: "\n", f: "\f", r: "\r", '"': '"', "\\": "\\" })[escape];
+    });
+}
+
+function keyPath(code) {
+  const keys = [];
+  let rest = code.trimStart();
+  for (;;) {
+    const match = /^(?:[A-Za-z0-9_-]+|'[^'\r\n]*'|"(?:[^"\\\r\n]|\\[^\r\n])*")/.exec(rest);
+    if (!match) unsafe("unrecognized TOML key");
+    keys.push(decodeKey(match[0]));
+    rest = rest.slice(match[0].length).trimStart();
+    if (!rest.startsWith(".")) return { keys, rest };
+    rest = rest.slice(1).trimStart();
+  }
+}
+
+function declaration(code) {
+  const header = code.startsWith("[");
+  const array = header && code.startsWith("[[");
+  const { keys, rest } = keyPath(header ? code.slice(array ? 2 : 1) : code);
+  if (header ? rest !== (array ? "]]" : "]") : !rest.startsWith("=")) unsafe();
+  return { keys, header, array, value: header ? null : rest.slice(1).trim() };
+}
+
+// An unchanged, newly generated sandbox has value provenance. A legacy or
+// edited sandbox belongs to the client as a whole and remains byte-preserved.
+function ownsSandbox(body) {
+  const metadata = body.filter(item => !item.code && item.raw.trim().startsWith(ROOT));
+  const values = body.filter(item => item.code);
+  if (metadata.length !== 1 || values.length !== 1) return false;
+  const value = values[0].code.match(/^writable_roots\s*=\s*(\[.*\])$/);
+  if (!value) return false;
+  try {
+    const root = JSON.parse(metadata[0].raw.trim().slice(ROOT.length));
+    const roots = JSON.parse(value[1]);
+    return typeof root === "string" && Array.isArray(roots)
+      && roots.length === 1 && roots[0] === root;
+  } catch { return false; }
+}
+
+function assertRegistration(body, keys) {
+  const values = body.filter(item => item.code).map(item => declaration(item.code));
+  if (values.some(item => item.keys.length !== 1 || !keys.includes(item.keys[0]))) {
+    unsafe("unknown key in owned table");
+  }
+  const valid = { source_type: /^["']local["']$/, source: /^(?:"(?:[^"\\]|\\.)*"|'[^']*')$/,
+    enabled: /^(?:true|false)$/ };
+  if (values.length !== keys.length || keys.some(key => values.filter(item =>
+    item.keys.length === 1 && item.keys[0] === key && valid[key].test(item.value)).length !== 1)) {
+    unsafe("changed or incomplete owned registration");
+  }
+}
+
+function tableBody(entries, index) {
+  const body = [];
+  for (const item of entries.slice(index + 1)) {
+    if (item.code && declaration(item.code).header) break;
+    body.push(item);
+  }
+  return body;
+}
+
+/**
+ * Ownership is an exact generated table inside real ACC comment markers, with
+ * only its generated keys. Other tables (including descendants) and comments
+ * are foreign. Unknown keys in an owned table are ambiguous: refuse, never
+ * discard them. Codex may insert foreign tables before END; retain their raw
+ * bytes in order and append the replacement block after them.
+ */
+function inspect(source) {
+  const kept = [], declarations = [];
+  let inside = false, owned = null, table = [];
+  const entries = [...statements(source)];
+  for (const [index, { raw, code }] of entries.entries()) {
+    if (!code && raw.trim() === BEGIN) {
+      if (inside) unsafe("nested BEGIN marker");
+      inside = true; continue;
+    }
+    if (!code && raw.trim() === END) {
+      if (!inside) unsafe("unmatched END marker");
+      inside = false; continue;
+    }
+    if (!code) {
+      if (!inside || !owned || (raw.trim() && !(table.length === 1
+        && table[0] === "sandbox_workspace_write" && raw.trim().startsWith(ROOT)))) kept.push(raw);
+      continue;
+    }
+    const entry = declaration(code);
+    if (entry.header) {
+      table = entry.keys;
+      owned = inside ? OWNED.get(JSON.stringify(table)) : null;
+      if (owned && table.length === 1 && table[0] === "sandbox_workspace_write"
+        && !ownsSandbox(tableBody(entries, index))) owned = null;
+      if (owned && entry.array) unsafe("owned table declared as an array");
+      if (owned && table[0] !== "sandbox_workspace_write") {
+        assertRegistration(tableBody(entries, index), owned);
+      }
+    } else if (owned) {
+      // Markers are comments, so END does not close a TOML table. Removing its
+      // header would attach any following foreign assignment to another table.
+      if (!inside) unsafe("assignment continues owned table after END marker");
+      if (entry.keys.length !== 1 || !owned.includes(entry.keys[0])) {
+        unsafe("unknown key in owned table");
+      }
+    }
+    if (!owned) {
+      kept.push(raw);
+      declarations.push({ keys: entry.header ? table : [...table, ...entry.keys],
+        header: entry.header });
+    }
+  }
+  if (inside) unsafe("missing END marker");
+  const has = prefix => declarations.some(({ keys }) => prefix.every((key, i) => keys[i] === key));
+  // Assignments occupy their exact namespace: even an empty inline parent is
+  // closed to later child tables. Ordinary headers and sibling keys stay valid.
+  const assignedParent = declarations.some(({ keys, header }) => !header
+    && keys.length === 1 && ["marketplaces", "plugins"].includes(keys[0]));
+  return { source: kept.join(""),
+    sandbox: has(["sandbox_workspace_write"]),
+    registration: assignedParent || has(["marketplaces", "acc-local"])
+      || has(["plugins", "agents-can-communicate@acc-local"]) };
+}
+
+export function inspectConfig(source, file = "config.toml") {
+  try {
+    return inspect(source);
+  } catch (error) {
+    if (!(error instanceof AccError)) throw error;
+    // Structural reasons are fixed labels: never include key names or values.
+    throw new AccError(error.code, `${file}: ${error.message}`, { ...error.details, file });
+  }
+}
+
+export async function readConfig(file) {
+  return readFile(file, "utf8").catch(error => {
+    if (error.code === "ENOENT") return "";
+    throw error;
+  });
+}
+
+export async function writeTomlBlock(file, body) {
+  const { source } = inspectConfig(await readConfig(file), file);
+  const separator = source === "" || source.endsWith("\n") ? "" : "\n";
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, `${source}${separator}${renderBlock(body)}\n`);
+  return file;
+}
+
+export async function removeTomlBlock(file) {
+  const before = await readConfig(file);
+  const { source } = inspectConfig(before, file);
+  if (source === before) return false;
+  await writeFile(file, source);
+  return true;
+}

package/node_modules/@agents-can-communicate/adapter-codex/src/hooks.mjs

@@ -148,5 +148,5 @@ export function allowOutcome() {
  * as data, because at this role the model reads text as instruction.
  */
 export function injectOutcome(context) {
-  return { stdout: context === "" ? "" : `${context}\n`, stderr: "", exitCode: 0 };
+  return { stdout: context, stderr: "", exitCode: 0 };
 }

package/node_modules/@agents-can-communicate/adapter-codex/src/install.mjs

@@ -1,13 +1,20 @@
+// Installation, removal, detection and planning share the exact marketplace,
+// cache and config paths below; keeping them together avoids divergent ownership.
 import { cp, mkdir, readdir, readFile, rm, rmdir, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { bakeSkillCommand, blankJson, blankText, removeIfEmpty, removeInstalledTree,
   keepOnlyVersion, ownVersion, stampPluginVersion,
-  removeTomlBlock, stripBlock, tomlString,
-  writeForeignJson, writeHookShim, writeTomlBlock }
+  tomlString, writeForeignJson, writeHookShim }
   from "@agents-can-communicate/adapter-sdk";
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
+import { inspectConfig, readConfig, removeTomlBlock, sandboxOwnership, writeTomlBlock } from "./config-block.mjs";
+
+// Kept cohesive above 300 lines because Codex plugin install, cache, config,
+// detection, and ownership share one client topology; splitting would duplicate
+// path authority and make install/uninstall symmetry harder to audit.
+
 
 const bundle = fileURLToPath(new URL("../plugin", import.meta.url));
 const PLUGIN_NAME = "agents-can-communicate";
@@ -24,6 +31,8 @@ const PLUGIN_NAME = "agents-can-communicate";
 // again to confirm a root of ACC's own is accepted and reported enabled.
 const MARKETPLACE = "acc-local";
 const QUALIFIED = `${PLUGIN_NAME}@${MARKETPLACE}`;
+const HOOK_REVIEW = "hook readiness unverified: open codex; check ACC is enabled in /plugins; in /hooks, review "
+  + "each ACC hook and enable/trust its current definition if needed, then restart the session";
 
 // A marketplace is a root holding `.agents/plugins/marketplace.json`, and every
 // `source.path` in that manifest - `./plugins/<name>` - is resolved by this
@@ -79,11 +88,12 @@ async function readJson(file, fallback) {
 // Replace the bundle's placeholder command with the shim just written. The
 // client copies an installed plugin into a cache of its own, so the command has
 // to be absolute: a path relative to the bundle would not survive the copy.
+const shellLiteral = value => `'${String(value).replaceAll("'", "'\\''")}'`;
 const withShim = (wiring, shim) => ({ ...wiring, hooks: Object.fromEntries(
   Object.entries(wiring.hooks).map(([event, entries]) => [event, entries.map(entry => ({
     ...entry,
     hooks: entry.hooks.map(hook => ({ ...hook,
-      command: `sh "${shim}" ${hook.command.split(" ").pop()}` })),
+      command: `sh ${shellLiteral(shim)} ${hook.command.split(" ").pop()}` })),
   }))])) });
 
 const writeJson = async (file, value) => {
@@ -136,20 +146,20 @@ const entryFor = () => ({
 const sandboxTable = (stateRoot, theirs) => {
   if (typeof stateRoot !== "string" || stateRoot === "") return [];
   if (theirs) return [];
-  return ["", "[sandbox_workspace_write]",
+  return ["", "[sandbox_workspace_write]", sandboxOwnership(stateRoot),
     `writable_roots = [${tomlString(stateRoot)}]`];
 };
 
-// Every spelling TOML allows for the same table: the header, a sub-table
-// header, a dotted key, and an inline table on one line. Missing one means ACC
-// appends a second declaration - which is the duplicate this exists to avoid,
-// and the client refuses the whole config over it.
-const declaresSandbox = config =>
-  /^\s*\[sandbox_workspace_write[\].]/m.test(config)
-  || /^\s*sandbox_workspace_write\s*[.=]/m.test(config);
+const declaresSandbox = config => inspectConfig(config).sandbox;
+
+const sandboxReview = (config, file, stateRoot) =>
+  typeof stateRoot === "string" && stateRoot !== "" && inspectConfig(config, file).sandbox
+    ? [`verify sandbox_workspace_write.writable_roots in ${file} includes ${stateRoot}; `
+      + "your existing sandbox configuration was preserved"]
+    : [];
 
 export async function installCodexPlugin({ home, agentsHome = home,
-  codexHome = path.join(home, ".codex"), stateRoot, runner, node }) {
+  codexHome = path.join(home, ".codex"), dataHome, stateRoot, runner, node, cli, preserveVersions = false }) {
   // Read before writing, so a manifest that will not parse is found before a
   // plugin tree is laid down that nothing will then be able to remove.
   const existing = await readJson(marketplacePath(agentsHome), { name: MARKETPLACE,
@@ -159,15 +169,26 @@ export async function installCodexPlugin({ home, agentsHome = home,
   // marketplace at this root - discovered without any config entry, under
   // whatever its manifest calls itself - the id ACC enabled was one the client
   // never forms, and the plugin sat there listed and not installed.
-  const before = await readFile(configPath(codexHome), "utf8").catch(() => "");
+  const config = configPath(codexHome);
+  const before = await readConfig(config);
+  const foreign = inspectConfig(before, config);
+  // Preflight before touching installed files: a duplicate table makes Codex
+  // refuse the config, and ambiguous ownership must never delete client state.
+  if (foreign.registration) {
+    throw new AccError(EXIT.CONFLICT,
+      `marketplace ${MARKETPLACE} or its plugin is already registered in this config; `
+      + "remove it and install again", { config });
+  }
+  const theirSandbox = foreign.sandbox;
 
   const target = pluginPath(agentsHome);
   await rm(target, { recursive: true, force: true });
   await cp(bundle, target, { recursive: true });
   // The skill ships with a placeholder where the command belongs: `acc` is
   // not on PATH everywhere, and an agent that cannot run it improvises.
-  await bakeSkillCommand({ root: target, node });
-  const shim = await writeHookShim({ dir: target, adapterId: "codex", runner, node });
+  await bakeSkillCommand({ root: target, node, cli, dataHome });
+  const shim = await writeHookShim({ dir: target, adapterId: "codex",
+    dataHome, runner, node });
   await writeJson(path.join(target, "hooks.json"),
     withShim(await readJson(path.join(bundle, "hooks.json"), { hooks: {} }), shim));
 
@@ -178,16 +199,6 @@ export async function installCodexPlugin({ home, agentsHome = home,
   const others = (existing.plugins ?? []).filter(entry => entry.name !== PLUGIN_NAME);
   await writeMarketplace(file, { ...existing, plugins: [...others, entryFor()] });
 
-  const config = configPath(codexHome);
-  // A marketplace declared twice makes this client refuse the whole config, and
-  // then every plugin the user has stops working. If they registered it
-  // themselves, say so rather than appending a duplicate table.
-  if (stripBlock(before).includes(`[marketplaces.${MARKETPLACE}]`)) {
-    throw new AccError(EXIT.CONFLICT,
-      `marketplace ${MARKETPLACE} is already registered in this config; `
-      + "remove it and install again", { config });
-  }
-  const theirSandbox = declaresSandbox(stripBlock(before));
   await writeTomlBlock(config, [
     `[marketplaces.${MARKETPLACE}]`,
     `source_type = "local"`,
@@ -212,7 +223,7 @@ export async function installCodexPlugin({ home, agentsHome = home,
   await cp(target, cached, { recursive: true });
   // One copy, the one just written - and only inside this plugin's own
   // directory. The marketplace cache root above it holds other people's plugins.
-  await keepOnlyVersion({ root: path.dirname(cached), version, io: { readdir, rm } });
+  if (!preserveVersions) await keepOnlyVersion({ root: path.dirname(cached), version, io: { readdir, rm } });
 
   // The plugin's own directory in the cache. Not the versioned one inside it,
   // which goes stale the moment the version changes - and not the marketplace
@@ -224,11 +235,9 @@ export async function installCodexPlugin({ home, agentsHome = home,
   // while ACC invented its own marketplace name and so had a root to itself.
   // make the record stale the moment the plugin version changes.
   return { ok: true, changes: [target, file, config, cachePath(codexHome)],
+    needsAction: [HOOK_REVIEW, ...sandboxReview(before, config, stateRoot)],
     diagnostics: ["hooks require explicit trust in Codex before they run",
-      ...(theirSandbox
-        ? [`this config sets its own sandbox_workspace_write; add ${stateRoot} to `
-          + "writable_roots, or an agent here can read the roster and record nothing"]
-        : [])] };
+      ...sandboxReview(before, config, stateRoot)] };
 }
 
 /** Remove each directory that is empty, in the order given. */
@@ -239,10 +248,21 @@ async function removeEmptyDirs(directories) {
 }
 
 
+export async function preflightCodexUninstall({ home, agentsHome = home,
+  codexHome = path.join(home, ".codex") }) {
+  const existing = await readJson(marketplacePath(agentsHome), null);
+  const before = await readFile(configPath(codexHome), "utf8").catch(error => {
+    if (error.code === "ENOENT") return "";
+    throw error;
+  });
+  return { existing, withoutOurs: inspectConfig(before, configPath(codexHome)).source };
+}
+
 export async function uninstallCodexPlugin({ home, agentsHome = home,
   codexHome = path.join(home, ".codex"), keep = [] }) {
   const file = marketplacePath(agentsHome);
-  const existing = await readJson(file, null);
+  // Direct adapter callers need the same check as the installer boundary.
+  const { existing, withoutOurs } = await preflightCodexUninstall({ home, agentsHome, codexHome });
   const changes = [];
   if (existing !== null) {
     const kept = (existing.plugins ?? []).filter(entry => entry.name !== PLUGIN_NAME);
@@ -259,9 +279,9 @@ export async function uninstallCodexPlugin({ home, agentsHome = home,
   // `hook: SessionStart Completed` while executing nothing, and ACC's write
   // guard is silently off while `acc doctor` reports the adapter installed.
   //
-  // The record is granted once, by a person, and survives ACC upgrades - hashes
-  // captured under 0.1.6 still admitted 0.1.10's hooks. Nothing ACC writes can
-  // put it back. So it is not ACC's to remove.
+  // Those historical hashes admitted the historical hooks. Current Codex checks
+  // exact definitions, so preservation cannot establish present readiness. The
+  // decision remains the client's to keep or revise, never ACC's to remove.
   // The marketplace directory is ACC's too, so it goes rather than being left
   // behind empty.
   // A blank TOML config and an absent one are the same to this client, and a
@@ -292,54 +312,42 @@ export async function uninstallCodexPlugin({ home, agentsHome = home,
     marketplaceRoot(agentsHome),
     cacheRoot(codexHome),
   ]);
-  return { ok: true, changes, diagnostics: [] };
+  return { ok: true, changes, diagnostics: declaresSandbox(withoutOurs)
+    ? ["existing sandbox_workspace_write configuration was preserved; review any retained writable_roots after removal"]
+    : [] };
 }
 
 export async function detectCodex({ home, agentsHome = home,
-  codexHome = path.join(home, ".codex") }) {
+  codexHome = path.join(home, ".codex"), stateRoot }) {
   const marketplace = await readJson(marketplacePath(agentsHome), null);
   const published = (marketplace?.plugins ?? []).some(entry => entry.name === PLUGIN_NAME);
   const config = await readFile(configPath(codexHome), "utf8").catch(() => "");
   const registered = config.includes(`[marketplaces.${MARKETPLACE}]`);
-  const enabled = config.includes(`[plugins."${QUALIFIED}"]`);
+  const pluginEntry = config.includes(`[plugins."${QUALIFIED}"]`);
   const cached = await stat(cachePath(codexHome))
     .then(() => true).catch(() => false);
-  // The condition that decides whether ACC runs here at all, and the only one
-  // this client will not tell you about: with no trust record it runs no hook,
-  // prints `hook: SessionStart Completed`, and executes nothing. Everything else
-  // - published, registered, enabled, cached - can be true while the write guard
-  // is off. Only asked when something is wired: a warning about hooks that do
-  // not exist is how a real one gets ignored.
-  const untrusted = cached && !config.includes(`hooks.state."${QUALIFIED}:`);
+  // Saved trust is not readiness. Codex compares every current definition's
+  // hash and can disable a trusted hook. Even a commented or stale single record
+  // previously suppressed this check. Leave verification to Codex's /hooks;
+  // detection neither invents its hash algorithm nor starts a client service.
   return { ok: true, changes: [], diagnostics: [
     published ? "acc plugin published in the marketplace" : "acc plugin not registered",
-    registered && enabled
-      ? "marketplace registered and plugin enabled"
-      : "marketplace not registered with the client; no hook would run",
+    registered && pluginEntry
+      ? "marketplace and plugin entries found in config; activation not verified"
+      : "marketplace/plugin registration not verified from this config",
     // Publishing, registering and enabling are all necessary and still not
     // sufficient: hooks stay silent until the client copies the plugin into its
     // own cache. Only the client does that, so ACC names the command.
     cached
       ? "plugin installed in the client's cache"
       : `plugin not installed yet; run: codex plugin add ${QUALIFIED}`,
-    // The condition that decides whether ACC runs here at all, and the only one
-    // this client will not tell you about: with no trust record it runs no hook,
-    // prints `hook: SessionStart Completed`, and executes nothing. Everything
-    // else - published, registered, enabled, cached - can be true while the
-    // write guard is off. Said only when there is something to trust, because a
-    // warning on a machine with nothing wired is how a real one gets ignored.
-    ...(untrusted
-      ? ["hooks are not trusted, so this client reports them completed and runs "
-        + "nothing"]
+    ...(cached
+      ? ["hook readiness is unverified by ACC; Codex checks whether each current "
+        + "definition is enabled and trusted"]
       : []),
   ],
-  // Said as an action rather than an observation, because a person has to do it
-  // and no acc command can: the client grants this once, from its own prompt.
-  // A diagnostic alone would have stayed in `--json`, which is where the first
-  // version of this fix put it and where nobody would have read it.
-  needsAction: untrusted
-    ? ["start codex once and accept the hook trust prompt  "
-      + "# its hooks run nothing until then"]
+  needsAction: cached
+    ? [HOOK_REVIEW, ...sandboxReview(config, configPath(codexHome), stateRoot)]
     : [] };
 }