@basou/cli 0.49.0 → 0.51.0

package/dist/index.js

@@ -866,6 +866,7 @@ import {
   basouPaths as basouPaths4,
   classifyFilesBySourceRoot,
   createAdHocSessionWithEvent,
+  displayPath,
   EVENT_SCHEMA_VERSION as EVENT_SCHEMA_VERSION2,
   findErrorCode as findErrorCode2,
   isValidPrefixedId,
@@ -1305,7 +1306,7 @@ async function warnLinkedFilesOutsideRoots(input) {
     });
     if (scope.outOfRoot.length === 0) return;
     const PATH_SAMPLE = 5;
-    const sample = scope.outOfRoot.slice(0, PATH_SAMPLE).join(", ");
+    const sample = scope.outOfRoot.slice(0, PATH_SAMPLE).map(displayPath).join(", ");
     const more = scope.outOfRoot.length > PATH_SAMPLE ? ` (... +${scope.outOfRoot.length - PATH_SAMPLE} more)` : "";
     console.error(
       `basou: ${scope.outOfRoot.length} linked file(s) resolve outside this project's source_roots: ${sample}${more} \u2014 this decision may belong to another project.`
@@ -2474,6 +2475,9 @@ import {
   evaluateStopHook,
   findBasouSessionStartHook,
   findBasouStopHookCommand,
+  findClaudeSessionStartHooks,
+  findUnrecognizedSessionStart,
+  isClaudeSessionStartMalformed,
   isProtocolUpdateDue,
   ORIENTATION_END as ORIENTATION_END2,
   ORIENTATION_START as ORIENTATION_START2,
@@ -2488,10 +2492,12 @@ import {
   readManifest as readManifest5,
   readMarkdownFile as readMarkdownFile6,
   recordSessionBaseline,
+  removeClaudeSessionStartHook,
   removeSessionStartHook,
   removeStopHook,
   renderProtocolUpdate,
   transcriptStartedAt,
+  upsertClaudeSessionStartHook,
   upsertSessionStartHook,
   upsertStopHook
 } from "@basou/core";
@@ -2913,6 +2919,7 @@ import {
   classifyFilesBySourceRoot as classifyFilesBySourceRoot2,
   claudeTranscriptToImportPayload,
   codexRolloutToImportPayload,
+  displayPath as displayPath2,
   enumerateSessionDirs,
   findErrorCode as findErrorCode5,
   importSessionFromJson,
@@ -3183,7 +3190,7 @@ async function importDerivedSessions(paths, manifest, options, sourceKind, candi
   if (crossProject.length > 0) {
     const PATH_SAMPLE = 5;
     for (const { externalId, outOfRoot } of crossProject) {
-      const sample = outOfRoot.slice(0, PATH_SAMPLE).join(", ");
+      const sample = outOfRoot.slice(0, PATH_SAMPLE).map(displayPath2).join(", ");
       const more = outOfRoot.length > PATH_SAMPLE ? ` (... +${outOfRoot.length - PATH_SAMPLE} more)` : "";
       console.error(
         `basou: session ${externalId} edited ${outOfRoot.length} file(s) outside this project's source_roots: ${sample}${more} \u2014 they may belong to another project.`
@@ -3842,11 +3849,14 @@ function registerHookCommand(program2) {
     });
   });
   hook.command("install [target]").description(
-    "Register a basou hook (reproducible, idempotent). Target `claude` (default): the Stop hook in ~/.claude/settings.json \u2014 advisory capture-only by default; --block opts into in-turn enforcement, --require-review into the review gate. Target `codex`: the SessionStart hook in ~/.codex/hooks.json, which hands each Codex session the position of the workspace it was opened in. Codex asks you to review and trust a new hook once before it runs."
+    "Register a basou hook (reproducible, idempotent). Target `claude` (default): the Stop hook and the SessionStart hook in ~/.claude/settings.json. The Stop hook is advisory capture-only by default; --block opts into in-turn enforcement, --require-review into the review gate. The SessionStart hook hands each session the workspace's position and records the git baseline the Stop hook measures the session's file changes against; --no-session-start leaves it out. Target `codex`: the SessionStart hook in ~/.codex/hooks.json, which hands each Codex session the position of the workspace it was opened in. Codex asks you to review and trust a new hook once before it runs."
   ).option(
     "--block",
     "claude: register the blocking (opt-in enforcement) form instead of advisory"
-  ).option("--require-review", "claude: register with the opt-in review gate enabled").option("--min-edits <n>", "claude: pass a custom file-edit threshold to the registered hook").option("--settings <path>", "claude: override the settings.json path (intended for tests)").option("--hooks <path>", "codex: override the hooks.json path (intended for tests)").option(
+  ).option("--require-review", "claude: register with the opt-in review gate enabled").option("--min-edits <n>", "claude: pass a custom file-edit threshold to the registered hook").option(
+    "--no-session-start",
+    "claude: register the Stop hook only, and leave any SessionStart hook as it is"
+  ).option("--settings <path>", "claude: override the settings.json path (intended for tests)").option("--hooks <path>", "codex: override the hooks.json path (intended for tests)").option(
     "--codex-config <path>",
     "codex: override the Codex config.toml path (intended for tests)"
   ).option(
@@ -3855,11 +3865,23 @@ function registerHookCommand(program2) {
   ).option("--dry-run", "Print what would change without writing").option("-v, --verbose", "Show error causes").action(async (target, opts) => {
     await dispatchHookTarget(target, opts, {
       claude: () => runHookInstall(opts),
-      codex: () => runCodexHookInstall(opts)
+      codex: async () => {
+        if (opts.sessionStart === false) {
+          renderCliError(
+            new Error(
+              "--no-session-start applies to target claude only; the Codex hook is itself a SessionStart hook."
+            ),
+            { verbose: isVerbose(opts) }
+          );
+          process.exitCode = 1;
+          return;
+        }
+        await runCodexHookInstall(opts);
+      }
     });
   });
   hook.command("uninstall [target]").description(
-    "Remove a basou hook, leaving other hooks intact. Target `claude` (default): the Stop hook in ~/.claude/settings.json. Target `codex`: the SessionStart hook in ~/.codex/hooks.json."
+    "Remove a basou hook, leaving other hooks intact. Target `claude` (default): the Stop hook and the SessionStart hook in ~/.claude/settings.json. Target `codex`: the SessionStart hook in ~/.codex/hooks.json."
   ).option("--settings <path>", "claude: override the settings.json path (intended for tests)").option("--hooks <path>", "codex: override the hooks.json path (intended for tests)").option("--dry-run", "Print what would change without writing").option("-v, --verbose", "Show error causes").action(async (target, opts) => {
     await dispatchHookTarget(target, opts, {
       claude: () => runHookUninstall(opts),
@@ -3867,7 +3889,7 @@ function registerHookCommand(program2) {
     });
   });
   hook.command("status [target]").description(
-    "Report whether a basou hook is registered. Target `claude` (default): the Stop hook and its mode. Target `codex`: the SessionStart hook, and whether Codex has trusted it yet."
+    "Report whether a basou hook is registered. Target `claude` (default): the Stop hook and its mode, and the SessionStart hook. Target `codex`: the SessionStart hook, and whether Codex has trusted it yet."
   ).option("--settings <path>", "claude: override the settings.json path (intended for tests)").option("--hooks <path>", "codex: override the hooks.json path (intended for tests)").option(
     "--codex-config <path>",
     "codex: override the Codex config.toml path (intended for tests)"
@@ -3915,9 +3937,11 @@ becomes the session's trusted context, so it withholds the position instead.
 Run 'basou refresh' to see which lines are responsible.
 
 Claude Code's SessionStart hook sends the same kind of payload (a JSON object
-with 'cwd') and adds stdout to context the same way, so a Claude Code user may
-register this command in ~/.claude/settings.json in place of 'basou orient' to
-get both gates. basou does not install that one.
+with 'cwd') and adds stdout to context the same way. 'basou hook install'
+registers this command there too, in ~/.claude/settings.json, and replaces a
+hand-registered 'basou orient' SessionStart hook with it. In Claude Code it also
+records where each declared repository stood when the session started, which is
+what the Stop hook measures the session's file changes against.
 
 Codex trusts hooks by hash. A newly installed or changed hook is skipped until
 you review it: the interactive CLI asks at startup ("Hooks need review"), the
@@ -4231,6 +4255,7 @@ function normalizeInstallOptions(raw) {
   const out = {};
   if (raw.block === true) out.block = true;
   if (raw.requireReview === true) out.requireReview = true;
+  if (raw.sessionStart === false) out.noSessionStart = true;
   if (raw.settings !== void 0) out.settings = raw.settings;
   if (raw.hooks !== void 0) out.hooks = raw.hooks;
   if (raw.codexConfig !== void 0) out.codexConfig = raw.codexConfig;
@@ -4302,15 +4327,32 @@ async function doRunHookInstall(options, ctx = {}) {
   });
   await assertNotSymlink(settingsPath);
   const { raw, parsed } = await readSettings(settingsPath);
-  const { settings, action } = upsertStopHook(parsed, command);
-  const newBody = `${JSON.stringify(settings, null, 2)}
-`;
-  if (raw !== null && newBody === raw) {
-    console.log(`The basou Stop hook is already registered (${mode}); no change.`);
-    return;
+  const stop = upsertStopHook(parsed, command);
+  let sessionStart;
+  if (options.noSessionStart === true) {
+    sessionStart = { kind: "skipped" };
+  } else {
+    try {
+      const upsert = upsertClaudeSessionStartHook(
+        stop.settings,
+        buildSessionStartHookCommand({ cliEntry })
+      );
+      sessionStart = { kind: "done", action: upsert.action, settings: upsert.settings };
+    } catch (error) {
+      if (!isClaudeSessionStartMalformed(stop.settings)) throw error;
+      sessionStart = { kind: "malformed" };
+    }
   }
-  if (options.dryRun === true) {
-    console.log(`[dry-run] Would ${action} the basou Stop hook (${mode}).`);
+  const settings = sessionStart.kind === "done" ? sessionStart.settings : stop.settings;
+  const changed = stop.action !== "unchanged" || sessionStart.kind === "done" && sessionStart.action !== "unchanged";
+  const dryRun = options.dryRun === true;
+  const lines = [
+    describeStopInstall(stop.action, mode, dryRun),
+    describeSessionStartInstall(sessionStart, dryRun),
+    ...describeSessionStartLeftovers(settings)
+  ];
+  if (!changed || dryRun) {
+    for (const line of lines) console.log(line);
     return;
   }
   const recheck = await readSettings(settingsPath);
@@ -4320,8 +4362,55 @@ async function doRunHookInstall(options, ctx = {}) {
     );
   }
   await backupSettingsOnce(settingsPath, raw);
-  await writeFileDurable(settingsPath, newBody);
-  console.log(`${action === "installed" ? "Installed" : "Updated"} the basou Stop hook (${mode}).`);
+  await writeFileDurable(settingsPath, `${JSON.stringify(settings, null, 2)}
+`);
+  for (const line of lines) console.log(line);
+}
+function describeStopInstall(action, mode, dryRun) {
+  if (action === "unchanged") {
+    return `The basou Stop hook is already registered (${mode}); no change.`;
+  }
+  if (dryRun) {
+    return `[dry-run] Would ${action === "installed" ? "install" : "update"} the basou Stop hook (${mode}).`;
+  }
+  return `${action === "installed" ? "Installed" : "Updated"} the basou Stop hook (${mode}).`;
+}
+function describeSessionStartInstall(outcome, dryRun) {
+  if (outcome.kind === "skipped") {
+    return "The SessionStart hook was left as it is (--no-session-start).";
+  }
+  if (outcome.kind === "malformed") {
+    return "The basou SessionStart hook was NOT installed: 'hooks.SessionStart' in settings.json is not a list of hook groups. Fix it and re-run 'basou hook install'.";
+  }
+  const action = outcome.action;
+  if (action === "unchanged") {
+    return "The basou SessionStart hook is already registered; no change.";
+  }
+  const prefix = dryRun ? "[dry-run] Would " : "";
+  if (action === "replaced") {
+    return `${prefix}${dryRun ? "replace" : "Replaced"} the hand-registered 'basou orient' SessionStart hook with 'basou hook session-start': the same position, plus the baseline the Stop hook measures the session's file changes against. It differs in three ways: it speaks only for a workspace registered in ~/.basou/portfolio.yaml, it does not rewrite .basou/orientation.md at session start, and it stays silent when the position names another registered workspace.`;
+  }
+  if (action === "updated") {
+    return `${prefix}${dryRun ? "update" : "Updated"} the basou SessionStart hook.`;
+  }
+  return `${prefix}${dryRun ? "install" : "Installed"} the basou SessionStart hook: each session gets the workspace's position, and the Stop hook can see the files the session changes through the shell.`;
+}
+function describeSessionStartLeftovers(settings) {
+  const own = findClaudeSessionStartHooks(settings);
+  if (own.length === 0) return [];
+  const lines = [];
+  for (const other of findUnrecognizedSessionStart(settings)) {
+    lines.push(
+      `note: this SessionStart hook runs basou '${other.runs === "orient" ? "orient" : "hook session-start"}' inside a longer command, so it was left as written, and a session may receive the position twice: ${other.command}`
+    );
+  }
+  if (own.length > 1) {
+    const matchers = own.map((o) => o.matcher ?? "(every source)").join(", ");
+    lines.push(
+      `note: ${own.length} basou SessionStart hooks remain, under different matchers (${matchers}). They were kept so that no session source stops firing; a source that more than one matches receives the position twice. Remove the one you do not want by hand.`
+    );
+  }
+  return lines;
 }
 async function runHookUninstall(options) {
   try {
@@ -4339,15 +4428,22 @@ async function doRunHookUninstall(options) {
     console.log("No settings.json; nothing to remove.");
     return;
   }
-  const { settings, action } = removeStopHook(parsed);
-  if (action === "absent") {
-    console.log("No basou Stop hook found; nothing removed.");
+  const stop = removeStopHook(parsed);
+  const sessionStart = removeClaudeSessionStartHook(stop.settings);
+  if (stop.action === "absent" && sessionStart.action === "absent") {
+    console.log("No basou Stop hook or SessionStart hook found; nothing removed.");
     return;
   }
-  const newBody = `${JSON.stringify(settings, null, 2)}
+  const newBody = `${JSON.stringify(sessionStart.settings, null, 2)}
 `;
+  const removedNames = [
+    ...stop.action === "removed" ? ["Stop hook"] : [],
+    ...sessionStart.action === "removed" ? ["SessionStart hook"] : []
+  ];
   if (options.dryRun === true) {
-    console.log("[dry-run] Would remove the basou Stop hook from settings.json.");
+    for (const name of removedNames) {
+      console.log(`[dry-run] Would remove the basou ${name} from settings.json.`);
+    }
     return;
   }
   const recheck = await readSettings(settingsPath);
@@ -4358,7 +4454,9 @@ async function doRunHookUninstall(options) {
   }
   await backupSettingsOnce(settingsPath, raw);
   await writeFileDurable(settingsPath, newBody);
-  console.log("Removed the basou Stop hook from settings.json.");
+  for (const name of removedNames) {
+    console.log(`Removed the basou ${name} from settings.json.`);
+  }
 }
 async function runHookStatus(options) {
   try {
@@ -4374,14 +4472,49 @@ async function doRunHookStatus(options) {
   const command = findBasouStopHookCommand(parsed);
   if (command === null) {
     console.log("basou Stop hook: not registered. Run 'basou hook install' to register it.");
+  } else {
+    const mode = describeHookMode({
+      block: / --block\b/.test(command),
+      review: / --require-review\b/.test(command)
+    });
+    console.log(`basou Stop hook: registered, ${mode}.`);
+    await reportHookEntryBuild(command);
+  }
+  reportSessionStartStatus(parsed);
+}
+function reportSessionStartStatus(parsed) {
+  if (isClaudeSessionStartMalformed(parsed)) {
+    console.log(
+      "basou SessionStart hook: cannot tell -- 'hooks.SessionStart' in settings.json is not a list of hook groups."
+    );
     return;
   }
-  const mode = describeHookMode({
-    block: / --block\b/.test(command),
-    review: / --require-review\b/.test(command)
-  });
-  console.log(`basou Stop hook: registered, ${mode}.`);
-  await reportHookEntryBuild(command);
+  const own = findClaudeSessionStartHooks(parsed);
+  const others = findUnrecognizedSessionStart(parsed);
+  for (const hook of own.filter((o) => o.kind === "session-start")) {
+    console.log(`basou SessionStart hook: registered, fires ${describeFiring(hook.matcher)}.`);
+  }
+  for (const hook of own.filter((o) => o.kind === "orient")) {
+    console.log(
+      `basou SessionStart hook: 'basou orient' registered by hand, fires ${describeFiring(hook.matcher)}. It delivers the position but records no git baseline, so the files a session changes through the shell are not observed; 'basou hook install' replaces it with 'basou hook session-start'.`
+    );
+  }
+  if (own.length === 0) {
+    if (others.length === 0) {
+      console.log(
+        "basou SessionStart hook: not registered. Sessions get no position at start, and the files a session changes through the shell are not observed. Run 'basou hook install' to register it."
+      );
+    }
+    for (const other of others) {
+      console.log(
+        other.runs === "orient" ? `basou SessionStart hook: not registered by basou. A SessionStart hook runs 'basou orient' inside a longer command, so sessions may get the position, but no git baseline is recorded: ${other.command}` : `basou SessionStart hook: not registered by basou. A SessionStart hook runs 'basou hook session-start' inside a longer command, which basou leaves as written: ${other.command}`
+      );
+    }
+  }
+  for (const line of describeSessionStartLeftovers(parsed)) console.log(line);
+}
+function describeFiring(matcher) {
+  return matcher === void 0 || matcher === "" || matcher === "*" ? "on every session source" : `on ${matcher}`;
 }
 async function reportHookEntryBuild(command) {
   console.log(`  this basou is: ${BASOU_VERSION_LINE}`);
@@ -9789,6 +9922,7 @@ import {
   appendEventToExistingSession as appendEventToExistingSession3,
   assertBasouRootSafe as assertBasouRootSafe13,
   basouPaths as basouPaths18,
+  displayPath as displayPath3,
   EVENT_SCHEMA_VERSION as EVENT_SCHEMA_VERSION6,
   enumerateSessionDirs as enumerateSessionDirs2,
   findErrorCode as findErrorCode12,
@@ -10057,7 +10191,7 @@ function formatWorkingDir(workingDir, repositoryRoot, options) {
 }
 function formatRelatedFiles(files) {
   if (files.length === 0) return "0 paths";
-  const head = files.slice(0, 3).join(", ");
+  const head = files.slice(0, 3).map(displayPath3).join(", ");
   const remaining = files.length - 3;
   if (remaining <= 0) return `${files.length} paths (${head})`;
   return `${files.length} paths (${head}, ... +${remaining} more)`;
@@ -10085,7 +10219,7 @@ function eventVariantSummary(ev) {
     case "git_snapshot":
       return `branch=${ev.branch} dirty=${ev.dirty}`;
     case "file_changed":
-      return `${ev.change_type} ${ev.path}`;
+      return `${ev.change_type} ${displayPath3(ev.path)}`;
     case "session_status_changed":
       return `${ev.from} -> ${ev.to}`;
     case "session_started":
@@ -13037,6 +13171,25 @@ var VIEW_HTML = `<!doctype html>
       detail.appendChild(tl);
     }).catch(fail);
   }
+  // The page cannot import @basou/core, so this mirrors its displayPath: a
+  // recorded name is shown with its control characters as visible escapes, so a
+  // newline in it does not read as a space and an invisible one stays visible.
+  // A test lifts this function and checks it agrees with displayPath.
+  function showPath(p) {
+    var out = '';
+    for (var i = 0; i < p.length; i++) {
+      var c = p.charCodeAt(i);
+      var acting = c <= 0x1f || (c >= 0x7f && c <= 0x9f) || c === 0x2028 || c === 0x2029 ||
+        (c >= 0x202a && c <= 0x202e) || (c >= 0x2066 && c <= 0x2069);
+      if (!acting) { out += p.charAt(i); continue; }
+      if (c === 10) out += '\\\\n';
+      else if (c === 13) out += '\\\\r';
+      else if (c === 9) out += '\\\\t';
+      else if (c <= 0xff) out += '\\\\x' + ('0' + c.toString(16)).slice(-2);
+      else out += '\\\\u' + ('000' + c.toString(16)).slice(-4);
+    }
+    return out;
+  }
   function eventSummary(ev) {
     if (ev.type === 'command_executed') {
       var cmd = (ev.args && ev.args.length) ? ev.args.join(' ') : ev.command;
@@ -13044,7 +13197,7 @@ var VIEW_HTML = `<!doctype html>
       var ex = (ev.exit_code === null || ev.exit_code === undefined) ? '' : ' (exit ' + ev.exit_code + ')';
       return cmd + ex;
     }
-    if (ev.type === 'file_changed') return ev.path + ' [' + ev.change_type + ']';
+    if (ev.type === 'file_changed') return showPath(ev.path) + ' [' + ev.change_type + ']';
     if (ev.type === 'decision_recorded') return ev.title || '';
     if (ev.type === 'decision_voided') {
       var vs = ev.superseded_by ? ' superseded by ' + ev.superseded_by : '';
@@ -13862,7 +14015,7 @@ async function assertWorkspaceInitialized15(basouRoot) {
 function readBuildStamp() {
   if (false) return void 0;
   try {
-    return JSON.parse('{"version":"0.49.0","commit":"6c4704a","committedAt":"2026-09-23T11:46:39+09:00"}');
+    return JSON.parse('{"version":"0.51.0","commit":"22ef44f","committedAt":"2026-09-23T22:27:59+09:00"}');
   } catch {
     return void 0;
   }