throughline 0.16.22 → 0.16.23

package/CHANGELOG.md

@@ -10,6 +10,29 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [0.16.23] — 2026-10-11
+
+### 修正
+
+- **`install`と`self-update`が、Codexの信用済みのhookを「変わったhook」にしていた**（[ADR 0052](docs/adr/0052-install-keeps-registered-codex-hook-command.md)）。Codexのhookの命令は`<node> <throughline.mjs> codex-hook <event>`で、`<node>`の表記は入れる側のPATHで決まる（PATHの上に今のnodeと同じ実体があればその表記、無ければ`process.execPath`）。`install`はhookを毎回作り直すので、前と違うPATHで入れると、同じnodeを指したまま文字列だけが変わった。Codexはhookの信用を命令の文字列で決めるので、Throughlineのhookが4つとも`modified`になり、新しい会話が起動の所で「Hooks need review」を出して、人が選ぶまで止まった。
+  - Linuxの実機で2026-10-11に起きた。09:20に`~/.local/bin`をPATHの先頭に付けて`self-update`を流し、`~/.local/lib/node-v24/bin/node`が、同じ実体を指すsymlinkの`~/.local/bin/node`に変わった。15:05に、常駐のprocessが立てるCodexの会話がそこで止まっていると知らせを受けた。
+  - 直した後は、登録済みの命令が今のnodeと`throughline.mjs`の実体（realpath）を指している時、その文字列のまま書く。`auto-handoff enable`が置く`PreCompact`も同じ。登録が無い時、旧い形の時、nodeかscriptの実体が違う時は、今までどおり書き直す。
+  - nodeの実体が変わった時（別の版の場所へ入れ直した時など）は命令が変わり、Codexは確認の画面を出す。これは変えていない。
+
+### 対応の範囲
+
+| | macOS | Linux | Windows |
+|---|---|---|---|
+| Codex | 直した。単体試験と、実機（Codex Desktop同梱の0.162.0-alpha.17.2）。仮のHOMEとCODEX_HOMEでhookを信用し、PATHだけ変えて入れ直すと、入っていた0.16.22は4つとも`modified`、この版は4つとも`trusted`で`hooks.json`は1バイトも変わらない | 直した。単体試験と、実機（codex-cli 0.162.1）で同じ確認 | 直した。単体試験（表記の違いは大文字と小文字で作る）と、実機（Codex Desktop同梱の0.162.0-alpha.17.2）で同じ確認 |
+| Claude Code | 変更なし（hookの命令は`throughline <subcommand>`で、nodeの場所が入らない） | 同じ | 同じ |
+| Grok | 変更なし。命令には同じ決め方でnodeの表記が入り、入れる側のPATHで変わる。Grokがhookの変更で確認を出すかは確かめていない | 同じ | 同じ |
+| Cursor | 変更なし。Grokと同じ | 同じ | 同じ |
+
+### 確かめていない事
+
+- 本物の`~/.codex`で、信用済みのhookを持つ端末へこの版を違うPATHから入れる所。確認は、仮のHOMEとCODEX_HOMEで、本物のCodexのApp Server（`hooks/list`）に信用の状態を聞く形で行った。
+- `doctor --codex`の「trusted」は、`trusted_hash`が記録されているかだけを見ている。Codexが今の命令と比べた結果は見ていないので、`modified`でも「trusted」と出る。この版では変えていない。
+
 ## [0.16.22] — 2026-10-11
 
 ### 変更
@@ -2378,7 +2401,8 @@ two attempts, instrument first instead of patching again.
 
 ---
 
-[Unreleased]: https://github.com/kitepon/Throughline/compare/v0.16.22...HEAD
+[Unreleased]: https://github.com/kitepon/Throughline/compare/v0.16.23...HEAD
+[0.16.23]: https://github.com/kitepon/Throughline/compare/v0.16.22...v0.16.23
 [0.16.22]: https://github.com/kitepon/Throughline/compare/v0.16.21...v0.16.22
 [0.16.21]: https://github.com/kitepon/Throughline/compare/v0.16.20...v0.16.21
 [0.16.20]: https://github.com/kitepon/Throughline/compare/v0.16.19...v0.16.20

package/docs/adr/0052-install-keeps-registered-codex-hook-command.md

@@ -0,0 +1,42 @@
+# ADR 0052: install は、今の node を指す登録済みの Codex hook の命令を書き換えない
+
+- Status: Accepted
+- Date: 2026-10-11
+
+## Context
+
+Codex は、hook を1つずつ信用の対象にする。信用は `config.toml` の `hooks.state."<hooks.json>:<event>:<group>:<hook>".trusted_hash`
+に残り、hook の定義（命令の文字列を含む）から作った hash と比べる。hash が違う hook は「変わった hook」（`modified`）になり、
+新しい会話は起動の所で「Hooks need review」の画面を出して、人が選ぶまで止まる。
+
+Throughline の Codex hook の命令は `<node> <throughline.mjs> codex-hook <event>` で、`<node>` は
+`resolveCodexHookNodePath` が決める。PATH の上に今の node と同じ実体があればその表記、無ければ `process.execPath`。
+Homebrew の node を版ごとの場所（Cellar）で登録しないための決め方だが、同じ端末でも、入れる側の PATH で表記が変わる。
+
+2026-10-11、Linux の実機で、`~/.local/bin` を PATH の先頭に付けて `self-update` を流した。それまで
+`~/.local/lib/node-v24/bin/node` だった表記が、同じ実体を指す symlink の `~/.local/bin/node` に変わった。
+Throughline の hook は4つとも `modified` になり、新しい Codex の会話が確認の画面で止まった。常駐の process が
+立てる会話も、そこで止まった。
+
+`install` は、Throughline の hook を毎回作り直して書いていた。`doctor` と `factory-diagnostics` は、登録済みの命令と
+期待する命令を実体（realpath）で比べるので、表記が違っても「登録済み」と出す。`install` だけが、文字列で置き換えていた。
+
+## Decision
+
+1. `install` と `auto-handoff enable` は、登録済みの Throughline の Codex hook の命令が、期待する命令と同じ実体
+   （node と `throughline.mjs` の realpath、event）を指している時、その文字列のまま書く。
+2. 登録が無い時、旧い形の時、node か script の実体が違う時（realpath を解決できない時を含む）は、今までどおり
+   期待する命令で書く。
+3. 表記を「より安定した物」へ寄せるための書き換えはしない。
+
+## Consequences
+
+- 入れる側の PATH が変わっても、同じ node を使っている間は、Codex の信用が残る。
+- node の実体が変わった時（別の版の場所へ入れ直した時など）は命令が変わり、Codex は確認の画面を出す。これは避けない。
+  命令が指す実行ファイルが変わった事を、利用者が確かめる場面だから。
+- 版ごとの場所（Homebrew の Cellar など）で登録された命令は、その場所が残っている間はそのまま残る。場所が消えた後の
+  `install` で、期待する命令へ書き直す。その間 hook は失敗する。`doctor` と `factory-diagnostics` は、実体を
+  解決できない登録を「登録済み」と見ないので、そこで分かる。
+- `doctor --codex` の「trusted」は、`trusted_hash` が記録されているかだけを見ている。Codex が今の命令と比べた結果
+  （`trusted`・`modified`・`untrusted`）は、Codex の App Server の `hooks/list` でしか分からない。この ADR では変えない。
+- Grok と Cursor の hook の命令も同じ決め方で node の表記が入るが、この ADR では変えない。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "throughline",
-  "version": "0.16.22",
+  "version": "0.16.23",
   "type": "module",
   "description": "Persistent memory hooks for Claude Code, Codex, Grok, and Cursor (/clear-safe context compression)",
   "keywords": [

package/src/cli/install.mjs

@@ -250,15 +250,25 @@ function isSameExecutablePath(a, b, realpath) {
   return left !== null && right !== null && left === right;
 }
 
-function createCodexHooks() {
+// 登録済みの命令が今の node と script の実体を指している時は、その文字列のまま返す（ADR 0052）。
+// node の表記は入れる側の PATH で変わる。Codex は hook の信用を命令の文字列で決めるので、表記だけを書き換えると
+// 信用済みの hook が「変わった hook」になり、新しい会話が確認の画面で止まる。
+function registeredCodexHookCommand(expected, groups) {
+  const registered = (Array.isArray(groups) ? groups : []).flatMap(group => group?.hooks ?? []).map(hook => hook?.command)
+    .find(command => isEquivalentCodexHookCommand(command, expected));
+  return registered ?? expected;
+}
+
+function createCodexHooks(registered = {}) {
+  const command = (event, expected) => registeredCodexHookCommand(expected, registered?.[event]);
   return {
-    PreCompact: { matcher: 'auto', hooks: [{ type: 'command', command: buildCodexPreCompactHookCommand(),
+    PreCompact: { matcher: 'auto', hooks: [{ type: 'command', command: command('PreCompact', buildCodexPreCompactHookCommand()),
       timeout: 30, async: false, statusMessage: 'Throughline: 自動継続を準備' }] },
     UserPromptSubmit: {
       hooks: [
         {
           type: 'command',
-          command: buildCodexUserPromptSubmitHookCommand(),
+          command: command('UserPromptSubmit', buildCodexUserPromptSubmitHookCommand()),
           timeout: 30,
           async: false,
           statusMessage: null,
@@ -269,7 +279,7 @@ function createCodexHooks() {
       hooks: [
         {
           type: 'command',
-          command: buildCodexPostToolUseHookCommand(),
+          command: command('PostToolUse', buildCodexPostToolUseHookCommand()),
           timeout: 30,
           async: false,
           statusMessage: null,
@@ -280,7 +290,7 @@ function createCodexHooks() {
       hooks: [
         {
           type: 'command',
-          command: buildCodexStopHookCommand(),
+          command: command('Stop', buildCodexStopHookCommand()),
           timeout: 300,
           async: false,
           statusMessage: null,
@@ -628,7 +638,7 @@ function installCodexHooks() {
   const configPath = resolveCodexConfigPath();
   const current = readSettings(hooksPath);
   const existingHooks = current.hooks ?? {};
-  const codexHooks = createCodexHooks();
+  const codexHooks = createCodexHooks(existingHooks);
 
   for (const [key, entry] of Object.entries(codexHooks)) {
     const list = existingHooks[key] ?? [];
@@ -705,7 +715,7 @@ export function installCodexAutoHandoffHook(codexHome = join(homedir(), '.codex'
   const configPath = join(codexHome, 'config.toml');
   const current = readSettings(hooksPath);
   current.hooks ??= {};
-  const entry = createCodexHooks().PreCompact;
+  const entry = createCodexHooks(current.hooks).PreCompact;
   const groups = current.hooks.PreCompact ?? [];
   const existing = groups.flatMap(group => group.hooks ?? []).filter(hook => isThroughlineCodexHookCommand(hook.command));
   if (existing.length !== 1 || existing[0].command !== entry.hooks[0].command || existing[0].timeout !== 30) {

package/src/cli/install.test.mjs

@@ -1,17 +1,19 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync, mkdirSync, symlinkSync, realpathSync } from 'node:fs';
 import { tmpdir, homedir } from 'node:os';
 import { join } from 'node:path';
 
 import {
   buildCodexPostToolUseHookCommand,
+  buildCodexPreCompactHookCommand,
   buildCodexStopHookCommand,
   buildCodexUserPromptSubmitHookCommand,
   buildCursorHookCommand,
   buildGrokHookCommand,
   createGrokHooksFile,
   createCursorHookEntries,
+  installCodexAutoHandoffHook,
   isEquivalentCodexHookCommand,
   isThroughlineCodexHookCommand,
   isThroughlineCursorHookCommand,
@@ -855,3 +857,94 @@ test('install is idempotent: second run keeps exactly one tl.md and one hook ent
     home.restore();
   }
 });
+
+// 今の node を指す、別の表記。POSIX は symlink、Windows は大文字と小文字を入れ替えた path（どちらも realpath が同じになる）。
+function alternateNodeSpelling(dir) {
+  if (process.platform === 'win32') {
+    const upper = process.execPath.toUpperCase();
+    return upper !== process.execPath ? upper : process.execPath.toLowerCase();
+  }
+  mkdirSync(join(dir, 'altbin'), { recursive: true });
+  const link = join(dir, 'altbin', 'node');
+  symlinkSync(realpathSync.native(process.execPath), link);
+  return link;
+}
+
+test('install は、今の node を指す登録済みの Codex hook の命令を書き換えない（Codex の信用を保つ）', async () => {
+  const home = makeTempHome();
+  if (home.resolved !== home.dir) {
+    home.restore();
+    return;
+  }
+  const unsilence = silence();
+  try {
+    const hooksPath = join(home.dir, '.codex', 'hooks.json');
+    await run([]);
+    const nodePath = alternateNodeSpelling(home.dir);
+    const registered = {
+      PreCompact: buildCodexPreCompactHookCommand({ nodePath }),
+      UserPromptSubmit: buildCodexUserPromptSubmitHookCommand({ nodePath }),
+      PostToolUse: buildCodexPostToolUseHookCommand({ nodePath }),
+      Stop: buildCodexStopHookCommand({ nodePath }),
+    };
+    assert.notEqual(registered.Stop, buildCodexStopHookCommand({ nodePath: process.execPath }));
+    // ほかの PATH から入れた時の登録を作る。node の表記だけが違い、指す実体は同じ。
+    const file = JSON.parse(readFileSync(hooksPath, 'utf8'));
+    for (const [event, command] of Object.entries(registered)) {
+      const own = file.hooks[event].flatMap(group => group.hooks).filter(hook => isThroughlineCodexHookCommand(hook.command));
+      assert.equal(own.length, 1);
+      own[0].command = command;
+    }
+    file.hooks.Stop.push({ hooks: [{ type: 'command', command: '/usr/bin/node /opt/other/bin/other codex-hook stop', timeout: 5 }] });
+    const before = JSON.stringify(file, null, 2) + '\n';
+    writeFileSync(hooksPath, before);
+
+    await run([]);
+    assert.equal(readFileSync(hooksPath, 'utf8'), before);
+    const autoHandoff = installCodexAutoHandoffHook(join(home.dir, '.codex'));
+    assert.equal(autoHandoff.command, registered.PreCompact);
+    assert.equal(readFileSync(hooksPath, 'utf8'), before);
+
+    // 登録済みの node が今の node でない時は、今までどおり書き直す。
+    const moved = JSON.parse(before);
+    moved.hooks.Stop[0].hooks[0].command = buildCodexStopHookCommand({ nodePath: join(home.dir, 'gone', 'node') });
+    writeFileSync(hooksPath, JSON.stringify(moved, null, 2) + '\n');
+    await run([]);
+    const after = JSON.parse(readFileSync(hooksPath, 'utf8'));
+    assert.equal(after.hooks.Stop[0].hooks[0].command, buildCodexStopHookCommand());
+    assert.equal(after.hooks.UserPromptSubmit[0].hooks[0].command, registered.UserPromptSubmit);
+    assert.equal(after.hooks.PostToolUse[0].hooks[0].command, registered.PostToolUse);
+    assert.equal(after.hooks.PreCompact.at(-1).hooks[0].command, registered.PreCompact);
+  } finally {
+    unsilence();
+    home.restore();
+  }
+});
+
+test('install は、入れる側の PATH が変わっても Codex hook の命令を変えない', { skip: process.platform === 'win32' }, async () => {
+  const home = makeTempHome();
+  if (home.resolved !== home.dir) {
+    home.restore();
+    return;
+  }
+  const originalPath = process.env.PATH;
+  const unsilence = silence();
+  try {
+    const hooksPath = join(home.dir, '.codex', 'hooks.json');
+    const nodePath = alternateNodeSpelling(home.dir);
+    // node の symlink がある場所を PATH の先頭に置いて入れ、次は PATH に node が無い状態で入れる。
+    process.env.PATH = join(home.dir, 'altbin');
+    await run([]);
+    const first = readFileSync(hooksPath, 'utf8');
+    assert.equal(JSON.parse(first).hooks.Stop[0].hooks[0].command, buildCodexStopHookCommand({ nodePath }));
+    process.env.PATH = '';
+    assert.notEqual(buildCodexStopHookCommand(), buildCodexStopHookCommand({ nodePath }));
+    await run([]);
+    assert.equal(readFileSync(hooksPath, 'utf8'), first);
+  } finally {
+    if (originalPath === undefined) delete process.env.PATH;
+    else process.env.PATH = originalPath;
+    unsilence();
+    home.restore();
+  }
+});