@cjhyy/code-shell-core 0.6.0-rc.8 → 0.7.0-beta.1

package/dist/tool-system/permission.d.ts

@@ -21,6 +21,17 @@ export declare class AutoApprovalBackend implements ApprovalBackend {
     requestApproval(req: ApprovalRequest): Promise<ApprovalResult>;
     private isSafeOperation;
 }
+/**
+ * Closed-session tombstones are a bounded replay guard. A prompt that started
+ * before close is still protected by the state-object identity check in
+ * isActiveSessionState(): clearSession deletes the captured state, so the late
+ * result cannot write into a new bucket even if an old tombstone has aged out.
+ * The tombstone only blocks fresh post-close calls carrying a recently closed
+ * sessionId from creating an empty bucket. 4096 is 256x the default
+ * ChatSessionManager.maxSessions (16), which covers normal late-result bursts
+ * while keeping long-lived processes from retaining every historical id.
+ */
+export declare const CLOSED_SESSION_TOMBSTONE_LIMIT = 4096;
 /**
  * Interactive approval backend — prompts the user via a callback.
  *
@@ -34,13 +45,11 @@ export declare class AutoApprovalBackend implements ApprovalBackend {
  * the next time the user opens the project.
  */
 export declare class InteractiveApprovalBackend implements ApprovalBackend {
-    private sessionAllowRules;
-    private sessionDenyRules;
+    private sessionStateById;
+    private closedSessionIds;
     private promptFn;
-    private cwd;
-    private savedProjectRules;
-    private onProjectRules;
-    private promptTurn;
+    private legacyPromptTurn;
+    private legacyContext;
     setPromptFn(fn: (request: ApprovalRequest) => Promise<ApprovalResult>): void;
     /**
      * Has someone installed a real prompt callback? Engine consults this
@@ -59,8 +68,18 @@ export declare class InteractiveApprovalBackend implements ApprovalBackend {
      * earlier approvals.
      */
     setOnProjectRules(fn: (rules: PermissionRule[]) => void): void;
+    setSessionContext(sessionId: string, context: {
+        cwd: string;
+        onProjectRules: (rules: PermissionRule[]) => void;
+    }): void;
+    openSession(sessionId: string): void;
+    clearSession(sessionId: string): void;
+    private rememberClosedSession;
+    private makeSessionState;
+    private getSessionState;
+    private isActiveSessionState;
     requestApproval(req: ApprovalRequest): Promise<ApprovalResult>;
-    /** Session-rule lookup — operation-scoped (see sessionAllowRules doc). Deny
+    /** Session-rule lookup — operation-scoped (see sessionStateById doc). Deny
      *  wins over allow if both somehow match (conservative). Null = no rule. */
     private checkSessionRules;
     /** The actual interactive ask + rule recording (runs inside the prompt turn). */
@@ -89,6 +108,8 @@ export declare function pathRuleArgsPattern(absPath: string, scope: "file" | "di
  */
 export declare function ruleMatches(rule: PermissionRule, toolName: string, args: Record<string, unknown>): boolean;
 export declare function getInteractiveApprovalBackend(): InteractiveApprovalBackend;
+export declare function openInteractiveApprovalSession(sessionId: string): void;
+export declare function clearInteractiveApprovalSession(sessionId: string): void;
 export declare function setInteractiveApprovalFn(fn: (request: ApprovalRequest) => Promise<ApprovalResult>): void;
 type BashSafetyLevel = "safe-read" | "safe-write" | "unsafe" | "dangerous";
 /**

package/dist/tool-system/permission.js

@@ -2,7 +2,7 @@
  * Permission system — classifier + approval backend.
  */
 import { resolve as resolvePath, dirname } from "node:path";
-import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { logger as rootPermLogger } from "../logging/logger.js";
 import { READ_ONLY_TOOLS } from "./plan-mode-allowlist.js";
@@ -93,6 +93,17 @@ export class AutoApprovalBackend {
         return false;
     }
 }
+/**
+ * Closed-session tombstones are a bounded replay guard. A prompt that started
+ * before close is still protected by the state-object identity check in
+ * isActiveSessionState(): clearSession deletes the captured state, so the late
+ * result cannot write into a new bucket even if an old tombstone has aged out.
+ * The tombstone only blocks fresh post-close calls carrying a recently closed
+ * sessionId from creating an empty bucket. 4096 is 256x the default
+ * ChatSessionManager.maxSessions (16), which covers normal late-result bursts
+ * while keeping long-lived processes from retaining every historical id.
+ */
+export const CLOSED_SESSION_TOMBSTONE_LIMIT = 4096;
 /**
  * Interactive approval backend — prompts the user via a callback.
  *
@@ -106,29 +117,21 @@ export class AutoApprovalBackend {
  * the next time the user opens the project.
  */
 export class InteractiveApprovalBackend {
-    // Session-scoped grants, keyed on the OPERATION (tool + narrowed argsPattern
-    // via buildProjectRule), NOT just the tool name. Approving `git status` for
-    // the session must not auto-allow `rm -rf /` (both are "Bash"). Allow and
-    // deny are tracked separately so a one-off deny of `curl evil` never blocks
-    // an unrelated `git status`. (TODO 5.1 会话级权限缓存.)
-    sessionAllowRules = [];
-    sessionDenyRules = [];
+    // Session-scoped grants are bucketed by ApprovalRequest.sessionId and then
+    // keyed on the OPERATION (tool + narrowed argsPattern via buildProjectRule),
+    // NOT just the tool name. Approving `git status` for one session must not
+    // auto-allow either `rm -rf /` in that same session or `git ...` in another.
+    // Allow and deny are tracked separately so a one-off deny of `curl evil`
+    // never blocks an unrelated `git status`.
+    sessionStateById = new Map();
+    closedSessionIds = new Set();
     promptFn = null;
-    cwd = null;
-    // Project rules saved during this session. Kept in-memory (not re-read from
-    // settings.local.json) so a stream of approvals all stay applied — the
-    // previous version passed only the freshly-added rule to the classifier,
-    // which silently dropped earlier approvals from the live classifier within
-    // the same session. We accumulate here and hand the full list to the callback.
-    savedProjectRules = [];
-    onProjectRules = null;
-    // Serialize prompts so a burst of parallel tool calls doesn't queue N
-    // identical cards: while one ask is outstanding, later requests wait here
-    // and RE-CHECK the session rules when their turn comes — the first
-    // "本会话一直允许" answer then silently absorbs the queued duplicates.
-    // (All callers were already serialized at the UI anyway — the renderer
-    // shows one approval card at a time.)
-    promptTurn = Promise.resolve();
+    legacyPromptTurn = Promise.resolve();
+    legacyContext = {
+        cwd: null,
+        savedProjectRules: [],
+        onProjectRules: null,
+    };
     setPromptFn(fn) {
         this.promptFn = fn;
     }
@@ -144,7 +147,7 @@ export class InteractiveApprovalBackend {
     }
     /** Inject the project root so persistence writes to the right settings file. */
     setCwd(cwd) {
-        this.cwd = cwd;
+        this.legacyContext.cwd = cwd;
     }
     /**
      * Inject a callback fired when the user approves "for this project". The
@@ -153,11 +156,68 @@ export class InteractiveApprovalBackend {
      * earlier approvals.
      */
     setOnProjectRules(fn) {
-        this.onProjectRules = fn;
+        this.legacyContext.onProjectRules = fn;
+    }
+    setSessionContext(sessionId, context) {
+        const state = this.getSessionState(sessionId, true);
+        if (!state)
+            return;
+        state.cwd = context.cwd;
+        state.onProjectRules = context.onProjectRules;
+    }
+    openSession(sessionId) {
+        if (!sessionId)
+            return;
+        this.closedSessionIds.delete(sessionId);
+    }
+    clearSession(sessionId) {
+        if (!sessionId)
+            return;
+        this.sessionStateById.delete(sessionId);
+        this.rememberClosedSession(sessionId);
+    }
+    rememberClosedSession(sessionId) {
+        this.closedSessionIds.delete(sessionId);
+        this.closedSessionIds.add(sessionId);
+        while (this.closedSessionIds.size > CLOSED_SESSION_TOMBSTONE_LIMIT) {
+            const oldest = this.closedSessionIds.values().next().value;
+            if (oldest === undefined)
+                break;
+            this.closedSessionIds.delete(oldest);
+        }
+    }
+    makeSessionState() {
+        return {
+            allowRules: [],
+            denyRules: [],
+            promptTurn: Promise.resolve(),
+            cwd: null,
+            savedProjectRules: [],
+            onProjectRules: null,
+        };
+    }
+    getSessionState(sessionId, create) {
+        if (!sessionId)
+            return null;
+        if (this.closedSessionIds.has(sessionId))
+            return null;
+        const existing = this.sessionStateById.get(sessionId);
+        if (existing || !create)
+            return existing ?? null;
+        const next = this.makeSessionState();
+        this.sessionStateById.set(sessionId, next);
+        return next;
+    }
+    isActiveSessionState(sessionId, state) {
+        return (!!sessionId &&
+            !!state &&
+            !this.closedSessionIds.has(sessionId) &&
+            this.sessionStateById.get(sessionId) === state);
     }
     async requestApproval(req) {
+        const state = this.getSessionState(req.sessionId, true);
         // Fast path: the operation may already be covered by a session rule.
-        const cached = this.checkSessionRules(req);
+        const cached = state ? this.checkSessionRules(req, state) : null;
         if (cached)
             return cached;
         if (!this.promptFn) {
@@ -167,51 +227,68 @@ export class InteractiveApprovalBackend {
         // field doc): a burst of parallel tool calls all passes the fast path
         // before the first decision lands; without the re-check the user had to
         // answer one card per duplicate.
-        const prevTurn = this.promptTurn;
+        const prevTurn = state ? state.promptTurn : this.legacyPromptTurn;
         let release;
-        this.promptTurn = new Promise((r) => (release = r));
+        const currentTurn = new Promise((r) => (release = r));
+        if (state) {
+            state.promptTurn = currentTurn;
+        }
+        else {
+            this.legacyPromptTurn = currentTurn;
+        }
         try {
             await prevTurn;
-            const nowCached = this.checkSessionRules(req);
+            const activeState = this.isActiveSessionState(req.sessionId, state) ? state : null;
+            const nowCached = activeState ? this.checkSessionRules(req, activeState) : null;
             if (nowCached)
                 return nowCached;
-            return await this.promptAndRecord(req);
+            return await this.promptAndRecord(req, activeState);
         }
         finally {
             release();
         }
     }
-    /** Session-rule lookup — operation-scoped (see sessionAllowRules doc). Deny
+    /** Session-rule lookup — operation-scoped (see sessionStateById doc). Deny
      *  wins over allow if both somehow match (conservative). Null = no rule. */
-    checkSessionRules(req) {
-        if (this.sessionDenyRules.some((r) => ruleMatches(r, req.toolName, req.args))) {
+    checkSessionRules(req, state) {
+        if (state.denyRules.some((r) => ruleMatches(r, req.toolName, req.args))) {
             return { approved: false };
         }
-        if (this.sessionAllowRules.some((r) => ruleMatches(r, req.toolName, req.args))) {
+        if (state.allowRules.some((r) => ruleMatches(r, req.toolName, req.args))) {
             return { approved: true };
         }
         return null;
     }
     /** The actual interactive ask + rule recording (runs inside the prompt turn). */
-    async promptAndRecord(req) {
+    async promptAndRecord(req, state) {
         if (!this.promptFn) {
             return { approved: false, reason: "interactive approval backend has no prompt function" };
         }
         const result = await this.promptFn(req);
         const scope = result.scope ?? (result.always ? "session" : "once");
+        const activeState = this.isActiveSessionState(req.sessionId, state) ? state : null;
+        const context = activeState ?? (!req.sessionId ? this.legacyContext : null);
         // Path narrowing only rides on an APPROVE: a path-scoped deny is confusing
         // (deny stays tool-wide). pathScope is ignored by buildProjectRule for
         // non-file tools / when absent.
         const ruleOpts = result.approved
-            ? { pathScope: result.pathScope, cwd: this.cwd ?? undefined }
+            ? { pathScope: result.pathScope, cwd: context?.cwd ?? undefined }
             : undefined;
         if (scope === "session" && result.always) {
+            if (!activeState) {
+                rootPermLogger.warn("permission.session_remember_ignored", {
+                    cat: "permission",
+                    tool: req.toolName,
+                    reason: req.sessionId ? "session_closed" : "missing_session_id",
+                });
+                return result;
+            }
             // Narrow to the operation (Bash → head command, file tools → path scope)
             // so the session grant is scoped, not tool-wide. A rule with no
             // argsPattern keeps the prior tool-granularity behavior.
             const rule = buildProjectRule(req.toolName, req.args, ruleOpts);
             if (rule) {
-                const target = result.approved ? this.sessionAllowRules : this.sessionDenyRules;
+                const target = result.approved ? activeState.allowRules : activeState.denyRules;
                 const dup = target.some((r) => r.tool === rule.tool &&
                     JSON.stringify(r.argsPattern) === JSON.stringify(rule.argsPattern));
                 if (!dup) {
@@ -225,23 +302,23 @@ export class InteractiveApprovalBackend {
             // We only persist allow rules — denies stay session-only because a
             // persisted deny is harder to recover from than a session deny.
             const rule = buildProjectRule(req.toolName, req.args, ruleOpts);
-            if (rule && this.cwd) {
+            if (rule && context?.cwd) {
                 try {
-                    persistProjectRule(this.cwd, rule);
+                    persistProjectRule(context.cwd, rule);
                     // Dedup against the in-memory list using the same equality used by
                     // persistProjectRule so re-prompts on the same tool/argsPattern
                     // don't bloat the live rule set.
-                    const dup = this.savedProjectRules.some((r) => r.tool === rule.tool &&
+                    const dup = context.savedProjectRules.some((r) => r.tool === rule.tool &&
                         r.decision === rule.decision &&
                         JSON.stringify(r.argsPattern) === JSON.stringify(rule.argsPattern));
                     if (!dup)
-                        this.savedProjectRules.push(rule);
-                    this.onProjectRules?.(this.savedProjectRules);
+                        context.savedProjectRules.push(rule);
+                    context.onProjectRules?.(context.savedProjectRules);
                     rootPermLogger.info("permission.persist", {
                         cat: "permission",
                         tool: rule.tool,
                         decision: rule.decision,
-                        totalProjectRules: this.savedProjectRules.length,
+                        totalProjectRules: context.savedProjectRules.length,
                         duplicate: dup,
                     });
                 }
@@ -258,11 +335,11 @@ export class InteractiveApprovalBackend {
             // Also seed the session allow list (operation-scoped) so the rest of
             // this REPL session benefits even if the classifier path doesn't pick
             // the rule up immediately.
-            if (rule) {
-                const dup = this.sessionAllowRules.some((r) => r.tool === rule.tool &&
+            if (rule && activeState) {
+                const dup = activeState.allowRules.some((r) => r.tool === rule.tool &&
                     JSON.stringify(r.argsPattern) === JSON.stringify(rule.argsPattern));
                 if (!dup)
-                    this.sessionAllowRules.push(rule);
+                    activeState.allowRules.push(rule);
             }
         }
         return result;
@@ -452,6 +529,12 @@ export function getInteractiveApprovalBackend() {
     }
     return _interactiveBackend;
 }
+export function openInteractiveApprovalSession(sessionId) {
+    getInteractiveApprovalBackend().openSession(sessionId);
+}
+export function clearInteractiveApprovalSession(sessionId) {
+    getInteractiveApprovalBackend().clearSession(sessionId);
+}
 export function setInteractiveApprovalFn(fn) {
     getInteractiveApprovalBackend().setPromptFn(fn);
 }
@@ -896,9 +979,7 @@ export class PermissionClassifier {
         let result;
         try {
             const baseDescription = this.describeToolCall(toolName, args);
-            const description = reason
-                ? `${baseDescription}\n\nReason (from pre_tool_use hook): ${reason}`
-                : baseDescription;
+            const description = reason ? `${baseDescription}\n\nReason:\n${reason}` : baseDescription;
             result = await this.approvalBackend.requestApproval({
                 ...(opts?.sessionId ? { sessionId: opts.sessionId } : {}),
                 toolName,

package/dist/tool-system/registry.js

@@ -1,7 +1,7 @@
 /**
  * Unified tool registry — built-in tools + MCP tools.
  */
-import { ConfigError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError } from "../exceptions.js";
+import { ConfigError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, } from "../exceptions.js";
 import { BUILTIN_TOOLS } from "./builtin/index.js";
 import { validateToolMetadata } from "./validate-tool-metadata.js";
 /**
@@ -22,7 +22,9 @@ export class ToolRegistry {
         if (selectedNames) {
             const unknown = [...selectedNames].filter((name) => !availableNames.has(name));
             if (unknown.length > 0) {
-                throw new ConfigError(`Unknown built-in tool(s): ${unknown.join(", ")}`, { unknownBuiltinTools: unknown });
+                throw new ConfigError(`Unknown built-in tool(s): ${unknown.join(", ")}`, {
+                    unknownBuiltinTools: unknown,
+                });
             }
         }
         for (const tool of BUILTIN_TOOLS) {
@@ -120,12 +122,18 @@ export class ToolRegistry {
             // 各取所有,缺的字段为 undefined。
             const contentBlocks = "contentBlocks" in result ? result.contentBlocks : undefined;
             const sandbox = "sandbox" in result ? result.sandbox : undefined;
+            const sensitive = "sensitive" in result ? result.sensitive : undefined;
+            const displayResult = "displayResult" in result ? result.displayResult : undefined;
+            const transcriptResult = "transcriptResult" in result ? result.transcriptResult : undefined;
             return {
                 id,
                 toolName: name,
                 result: result.result ?? (contentBlocks ? "(image)" : ""),
                 contentBlocks,
                 sandbox,
+                sensitive,
+                displayResult,
+                transcriptResult,
             };
         }
         catch (err) {
@@ -133,8 +141,7 @@ export class ToolRegistry {
             parentSignal?.removeEventListener("abort", onParentAbort);
             // Always return error as ToolResult, never throw
             let errorMsg;
-            const isAbort = err?.name === "AbortError" ||
-                parentSignal?.aborted === true;
+            const isAbort = err?.name === "AbortError" || parentSignal?.aborted === true;
             if (err instanceof ToolTimeoutError) {
                 errorMsg = `Tool timed out after ${timeout}ms: ${name}`;
             }

package/dist/tool-system/tool-result-redaction.d.ts

@@ -0,0 +1,7 @@
+import type { Message, ToolResult } from "../types.js";
+export declare const SENSITIVE_TOOL_RESULT_PLACEHOLDER = "[credential value withheld]";
+export declare function toolResultDisplayText(result: ToolResult): string | undefined;
+export declare function toolResultTranscriptText(result: ToolResult): string | undefined;
+export declare function toolResultForDisplay(result: ToolResult): ToolResult;
+export declare function toolResultsForDisplay(results: ToolResult[]): ToolResult[];
+export declare function redactSensitiveToolResultsInMessages(messages: Message[], redactions: ReadonlyMap<string, string>): Message[];

package/dist/tool-system/tool-result-redaction.js

@@ -0,0 +1,48 @@
+export const SENSITIVE_TOOL_RESULT_PLACEHOLDER = "[credential value withheld]";
+export function toolResultDisplayText(result) {
+    if (!result.sensitive)
+        return result.result;
+    return result.displayResult ?? result.transcriptResult ?? SENSITIVE_TOOL_RESULT_PLACEHOLDER;
+}
+export function toolResultTranscriptText(result) {
+    if (!result.sensitive)
+        return result.result;
+    return result.transcriptResult ?? result.displayResult ?? SENSITIVE_TOOL_RESULT_PLACEHOLDER;
+}
+export function toolResultForDisplay(result) {
+    if (!result.sensitive)
+        return result;
+    const { displayResult: _displayResult, transcriptResult: _transcriptResult, ...rest } = result;
+    return {
+        ...rest,
+        result: toolResultDisplayText(result),
+        contentBlocks: undefined,
+    };
+}
+export function toolResultsForDisplay(results) {
+    return results.map((result) => toolResultForDisplay(result));
+}
+export function redactSensitiveToolResultsInMessages(messages, redactions) {
+    if (redactions.size === 0)
+        return messages;
+    let changed = false;
+    const out = messages.map((message) => {
+        if (!Array.isArray(message.content))
+            return message;
+        let contentChanged = false;
+        const content = message.content.map((block) => {
+            if (block.type !== "tool_result")
+                return block;
+            const replacement = typeof block.tool_use_id === "string" ? redactions.get(block.tool_use_id) : undefined;
+            if (replacement === undefined)
+                return block;
+            contentChanged = true;
+            return { ...block, content: replacement };
+        });
+        if (!contentChanged)
+            return message;
+        changed = true;
+        return { ...message, content };
+    });
+    return changed ? out : messages;
+}

package/dist/tool-system/workspace-bridge.d.ts

@@ -0,0 +1,11 @@
+import type { SessionWorkspace } from "../types.js";
+/**
+ * WorkspaceBridge — host-backed session workspace switching.
+ *
+ * Desktop implements this through Electron main so model-initiated switches use
+ * the same service path as the UI workspace switcher. Undefined in headless or
+ * non-desktop contexts.
+ */
+export interface WorkspaceBridge {
+    switch(target: string): Promise<SessionWorkspace>;
+}

package/dist/tool-system/workspace-bridge.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -43,7 +43,15 @@ export interface ToolCall {
 export interface ToolResult {
     id: string;
     toolName: string;
+    /**
+     * Sensitive tool results keep `result` as the model-facing value for the
+     * current model round only. Persisted/displayed/streamed observers must use
+     * `transcriptResult`/`displayResult` (or the standard placeholder) instead.
+     */
+    sensitive?: boolean;
     result?: string;
+    displayResult?: string;
+    transcriptResult?: string;
     /**
      * 结构化结果块(目前仅图片)。存在时优先于 `result` 用作发给 LLM 的
      * tool_result content —— view_image 用它把本地图片以 image ContentBlock
@@ -54,13 +62,13 @@ export interface ToolResult {
     error?: string;
     isError?: boolean;
     /**
-     * Set by tools that execute under the sandbox (Bash / background shell /
-     * worktree) so the UI can show whether THIS call was isolated. `backend`
+     * Set by command-executing tools with sandbox visibility (Bash / background
+     * shell / worktree / PowerShell) so the UI can show whether THIS call was isolated. `backend`
      * "off" means the command ran un-sandboxed (we surface it explicitly so the
      * user sees "未隔离" rather than guessing from an absent badge); "seatbelt"
      * / "bwrap" mean OS-level isolation applied. `network` is the policy that
-     * was in force (absent when off). Tools that don't touch the sandbox leave
-     * this undefined and the UI renders no badge.
+     * was in force (absent when off). Tools with no sandbox visibility leave this
+     * undefined and the UI renders no badge.
      */
     sandbox?: {
         backend: "off" | "seatbelt" | "bwrap";
@@ -97,6 +105,12 @@ export interface RegisteredTool {
     inputSchema: Record<string, unknown>;
     source: ToolSource;
     serverName?: string;
+    /**
+     * Declarative UI/metadata hint for hosts, docs, and capability listings.
+     * It is not an execution-policy input: PermissionClassifier does not read
+     * RegisteredTool and runtime decisions come from explicit rules, permission
+     * mode, approval backend, and tool-specific gates.
+     */
     permissionDefault: PermissionDecision;
     isConcurrencySafe?: boolean;
     isReadOnly?: boolean;
@@ -139,13 +153,51 @@ export type SessionStatus = "active" | "paused" | TerminalReason;
 /** Which host/context created a session — used by the desktop disk-rebuild to
  *  filter the sidebar (only `desktop` + `automation` are shown). */
 export type SessionOrigin = "desktop" | "tui" | "automation" | "subagent";
+export interface SessionWorkspace {
+    root: string;
+    kind: "main" | "worktree";
+    worktree?: {
+        path: string;
+        branch: string;
+        baseRef: string;
+        createdBy: "codeshell";
+    };
+}
+export interface ContextUsageAnchor {
+    promptTokens: number;
+    messageCount: number;
+    estimateAtAnchor?: number;
+    recordedAt: number;
+    provider?: string;
+    model?: string;
+}
 export interface SessionState {
     sessionId: string;
     cwd: string;
+    /** Current session workspace pointer. Absent only on legacy state.json files. */
+    workspace?: SessionWorkspace;
     startedAt: number;
     model: string;
     provider: string;
+    /**
+     * Legacy/model-scoped usage summary. Some flows reset this accounting window
+     * (for example model switches), so it must not drive whole-session metrics.
+     */
     tokenUsage: TokenUsage;
+    /**
+     * Last provider-reported prompt-token count for the current context window.
+     * Separate from cumulative tokenUsage; used only to seed context-size estimates
+     * before the next provider response.
+     */
+    contextUsageAnchor?: ContextUsageAnchor;
+    /**
+     * Monotonic prompt-cache counters for the whole session. These only increase
+     * from session start and are separate from the resettable tokenUsage window.
+     * Optional on legacy state.json files; SessionManager normalizes them on load.
+     */
+    cumulativePromptTokens?: number;
+    cumulativeCacheReadTokens?: number;
+    cumulativeCacheCreationTokens?: number;
     turnCount: number;
     /**
      * Conversation-turn counter where ONE user message = one turn (incremented in
@@ -281,10 +333,14 @@ export interface TaskInfo {
     activeForm?: string;
     status: "pending" | "in_progress" | "completed" | "stopped";
 }
+export type PromptTokenSource = "provider_usage" | "anchor_delta" | "anchor_rescale" | "calibrated_estimate" | "heuristic_estimate" | "session_cumulative";
+export type PromptTokenConfidence = "high" | "medium" | "low";
 export type StreamEvent = {
     type: "session_started";
     sessionId: string;
     promptTokens: number;
+    promptTokensSource?: PromptTokenSource;
+    promptTokensConfidence?: PromptTokenConfidence;
 } | {
     type: "session_title";
     sessionId: string;
@@ -292,6 +348,7 @@ export type StreamEvent = {
 } | {
     type: "stream_request_start";
     turnNumber: number;
+    messageId?: string;
     agentId?: string;
 } | {
     type: "steer_injected";
@@ -318,6 +375,7 @@ export type StreamEvent = {
 } | {
     type: "assistant_message";
     message: Message;
+    messageId?: string;
     agentId?: string;
 } | {
     type: "turn_complete";
@@ -348,6 +406,7 @@ export type StreamEvent = {
 } | {
     type: "tombstone";
     messageId: string;
+    agentId?: string;
 } | {
     type: "task_update";
     tasks: TaskInfo[];
@@ -389,15 +448,19 @@ export type StreamEvent = {
 } | {
     type: "tool_summary";
     summary: string;
+    toolCallIds?: string[];
+    agentId?: string;
 } | {
     type: "context_compact";
-    strategy: "micro" | "summary" | "window" | "snip" | "emergency";
+    strategy: "micro" | "summary" | "window" | "snip" | "emergency" | "compacted";
     before: number;
     after: number;
     agentId?: string;
 } | {
     type: "usage_update";
     promptTokens: number;
+    promptTokensSource?: PromptTokenSource;
+    promptTokensConfidence?: PromptTokenConfidence;
     /**
      * Provider-reported prompt-cache counts, forwarded so the UI can show a
      * cache hit rate in the context-ring tooltip. Present only when the LLM
@@ -407,6 +470,24 @@ export type StreamEvent = {
      */
     cacheReadTokens?: number;
     cacheCreationTokens?: number;
+    /**
+     * Prompt-cache metrics for the current turn only. These are reset at the
+     * start of each turn-loop iteration and sum every LLM response in that
+     * turn, including max-token continuations.
+     */
+    singleTurnPromptTokens?: number;
+    singleTurnCacheReadTokens?: number;
+    singleTurnCacheCreationTokens?: number;
+    singleTurnCacheHitRate?: number;
+    /**
+     * Whole-session monotonic prompt-cache counters/rate. Unlike the legacy
+     * session* fields below, these are not derived from the resettable
+     * tokenUsage accounting window.
+     */
+    cumulativePromptTokens?: number;
+    cumulativeCacheReadTokens?: number;
+    cumulativeCacheCreationTokens?: number;
+    cumulativeCacheHitRate?: number;
     /**
      * SESSION-CUMULATIVE cache counts (sum across every LLM response this
      * session, across runs and turns), emitted from the engine's turn