@coworker-jp/aidr 0.1.318 → 0.1.323

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coworker-jp/aidr",
-  "version": "0.1.318",
+  "version": "0.1.323",
   "description": "AIDR setup CLI - installs ai-scanner hooks for 19+ AI coding agents",
   "type": "module",
   "bin": {

package/src/agents/claude.mjs

@@ -21,7 +21,10 @@ const SCRIPT_FILES = [
 // `rmdirIfEmpty` が効かないので、アンインストール後にディレクトリと記録が居座る。
 // 7 エージェントすべて同じ表を持ち、`tests/bin-dir-artifacts.test.mjs` が
 // 「表 ⇔ テンプレートが実際に書く名前」を両方向で照合する。
-const BIN_FILES = ["ai-scanner", "opengrep", ".ai-scanner-unscanned", ".ai-scanner-last-pull"];
+// #2366: 配布物は 2 本。`ai-harness` が hook の 8 コンテキストを持ち、
+// `ai-scanner` が定期インベントリ送信を持つ。**両方を消す対象に入れる** ——
+// 片方だけ残すと bin ディレクトリが空にならず `rmdirIfEmpty` が効かない。
+const BIN_FILES = ["ai-scanner", "ai-harness", "opengrep", ".ai-scanner-unscanned", ".ai-scanner-last-pull"];
 
 export const meta = {
   name: "claude",

package/src/agents/codex.mjs

@@ -35,7 +35,10 @@ const SCRIPT_FILES = [
 // `rmdirIfEmpty` が効かないので、アンインストール後にディレクトリと記録が居座る。
 // 7 エージェントすべて同じ表を持ち、`tests/bin-dir-artifacts.test.mjs` が
 // 「表 ⇔ テンプレートが実際に書く名前」を両方向で照合する。
-const BIN_FILES = ["ai-scanner", "opengrep", ".ai-scanner-unscanned", ".ai-scanner-last-pull"];
+// #2366: 配布物は 2 本。`ai-harness` が hook の 8 コンテキストを持ち、
+// `ai-scanner` が定期インベントリ送信を持つ。**両方を消す対象に入れる** ——
+// 片方だけ残すと bin ディレクトリが空にならず `rmdirIfEmpty` が効かない。
+const BIN_FILES = ["ai-scanner", "ai-harness", "opengrep", ".ai-scanner-unscanned", ".ai-scanner-last-pull"];
 const ROOT_FILES = ["AGENTS.md"];
 
 export const meta = {
@@ -49,8 +52,10 @@ const CODEX_AGENTS_MD = `# AIDR Scanner
 
 AIDR security scanner is active for this Codex session. Set the access key
 via the \`AI_SCANNER_ACCESS_KEY\` environment variable. Hooks are registered
-in \`.codex/hooks.json\` and require \`[features] codex_hooks = true\` in
-\`.codex/config.toml\` (this setup writes both for you).
+in \`.codex/hooks.json\` and require \`[features] hooks = true\` in
+\`.codex/config.toml\` (this setup writes both for you). The older
+\`[features] codex_hooks\` spelling is deprecated by Codex — if your config
+still has it, setup renames it to \`hooks\` in place.
 
 Codex currently emits Bash tool events only. Read / Edit / WebFetch / WebSearch
 are not hookable — for those, use Claude Code.
@@ -180,7 +185,7 @@ async function mergeCodexConfigToml(target, { dryRun, stderr = process.stderr })
     if (stat) {
       stderr.write(
         `WARNING: ${target} already exists. (dry-run: would back up)\n` +
-        `Merging [features] codex_hooks; your other settings are preserved.\n`
+        `Merging [features] hooks (the deprecated codex_hooks key is migrated if present); your other settings are preserved.\n`
       );
     }
     process.stdout.write(
@@ -196,7 +201,7 @@ async function mergeCodexConfigToml(target, { dryRun, stderr = process.stderr })
     await fsp.copyFile(target, backupPath);
     stderr.write(
       `WARNING: ${target} already exists. Backed up to ${backupPath}.\n` +
-      `Merging [features] codex_hooks; your other settings are preserved.\n`
+      `Merging [features] hooks (the deprecated codex_hooks key is migrated if present); your other settings are preserved.\n`
     );
   }
 

package/src/agents/cursor.mjs

@@ -36,7 +36,10 @@ const SCRIPT_FILES = [
 // `rmdirIfEmpty` が効かないので、アンインストール後にディレクトリと記録が居座る。
 // 7 エージェントすべて同じ表を持ち、`tests/bin-dir-artifacts.test.mjs` が
 // 「表 ⇔ テンプレートが実際に書く名前」を両方向で照合する。
-const BIN_FILES = ["ai-scanner", "opengrep", ".ai-scanner-unscanned", ".ai-scanner-last-pull"];
+// #2366: 配布物は 2 本。`ai-harness` が hook の 8 コンテキストを持ち、
+// `ai-scanner` が定期インベントリ送信を持つ。**両方を消す対象に入れる** ——
+// 片方だけ残すと bin ディレクトリが空にならず `rmdirIfEmpty` が効かない。
+const BIN_FILES = ["ai-scanner", "ai-harness", "opengrep", ".ai-scanner-unscanned", ".ai-scanner-last-pull"];
 
 export const meta = {
   name: "cursor",

package/src/agents/gemini.mjs

@@ -13,7 +13,10 @@ const HOOK_FILES = ["aidr-pre.sh"];
 // `rmdirIfEmpty` が効かないので、アンインストール後にディレクトリと記録が居座る。
 // 7 エージェントすべて同じ表を持ち、`tests/bin-dir-artifacts.test.mjs` が
 // 「表 ⇔ テンプレートが実際に書く名前」を両方向で照合する。
-const BIN_FILES = ["ai-scanner", "opengrep", ".ai-scanner-unscanned", ".ai-scanner-last-pull"];
+// #2366: 配布物は 2 本。`ai-harness` が hook の 8 コンテキストを持ち、
+// `ai-scanner` が定期インベントリ送信を持つ。**両方を消す対象に入れる** ——
+// 片方だけ残すと bin ディレクトリが空にならず `rmdirIfEmpty` が効かない。
+const BIN_FILES = ["ai-scanner", "ai-harness", "opengrep", ".ai-scanner-unscanned", ".ai-scanner-last-pull"];
 
 export const meta = {
   name: "gemini",
@@ -26,11 +29,13 @@ export async function install(home, accessKey, opts = {}) {
   const { dryRun = false, scope = "project" } = opts;
   const base = meta.configDir(home);
   const hooks = path.join(base, "hooks");
-  const binary = path.join(home, meta.agentDir, "bin", "ai-scanner");
+  // #2366: hook が呼ぶのは `ai-harness` (8 コンテキスト)。`ai-scanner` は
+  // 定期インベントリ送信で、`scan read-input` 等のサブコマンドを持たない。
+  const binary = path.join(home, meta.agentDir, "bin", "ai-harness");
   const settingsPath = path.join(base, "settings.json");
   const preHookPath = path.join(hooks, "aidr-pre.sh");
   const [settingsRes, hookRes] = await Promise.all([
-    writeJsonMerge(settingsPath, buildGeminiSettings(accessKey, binary), mergeGeminiSettings, { dryRun, backup: scope !== "project" }),
+    writeJsonMerge(settingsPath, buildGeminiSettings(accessKey, hooks), mergeGeminiSettings, { dryRun, backup: scope !== "project" }),
     writeFileSafe(preHookPath, T.getGeminiPreHookSh(binary), { dryRun, force: true, mode: 0o755 }),
   ]);
   return {

package/src/agents/kiro.mjs

@@ -26,7 +26,10 @@ const SCRIPT_FILES = [
 // `rmdirIfEmpty` が効かないので、アンインストール後にディレクトリと記録が居座る。
 // 7 エージェントすべて同じ表を持ち、`tests/bin-dir-artifacts.test.mjs` が
 // 「表 ⇔ テンプレートが実際に書く名前」を両方向で照合する。
-const BIN_FILES = ["ai-scanner", "opengrep", ".ai-scanner-unscanned", ".ai-scanner-last-pull"];
+// #2366: 配布物は 2 本。`ai-harness` が hook の 8 コンテキストを持ち、
+// `ai-scanner` が定期インベントリ送信を持つ。**両方を消す対象に入れる** ——
+// 片方だけ残すと bin ディレクトリが空にならず `rmdirIfEmpty` が効かない。
+const BIN_FILES = ["ai-scanner", "ai-harness", "opengrep", ".ai-scanner-unscanned", ".ai-scanner-last-pull"];
 
 export const meta = {
   name: "kiro",

package/src/agents/standalone.mjs

@@ -10,7 +10,10 @@ import { pathExists, rmdirIfEmpty } from "../fs-utils.mjs";
 // `rmdirIfEmpty` が効かないので、アンインストール後にディレクトリと記録が居座る。
 // 7 エージェントすべて同じ表を持ち、`tests/bin-dir-artifacts.test.mjs` が
 // 「表 ⇔ テンプレートが実際に書く名前」を両方向で照合する。
-const BIN_FILES = ["ai-scanner", "opengrep", ".ai-scanner-unscanned", ".ai-scanner-last-pull"];
+// #2366: 配布物は 2 本。`ai-harness` が hook の 8 コンテキストを持ち、
+// `ai-scanner` が定期インベントリ送信を持つ。**両方を消す対象に入れる** ——
+// 片方だけ残すと bin ディレクトリが空にならず `rmdirIfEmpty` が効かない。
+const BIN_FILES = ["ai-scanner", "ai-harness", "opengrep", ".ai-scanner-unscanned", ".ai-scanner-last-pull"];
 
 export const meta = {
   name: "standalone",

package/src/agents/windsurf.mjs

@@ -33,7 +33,10 @@ const SCRIPT_FILES = [
 // `rmdirIfEmpty` が効かないので、アンインストール後にディレクトリと記録が居座る。
 // 7 エージェントすべて同じ表を持ち、`tests/bin-dir-artifacts.test.mjs` が
 // 「表 ⇔ テンプレートが実際に書く名前」を両方向で照合する。
-const BIN_FILES = ["ai-scanner", "opengrep", ".ai-scanner-unscanned", ".ai-scanner-last-pull"];
+// #2366: 配布物は 2 本。`ai-harness` が hook の 8 コンテキストを持ち、
+// `ai-scanner` が定期インベントリ送信を持つ。**両方を消す対象に入れる** ——
+// 片方だけ残すと bin ディレクトリが空にならず `rmdirIfEmpty` が効かない。
+const BIN_FILES = ["ai-scanner", "ai-harness", "opengrep", ".ai-scanner-unscanned", ".ai-scanner-last-pull"];
 
 export const meta = {
   name: "windsurf",

package/src/binary-fetcher.mjs

@@ -282,8 +282,18 @@ export async function fetchAsset(binUrl, destPath, { accessKey, checksumOpts } =
   return { path: destPath, sha256, verified };
 }
 
+//: The product served at the BARE platform key. Every other product is
+//: addressed as `<product>/<platform>`; see `fetchBinary` for why this one is
+//: not, and why that asymmetry is deliberate rather than an oversight.
+export const DEFAULT_PRODUCT = "ai-scanner";
+
+//: The hook binary (issue #2348 split, wired up in #2366). This is what every
+//: hook adapter invokes — the eight tool-call scan contexts live here, NOT in
+//: `ai-scanner`, which is the periodic endpoint-inventory collector.
+export const HARNESS_PRODUCT = "ai-harness";
+
 /**
- * Download ai-scanner for the current platform into `destPath`.
+ * Download one scanner-family binary for the current platform into `destPath`.
  *
  * TWO KEYS, ONE FALLBACK (issue #1687)
  * ------------------------------------
@@ -312,19 +322,28 @@ export async function fetchAsset(binUrl, destPath, { accessKey, checksumOpts } =
  * `servedUnpinned: true` means the caller must NOT claim the pinned version was
  * installed — what landed is whatever the endpoint currently publishes.
  */
-export async function fetchBinary(destPath, { env = "prod", accessKey, version, baseUrl } = {}) {
+export async function fetchBinary(destPath, { env = "prod", accessKey, version, baseUrl, product = DEFAULT_PRODUCT } = {}) {
   const platform = detectPlatform();
   const base = baseUrl || downloadBase(env);
-  const unpinnedUrl = `${base}/${platform}`;
+  // ONE ROUTE, TWO PRODUCTS (issue #2366)
+  // ------------------------------------
+  // `ai-scanner` keeps the BARE platform key it has always had — that key is a
+  // wire contract with every endpoint already in the field, and the binary's own
+  // self-updater composes it. Everything else is addressed under its own name.
+  // Composing `ai-scanner/<platform>` "for symmetry" would ask a Lambda that
+  // predates the split for a path it rejects, and the endpoints that would hit
+  // it are exactly the ones with no other way in.
+  const seg = product === DEFAULT_PRODUCT ? "" : `${product}/`;
+  const unpinnedUrl = `${base}/${seg}${platform}`;
 
   if (!version) {
     const result = await fetchAsset(unpinnedUrl, destPath, { accessKey });
-    return { ...result, platform, requestedVersion: null, servedUnpinned: false };
+    return { ...result, platform, product, requestedVersion: null, servedUnpinned: false };
   }
 
   try {
-    const result = await fetchAsset(`${base}/v${version}/${platform}`, destPath, { accessKey });
-    return { ...result, platform, requestedVersion: version, servedUnpinned: false };
+    const result = await fetchAsset(`${base}/v${version}/${seg}${platform}`, destPath, { accessKey });
+    return { ...result, platform, product, requestedVersion: version, servedUnpinned: false };
   } catch (e) {
     // A pinned release whose CHECKSUM is a definite 404 is incomplete in exactly
     // the same way as one whose binary is (#1773): half a release is not a
@@ -333,7 +352,7 @@ export async function fetchBinary(destPath, { env = "prod", accessKey, version,
     // unverified install, because `fetchAsset` refuses that on both keys.
     if (e?.status !== 404) throw e;
     const result = await fetchAsset(unpinnedUrl, destPath, { accessKey });
-    return { ...result, platform, requestedVersion: version, servedUnpinned: true };
+    return { ...result, platform, product, requestedVersion: version, servedUnpinned: true };
   }
 }
 

package/src/cli.mjs

@@ -10,7 +10,7 @@ import { Command } from "commander";
 const execFileP = promisify(execFile);
 import { AGENT_ORDER, AGENT_REGISTRY, loadAgent } from "./agents/index.mjs";
 import { verifyKey, maskKey } from "./verify.mjs";
-import { fetchBinary, fetchOpengrep, assertVerified } from "./binary-fetcher.mjs";
+import { fetchBinary, fetchOpengrep, assertVerified, HARNESS_PRODUCT } from "./binary-fetcher.mjs";
 import { detectInstalled } from "./detect.mjs";
 import { evaluateInstallGate, formatLocalPcGuidance } from "./env-gate.mjs";
 import { resolveCallerHome, isRunningUnderSudo, chownToCaller } from "./sudo-user.mjs";
@@ -201,15 +201,33 @@ async function cmdInstall(opts) {
           version: PINNED_VERSION,
         };
 
-        // ai-scanner + bundled Opengrep (LGPL-2.1). Both land in the same bin
-        // dir so ai-scanner's sibling-lookup finds opengrep without relying on
-        // PATH. Users can point AI_SCANNER_OPENGREP elsewhere to substitute
-        // their own LGPL-2.1 build.
+        // THREE files, one bin dir (issue #2366).
+        //
+        //   ai-harness  the hook binary — the eight tool-call scan contexts.
+        //               Every adapter this installer writes invokes THIS one,
+        //               so it is fetched first: it is what "this machine is
+        //               being scanned" means.
+        //   ai-scanner  the periodic endpoint-inventory collector, and the
+        //               self-update vehicle start_scanner.sh drives.
+        //   opengrep    bundled Opengrep (LGPL-2.1), a sibling so the scanner's
+        //               sibling-lookup finds it without relying on PATH. Users
+        //               can point AI_SCANNER_OPENGREP elsewhere to substitute
+        //               their own LGPL-2.1 build.
+        const harnessRes = assertVerified(
+          await fetchBinary(path.join(primaryDir, "ai-harness"),
+            { ...fetchOpts, product: HARNESS_PRODUCT }),
+          "the ai-harness binary",
+        );
+        // Set by the HOOK binary, not the periodic one: this flag is what
+        // decides between "nothing on this machine scans" and "scanning is in
+        // place, one piece is missing". Tying it to ai-scanner would report the
+        // reassuring half of that pair while every tool call ran unscanned.
+        binaryOutcome.scannerInstalled = true;
+        console.log(`binary: ${harnessRes.path} (${harnessRes.platform}, sha256 verified)`);
         const scannerRes = assertVerified(
           await fetchBinary(path.join(primaryDir, "ai-scanner"), fetchOpts),
           "the ai-scanner binary",
         );
-        binaryOutcome.scannerInstalled = true;
         // Stated unconditionally, because it is now a condition of getting here
         // rather than a caption on a file that may or may not have been checked
         // (#1773): `fetchAsset` throws unless the bytes matched the published
@@ -231,7 +249,7 @@ async function cmdInstall(opts) {
         console.log(`binary: ${opengrepRes.path} (opengrep ${opengrepRes.platform}, sha256 verified)`);
 
         const copyOps = restDirs.flatMap(restDir =>
-          ["ai-scanner", "opengrep"].map(async (file) => {
+          ["ai-harness", "ai-scanner", "opengrep"].map(async (file) => {
             const src = path.join(primaryDir, file);
             const dest = path.join(restDir, file);
             await fs.mkdir(restDir, { recursive: true });
@@ -366,7 +384,10 @@ async function cmdInstall(opts) {
     const stranded = needBinary.filter((r) => !r.selfHeals).map((r) => r.displayName);
     const binPaths = (await Promise.all(needBinary.map(async (r) => {
       const mod = await loadAgent(r.name);
-      return mod.meta.agentDir ? path.join(home, mod.meta.agentDir, "bin", "ai-scanner") : null;
+      // The hook binary: this list is read out to someone checking whether the
+      // machine is scanned, and `ai-scanner` sitting there would answer "yes"
+      // to a question about a file that runs no hooks (#2366).
+      return mod.meta.agentDir ? path.join(home, mod.meta.agentDir, "bin", "ai-harness") : null;
     }))).filter(Boolean);
     console.error(formatMissingBinaryStatus({
       reason, selfHealing, stranded, binPaths, installCommand: INSTALL_COMMAND_HINT,
@@ -599,13 +620,24 @@ async function cmdDoctor() {
     const mod = await loadAgent(name);
     const agentDir = mod.meta.agentDir;
     if (!agentDir) return null;
-    const bin = path.join(home, agentDir, "bin", "ai-scanner");
-    let present = false;
-    try {
-      await fs.access(bin, fs.constants.F_OK);
-      present = true;
-    } catch {}
-    const out = [`binary: ${bin} ${present ? "[present]" : "[missing]"}`];
+    // TWO binaries since the split (issue #2366), and only ONE of them decides
+    // whether tool calls are scanned. `ai-harness` carries the eight hook
+    // contexts; `ai-scanner` is the periodic collector. Reporting only the
+    // latter would print "[present]" on a machine whose every hook fail-opens.
+    const bin = path.join(home, agentDir, "bin", "ai-harness");
+    const periodicBin = path.join(home, agentDir, "bin", "ai-scanner");
+    const exists = async (p) => {
+      try { await fs.access(p, fs.constants.F_OK); return true; } catch { return false; }
+    };
+    const present = await exists(bin);
+    const periodicPresent = await exists(periodicBin);
+    const out = [
+      `tool-call scanner: ${bin} ${present ? "[present]" : "[missing]"}`,
+      `periodic collector: ${periodicBin} ${periodicPresent ? "[present]" : "[missing]"}`,
+    ];
+    if (!present) {
+      out.push(`  Tool calls on this machine are NOT being scanned. Re-run the installer (${INSTALL_COMMAND_HINT}), or contact your IT administrator.`);
+    }
     // What the hooks recorded while there was no binary (#1774). Without this,
     // "[missing]" was the only trace, and it said nothing about how long the
     // machine had been unscanned or how much had gone through unscanned —

package/src/install-status.mjs

@@ -41,7 +41,10 @@ export function formatMissingBinaryStatus({
   const lines = [
     "",
     RULE,
-    "This machine is NOT being scanned yet — the ai-scanner binary is not in place.",
+    // Names `ai-harness`, because that is the binary that scans a tool call
+    // (issue #2366). Saying "ai-scanner" here would send the reader to check a
+    // file that can be perfectly present on a machine where nothing is scanned.
+    "This machine is NOT being scanned yet — the ai-harness binary is not in place.",
     "",
     `  what stopped it: ${reason}`,
     "",

package/src/merge.mjs

@@ -24,8 +24,17 @@
 export const CLAUDE_OUR_COMMAND_RE =
   /^(?:"\$(?:CLAUDE_PROJECT_DIR|HOME)"|\$(?:CLAUDE_PROJECT_DIR|HOME))\/\.claude\/coworker-ai\/(?:start_scanner|stop_scanner|scan_[a-z_]+|log_web_urls)\.sh(?:\s|$|"|')/;
 
+// Matches BOTH the adapter we install today AND the broken pre-#2354 command.
+// **The legacy alternative is load-bearing, not tidiness**: an endpoint that
+// already ran the old installer has the broken command sitting in its
+// `settings.json`. `mergeGeminiSettings` / `unmergeGeminiSettings` use this
+// predicate to recognise our own entries — if it stopped matching the old form,
+// an upgrade would **leave the broken hook in place and add the new one beside
+// it**, so every tool call would still hit a command that exits 2, and
+// uninstall would leave it behind forever. Drop the legacy branch only once no
+// endpoint in the field can still carry it.
 export const GEMINI_OUR_COMMAND_RE =
-  /ai-scanner["']?\s+scan\s+hook-gemini\b/;
+  /(?:\/\.gemini\/hooks\/aidr-(?:pre|post)\.sh|ai-scanner["']?\s+scan\s+hook-gemini\b)/;
 
 // Matches our Codex hook wrappers whether installed at the repo root
 // (.codex/coworker-ai/pre_shell.sh) or absolute user-scope path
@@ -229,7 +238,27 @@ export function buildWindsurfHooksJson(scope = "project", absHome = "") {
   };
 }
 
-export function buildGeminiSettings(accessKey, binary) {
+// **2026-09-08 (issue #2354): this pointed at a subcommand that does not exist.**
+// It emitted `<binary> scan hook-gemini --stage pre|post`; the scanner has no
+// `hook-gemini` subcommand, so every invocation died with
+// `error: unrecognized subcommand` and **exit code 2**. Install reported
+// success, `settings.json` filled with hooks, and **not one tool call was ever
+// scanned** — while the working adapter (`~/.gemini/hooks/aidr-pre.sh`) was
+// written to disk on every install and referenced by nothing.
+//
+// Two things were wrong, not one. Exit 2 is also the *block* code, and this was
+// the **only** agent calling the binary directly rather than through a shell
+// wrapper — so it sat outside the fail-open invariant that every other agent
+// gets from `run_scanner` (which maps a timeout's 124 to 0). Pointing at the
+// adapter fixes both at once: the scan actually runs, **and** it runs inside
+// the wrapper.
+//
+// `AfterTool` is gone rather than re-pointed: **there is no post adapter.**
+// `agents/gemini.mjs` installs `aidr-pre.sh` only, and inventing post coverage
+// here would be new agent coverage (#2350's scope), not a defect fix. Declaring
+// only what exists is the point — the previous declaration is exactly how a
+// hook that never ran looked installed.
+export function buildGeminiSettings(accessKey, hooksDir) {
   // timeout is in milliseconds (Gemini convention). Default 60000 (1 min)
   // is too long for an inline hook — cap at 15000 so the editor kills a
   // hung scanner cleanly. The shell-side run_scanner cap fires first under
@@ -241,10 +270,7 @@ export function buildGeminiSettings(accessKey, binary) {
     },
     hooks: {
       BeforeTool: [
-        { hooks: [{ type: "command", command: `"${binary}" scan hook-gemini --stage pre`, timeout: 15000 }] },
-      ],
-      AfterTool: [
-        { hooks: [{ type: "command", command: `"${binary}" scan hook-gemini --stage post`, timeout: 15000 }] },
+        { hooks: [{ type: "command", command: `"${hooksDir}/aidr-pre.sh"`, timeout: 15000 }] },
       ],
     },
   };

package/src/templates.mjs

@@ -11,11 +11,44 @@ export function getSettingsJson(accessKey, scope = "project") {
 }
 
 // start_scanner.sh — parameterized by the verify endpoint (prod / dev).
+// ── このスクリプトが端末へ出す文言は ja / en を併記する (issue #2372 条件 3) ──
+//
+// **決定 (2026-09-09): (a) 併記する。** `docs/product/UI_COPY.md` の表の
+// 「`aidr` CLI (端末のターミナルに出る文字列)」の行が既にこう決めており、
+// **その行の理由がこの面にそのまま当たる**:
+//
+//   * **読み手を実行時に特定できない。** 同じ端末で情シスも開発者も読む。
+//   * **出し分ける先が無い。** フックはロケールを持たない bash なので、
+//     1 つの出力を全員が読む。**片方だけにすると、読めない側にとっては
+//     何も書かれていないのと同じである。**
+//
+// この 2 つは「利用者が打ったコマンド」かどうかに依存しない。むしろこの面は
+// CLI より弱い —— **利用者はこの出力を頼んでいない**ので、読めない言語で
+// 出された行は、そのまま読み飛ばされる。
+//
+// **(b)「フックの stderr は en のみ」と明文化する案は採らなかった。** 採れば
+// この面だけが表の 4 行のどれとも違う基準を持つことになり、**なぜここだけ
+// 違うのかを説明できない** (英語だけだったのは判断の結果ではなく、
+// 基準を持たないまま書かれ続けた結果である —— `UI_COPY.md` の
+// `GAP-2355-CLI-COPY-JA-EN-UNEVEN` がその状態を名指ししている)。
+//
+// **★ 短くするために事実や次の行動を削らないこと** (`UI_COPY.md` 【非交渉】)。
+// 1 文が長くなるなら**文を割る**。en 行はそのまま残してある —— 併記は
+// 「英語を日本語で置き換える」ことではない。
+//
+// **ここで揃うのはこのスクリプトだけである** (`GAP-2372-AIDR-JA-EN-PARTIAL`)。
+// `packages/aidr` の他の出力 (`red-team.mjs::redTeamInstallFailureText` など) は
+// 英語のままで、揃えるのは別の作業である。**「aidr は併記済み」と読まないこと。**
 // `agentType` is currently unused inside the script (endpoint-info has moved
 // to schedule-only invocation via aidr --scheduled), but the parameter
 // is kept for signature stability with callers and the wider TS template.
 // eslint-disable-next-line no-unused-vars
 export function getStartScannerSh(downloadBase = "https://pytd2jd5p7.execute-api.ap-northeast-1.amazonaws.com/download", agentType = "claude-code") {
+  // `agentType` is the endpoint-info spelling (`claude-code`); `setup --agent`
+  // takes the installer/portal spelling (`claude`). They differ for exactly one
+  // agent, so the mapping is stated here rather than guessed at the call site —
+  // guessing would make the self-repair below configure the WRONG agent.
+  const setupAgentName = agentType === "claude-code" ? "claude" : agentType;
   // Which installer to quote back at the user, derived from the endpoint this
   // script was generated against. The DEV package must never tell anyone to
   // install PROD (same rule as cli.mjs's INSTALL_COMMAND_HINT) — and here the
@@ -32,6 +65,16 @@ export function getStartScannerSh(downloadBase = "https://pytd2jd5p7.execute-api
 # - Fail-open: never block Claude Code startup
 BIN="\${AI_SCANNER_BIN:-$HOME/.claude/bin/ai-scanner}"
 BIN_DIR="$(dirname "$BIN")"
+# TWO binaries since the split (issue #2366). \`ai-harness\` runs the eight
+# tool-call scan contexts — it is the one every hook adapter invokes, so it is
+# the one whose absence means "this session is not being scanned". \`ai-scanner\`
+# is the periodic inventory collector and the self-update vehicle. They are
+# built from one crate and therefore must stay on ONE version; the skew check
+# further down is what enforces that.
+#
+# Two env names, never one shared: pointing a single override at one product
+# would silently leave the other pointing at a file that is not it.
+HARNESS="\${AI_HARNESS_BIN:-$BIN_DIR/ai-harness}"
 # The self-update throttle belongs to the binary it throttles, so it is derived
 # from \$BIN — the one source this script already trusts for "where is my copy"
 # (\`.ai-scanner-unscanned\` is placed the same way). It used to be pinned to
@@ -132,7 +175,8 @@ sha256_of() {
 # \`$UNVERIFIED_REASON\` carries WHY, so the message can name it.
 download_binary() {
     local url="$1"
-    local tmp=$(mktemp "\${BIN_DIR}/ai-scanner.XXXXXX")
+    local dest="$2"
+    local tmp=$(mktemp "\${BIN_DIR}/.download.XXXXXX")
     local auth_args=()
     if [ -n "\${AI_SCANNER_ACCESS_KEY:-}" ]; then
         auth_args=(-H "x-access-key: \${AI_SCANNER_ACCESS_KEY}")
@@ -166,10 +210,34 @@ download_binary() {
     # macOS: strip Gatekeeper quarantine so unsigned binary can execute
     # (no-op on Linux where xattr isn't typically present)
     xattr -d com.apple.quarantine "$tmp" 2>/dev/null || true
-    mv -f "$tmp" "$BIN"
+    mv -f "$tmp" "$dest"
     return 0
 }
 
+# Fetch one product into place if it is not already there. The download route
+# serves \`ai-scanner\` at the bare platform key (unchanged wire contract) and
+# every other product under its own name.
+#
+# Says "installed" only when it actually installed something. Printing it on
+# every session start for a file that was already there turns the line into
+# noise, and the next reader stops distinguishing it from the one that matters.
+#   $1 = absolute destination, $2 = product name
+ensure_binary() {
+    local dest="$1" product="$2" url
+    [ -x "$dest" ] && return 0
+    if [ "$product" = "ai-scanner" ]; then
+        url="\${DOWNLOAD_BASE}/\${PLATFORM_SLUG}"
+    else
+        url="\${DOWNLOAD_BASE}/\${product}/\${PLATFORM_SLUG}"
+    fi
+    if download_binary "$url" "$dest"; then
+        echo "$product のバイナリを導入しました (\${PLATFORM_SLUG}、チェックサム検証済み)。" >&2
+        echo "$product binary installed (\${PLATFORM_SLUG}, checksum verified)" >&2
+        return 0
+    fi
+    return 1
+}
+
 # What has already run unscanned on this machine, if anything (#1774). The scan
 # hooks append to this file every time they exit without a binary; this is the
 # first moment anyone can say it out loud, and it is deleted the moment a binary
@@ -187,6 +255,7 @@ report_unscanned_history() {
     # itself is the fallback — printing nothing here would drop the fact.
     local when
     when=$(date -d "@$first" 2>/dev/null || date -r "$first" 2>/dev/null || echo "epoch $first")
+    echo "ai-scanner: この端末では、すでに $count 件のツールコールが検査されないまま実行されています (最初は $when)。" >&2
     echo "ai-scanner: $count tool call(s) have already run unscanned on this machine (first at $when)." >&2
 }
 
@@ -195,8 +264,10 @@ report_unscanned_history() {
 # reads as cosmetic (docs/product/UI_COPY.md 【非交渉】) — and unlike a failed
 # download, re-running the installer cannot fix it, so the action is different.
 unsupported_platform() {
+    echo "ai-scanner: このセッションは検査されていません。このプラットフォーム ($1) 向けのスキャナーが存在しません。" >&2
     echo "ai-scanner: this session is NOT being scanned — there is no scanner build for this platform ($1)." >&2
     report_unscanned_history
+    echo "ai-scanner: ツールコールは動き続けますが、この端末では検査されないまま実行されます。このメッセージを添えて、社内の IT 管理者にご連絡ください。" >&2
     echo "ai-scanner: tool calls keep working, and they run unscanned on this machine. Contact your IT administrator with this message." >&2
 }
 
@@ -234,26 +305,46 @@ case "$OS" in
         ;;
 esac
 
-# Binary missing → fetch it
-if [ ! -x "$BIN" ]; then
-    if download_binary "\${DOWNLOAD_BASE}/\${PLATFORM_SLUG}"; then
-        echo "ai-scanner binary installed (\${PLATFORM_SLUG}, checksum verified)" >&2
-        rm -f "$UNSCANNED_STAMP"
+# The HOOK binary first: tool-call scanning depends on this one, so its absence
+# is what the session-level message is about.
+#
+# docs/product/UI_COPY.md 【非交渉】: the fact, stated so it cannot be read as
+# harmless, and then the next action. The old single line ("Warning: Failed to
+# download …") said neither what it meant for the session nor what to do, and it
+# was the ONLY trace anywhere (#1774).
+SCANNING=0
+if ensure_binary "$HARNESS" ai-harness; then
+    SCANNING=1
+    # A binary IS in place. Clear any record of having run unscanned, so the
+    # record only ever describes the machine's CURRENT state.
+    rm -f "$UNSCANNED_STAMP"
+else
+    echo "ai-scanner: このセッションは検査されていません。ツールコール検査機 (ai-harness) がこの端末になく、今回も導入できませんでした: \${UNVERIFIED_REASON:-ダウンロードに失敗しました}。" >&2
+    echo "ai-scanner: this session is NOT being scanned — the tool-call scanner (ai-harness) is not installed on this machine and could not be installed now: \${UNVERIFIED_REASON:-the download failed}." >&2
+    report_unscanned_history
+    echo "ai-scanner: ツールコールは動き続けますが、導入されるまで検査されないまま実行されます。導入コマンド (${installCommand}) をもう一度実行してください。それでも直らなければ、このメッセージを添えて社内の IT 管理者にご連絡ください。" >&2
+    echo "ai-scanner: tool calls keep working, and they run unscanned until it is in place. Re-run the installer (${installCommand}), or contact your IT administrator with this message." >&2
+fi
+
+# The PERIODIC binary. Its absence does NOT stop tool-call scanning, so it gets
+# its own, narrower sentence rather than borrowing the one above — saying "this
+# session is NOT being scanned" when it IS would train the reader to ignore the
+# line that means it.
+if ! ensure_binary "$BIN" ai-scanner; then
+    # Only claims scanning is unaffected when it actually is — the harness may
+    # have failed too, and the line above is the one that says so.
+    if [ "$SCANNING" = 1 ]; then
+        echo "ai-scanner: ツールコールの検査は続いています。ただし定期の端末情報収集は導入できませんでした: \${UNVERIFIED_REASON:-ダウンロードに失敗しました}。この端末がポータルに現れなくなったら、導入コマンド (${installCommand}) をもう一度実行してください。" >&2
+        echo "ai-scanner: tool calls are still being scanned, but the periodic endpoint-inventory collector could not be installed: \${UNVERIFIED_REASON:-the download failed}. Re-run the installer (${installCommand}) if this endpoint stops appearing in the portal." >&2
     else
-        # docs/product/UI_COPY.md 【非交渉】: the fact, stated so it cannot be
-        # read as harmless, and then the next action. The old single line
-        # ("Warning: Failed to download …") said neither what it meant for the
-        # session nor what to do, and it was the ONLY trace anywhere (#1774).
-        echo "ai-scanner: this session is NOT being scanned — the scanner is not installed on this machine and could not be installed now: \${UNVERIFIED_REASON:-the download failed}." >&2
-        report_unscanned_history
-        echo "ai-scanner: tool calls keep working, and they run unscanned until it is in place. Re-run the installer (${installCommand}), or contact your IT administrator with this message." >&2
+        echo "ai-scanner: 定期の端末情報収集も導入できませんでした: \${UNVERIFIED_REASON:-ダウンロードに失敗しました}。導入コマンド (${installCommand}) をもう一度実行してください。それでも直らなければ、このメッセージを添えて社内の IT 管理者にご連絡ください。" >&2
+        echo "ai-scanner: the periodic endpoint-inventory collector could not be installed either: \${UNVERIFIED_REASON:-the download failed}. Re-run the installer (${installCommand}), or contact your IT administrator with this message." >&2
     fi
-    exit 0
 fi
 
-# A binary IS in place. Clear any record of having run unscanned, so the record
-# only ever describes the machine's CURRENT state.
-rm -f "$UNSCANNED_STAMP"
+# Neither is in place: nothing below can run, and the message above already said
+# so with its next action.
+[ -x "$BIN" ] || exit 0
 
 # Binary exists — throttled self-update check.
 #
@@ -275,17 +366,130 @@ if should_check_update; then
     want_host=$(printf '%s' "$DOWNLOAD_BASE" | sed -E 's#^[a-z]+://([^/]+).*#\\1#')
     have_host=$(timeout "$VERSION_TIMEOUT" "$BIN" version 2>/dev/null | sed -n 's#^server: [a-z]*://\\([^/]*\\).*#\\1#p' | head -1)
     if [ -n "$have_host" ] && [ -n "$want_host" ] && [ "$have_host" != "$want_host" ]; then
+        echo "ai-scanner: 導入済みのバイナリは $have_host を見ていますが、この導入は $want_host から配信しています。アクセスキーは決して受け付けられず、検知ログは拒否されて捨てられます。一致するバイナリを取り直しています。" >&2
         echo "ai-scanner: the installed binary talks to $have_host, but this installation provisions from $want_host, so its access key can never be accepted (detection logs are refused and discarded). Re-downloading the matching binary." >&2
-        download_binary "\${DOWNLOAD_BASE}/\${PLATFORM_SLUG}" || \\
+        download_binary "\${DOWNLOAD_BASE}/\${PLATFORM_SLUG}" "$BIN" || \\
+            echo "ai-scanner: 食い違ったバイナリを置き換えられませんでした: \${UNVERIFIED_REASON:-ダウンロードに失敗しました}。手元の検査は続きますが、検知ログは拒否され続けます。導入コマンドをもう一度実行してください。それでも直らなければ、このメッセージを添えて社内の IT 管理者にご連絡ください。" >&2
             echo "ai-scanner: could not replace the mismatched binary: \${UNVERIFIED_REASON:-the download failed}. Scanning continues locally, but detection logs will keep being refused. Re-run the installer, or contact your IT administrator with this message." >&2
     elif [ -z "$have_host" ]; then
+        echo "ai-scanner: 導入済みのバイナリがどのライセンスサーバーを見ているか読めなかったので、環境が一致するかは確認していません。検知ログが拒否されているようなら、導入コマンドをもう一度実行してください。" >&2
         echo "ai-scanner: could not read which license server the installed binary uses, so the environment match was NOT checked. If detection logs are being refused, re-run the installer." >&2
     fi
     timeout "$UPDATE_TIMEOUT" "$BIN" update 2>/dev/null || \\
+        echo "ai-scanner: スキャナーは今回、自分を更新できませんでした。すでに持っているルールで検査は続きます。これが繰り返されるなら、導入コマンドをもう一度実行してください。それでも直らなければ社内の IT 管理者にご連絡ください。" >&2
         echo "ai-scanner: the scanner could not update itself just now. It keeps scanning with the rules it already has; if this repeats, re-run the installer or contact your IT administrator." >&2
+
+    # Keep the hook binary on the SAME build as the periodic one (issue #2366).
+    # They come from one crate and share one version, so a skew means an update
+    # moved only ai-scanner and left the harness behind.
+    #
+    # \`"$HARNESS" update\` is deliberately NOT used (issue #2368): that
+    # self-update resolves the bare platform key, which serves ai-scanner —
+    # running it would overwrite the harness with the periodic binary and take
+    # every hook down with it. Refreshing through the same checksum-verified
+    # download path avoids that. **Do not "simplify" this into an update call.**
+    #
+    # \`GAP-UNOBSERVED-OVERWRITE\`: the overwrite itself has NOT been observed.
+    # Reproducing it needs \`/verify\` to advertise a newer version, and v0.1.319
+    # has zero keys in S3, so the precondition does not exist yet. What is
+    # written above is the mechanism read off \`cli/mod.rs::cmd_update\` — which is
+    # enough to route around, and NOT enough to call measured.
+    if [ -x "$HARNESS" ]; then
+        scanner_ver=$(timeout "$VERSION_TIMEOUT" "$BIN" version 2>/dev/null | awk 'NR==1{print $2}')
+        harness_ver=$(timeout "$VERSION_TIMEOUT" "$HARNESS" version 2>/dev/null | awk 'NR==1{print $2}')
+        if [ -n "$scanner_ver" ] && [ -n "$harness_ver" ] && [ "$scanner_ver" != "$harness_ver" ]; then
+            echo "ai-scanner: ツールコール検査機は $harness_ver、この端末は $scanner_ver です。同じビルドで揃うよう、いま取り直しています。" >&2
+            echo "ai-scanner: the tool-call scanner is on $harness_ver while this endpoint is on $scanner_ver. Refreshing it so both run one build." >&2
+            download_binary "\${DOWNLOAD_BASE}/ai-harness/\${PLATFORM_SLUG}" "$HARNESS" || \\
+                echo "ai-scanner: ツールコール検査機を取り直せませんでした: \${UNVERIFIED_REASON:-ダウンロードに失敗しました}。検査は $harness_ver のまま続きます。これが繰り返されるなら、導入コマンド (${installCommand}) をもう一度実行してください。" >&2
+                echo "ai-scanner: could not refresh the tool-call scanner: \${UNVERIFIED_REASON:-the download failed}. Scanning continues on $harness_ver; re-run the installer (${installCommand}) if this repeats." >&2
+        fi
+    fi
     date +%s > "$PULL_STAMP"
 fi
 
+# ── 既に撒かれたラッパーを現行の形へ収束させる (issue #2372、案 1) ────────────
+#
+# **バイナリは自動で届くが、設定は届かない。** アダプタは導入時に 1 度だけ
+# 書かれ、以後どの経路でも書き換わらない一方、自己更新はそれが名指すバイナリを
+# 黙って差し替える。その非対称が #2372 の本体で、ここはその片側を閉じる。
+#
+# **なぜ SessionStart なのか (同意の範囲)**: これは**利用者が自分でエディタを
+# 起動したときにだけ、その利用者として**走る。「そのエディタのフックを直す」と
+# いう範囲から出ない。常駐が利用者の home を書く案 (#2372 案 2) は
+# **同意の範囲の判断なので採らない** —— --agent が常駐を入れないという既存の
+# 判断の、ちょうど裏返しである。
+#
+# **★ この経路が届かない端末が在る (正直に置く)。** 収束させるコードはこの
+# スクリプトの中に在るので、**この版より前の start_scanner.sh を持つ端末には
+# 届かない。** そこは agent_hooks の hook_wiring (endpoint-info) が
+# **数として見えるようにする**部分が受け持つ —— だから #2372 の案 3 は
+# 「あとで」ではなく必須である。GAP-2372-PRE-REPAIR-ADAPTERS-UNREACHED。
+#
+# 4 つの門。**どれも「直せない」を「直した」と読ませないため**にある:
+#   1. hook のバイナリが在る (無ければ上の節が既に名指している)
+#   2. その版が setup を持つ (旧い版は持たない。持たないことは失敗ではない)
+#   3. アクセスキーが env に在る —— **無いまま書くと、鍵の無い settings.json を
+#      置くことになり、いま効いている保護を壊す**
+#   4. 兄弟のラッパーが実際に旧い形である (新しい形なら 1 バイトも書かない)
+CONFIG_ROOT="$(cd "$(dirname "$0")/../.." 2>/dev/null && pwd)"
+SELF_DIR="$(dirname "$0")"
+if [ -x "$HARNESS" ] && [ -n "$CONFIG_ROOT" ] && [ -n "\${AI_SCANNER_ACCESS_KEY:-}" ]; then
+    # 旧い形の判定は endpoint-info の hook_wiring と**同じ集合・同じ述語**である
+    # (agent_hooks.rs の HookWiring::from_wrapper_dir / from_wrapper_text)。
+    # 2 つ目の判定を作らない ——作ると、ポータルが数えている集合と、
+    # ここが直す集合がずれる。
+    #
+    # **【2026-09-10 訂正 —— issue #2407】かつてこの行は「同じ述語である」と
+    # 宣言しながら、実体は別のファイルを読んでいた。** 数える側は印
+    # (\`hook_marker\`) 1 本を読んでおり、claude-code のそれは
+    # **\`start_scanner.sh\` そのもの** = 分割後のビルドでは必ず \`ai-harness\` を
+    # 名指すスクリプトである。一方ここが直すのは**その兄弟**なので、
+    # **「新しい start_scanner.sh + 旧い兄弟」= まさに収束に失敗した端末が
+    # \`ai-harness\` (移行済み) として数から消えていた** (DDB 読み戻しで実測)。
+    # **数える側をこの集合へ合わせて直した** —— 直す側に \`start_scanner.sh\` を
+    # 足すのは、数える側の食い違いを 1 ミリも動かさない。
+    #
+    # **下の 4 行 (glob / 除外の case / 2 本の grep) は実体から抜き出されて
+    # 機械照合される** —— \`agent_hooks::tests::w1_the_repair_loop_and_this_module_read_one_set\`
+    # が綴りだけでなく**向き** (\`|| continue\` か \`|| stale=1\` か) まで見る。
+    # 書き換えるときは、あちらの \`WIRING_EXCLUDED_WRAPPERS\` /
+    # \`SCANNER_TOKENS\` / \`HARNESS_TOKENS\` も同じ PR で直すこと。
+    # なぜ grep -E なのか (issue #2372。実測で 1 度落ちている)。
+    # ここは長く BRE の grep -q 'ai-scanner\\|AI_SCANNER_BIN' と書かれていたが、
+    # **この本文は JS のテンプレートリテラルなので、書いたバックスラッシュ 1 つは
+    # 出力に残らない** —— 端末に置かれていたのは 'ai-scanner|AI_SCANNER_BIN' で、
+    # BRE の | はただの文字なので **この行は決して一致せず、収束は 1 度も
+    # 走らなかった** (2026-09-09 に linux-testbed で実測: 旧い形のラッパーを
+    # 置いて start_scanner.sh を回しても 1 バイトも書き換わらない)。
+    # **症状は出ない** —— 収束しないことと「収束すべきものが無い」ことが
+    # 端末側から区別できない。-E にすれば JS の逃がしが要らず (パターンに
+    # バックスラッシュが 1 つも無い)、BSD grep (macOS) が BRE の \\| を
+    # 解さない問題も同時に消える。**BRE へ戻さないこと。**
+    stale=0
+    for w in "$SELF_DIR"/*.sh; do
+        [ -r "$w" ] || continue
+        case "$w" in *"/start_scanner.sh"|*"/stop_scanner.sh") continue ;; esac
+        grep -Eq 'ai-scanner|AI_SCANNER_BIN' "$w" || continue
+        grep -Eq 'ai-harness|AI_HARNESS_BIN' "$w" || stale=1
+    done
+    if [ "$stale" = 1 ] && timeout "$VERSION_TIMEOUT" "$HARNESS" setup --help >/dev/null 2>&1; then
+        # --home を渡すので根の解決は起きない。--scope は settings.json に焼く
+        # 根の綴り ("$CLAUDE_PROJECT_DIR" か "$HOME") を決めるだけなので、
+        # **いまの設置場所から導く** —— 推測すると、リポジトリに置いた設定が
+        # 端末個別の設定として書き直される。
+        if [ "$CONFIG_ROOT" = "$HOME" ]; then repair_scope=user; else repair_scope=project; fi
+        echo "ai-scanner: この端末のフックアダプタは分割前の形で、ツールコール検査機ではなく定期実行のバイナリを呼んでいます。いま更新しています。お手元での操作は要りません。" >&2
+        echo "ai-scanner: this endpoint's hook adapters are the pre-split shape, so they still call the periodic binary instead of the tool-call scanner. Updating them now; no action is needed from you." >&2
+        timeout "$UPDATE_TIMEOUT" "$HARNESS" setup \\
+            --agent ${setupAgentName} --scope "$repair_scope" \\
+            --access-key "$AI_SCANNER_ACCESS_KEY" \\
+            --download-base "$DOWNLOAD_BASE" --home "$CONFIG_ROOT" >/dev/null 2>&1 || \\
+            echo "ai-scanner: この端末のフックアダプタは分割前の形のままで、今回は更新できませんでした。ツールコールは、すでに導入済みのバイナリが検査し続けます。このメッセージが繰り返されるなら、導入コマンド (${installCommand}) をもう一度実行してください。それでも直らなければ、このメッセージを添えて社内の IT 管理者にご連絡ください。" >&2
+            echo "ai-scanner: the hook adapters on this endpoint are still the pre-split shape and could not be updated just now. Tool calls keep being scanned by the binary already installed; if this message repeats, re-run the installer (${installCommand}) or contact your IT administrator with this message." >&2
+    fi
+fi
+
 exit 0
 `;
 }
@@ -368,7 +572,7 @@ const SCAN_HELPERS = `run_scanner() {
 export const SCAN_BASH_SH = `#!/bin/bash
 # PostToolUse hook for Bash: Scan command output.
 # Thin Claude Code adapter — Rust handles cap, detection log, actor resolution.
-BIN="\${AI_SCANNER_BIN:-$HOME/.claude/bin/ai-scanner}"
+BIN="\${AI_HARNESS_BIN:-$HOME/.claude/bin/ai-harness}"
 ${UNSCANNED_NOTE}
 [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 
@@ -385,7 +589,7 @@ jq -r '.tool_response // ""' <<<"$INPUT" \\
 export const SCAN_BASH_INPUT_SH = `#!/bin/bash
 # PreToolUse hook for Bash: Scan command before execution.
 # Thin Claude Code adapter — Rust handles cap, detection log, actor resolution.
-BIN="\${AI_SCANNER_BIN:-$HOME/.claude/bin/ai-scanner}"
+BIN="\${AI_HARNESS_BIN:-$HOME/.claude/bin/ai-harness}"
 ${UNSCANNED_NOTE}
 [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 
@@ -403,7 +607,7 @@ export const SCAN_EDIT_SH = `#!/bin/bash
 # PreToolUse hook for Edit/MultiEdit: Scan new content before write.
 # Thin Claude Code adapter — Rust handles cap, exclude dirs, detection log.
 # Only the Edit-vs-MultiEdit content extraction is Claude Code specific.
-BIN="\${AI_SCANNER_BIN:-$HOME/.claude/bin/ai-scanner}"
+BIN="\${AI_HARNESS_BIN:-$HOME/.claude/bin/ai-harness}"
 ${UNSCANNED_NOTE}
 [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 
@@ -429,7 +633,7 @@ printf '%s' "$CONTENT" | run_scanner scan edit-input --file "$FILE_PATH"
 export const SCAN_READ_SH = `#!/bin/bash
 # PostToolUse hook for Read: Scan file content Claude just read.
 # Thin Claude Code adapter — Rust handles cap, exclude dirs, detection log.
-BIN="\${AI_SCANNER_BIN:-$HOME/.claude/bin/ai-scanner}"
+BIN="\${AI_HARNESS_BIN:-$HOME/.claude/bin/ai-harness}"
 ${UNSCANNED_NOTE}
 [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 
@@ -449,7 +653,7 @@ jq -r '.tool_response.file.content // .tool_response // ""' <<<"$INPUT" \\
 export const SCAN_EDIT_OUTPUT_SH = `#!/bin/bash
 # PostToolUse hook for Edit/MultiEdit/Write: Scan final file content.
 # Thin Claude Code adapter — Rust handles cap, exclude dirs, detection log.
-BIN="\${AI_SCANNER_BIN:-$HOME/.claude/bin/ai-scanner}"
+BIN="\${AI_HARNESS_BIN:-$HOME/.claude/bin/ai-harness}"
 ${UNSCANNED_NOTE}
 [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 
@@ -470,7 +674,7 @@ export const SCAN_READ_INPUT_SH = `#!/bin/bash
 # This is a thin Claude Code adapter — all scanning logic lives in the Rust
 # binary, including actor resolution, exclude-dir filtering, content cap, and
 # detection-log writing.
-BIN="\${AI_SCANNER_BIN:-$HOME/.claude/bin/ai-scanner}"
+BIN="\${AI_HARNESS_BIN:-$HOME/.claude/bin/ai-harness}"
 ${UNSCANNED_NOTE}
 [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 
@@ -488,7 +692,7 @@ run_scanner scan read-input --file "$FILE_PATH" </dev/null
 export const SCAN_WEBFETCH_SH = `#!/bin/bash
 # PreToolUse hook for WebFetch: Scan URL before Claude fetches it.
 # Thin Claude Code adapter — Rust handles phishing scoring + YARA + detection log.
-BIN="\${AI_SCANNER_BIN:-$HOME/.claude/bin/ai-scanner}"
+BIN="\${AI_HARNESS_BIN:-$HOME/.claude/bin/ai-harness}"
 ${UNSCANNED_NOTE}
 [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 
@@ -505,7 +709,7 @@ run_scanner scan webfetch --url "$URL" </dev/null
 export const SCAN_WEBSEARCH_SH = `#!/bin/bash
 # PostToolUse hook for WebSearch: Scan search results for phishing URLs.
 # Thin Claude Code adapter — Rust handles cap, phishing scoring, detection log.
-BIN="\${AI_SCANNER_BIN:-$HOME/.claude/bin/ai-scanner}"
+BIN="\${AI_HARNESS_BIN:-$HOME/.claude/bin/ai-harness}"
 ${UNSCANNED_NOTE}
 [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 
@@ -551,6 +755,12 @@ export function agentEnvSh(accessKey, agentDir) {
   return `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
 export AI_SCANNER_BIN="\${AI_SCANNER_BIN:-$HOME/${agentDir}/bin/ai-scanner}"
+# The hook binary (issue #2366). Every adapter below scans through THIS one:
+# the eight tool-call contexts live in \`ai-harness\`, not in \`ai-scanner\`
+# (which is the periodic endpoint-inventory collector). Two names, never one
+# shared override — pointing a single variable at one product would leave the
+# other silently addressing a file that is not it.
+export AI_HARNESS_BIN="\${AI_HARNESS_BIN:-$HOME/${agentDir}/bin/ai-harness}"
 export AI_SCANNER_ACCESS_KEY="${accessKey}"
 export AI_SCANNER_LEVEL="\${AI_SCANNER_LEVEL:-high}"
 export AI_SCANNER_EXCLUDE_DIRS="\${AI_SCANNER_EXCLUDE_DIRS:-}"
@@ -569,11 +779,11 @@ ${UNSCANNED_NOTE}
 
 run_scanner() {
   if command -v timeout >/dev/null 2>&1; then
-    timeout --kill-after=2s "\${AI_SCANNER_HOOK_TIMEOUT}" "\${AI_SCANNER_BIN}" "$@"
+    timeout --kill-after=2s "\${AI_SCANNER_HOOK_TIMEOUT}" "\${AI_HARNESS_BIN}" "$@"
   elif command -v gtimeout >/dev/null 2>&1; then
-    gtimeout --kill-after=2s "\${AI_SCANNER_HOOK_TIMEOUT}" "\${AI_SCANNER_BIN}" "$@"
+    gtimeout --kill-after=2s "\${AI_SCANNER_HOOK_TIMEOUT}" "\${AI_HARNESS_BIN}" "$@"
   else
-    "\${AI_SCANNER_BIN}" "$@"
+    "\${AI_HARNESS_BIN}" "$@"
   fi
   local rc=$?
   [ $rc -eq 124 ] && return 0
@@ -593,7 +803,7 @@ source "$SCRIPT_DIR/env.sh"
 cat > /dev/null
 bash "$SCRIPT_DIR/start_scanner.sh" 2>/dev/null || true
 cat <<EOF
-{"env":{"AI_SCANNER_BIN":"\${AI_SCANNER_BIN}","AI_SCANNER_ACCESS_KEY":"${accessKey}","AI_SCANNER_LEVEL":"high"}}
+{"env":{"AI_SCANNER_BIN":"\${AI_SCANNER_BIN}","AI_HARNESS_BIN":"\${AI_HARNESS_BIN}","AI_SCANNER_ACCESS_KEY":"${accessKey}","AI_SCANNER_LEVEL":"high"}}
 EOF
 `;
 }
@@ -601,7 +811,7 @@ EOF
 export const CURSOR_PRE_SHELL_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 jq -r '.tool_input.command // ""' | run_scanner scan bash-input
 `;
@@ -609,7 +819,7 @@ jq -r '.tool_input.command // ""' | run_scanner scan bash-input
 export const CURSOR_PRE_READ_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 FILE_PATH=$(jq -r '.tool_input.file_path // ""')
 [ -z "$FILE_PATH" ] || [ "$FILE_PATH" = "null" ] && exit 0
@@ -619,7 +829,7 @@ run_scanner scan read-input --file "$FILE_PATH" </dev/null
 export const CURSOR_PRE_EDIT_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 FILE_PATH=$(jq -r '.tool_input.file_path // ""' <<<"$INPUT")
@@ -636,7 +846,7 @@ printf '%s' "$CONTENT" | run_scanner scan edit-input --file "$FILE_PATH"
 export const CURSOR_POST_SHELL_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 COMMAND=$(jq -r '.tool_output // ""' <<<"$INPUT" | head -1 && jq -r '.tool_input.command // ""' <<<"$INPUT")
@@ -646,7 +856,7 @@ jq -r '.tool_output // ""' <<<"$INPUT" | run_scanner scan bash-output --command
 export const CURSOR_POST_READ_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 FILE_PATH=$(jq -r '.tool_input.file_path // ""' <<<"$INPUT")
@@ -657,7 +867,7 @@ jq -r '.tool_output // ""' <<<"$INPUT" | run_scanner scan read-output --file "$F
 export const CURSOR_POST_WRITE_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 FILE_PATH=$(jq -r '.tool_input.file_path // ""' <<<"$INPUT")
@@ -672,7 +882,7 @@ run_scanner scan edit-output --file "$FILE_PATH" < "$FILE_PATH"
 export const WINDSURF_ENSURE_SCANNER_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"
+BIN="$AI_HARNESS_BIN"
 LOCK_FILE="/tmp/.ai-scanner-ensure.lock"
 if [ -x "$BIN" ] && timeout 2 "$BIN" health >/dev/null 2>&1; then
     return 0 2>/dev/null || true
@@ -688,7 +898,7 @@ return 0 2>/dev/null || true
 export const WINDSURF_PRE_COMMAND_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/ensure_scanner.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 CONTENT=$(jq -r '.tool_info.command_line // ""')
 [ -z "$CONTENT" ] || [ "$CONTENT" = "null" ] && exit 0
@@ -698,7 +908,7 @@ printf '%s' "$CONTENT" | run_scanner scan bash-input
 export const WINDSURF_PRE_READ_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/ensure_scanner.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 FILE_PATH=$(jq -r '.tool_info.file_path // ""')
 [ -z "$FILE_PATH" ] || [ "$FILE_PATH" = "null" ] && exit 0
@@ -708,7 +918,7 @@ run_scanner scan read-input --file "$FILE_PATH" </dev/null
 export const WINDSURF_PRE_WRITE_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/ensure_scanner.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 FILE_PATH=$(jq -r '.tool_info.file_path // ""' <<<"$INPUT")
@@ -720,7 +930,7 @@ printf '%s' "$CONTENT" | run_scanner scan edit-input --file "$FILE_PATH"
 export const WINDSURF_POST_READ_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/ensure_scanner.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 FILE_PATH=$(jq -r '.tool_info.file_path // ""')
 [ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ] && exit 0
@@ -730,7 +940,7 @@ run_scanner scan read-output --file "$FILE_PATH" < "$FILE_PATH"
 export const WINDSURF_POST_WRITE_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/ensure_scanner.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 FILE_PATH=$(jq -r '.tool_info.file_path // ""')
 [ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ] && exit 0
@@ -773,7 +983,7 @@ exec "$SCRIPT_DIR/start_scanner.sh"
 export const KIRO_PRE_SHELL_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 jq -r '.tool_input.command // ""' | run_scanner scan bash-input
 `;
@@ -781,7 +991,7 @@ jq -r '.tool_input.command // ""' | run_scanner scan bash-input
 export const KIRO_PRE_READ_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 FILE_PATH=$(jq -r '.tool_input.file_path // .tool_input.operations[0].path // ""')
 [ -z "$FILE_PATH" ] || [ "$FILE_PATH" = "null" ] && exit 0
@@ -791,7 +1001,7 @@ run_scanner scan read-input --file "$FILE_PATH" </dev/null
 export const KIRO_PRE_WRITE_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 FILE_PATH=$(jq -r '.tool_input.file_path // .tool_input.path // ""' <<<"$INPUT")
@@ -803,7 +1013,7 @@ printf '%s' "$CONTENT" | run_scanner scan edit-input --file "$FILE_PATH"
 export const KIRO_POST_SHELL_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 COMMAND=$(jq -r '.tool_input.command // ""' <<<"$INPUT")
@@ -814,7 +1024,7 @@ printf '%s' "$RESPONSE" | run_scanner scan bash-output --command "$COMMAND"
 export const KIRO_POST_READ_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 FILE_PATH=$(jq -r '.tool_input.file_path // .tool_input.operations[0].path // ""' <<<"$INPUT")
@@ -826,7 +1036,7 @@ printf '%s' "$RESPONSE" | run_scanner scan read-output --file "$FILE_PATH"
 export const KIRO_POST_WRITE_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 FILE_PATH=$(jq -r '.tool_input.file_path // .tool_input.path // ""' <<<"$INPUT")
@@ -902,7 +1112,7 @@ export const CODEX_SESSION_INIT_SH = `#!/bin/bash
 SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]:-$0}")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
 cat > /dev/null   # drain stdin so Codex doesn't block on a write
-BIN="$AI_SCANNER_BIN"
+BIN="$AI_HARNESS_BIN"
 LOCK_FILE="/tmp/.ai-scanner-codex-init.lock"
 if [ -x "$BIN" ] && timeout 2 "$BIN" health >/dev/null 2>&1; then
   exit 0
@@ -919,7 +1129,7 @@ export const CODEX_PRE_SHELL_SH = `#!/bin/bash
 # Codex PreToolUse Bash hook: scan command and return block JSON to Codex.
 SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]:-$0}")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 CMD=$(jq -r '.tool_input.command // ""' <<<"$INPUT" 2>/dev/null)
@@ -949,7 +1159,7 @@ export const CODEX_POST_SHELL_SH = `#!/bin/bash
 # Codex PostToolUse Bash hook: scan command output and return feedback JSON.
 SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]:-$0}")" && pwd)"
 source "$SCRIPT_DIR/env.sh"
-BIN="$AI_SCANNER_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
+BIN="$AI_HARNESS_BIN"; [ ! -x "$BIN" ] && { note_unscanned; exit 0; }
 export AI_SCANNER_DETECTION_LOG
 INPUT=$(cat)
 CMD=$(jq -r '.tool_input.command // ""' <<<"$INPUT" 2>/dev/null)

package/src/toml-merge.mjs

@@ -1,14 +1,54 @@
 // Line-based TOML merger for Codex's ~/.codex/config.toml feature flag.
-// Codex requires `[features] codex_hooks = true` to activate hook dispatch.
+//
+// Codex requires `[features] hooks = true` to activate hook dispatch. The older
+// spelling `[features] codex_hooks = true` is a **deprecated alias**: Codex still
+// honours it, but prints
+//
+//   ⚠ `[features].codex_hooks` is deprecated. Use `[features].hooks` instead.
+//
+// on every start (issue #2367). So we write the canonical key and *migrate* any
+// legacy key we find, instead of leaving both around.
+//
 // Users may already have their own config (model settings, other features), so
 // we must merge rather than overwrite.
 //
-// Scope: *only* handles a single key inside a single section. No full TOML
-// parser, no external deps. Preserves comments, blank lines, ordering, and
+// Scope: *only* handles a single logical flag inside a single section. No full
+// TOML parser, no external deps. Preserves comments, blank lines, ordering, and
 // other sections exactly.
+//
+// ── Migration decision table (merge) ─────────────────────────────────
+// Only the *first* `[features]` section is considered (duplicate table headers
+// are invalid TOML anyway — see the known limitation at the bottom of this file).
+//
+//   old key | new key | result
+//   --------+---------+--------------------------------------------------------
+//   absent  | absent  | insert `hooks = true` right under the section header
+//   absent  | true    | no-op (byte-identical output)
+//   absent  | false   | value flipped to true, line position/comment preserved
+//   true    | absent  | line RENAMED in place -> `hooks = true`
+//                       (indentation, position and trailing comment preserved)
+//   false   | absent  | same rename, and the value is set to true
+//   any     | any     | the canonical `hooks` line wins and is set to true;
+//                       the deprecated `codex_hooks` line is REMOVED entirely.
+//                       This is the only case where a trailing comment can be
+//                       lost, because it is attached to the line we delete.
+//                       Conflicting values need no tie-break: setup means
+//                       "hooks on", so the result is always `hooks = true`.
+//
+// Standalone comment lines are never deleted, even when they sit directly above
+// a removed legacy key — deleting prose a user wrote is worse than leaving it.
+//
+// ── unmerge ──────────────────────────────────────────────────────────
+// Strips BOTH spellings, so a config written by an older aidr (legacy key) is
+// fully cleaned up by a newer aidr's uninstall. Everything else in `[features]`
+// (the user's own flags and comments) survives; the section header is dropped
+// only when nothing but blanks/comments would remain.
 
 const SECTION = "features";
-const KEY = "codex_hooks";
+// Canonical key. Codex >= the version that introduced `[features].hooks`.
+export const FEATURE_KEY = "hooks";
+// Deprecated alias still accepted by Codex, but it prints a warning (#2367).
+export const LEGACY_FEATURE_KEY = "codex_hooks";
 const VALUE = "true";
 
 // Match a section header line: optional leading whitespace, `[name]`, optional trailing comment.
@@ -20,10 +60,22 @@ function sectionHeader(name) {
 // Match any section header (used to find section boundaries).
 const ANY_SECTION_RE = /^\s*\[\s*[^\]]+\s*\](?:\s*#.*)?$/;
 
-// Match `key = value` with optional trailing comment; capture the value token.
+// Match `key = value` with optional trailing comment.
+// Groups: 1 = indent, 2 = key, 3 = ` = `, 4 = value token, 5 = trailing comment.
+// The `^\s*` anchor means the `hooks` matcher can never hit a `codex_hooks`
+// line (and vice versa) — the key must start the line after whitespace only.
 function keyAssignment(key) {
   const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return new RegExp(`^(\\s*${escaped}\\s*=\\s*)([^#\\n]*?)(\\s*(?:#.*)?)$`);
+  return new RegExp(`^(\\s*)(${escaped})(\\s*=\\s*)([^#\\n]*?)(\\s*(?:#.*)?)$`);
+}
+
+const CANONICAL_RE = keyAssignment(FEATURE_KEY);
+const LEGACY_RE = keyAssignment(LEGACY_FEATURE_KEY);
+
+// Rewrite a matched assignment line as `<indent>hooks<eq>true<trailing>`.
+function rewriteAsEnabled(line, re) {
+  const m = re.exec(line);
+  return `${m[1]}${FEATURE_KEY}${m[3]}${VALUE}${m[5]}`;
 }
 
 // Detect obvious malformed TOML so we fail closed instead of silently corrupting.
@@ -61,37 +113,64 @@ function findSectionRange(lines, section) {
   return { start, end };
 }
 
-// Merge `[features] codex_hooks = true` into the given TOML text, preserving
-// everything else. Idempotent: re-running on an already-merged file is a no-op.
+// Locate the first canonical / first legacy assignment inside a section range.
+function findKeys(lines, range) {
+  let canonical = -1;
+  let legacy = -1;
+  for (let i = range.start + 1; i < range.end; i++) {
+    if (canonical === -1 && CANONICAL_RE.test(lines[i])) canonical = i;
+    if (legacy === -1 && LEGACY_RE.test(lines[i])) legacy = i;
+  }
+  return { canonical, legacy };
+}
+
+// Merge `[features] hooks = true` into the given TOML text, migrating the
+// deprecated `codex_hooks` spelling and preserving everything else.
+// Idempotent: re-running on an already-merged file returns the input verbatim.
 export function mergeCodexHookFeature(text) {
   const input = text ?? "";
   if (input !== "") validate(input);
 
   // Empty file / whitespace-only: write a fresh minimal TOML.
   if (input.trim() === "") {
-    return `[${SECTION}]\n${KEY} = ${VALUE}\n`;
+    return `[${SECTION}]\n${FEATURE_KEY} = ${VALUE}\n`;
   }
 
   const lines = input.split("\n");
   // Preserve final newline state — JSON.stringify-style: if original ended with
   // "\n", .split gives a trailing "" element we'll keep and rejoin with.
   const range = findSectionRange(lines, SECTION);
-  const assignRe = keyAssignment(KEY);
 
   if (range) {
-    // Section exists — look for the key inside it.
-    for (let i = range.start + 1; i < range.end; i++) {
-      const m = assignRe.exec(lines[i]);
-      if (m) {
-        const currentValue = m[2].trim();
-        if (currentValue === VALUE) return input; // already correct, no-op
-        lines[i] = `${m[1]}${VALUE}${m[3]}`;      // overwrite `false` / other
-        return lines.join("\n");
-      }
+    const { canonical, legacy } = findKeys(lines, range);
+
+    if (canonical !== -1 && legacy !== -1) {
+      // Both spellings present. The canonical line wins (position + comment
+      // kept); the deprecated alias line goes away, which is what silences the
+      // warning. Conflicting values resolve to `true` because that is what this
+      // setup means.
+      lines[canonical] = rewriteAsEnabled(lines[canonical], CANONICAL_RE);
+      lines.splice(legacy, 1);
+      return lines.join("\n");
     }
+
+    if (legacy !== -1) {
+      // Legacy only — rename in place so ordering, indentation and any trailing
+      // comment survive. `codex_hooks = false` becomes `hooks = true`.
+      lines[legacy] = rewriteAsEnabled(lines[legacy], LEGACY_RE);
+      return lines.join("\n");
+    }
+
+    if (canonical !== -1) {
+      const m = CANONICAL_RE.exec(lines[canonical]);
+      if (m[4].trim() === VALUE) return input; // already correct, no-op
+      lines[canonical] = rewriteAsEnabled(lines[canonical], CANONICAL_RE);
+      return lines.join("\n");
+    }
+
     // Key absent — insert right after the section header (before any subkeys),
     // so the new line doesn't get buried under a long section.
-    lines.splice(range.start + 1, 0, `${KEY} = ${VALUE}`);
+    lines.splice(range.start + 1, 0, `${FEATURE_KEY} = ${VALUE}`);
     return lines.join("\n");
   }
 
@@ -100,12 +179,14 @@ export function mergeCodexHookFeature(text) {
   const needsLeadingBlank = input.length > 0 && !input.endsWith("\n\n");
   const prefix = input.endsWith("\n") ? "" : "\n";
   const spacer = needsLeadingBlank ? "\n" : "";
-  return `${input}${prefix}${spacer}[${SECTION}]\n${KEY} = ${VALUE}\n`;
+  return `${input}${prefix}${spacer}[${SECTION}]\n${FEATURE_KEY} = ${VALUE}\n`;
 }
 
-// Reverse of mergeCodexHookFeature: strip our `codex_hooks = true` line.
-// - Removes the key line.
-// - Removes an empty `[features]` section if our line was the only content.
+// Reverse of mergeCodexHookFeature: strip our feature flag line(s).
+// - Removes `hooks` AND the deprecated `codex_hooks` (a config written by an
+//   older aidr carries the legacy spelling; leaving it behind would keep the
+//   deprecation warning alive after uninstall).
+// - Removes an empty `[features]` section if our line(s) were the only content.
 // Returns { text, empty } — empty=true means the TOML is now effectively blank
 // so the caller can delete the file entirely.
 export function unmergeCodexHookFeature(text) {
@@ -120,17 +201,17 @@ export function unmergeCodexHookFeature(text) {
     return { text: input, empty: input.trim() === "" };
   }
 
-  const assignRe = keyAssignment(KEY);
-  let removedIdx = -1;
+  const removed = [];
   for (let i = range.start + 1; i < range.end; i++) {
-    if (assignRe.test(lines[i])) { removedIdx = i; break; }
+    if (CANONICAL_RE.test(lines[i]) || LEGACY_RE.test(lines[i])) removed.push(i);
   }
 
-  if (removedIdx === -1) {
+  if (removed.length === 0) {
     return { text: input, empty: input.trim() === "" };
   }
 
-  lines.splice(removedIdx, 1);
+  // Delete back-to-front so earlier indices stay valid.
+  for (let k = removed.length - 1; k >= 0; k--) lines.splice(removed[k], 1);
 
   // Re-evaluate the section bounds after removal.
   const newRange = findSectionRange(lines, SECTION);
@@ -165,3 +246,10 @@ export function unmergeCodexHookFeature(text) {
   const result = lines.join("\n");
   return { text: result, empty: result.trim() === "" };
 }
+
+// ── Known limitation (declared, not fixed) ───────────────────────────
+// Only the FIRST `[features]` table is inspected. A file with two `[features]`
+// headers is already invalid TOML (duplicate table), so Codex would reject it
+// before our flag mattered; handling it here would mean writing a real parser.
+// If such a file ever appears, a legacy key living in the second block would
+// survive the migration and the deprecation warning would persist.