chainlesschain 0.162.158 → 0.162.160

package/src/repl/voice-dictation.js

@@ -0,0 +1,132 @@
+/**
+ * Voice dictation for the agent REPL (gap-2026-07-11 P2#11).
+ *
+ * Claude Code's `/voice` dictates a prompt by speech. cc generalizes it to a
+ * pluggable STT backend with a strict local-first priority so nothing leaves
+ * the box unless the user opts into cloud transcription:
+ *
+ *   local Whisper  >  system STT (OS dictation)  >  cloud (opt-in)
+ *
+ * Two capture modes mirror the upstream UX:
+ *   - hold : push-to-talk — record while a key is held, transcribe on release.
+ *   - tap  : toggle — tap to start, tap again to stop.
+ *
+ * Real audio capture is a host binding (a Whisper binary, an OS dictation API);
+ * it is injected, so on a host with no backend — or a headless/SSH session where
+ * there is no microphone — `/voice` degrades to a clear message instead of
+ * pretending to listen. This module is the pure decision core (mode/command
+ * parse, environment degradation, backend priority, status render).
+ */
+
+export const VOICE_MODES = Object.freeze(["off", "hold", "tap"]);
+export const DEFAULT_VOICE_MODE = "off";
+
+/**
+ * STT backends in priority order. `local` never sends audio off the box;
+ * `cloud` requires explicit opt-in (config voice.allowCloud). Each entry names
+ * the capability probe the host binding fills in.
+ */
+export const STT_BACKENDS = Object.freeze([
+  { id: "whisper-local", kind: "local", label: "local Whisper" },
+  { id: "system-stt", kind: "system", label: "system STT" },
+  { id: "cloud", kind: "cloud", label: "cloud transcription" },
+]);
+
+/**
+ * Parse `/voice [hold|tap|off|status]`. Returns null for non-/voice input,
+ * `{ error }` for a bad arg, else `{ action }`. Bare `/voice` shows status.
+ * Pure.
+ */
+export function parseVoiceCommand(input) {
+  const t = String(input || "").trim();
+  if (t !== "/voice" && !t.startsWith("/voice ")) return null;
+  const arg = t.slice("/voice".length).trim().toLowerCase();
+  if (!arg || arg === "status") return { action: "status" };
+  if (arg === "hold" || arg === "ptt" || arg === "push")
+    return { action: "hold" };
+  if (arg === "tap" || arg === "toggle") return { action: "tap" };
+  if (arg === "off" || arg === "stop" || arg === "0") return { action: "off" };
+  return {
+    error: `Unknown /voice option "${arg}". Use: hold | tap | off | status`,
+  };
+}
+
+/**
+ * Decide whether voice capture is usable in this environment. Headless / SSH /
+ * CI sessions have no local microphone, so dictation degrades. Pure over the
+ * passed env + tty flags.
+ * @returns {{ supported, reason }}
+ */
+export function detectVoiceEnvironment({ env = {}, isTTY = true } = {}) {
+  if (!isTTY) {
+    return {
+      supported: false,
+      reason: "not a TTY — no interactive microphone",
+    };
+  }
+  if (env.SSH_TTY || env.SSH_CONNECTION) {
+    return {
+      supported: false,
+      reason:
+        "remote SSH session — capture audio locally and paste, or use a cloud STT relay",
+    };
+  }
+  if (isTruthy(env.CI)) {
+    return { supported: false, reason: "CI environment — no microphone" };
+  }
+  if (isTruthy(env.CC_NO_VOICE)) {
+    return { supported: false, reason: "disabled via CC_NO_VOICE" };
+  }
+  return { supported: true, reason: "" };
+}
+
+/**
+ * Pick the highest-priority available STT backend. `available` is a map of
+ * backend id → boolean from the host capability probe. Cloud is only eligible
+ * when `allowCloud` is true (config voice.allowCloud). Returns
+ * `{ backend, reason }` or `{ backend: null, reason }`. Pure.
+ */
+export function resolveSttBackend({
+  available = {},
+  allowCloud = false,
+  prefer = null,
+} = {}) {
+  const eligible = STT_BACKENDS.filter((b) => {
+    if (!available[b.id]) return false;
+    if (b.kind === "cloud" && !allowCloud) return false;
+    return true;
+  });
+  if (eligible.length === 0) {
+    return {
+      backend: null,
+      reason:
+        "no STT backend available — install a local Whisper build or enable system dictation (voice.allowCloud for cloud)",
+    };
+  }
+  // Honor an explicit preference if it's eligible; else take the top priority.
+  const chosen =
+    (prefer && eligible.find((b) => b.id === prefer)) || eligible[0];
+  return { backend: chosen, reason: `using ${chosen.label}` };
+}
+
+/** One-line `/voice status`. Pure. */
+export function renderVoiceStatus({ mode = "off", backend = null, env } = {}) {
+  const m = VOICE_MODES.includes(mode) ? mode : "off";
+  if (env && !env.supported) {
+    return `Voice: unavailable — ${env.reason}.`;
+  }
+  if (m === "off") {
+    return "Voice: off. /voice hold (push-to-talk) or /voice tap (toggle).";
+  }
+  const be = backend ? backend.label : "no backend";
+  const how =
+    m === "hold" ? "hold the dictation key to talk" : "tap to start/stop";
+  return `Voice: ${m} — ${how}; ${be}.`;
+}
+
+function isTruthy(v) {
+  const n = String(v == null ? "" : v)
+    .toLowerCase()
+    .trim();
+  return n === "1" || n === "true" || n === "yes" || n === "on";
+}

package/src/runtime/agent-core.js

@@ -673,8 +673,8 @@ Key behaviors:
 When the user's problem involves data processing, calculations, file operations, text parsing, API calls, web scraping, or any task that can be solved programmatically:
 - Proactively write and execute code using run_code tool
 - Choose the best language: Python for data/math/scraping, Node.js for JSON/API, Bash for system tasks
-- Missing Python packages are auto-installed via pip when import errors are detected
-- Scripts are persisted in .chainlesschain/agent-scripts/ for reference
+- Missing Python packages are NOT auto-installed by default; the tool result tells you (and the user) how to opt in (settings runCode.autoInstall)
+- Scripts run from a temp file by default; pass persist:true to keep one in .chainlesschain/agent-scripts/ for reference
 - Show the results and explain them clearly
 - If the first attempt fails, debug and retry with a different approach
 
@@ -1263,6 +1263,8 @@ export async function executeTool(name, args, context = {}) {
   // Sensitive-file write guard (Claude-Code 2.1.160 parity): shell startup
   // files / PowerShell profiles / git+husky hooks execute code on the user's
   // next shell or commit — even otherwise-permitted edit flows confirm first.
+  // Auto-exec configs (.vscode/tasks.json, .mcp.json, .idea run configs, …)
+  // ride the same gate via autoExecConfigReason.
   // An explicit settings `allow` rule is the only bypass (exact user
   // pre-authorization); headless without a confirmer fails closed.
   if (
@@ -1272,9 +1274,10 @@ export async function executeTool(name, args, context = {}) {
     settingsVerdict.decision !== "allow" &&
     args?.path
   ) {
-    const { sensitiveFileReason } =
+    const { sensitiveFileReason, autoExecConfigReason } =
       await import("../lib/sensitive-file-guard.js");
-    const sensReason = sensitiveFileReason(args.path);
+    const sensReason =
+      sensitiveFileReason(args.path) || autoExecConfigReason(args.path);
     if (sensReason) {
       const ok = await requestInteractivePermission(name, args, context, cwd, {
         tool: name,
@@ -1291,6 +1294,38 @@ export async function executeTool(name, args, context = {}) {
     }
   }
 
+  // Session-store write guard (transcript tamper protection): JSONL
+  // transcripts under ~/.chainlesschain/sessions are hash-chained and treated
+  // as an audit surface — an agent editing a transcript rewrites the history
+  // that `cc session verify` and resume trust. Same posture as the
+  // sensitive-file guard: confirm-first, an explicit settings `allow` rule is
+  // the only bypass, headless without a confirmer fails closed.
+  if (
+    (name === "write_file" ||
+      name === "edit_file" ||
+      name === "notebook_edit") &&
+    settingsVerdict.decision !== "allow" &&
+    args?.path
+  ) {
+    const { sessionStorePathReason } =
+      await import("../lib/session-store-guard.js");
+    const storeReason = sessionStorePathReason(args.path, { cwd });
+    if (storeReason) {
+      const ok = await requestInteractivePermission(name, args, context, cwd, {
+        tool: name,
+        args,
+        rule: null,
+        reason: `session store: ${storeReason}`,
+      });
+      if (!ok) {
+        return {
+          error: `[Session Store] Writing "${args.path}" would modify a session transcript (${storeReason}) — denied. Add a settings allow rule to pre-authorize.`,
+          policy: { decision: "ask", via: "session-store-guard" },
+        };
+      }
+    }
+  }
+
   // Destructive-git guard (Claude-Code 2.1.183 parity: "destructive git
   // commands blocked when unintended"). The `git` tool otherwise runs any
   // command unguarded in auto mode — including `reset --hard`, `clean -fd`,
@@ -1438,6 +1473,14 @@ export async function executeTool(name, args, context = {}) {
       parentMessages: context.parentMessages,
       interaction: context.interaction,
       sessionId: context.sessionId || null,
+      // Parent LLM config — documented at toolContext as forwarded to
+      // spawn_sub_agent for provider/key inheritance; without this line it
+      // never actually reached executeToolInner (sub-agents silently fell
+      // back to config defaults and their usage was mis-attributed).
+      llmOptions: context.llmOptions || null,
+      // 用量归因: shared per-run sink for child-loop (sub-agent / isolated
+      // skill) token usage, drained by agentLoop as attributed events.
+      subAgentUsageSink: context.subAgentUsageSink || null,
       hostManagedToolPolicy: context.hostManagedToolPolicy || null,
       externalToolDescriptors: context.externalToolDescriptors || null,
       externalToolExecutors: context.externalToolExecutors || null,
@@ -2074,6 +2117,7 @@ async function executeToolInner(
     settingsHooks = null,
     signal = null,
     backgroundSubAgents = null,
+    subAgentUsageSink = null,
   },
 ) {
   const localToolDescriptor =
@@ -2706,6 +2750,21 @@ async function executeToolInner(
           }
           output = res.stdout ?? "";
         }
+        // PR/session linking (gap-2026-07-11 P1#9): a successful `gh pr …`
+        // (or `git push`) ties this session to the PR it touched. Async and
+        // best-effort — never delays or fails the tool result.
+        if (sessionId) {
+          import("../lib/pr-link-ledger.js")
+            .then((m) =>
+              m.recordFromShellCommand({
+                sessionId,
+                command: args.command,
+                output: String(output || ""),
+                cwd: args.cwd || cwd,
+              }),
+            )
+            .catch(() => {});
+        }
         return attachDescriptor(
           {
             stdout: output.substring(0, 30000),
@@ -2883,6 +2942,7 @@ async function executeToolInner(
           settingsHooks,
           signal,
           backgroundSubAgents,
+          subAgentUsageSink,
         }),
       );
     }
@@ -3221,6 +3281,77 @@ async function executeToolInner(
       }
     }
 
+    case "browser_act": {
+      // Gap-analysis #6: the ACTION side of the Chrome connector.
+      // browser_state stays the read-only default; browser_act explicitly
+      // drives the user's logged-in browser (click/type/press/navigate/
+      // waitForSelector/screenshot/assertText) and is gated like run_code:
+      // HIGH risk through the ApprovalGate (CONFIRM even on the trusted/auto
+      // tier), pre-authorizable only by an explicit settings allow rule
+      // (ruleAllowed). Unlike run_code there is no legacy ungated behavior to
+      // preserve, so the gate applies whenever an ApprovalGate is wired —
+      // headless without a confirmer fails closed. Screenshot paths are
+      // generated inside performActions (never agent-chosen), and each
+      // executed step is audit-logged to ~/.chainlesschain/browser-actions/.
+      try {
+        if (
+          approvalGate &&
+          !ruleAllowed &&
+          typeof approvalGate.decide === "function"
+        ) {
+          const { APPROVAL_RISK, APPROVAL_DECISION } =
+            await import("@chainlesschain/session-core");
+          const summary = Array.isArray(args.actions)
+            ? args.actions
+                .map((a) => a?.type)
+                .filter(Boolean)
+                .slice(0, 10)
+                .join(",")
+            : "";
+          const gate = await approvalGate.decide({
+            sessionId,
+            riskLevel: APPROVAL_RISK.HIGH,
+            tool: "browser_act",
+            args: { actions: summary },
+          });
+          if (gate.decision !== APPROVAL_DECISION.ALLOW) {
+            const tierLabel =
+              typeof gate.policy === "string" ? `"${gate.policy}" ` : "";
+            return attachDescriptor({
+              error: `[ApprovalGate] browser_act denied by the ${tierLabel}approval policy (via ${gate.via}). Retrying won't help — driving the user's browser needs their approval. Tell the user (they can approve it or relax the policy) and continue with other work.`,
+              approval: {
+                decision: gate.decision,
+                via: gate.via,
+                riskLevel: "high",
+                policy: gate.policy,
+              },
+            });
+          }
+        }
+        const { performActions } = await import("../lib/chrome-connector.js");
+        const result = await performActions(args.actions, {
+          port: args.port != null ? Number(args.port) : undefined,
+          cdpUrl: args.cdp_url != null ? String(args.cdp_url) : null,
+          tab: args.tab != null ? Number(args.tab) : undefined,
+          continueOnError: args.continue_on_error === true,
+          sessionId: sessionId ? String(sessionId) : null,
+        });
+        if (!result.ok && result.error) {
+          // Nothing ran (validation / attach failure) — surface as an error.
+          // A step-level failure returns the per-step outcomes instead so the
+          // model can see exactly which step broke.
+          return attachDescriptor({
+            error: `browser_act failed: ${result.error}`,
+          });
+        }
+        return attachDescriptor(result);
+      } catch (err) {
+        return attachDescriptor({
+          error: `browser_act failed: ${err.message}`,
+        });
+      }
+    }
+
     case "search_files": {
       // An explicit directory scopes the search to one root; otherwise span
       // cwd plus any --add-dir roots so cross-package searches find matches.
@@ -3429,13 +3560,46 @@ async function executeToolInner(
       // Check if skill requests isolation (via SKILL.md frontmatter)
       const skillIsolation = match.isolation === true;
       if (skillIsolation) {
+        // 用量归因: an isolated skill runs as a child loop whose real token
+        // usage would otherwise be invisible — forward it into the parent
+        // run's sink tagged origin:"skill" so `cc session usage --by skill`
+        // can break it out. A nested frame passes through unchanged.
+        const skillUsageSink = Array.isArray(subAgentUsageSink)
+          ? subAgentUsageSink
+          : null;
+        let skillSubRef = null;
         // Run skill through isolated sub-agent context
         const subCtx = SubAgentContext.create({
           role: `skill-${args.skill_name}`,
           task: `Execute the "${args.skill_name}" skill with input: ${(args.input || "").substring(0, 200)}`,
           allowedTools: ["read_file", "search_files", "list_dir"],
           cwd,
+          onUsage: skillUsageSink
+            ? (u) => {
+                try {
+                  skillUsageSink.push(
+                    u && u.attribution
+                      ? u
+                      : {
+                          provider: u?.provider ?? null,
+                          model: u?.model ?? null,
+                          usage: u?.usage || null,
+                          attribution: {
+                            origin: "skill",
+                            skill: args.skill_name,
+                            subagentId: skillSubRef?.id || null,
+                            parentSessionId: sessionId || null,
+                            depth: (subAgentDepth || 0) + 1,
+                          },
+                        },
+                  );
+                } catch (_e) {
+                  // usage forwarding is best-effort
+                }
+              }
+            : null,
         });
+        skillSubRef = subCtx;
         try {
           const result = await subCtx.run(args.input);
           return attachDescriptor({
@@ -3747,7 +3911,10 @@ async function _executeRunCode(args, cwd) {
   const lang = args.language;
   const code = args.code;
   const timeoutSec = Math.min(Math.max(args.timeout || 60, 1), 300);
-  const persist = args.persist !== false; // default true
+  // gap-analysis 2026-07-11 P0 "依赖安装与凭据": agent-generated scripts
+  // default to the OS temp dir; only an explicit persist:true lands them in
+  // the project (.chainlesschain/agent-scripts/).
+  const persist = args.persist === true; // default false (temp dir)
 
   const extMap = { python: ".py", node: ".js", bash: ".sh" };
   const ext = extMap[lang];
@@ -3817,6 +3984,51 @@ async function _executeRunCode(args, cwd) {
             };
           }
 
+          // Auto-install is OPT-IN (settings runCode.autoInstall / env
+          // CC_RUN_CODE_AUTO_INSTALL=1) with an optional package allowlist;
+          // every attempt — including refused ones — is audited.
+          const {
+            resolveAutoInstallPolicy,
+            isPackageAllowed,
+            autoInstallDisabledHint,
+            recordInstallAudit,
+          } = await import("../lib/dependency-install-policy.js");
+          const installPolicy = resolveAutoInstallPolicy({ cwd });
+          if (!installPolicy.enabled) {
+            recordInstallAudit({
+              package: packageName,
+              interpreter,
+              cwd,
+              outcome: "disabled",
+            });
+            return {
+              error: (stderr || message).substring(0, 5000),
+              stderr: stderr.substring(0, 5000),
+              exitCode: err.status,
+              language: lang,
+              ...classified,
+              hint: autoInstallDisabledHint(packageName),
+              scriptPath: persist ? scriptPath : undefined,
+            };
+          }
+          if (!isPackageAllowed(packageName, installPolicy.allowlist)) {
+            recordInstallAudit({
+              package: packageName,
+              interpreter,
+              cwd,
+              outcome: "blocked",
+            });
+            return {
+              error: (stderr || message).substring(0, 5000),
+              stderr: stderr.substring(0, 5000),
+              exitCode: err.status,
+              language: lang,
+              ...classified,
+              hint: `Package "${packageName}" is not in runCode.installAllowlist — install it manually or add it to the allowlist.`,
+              scriptPath: persist ? scriptPath : undefined,
+            };
+          }
+
           // Attempt pip install
           try {
             execSync(`${interpreter} -m pip install ${packageName}`, {
@@ -3825,6 +4037,12 @@ async function _executeRunCode(args, cwd) {
               maxBuffer: 2 * 1024 * 1024,
               stdio: ["pipe", "pipe", "pipe"],
             });
+            recordInstallAudit({
+              package: packageName,
+              interpreter,
+              cwd,
+              outcome: "installed",
+            });
 
             // Retry execution
             const retryStart = Date.now();
@@ -3845,6 +4063,13 @@ async function _executeRunCode(args, cwd) {
               scriptPath: persist ? scriptPath : undefined,
             };
           } catch (pipErr) {
+            recordInstallAudit({
+              package: packageName,
+              interpreter,
+              cwd,
+              outcome: "failed",
+              detail: (pipErr.stderr || pipErr.message || "").substring(0, 200),
+            });
             return {
               error: (stderr || message).substring(0, 5000),
               stderr: stderr.substring(0, 5000),
@@ -4020,6 +4245,27 @@ function _backgroundSubAgentResultText(entry) {
   );
 }
 
+/**
+ * Drain the run's attributed child-loop usage sink (spawn_sub_agent /
+ * isolated run_skill — see toolContext.subAgentUsageSink), re-yielding each
+ * record as a regular `token-usage` event that carries its `attribution`
+ * frame. Consumers that ignore `attribution` see ordinary usage events;
+ * attribution-aware consumers (REPL persistence, headless runner) can split
+ * child spend from the main conversation's.
+ */
+function* _drainSubAgentUsage(sink) {
+  while (Array.isArray(sink) && sink.length > 0) {
+    const u = sink.shift();
+    yield {
+      type: "token-usage",
+      provider: u?.provider ?? null,
+      model: u?.model ?? null,
+      usage: u?.usage || {},
+      attribution: u?.attribution || null,
+    };
+  }
+}
+
 async function _executeSpawnSubAgent(args, ctx) {
   // Nesting cap: refuse before any context/registry work.
   const currentDepth = ctx.subAgentDepth || 0;
@@ -4051,6 +4297,17 @@ async function _executeSpawnSubAgent(args, ctx) {
     tools: explicitTools,
     profile: profileName,
   } = args;
+  // Extended sub-agent contract (gap 2026-07-11 P1): per-spawn deny-list,
+  // iteration cap and worktree isolation — spawn args win over the agent
+  // file's frontmatter defaults.
+  let disallowedTools = Array.isArray(args.disallowedTools)
+    ? args.disallowedTools.filter(Boolean)
+    : null;
+  let subMaxTurns =
+    Number.isFinite(Number(args.maxTurns)) && Number(args.maxTurns) > 0
+      ? Math.floor(Number(args.maxTurns))
+      : null;
+  let subIsolation = args.isolation === "worktree" ? "worktree" : null;
 
   // Named subagent delegation (cc agents / .chainlesschain|.claude/agents/*.md):
   // load the agent's persona (its body = system prompt) + tool allow-list.
@@ -4068,6 +4325,13 @@ async function _executeSpawnSubAgent(args, ctx) {
       }
       role = role || md.name;
       if (!explicitTools && Array.isArray(md.tools)) explicitTools = md.tools;
+      if (!disallowedTools && Array.isArray(md.disallowedTools)) {
+        disallowedTools = md.disallowedTools;
+      }
+      if (!subMaxTurns && md.maxTurns) subMaxTurns = md.maxTurns;
+      if (!subIsolation && md.isolation === "worktree") {
+        subIsolation = "worktree";
+      }
       if (md.model) mdModel = md.model;
       if (md.systemPrompt) {
         mdProfile = { name: md.name, systemPrompt: md.systemPrompt };
@@ -4107,9 +4371,19 @@ async function _executeSpawnSubAgent(args, ctx) {
   // profile.systemPrompt seam) when no declarative profile was requested.
   if (!profile && mdProfile) profile = mdProfile;
 
-  const allowedTools = Array.isArray(explicitTools)
+  let allowedTools = Array.isArray(explicitTools)
     ? explicitTools
     : profile?.toolAllowlist || null;
+  // Deny-list: subtract from the resolved allow-list; with no allow-list
+  // ("all tools"), subtract from the full built-in contract set. spawn itself
+  // is always denied downstream by depth/breadth caps, so no special-casing.
+  if (Array.isArray(disallowedTools) && disallowedTools.length > 0) {
+    const deny = new Set(disallowedTools.map((t) => String(t).trim()));
+    const base = Array.isArray(allowedTools)
+      ? allowedTools
+      : listCodingAgentToolNames();
+    allowedTools = base.filter((t) => !deny.has(t));
+  }
 
   // Auto-condense parent context if caller didn't provide explicit context
   let resolvedContext = inheritedContext || null;
@@ -4169,6 +4443,40 @@ async function _executeSpawnSubAgent(args, ctx) {
     model: mdModel || parentLlm.model || undefined,
   };
 
+  // 用量归因: forward the child's real token usage into the parent run's sink
+  // (threaded through toolContext) so agentLoop re-yields it as attributed
+  // `token-usage` events. A nested child's already-attributed record passes
+  // through unchanged (deepest frame wins). subCtxRef closes over the created
+  // context so the frame can carry the sub-agent's id.
+  const usageSink = Array.isArray(ctx.subAgentUsageSink)
+    ? ctx.subAgentUsageSink
+    : null;
+  let subCtxRef = null;
+  const onUsage = usageSink
+    ? (u) => {
+        try {
+          usageSink.push(
+            u && u.attribution
+              ? u
+              : {
+                  provider: u?.provider ?? null,
+                  model: u?.model ?? null,
+                  usage: u?.usage || null,
+                  attribution: {
+                    origin: "subagent",
+                    subagentId: subCtxRef?.id || null,
+                    role: subCtxRef?.role || role || null,
+                    parentSessionId,
+                    depth: currentDepth + 1,
+                  },
+                },
+          );
+        } catch (_e) {
+          // usage forwarding is best-effort
+        }
+      }
+    : null;
+
   const subCtx = SubAgentContext.create({
     role,
     task,
@@ -4182,7 +4490,13 @@ async function _executeSpawnSubAgent(args, ctx) {
     // Same shared counter object so the child's own spawns draw from the run's
     // single total-sub-agent pool (breadth cap spans the whole tree).
     subAgentBudget: ctx.subAgentBudget || null,
+    onUsage,
+    // Extended contract (gap 2026-07-11): per-agent iteration cap + opt-in
+    // worktree isolation. undefined keeps the profile/flag defaults intact.
+    ...(subMaxTurns ? { maxIterations: subMaxTurns } : {}),
+    ...(subIsolation === "worktree" ? { useWorktree: true } : {}),
   });
+  subCtxRef = subCtx;
 
   const emit = (type, payload) => {
     if (!interaction || typeof interaction.emit !== "function") return;
@@ -5793,8 +6107,18 @@ export async function* agentLoop(messages, options) {
     // any are still running (it waits, injects, and gives the model one more
     // turn) so a background result can never be silently lost.
     backgroundSubAgents: new Map(),
+    // 用量归因: per-run sink for child-loop (spawn_sub_agent / isolated
+    // run_skill) token usage. Child loops consume their own generator events,
+    // so their real usage never reaches this loop's consumers — the spawn
+    // wiring pushes it here and the loop drains it at iteration boundaries as
+    // `token-usage` events carrying an `attribution` frame. Callers may pass
+    // their own array to observe it directly.
+    subAgentUsageSink: Array.isArray(options.subAgentUsageSink)
+      ? options.subAgentUsageSink
+      : [],
   };
   const backgroundSubAgents = toolContext.backgroundSubAgents;
+  const subAgentUsageSink = toolContext.subAgentUsageSink;
 
   throwIfAborted(signal);
 
@@ -5930,6 +6254,10 @@ export async function* agentLoop(messages, options) {
     budget.consume();
     throwIfAborted(signal);
 
+    // Surface attributed child-loop usage collected since the last boundary
+    // (blocking spawns push during executeTool; background spawns push live).
+    yield* _drainSubAgentUsage(subAgentUsageSink);
+
     // Emit progressive warnings (once per level)
     const level = budget.warningLevel();
     if (
@@ -6504,7 +6832,9 @@ export async function* agentLoop(messages, options) {
     }
   }
 
-  // Budget exhausted — yield exhaustion event + final message
+  // Budget exhausted — flush any child usage the final iteration produced,
+  // then yield exhaustion event + final message
+  yield* _drainSubAgentUsage(subAgentUsageSink);
   yield { type: "iteration-budget-exhausted", budget: budget.toSummary() };
   yield {
     type: "response-complete",
@@ -6559,6 +6889,13 @@ export function formatToolArgs(name, args) {
       return `${args.kind || "other"}: ${(args.title || args.path || "").substring(0, 60)}`;
     case "browser_state":
       return `tab=${args.tab ?? 0} port=${args.port ?? 9222}${args.reload ? " reload" : ""}`;
+    case "browser_act": {
+      const kinds = Array.isArray(args.actions)
+        ? args.actions.map((a) => a?.type).filter(Boolean)
+        : [];
+      const head = kinds.slice(0, 4).join(",");
+      return `${kinds.length} action(s)${head ? `: ${head}` : ""}${kinds.length > 4 ? ",…" : ""} tab=${args.tab ?? 0} port=${args.port ?? 9222}`;
+    }
     case "schedule":
       return args.action === "cron"
         ? `cron ${args.cron || ""}`.trim()