chainlesschain 0.162.49 → 0.162.60

package/src/repl/agent-repl.js

@@ -24,6 +24,11 @@ import os from "os";
 import path from "path";
 import { logger } from "../lib/logger.js";
 import { getPlanModeManager, PlanState } from "../lib/plan-mode.js";
+import { createVimState, feedNormalKey } from "../lib/repl-vim.js";
+import {
+  analyzeContinuation,
+  joinContinuation,
+} from "../lib/repl-multiline.js";
 import { bootstrap, shutdown } from "../runtime/bootstrap.js";
 import {
   createSession,
@@ -73,7 +78,10 @@ import {
 } from "../runtime/agent-core.js";
 import { expandFileRefs } from "../runtime/file-ref-expander.js";
 import { composeSystemPrompt } from "../runtime/system-prompt.js";
-import { makeFallbackChatFn } from "../runtime/fallback-model.js";
+import {
+  makeFallbackChatFn,
+  normalizeFallbackModels,
+} from "../runtime/fallback-model.js";
 import { resolveSlashMacro } from "./slash-macro.js";
 import { expandMcpPrompt, renderMcpSurface } from "./mcp-prompt.js";
 import { newCostStore, addUsage } from "./session-cost.js";
@@ -168,6 +176,17 @@ async function agentLoop(messages, options) {
     ...options,
   })) {
     if (event.type === "checkpoint") {
+      // Remember which file snapshot lines up with the live conversation so
+      // `/rewind <n>` can restore code + conversation together (Claude-Code
+      // parity). atMessageCount = messages.length at snapshot time; see
+      // repl-rewind.js for how a turn is matched back to its checkpoint.
+      if (Array.isArray(options.checkpointMarks)) {
+        options.checkpointMarks.push({
+          atMessageCount: messages.length,
+          id: event.id,
+          tool: event.tool,
+        });
+      }
       process.stdout.write(
         chalk.gray(`  ⎌ checkpoint ${event.id} (before ${event.tool})\n`),
       );
@@ -245,12 +264,19 @@ export async function startAgentRepl(options = {}) {
   // can `cc checkpoint restore` to just before any tool call.
   const autoCheckpoint = options.autoCheckpoint === true;
 
-  // --fallback-model: retry a turn's LLM call once on a backup model when the
-  // primary errors out (overload / network). Built once; passed into every
-  // agentLoop call via chatFn. Undefined when no fallback configured.
-  const _fallbackChatFn = options.fallbackModel
+  // --fallback-model: walk an ordered backup-model chain when a turn's LLM
+  // call fails (transient error or model-not-found). Built once; passed into
+  // every agentLoop call via chatFn. Accepts the resolved chain
+  // (options.fallbackModels) or a legacy single model (options.fallbackModel).
+  // Undefined when no fallback configured.
+  const _fallbackModels = normalizeFallbackModels(
+    options.fallbackModels != null
+      ? options.fallbackModels
+      : options.fallbackModel,
+  );
+  const _fallbackChatFn = _fallbackModels.length
     ? makeFallbackChatFn({
-        fallbackModel: options.fallbackModel,
+        fallbackModels: _fallbackModels,
         onFallback: ({ from, to, error }) =>
           logger.info(
             chalk.yellow(
@@ -491,6 +517,10 @@ export async function startAgentRepl(options = {}) {
   );
   let _activeOutputStyle = null; // { name, body }
   const messages = [{ role: "system", content: _replBaseSystem }];
+  // Checkpoint marks ({ atMessageCount, id, tool }) recorded as the agent loop
+  // emits `checkpoint` events, so `/rewind <n>` can also restore files to the
+  // snapshot taken before that turn (Claude-Code rewind = code + conversation).
+  const _checkpointMarks = [];
   // Apply --output-style or the settings.json `outputStyle` default at startup.
   try {
     const { resolveOutputStyle } = await import("../lib/output-styles.js");
@@ -638,6 +668,8 @@ export async function startAgentRepl(options = {}) {
           // (parity with headless; auto-detect already works via process.env).
           ide: options.ide,
           cwd: process.cwd(),
+          // advertise the session id to spawned stdio MCP servers
+          sessionId,
         },
         { writeErr: (s) => process.stderr.write(s) },
       );
@@ -734,16 +766,31 @@ export async function startAgentRepl(options = {}) {
     }
   }
 
+  // Vim mode (Claude-Code `/vim` parity): opt-in modal line editing. `_vim`
+  // holds the NORMAL-mode engine state while normal mode is active (readline's
+  // own key handling is suspended then); it is null in INSERT mode (readline
+  // owns editing). Default off — toggled by `/vim`, or on at startup via
+  // --vim / CC_VIM=1.
+  let _vimEnabled =
+    options.vimMode === true || process.env.CC_VIM === "1" ? true : false;
+  let _vim = null;
+
   const getPrompt = () => {
+    // Mode indicator first so it survives the plan-mode prompt variants.
+    const vim = _vimEnabled
+      ? _vim
+        ? chalk.cyan("[N] ")
+        : chalk.dim("[I] ")
+      : "";
     const planManager = getPlanModeManager();
     if (planManager.isActive()) {
       const state = planManager.state;
       if (state === PlanState.APPROVED || state === PlanState.EXECUTING) {
-        return chalk.green("[plan:exec] > ");
+        return vim + chalk.green("[plan:exec] > ");
       }
-      return chalk.yellow("[plan] > ");
+      return vim + chalk.yellow("[plan] > ");
     }
-    return chalk.green("> ");
+    return vim + chalk.green("> ");
   };
 
   // `@` tab-completion (Claude-Code @-mention parity): filesystem paths +
@@ -786,6 +833,7 @@ export async function startAgentRepl(options = {}) {
       "/statusline",
       "/sub-agents",
       "/task",
+      "/vim",
     ],
     getIdeOpenFiles: async () => {
       const exec = _adhocMcp?.externalToolExecutors?.mcp__ide__getOpenEditors;
@@ -813,6 +861,54 @@ export async function startAgentRepl(options = {}) {
     completer: atCompleter,
   });
 
+  // Vim-mode plumbing: capture readline's OWN keypress listeners now so we can
+  // suspend them while in NORMAL mode (the engine drives editing then) and
+  // reattach them for INSERT mode (readline's rich editing/history/completion).
+  const _rlKeypressListeners = process.stdin.isTTY
+    ? process.stdin.listeners("keypress").slice()
+    : [];
+  const _suspendReadlineKeys = () => {
+    for (const l of _rlKeypressListeners)
+      process.stdin.removeListener("keypress", l);
+  };
+  const _resumeReadlineKeys = () => {
+    const cur = process.stdin.listeners("keypress");
+    for (const l of _rlKeypressListeners)
+      if (!cur.includes(l)) process.stdin.on("keypress", l);
+  };
+  // Push the engine's line/cursor onto readline and redraw the current line.
+  const _vimSync = (vstate) => {
+    try {
+      rl.line = vstate.line;
+      rl.cursor = Math.max(0, Math.min(vstate.cursor, vstate.line.length));
+      if (typeof rl._refreshLine === "function") rl._refreshLine();
+    } catch {
+      /* redraw is best-effort */
+    }
+  };
+  const _vimEnterNormal = () => {
+    const cur = Math.max(
+      0,
+      Math.min(rl.cursor, Math.max(0, rl.line.length - 1)),
+    );
+    _vim = { ...createVimState(rl.line, cur), mode: "normal" };
+    _suspendReadlineKeys();
+    rl.setPrompt(getPrompt());
+    _vimSync(_vim);
+  };
+  const _vimEnterInsert = (vstate) => {
+    _resumeReadlineKeys();
+    _vim = null;
+    rl.setPrompt(getPrompt());
+    _vimSync(vstate);
+  };
+  // Exposed so /vim can leave normal mode cleanly when disabling.
+  const _vimDisable = () => {
+    if (_vim) _resumeReadlineKeys();
+    _vim = null;
+    _vimEnabled = false;
+  };
+
   // Esc interrupt (Claude-Code parity): pressing Esc while a turn is in
   // flight aborts the in-flight agentLoop through its existing AbortSignal
   // seam (throwIfAborted at each iteration); partial conversation is kept.
@@ -822,8 +918,9 @@ export async function startAgentRepl(options = {}) {
   let _lastIdleEscAt = 0;
   if (process.stdin.isTTY) {
     process.stdin.on("keypress", (_str, key) => {
-      if (!key || key.name !== "escape" || key.meta) return;
-      if (_turnAbort) {
+      const k = key || {};
+      // 1) Turn abort always wins, regardless of vim mode.
+      if (k.name === "escape" && !k.meta && _turnAbort) {
         process.stdout.write(chalk.yellow("\n⎋ interrupting…\n"));
         try {
           _turnAbort.abort();
@@ -833,8 +930,34 @@ export async function startAgentRepl(options = {}) {
         _turnAbort = null;
         return;
       }
-      // Double-Esc while idle → rewind picker shortcut (Claude-Code parity);
-      // the actual rewind is `/rewind <n>` so stdin stays readline-owned.
+
+      // 2) Vim mode: modal editing on the current input line.
+      if (_vimEnabled && !_turnAbort) {
+        if (!_vim) {
+          // INSERT mode — readline owns the keys; Esc switches to NORMAL.
+          if (k.name === "escape" && !k.meta) _vimEnterNormal();
+          return;
+        }
+        // NORMAL mode — readline suspended; the engine interprets every key.
+        const res = feedNormalKey(_vim, _str || "", k);
+        if (res.submit) {
+          // Hand the line to readline as a normal Enter (fires 'line', clears).
+          _vimEnterInsert({ ...res, cursor: res.line.length });
+          process.stdin.emit("keypress", "\r", { name: "return" });
+          return;
+        }
+        if (res.mode === "insert") {
+          _vimEnterInsert(res);
+          return;
+        }
+        _vim = res;
+        if (res.message === "bell") process.stdout.write("\x07");
+        _vimSync(res);
+        return;
+      }
+
+      // 3) Non-vim: double-Esc while idle → rewind picker shortcut.
+      if (k.name !== "escape" || k.meta) return;
       const nowTs = Date.now();
       if (nowTs - _lastIdleEscAt < 600) {
         _lastIdleEscAt = 0;
@@ -848,7 +971,9 @@ export async function startAgentRepl(options = {}) {
             );
             process.stdout.write(
               chalk.gray(
-                "Run /rewind <n> to rewind the conversation (files: cc checkpoint restore).\n",
+                _checkpointMarks.length
+                  ? "Run /rewind <n> to rewind the conversation (and optionally its files).\n"
+                  : "Run /rewind <n> to rewind the conversation.\n",
               ),
             );
             prompt();
@@ -950,7 +1075,24 @@ export async function startAgentRepl(options = {}) {
   // when the current turn finishes.
   let _processingLine = false;
   const _pendingLines = [];
+  // Multiline input (Claude-Code parity): a physical line ending in a
+  // continuation backslash keeps the prompt open; `_mlBuffer` accumulates the
+  // pieces and the whole block submits when a line does not continue.
+  const _mlBuffer = [];
   const handleLine = async (input) => {
+    // Backslash continuation — accumulate and re-prompt without firing a turn.
+    const _cont = analyzeContinuation(input);
+    if (_cont.continued) {
+      _mlBuffer.push(_cont.text);
+      rl.setPrompt(chalk.dim("... "));
+      rl.prompt();
+      return;
+    }
+    if (_mlBuffer.length) {
+      input = joinContinuation(_mlBuffer, input);
+      _mlBuffer.length = 0;
+    }
+
     const trimmed = input.trim();
     if (!trimmed) {
       prompt();
@@ -1022,12 +1164,18 @@ export async function startAgentRepl(options = {}) {
       logger.log(
         `  ${chalk.cyan("# <note>")}    Remember a note in the project cc.md`,
       );
+      logger.log(
+        `  ${chalk.cyan("… \\")}         End a line with \\ to continue input onto the next line`,
+      );
       logger.log(`  ${chalk.cyan("/exit")}       Exit the agent`);
       logger.log(
         `  ${chalk.cyan("/model")}      Show/change model (/model <name>)`,
       );
       logger.log(`  ${chalk.cyan("/provider")}   Show/change provider`);
       logger.log(`  ${chalk.cyan("/clear")}      Clear conversation`);
+      logger.log(
+        `  ${chalk.cyan("/vim")}        Toggle vim-mode line editing (/vim [on|off]; Esc → NORMAL)`,
+      );
       logger.log(
         `  ${chalk.cyan("/statusline")} Context-usage line on/off (/statusline [on|off])`,
       );
@@ -1044,7 +1192,7 @@ export async function startAgentRepl(options = {}) {
         `  ${chalk.cyan("/context")}    Live context-window usage by role`,
       );
       logger.log(
-        `  ${chalk.cyan("/cost")}       Session token spend + estimated $ (so far)`,
+        `  ${chalk.cyan("/cost")}       Session token spend + estimated $ (per model & category)`,
       );
       logger.log(
         `  ${chalk.cyan("/permissions")} Allow/ask/deny rules in effect this session`,
@@ -1053,7 +1201,7 @@ export async function startAgentRepl(options = {}) {
         `  ${chalk.cyan("/export")}     Save this conversation to a Markdown file (/export [path])`,
       );
       logger.log(
-        `  ${chalk.cyan("/rewind")}     Rewind conversation to an earlier turn (double-Esc lists)`,
+        `  ${chalk.cyan("/rewind")}     Rewind conversation + files to an earlier turn (double-Esc lists)`,
       );
       logger.log(
         `  ${chalk.cyan("/cd <dir>")}   Change working directory mid-session (completion/memory follow)`,
@@ -1230,11 +1378,30 @@ export async function startAgentRepl(options = {}) {
 
     if (trimmed === "/clear") {
       messages.length = 1; // Keep system prompt
+      _checkpointMarks.length = 0; // checkpoint marks no longer map to anything
       logger.info("Conversation cleared");
       prompt();
       return;
     }
 
+    if (trimmed === "/vim" || trimmed.startsWith("/vim ")) {
+      const arg = trimmed.slice("/vim".length).trim().toLowerCase();
+      const turnOn = arg === "on" || (arg === "" && !_vimEnabled);
+      if (turnOn) {
+        _vimEnabled = true;
+        logger.info(
+          chalk.gray(
+            "Vim mode: on — Esc → NORMAL (hjkl/w/b/e, x/dd/dw, i/a/A, etc.), i to insert.",
+          ),
+        );
+      } else {
+        _vimDisable();
+        logger.info(chalk.gray("Vim mode: off"));
+      }
+      prompt();
+      return;
+    }
+
     if (trimmed === "/statusline" || trimmed.startsWith("/statusline ")) {
       const arg = trimmed.slice("/statusline".length).trim().toLowerCase();
       if (arg === "off") {
@@ -1327,17 +1494,21 @@ export async function startAgentRepl(options = {}) {
 
     if (trimmed === "/rewind" || trimmed.startsWith("/rewind ")) {
       try {
-        const { listUserTurns, rewindToTurn, renderTurnList } =
-          await import("../lib/repl-rewind.js");
+        const {
+          listUserTurns,
+          rewindToTurn,
+          renderTurnList,
+          pickCheckpointForTurn,
+          pruneMarksAfter,
+        } = await import("../lib/repl-rewind.js");
         const arg = trimmed.slice("/rewind".length).trim();
         if (!arg) {
           logger.log(chalk.bold("\nRewind — pick a user turn (newest first):"));
           logger.log(renderTurnList(listUserTurns(messages)));
-          logger.log(
-            chalk.gray(
-              "Usage: /rewind <n>  (conversation only — restore files with `cc checkpoint restore`)",
-            ),
-          );
+          const fileHint = _checkpointMarks.length
+            ? "  (restores files to that point too — checkpoints are on)"
+            : "  (conversation only — start with --checkpoint / git to also rewind files)";
+          logger.log(chalk.gray(`Usage: /rewind <n>${fileHint}`));
         } else {
           const res = rewindToTurn(messages, arg);
           if (!res) {
@@ -1348,6 +1519,48 @@ export async function startAgentRepl(options = {}) {
                 `⎌ rewound — dropped ${res.removed} message(s); edit and resend below`,
               ),
             );
+            // Claude-Code parity: rewind restores files too. Match the dropped
+            // turn to the snapshot taken just before it first mutated the tree,
+            // then offer to roll the working tree back to it (undoable — the
+            // restore takes its own safety checkpoint first).
+            const cp = pickCheckpointForTurn(_checkpointMarks, res.index);
+            pruneMarksAfter(_checkpointMarks, res.index);
+            if (cp) {
+              const q = (p) => new Promise((r) => rl.question(p, r));
+              const ans = (
+                await q(
+                  chalk.yellow(
+                    `  Also restore files to before this turn? (checkpoint ${cp.id}) [Y/n] `,
+                  ),
+                )
+              )
+                .trim()
+                .toLowerCase();
+              if (ans === "" || ans === "y" || ans === "yes") {
+                try {
+                  const { rewindTo } =
+                    await import("../lib/checkpoint-store.js");
+                  const r = rewindTo(process.cwd(), cp.id, {
+                    session: sessionId,
+                  });
+                  logger.log(
+                    chalk.green(
+                      `  ⎌ files restored to ${cp.id} (${r.modified} changed, ${r.deleted} removed, ${r.recreated} recreated; undo: cc checkpoint restore ${r.safetyId})`,
+                    ),
+                  );
+                } catch (e) {
+                  logger.error(
+                    `  file restore skipped: ${e.message} (conversation already rewound)`,
+                  );
+                }
+              } else {
+                logger.log(
+                  chalk.gray(
+                    `  files left as-is — restore later with  cc checkpoint restore ${cp.id}`,
+                  ),
+                );
+              }
+            }
             prompt();
             if (res.text) rl.write(res.text);
             return;
@@ -2279,15 +2492,27 @@ export async function startAgentRepl(options = {}) {
     // parity). In-memory accumulation, so it works without session persistence.
     if (trimmed === "/cost" || trimmed === "/cost ") {
       let overrides;
+      let visionModel;
       try {
         const { loadConfig } = await import("../lib/config-manager.js");
-        overrides = loadConfig()?.llm?.pricing;
+        const cfg = loadConfig();
+        overrides = cfg?.llm?.pricing;
+        visionModel = cfg?.llm?.visionModel;
       } catch (_err) {
-        // pricing overrides are optional — fall back to the built-in table
-      }
+        // config is optional — fall back to the built-in pricing table
+      }
+      // Category breakdown (Claude-Code parity): classify spend by model role —
+      // the live model is "main", the vision model "vision", the fallback chain
+      // "fallback", a switched-to model "other". Shown only when >1 was used.
+      const roles = {
+        mainProvider: provider,
+        mainModel: _curModel || model,
+        visionModel: visionModel || "doubao-seed-1-6-vision-250815",
+        fallbackModels: _fallbackModels || [],
+      };
       const { renderSessionCost } = await import("./session-cost.js");
       logger.log(
-        renderSessionCost(_costStore, { pricingOverrides: overrides }),
+        renderSessionCost(_costStore, { pricingOverrides: overrides, roles }),
       );
       prompt();
       return;
@@ -2522,6 +2747,7 @@ export async function startAgentRepl(options = {}) {
         additionalDirectories,
         autoCheckpoint,
         checkpointSession: sessionId,
+        checkpointMarks: _checkpointMarks,
         prepareCall,
         approvalGate: _approvalGate,
         permissionRules: _permissionRules,

package/src/repl/session-cost.js

@@ -69,6 +69,81 @@ export function addUsage(store, events) {
   return s;
 }
 
+/**
+ * Classify a priced model row into a cost CATEGORY by its role in the session
+ * (Claude-Code `/cost` breakdown parity). Roles are derived from config + the
+ * live session: the active model is "main", the configured vision model is
+ * "vision", any model in the fallback chain is "fallback", anything else (e.g.
+ * a model switched to mid-session) is "other".
+ *
+ * The active model wins over vision/fallback when names collide, so a session
+ * that never used vision shows everything as "main".
+ *
+ * @param {string} provider
+ * @param {string} model
+ * @param {{mainProvider?:string, mainModel?:string, visionModel?:string, fallbackModels?:string[]}} roles
+ * @returns {"main"|"vision"|"fallback"|"other"}
+ */
+export function classifyModelRole(provider, model, roles = {}) {
+  const lc = (x) => String(x || "").toLowerCase();
+  const p = lc(provider);
+  const m = lc(model);
+  if (
+    roles.mainModel &&
+    m === lc(roles.mainModel) &&
+    (!roles.mainProvider || p === lc(roles.mainProvider))
+  ) {
+    return "main";
+  }
+  if (roles.visionModel && m === lc(roles.visionModel)) return "vision";
+  if (
+    Array.isArray(roles.fallbackModels) &&
+    roles.fallbackModels.some((fm) => lc(fm) === m)
+  ) {
+    return "fallback";
+  }
+  return "other";
+}
+
+/**
+ * Group a priced rollup's per-model rows into categories. Operates on the output
+ * of priceRollup (rows carry cost/matched/free), so dollar sums are accurate and
+ * unpriced models are flagged rather than silently counted as $0.
+ *
+ * @returns {Array<{category,inputTokens,outputTokens,totalTokens,calls,cost,models,anyUnpriced}>}
+ *          sorted by cost (then tokens) descending.
+ */
+export function categorizeByRole(pricedResult, roles = {}) {
+  const cats = new Map();
+  for (const row of pricedResult?.byModel || []) {
+    const category = classifyModelRole(row.provider, row.model, roles);
+    let c = cats.get(category);
+    if (!c) {
+      c = {
+        category,
+        inputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0,
+        calls: 0,
+        cost: 0,
+        models: [],
+        anyUnpriced: false,
+      };
+      cats.set(category, c);
+    }
+    c.inputTokens += num(row.inputTokens);
+    c.outputTokens += num(row.outputTokens);
+    c.totalTokens += num(row.totalTokens);
+    c.calls += num(row.calls);
+    if (row.matched && !row.free) c.cost += num(row.cost);
+    if (!row.matched && !row.free) c.anyUnpriced = true;
+    if (row.model && !c.models.includes(row.model)) c.models.push(row.model);
+  }
+  return Array.from(cats.values()).sort(
+    (a, b) => b.cost - a.cost || b.totalTokens - a.totalTokens,
+  );
+}
+
 /** Snapshot the store as the `{ total, byModel[] }` aggregate priceRollup wants. */
 export function costAggregate(store) {
   const s = store || newCostStore();
@@ -84,7 +159,7 @@ export function costAggregate(store) {
  * Render the live session cost. `pricingOverrides` is typically
  * `config.llm.pricing`. Returns plain text (the REPL does the I/O).
  */
-export function renderSessionCost(store, { pricingOverrides } = {}) {
+export function renderSessionCost(store, { pricingOverrides, roles } = {}) {
   const agg = costAggregate(store);
   if (agg.total.calls === 0) {
     return "Session cost: no LLM calls yet this session.";
@@ -108,6 +183,28 @@ export function renderSessionCost(store, { pricingOverrides } = {}) {
         : "unpriced";
     lines.push(`  ${provider} ${model} ${price}  ${tokens}`);
   }
+
+  // Category breakdown (main / vision / fallback / other) — only worth showing
+  // when more than one category was actually used; a single-model session is
+  // already fully described by the per-model rows above.
+  if (roles) {
+    const cats = categorizeByRole(result, roles);
+    if (cats.length >= 2) {
+      const totalCost = num(result.cost.totalCost);
+      lines.push("  by category:");
+      for (const c of cats) {
+        const label = c.category.padEnd(9);
+        const price =
+          c.anyUnpriced && c.cost === 0 ? "unpriced" : fmtUsd(c.cost);
+        const pct =
+          totalCost > 0 ? ` (${Math.round((c.cost / totalCost) * 100)}%)` : "";
+        lines.push(
+          `    ${label} ${price}${pct}  in=${c.inputTokens} out=${c.outputTokens} ${c.calls} calls`,
+        );
+      }
+    }
+  }
+
   if (result.unpriced.length > 0) {
     lines.push(
       `  note: ${result.unpriced.length} model(s) have no rate — ` +

package/src/runtime/agent-core.js

@@ -921,9 +921,8 @@ export async function executeTool(name, args, context = {}) {
     settingsVerdict.decision !== "allow" &&
     args?.path
   ) {
-    const { sensitiveFileReason } = await import(
-      "../lib/sensitive-file-guard.js"
-    );
+    const { sensitiveFileReason } =
+      await import("../lib/sensitive-file-guard.js");
     const sensReason = sensitiveFileReason(args.path);
     if (sensReason) {
       const confirm = context.permissionConfirm || context.shellConfirm || null;
@@ -1409,10 +1408,18 @@ async function executeToolInner(
             cwd: task.cwd,
             shell: true,
             windowsHide: true,
-            // Same CC_SESSION_ID correlation as the foreground path.
+            // Same agent-identity env as the foreground path: CLAUDECODE marks
+            // "running under the agent"; the session id correlates work to the
+            // run (CC_SESSION_ID + CLAUDE_CODE_SESSION_ID for Claude-Code parity).
             env: {
               ...process.env,
-              ...(sessionId ? { CC_SESSION_ID: String(sessionId) } : {}),
+              CLAUDECODE: "1",
+              ...(sessionId
+                ? {
+                    CC_SESSION_ID: String(sessionId),
+                    CLAUDE_CODE_SESSION_ID: String(sessionId),
+                  }
+                : {}),
             },
             // POSIX: own process group so check_shell{kill}/teardown can signal
             // the whole tree (shell + its grandchild command). No-op on Windows
@@ -1471,11 +1478,19 @@ async function executeToolInner(
           encoding: "utf8",
           timeout: _resolveShellTimeout(args.timeout),
           maxBuffer: 1024 * 1024,
-          // CC_SESSION_ID (Claude-Code CLAUDE_CODE_SESSION_ID parity,
-          // 2.1.132): lets scripts/hooks correlate work to the agent session.
+          // Agent-identity env for shell subprocesses (Claude-Code 2.1.132
+          // parity): CLAUDECODE=1 marks "running under the agent"; CC_SESSION_ID
+          // + its CLAUDE_CODE_SESSION_ID mirror let scripts/hooks correlate work
+          // to the agent session (the mirror is what CC-targeting tools expect).
           env: {
             ...process.env,
-            ...(sessionId ? { CC_SESSION_ID: String(sessionId) } : {}),
+            CLAUDECODE: "1",
+            ...(sessionId
+              ? {
+                  CC_SESSION_ID: String(sessionId),
+                  CLAUDE_CODE_SESSION_ID: String(sessionId),
+                }
+              : {}),
           },
         });
         return attachDescriptor(