Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

420 KB
Raw Blame
/**
 * ClaudeCodeAgent — Claude Code 的 maker-core 一等公民实现。
 *
 * 设计来源:从 desktop apps/desktop/src/main/vendor/claude/runtime.ts 搬迁过来,
 * 去除了 desktop-only 的依赖(in-process MCP server、systemPromptLoader)。
 *
 * systemPrompt 三段:
 * - [1] cc preset (SDK 自带, 不可见)
 * - [2] MAKER_SYSTEM_PROMPT_APPEND (maker engine, system-prompt-append.md)
 * - [3] runtimeConfig.systemPrompt (host runtime, host 维护的 .md)
 *
 * Stage 2 B: 运行时切换 setModel / setEffort / setPermissionMode 已接通
 * (Query.setModel / applyFlagSettings({ effortLevel }) / Query.setPermissionMode)。
 *
 * 与 vendor/claude/runtime.ts 的差异:
 * - env 三段组装走 maker-core 的 AuthAdapter.getAuthEnv() + AgentRuntimeConfig
 * - mcpServers 字段由 host 注入的 mcpProviders 生成(具体 MCP 不在 maker-core 内)
 * - systemPrompt.append 由 maker-core 拼接四段(preset / engine / host产品级 / per-call)
 * - vendorOptions.source / forkSession / resumeSessionAt / extraSystemPrompt / onStderrLine
 *   仍然通过 vendorOptions 透传(与 vendor 版语义一致)
 *
 * 文件结构对标 codex/index.ts,方便对照阅读。
 */

import { LIBRARY_READ_ROOT, withLibraryNativeReadContext } from '../shared/library-native-read.js';
import { promises as fs } from 'node:fs';
import { randomUUID } from 'node:crypto';
import os from 'node:os';
import path from 'node:path';

import {
  query as sdkQuery,
  forkSession as sdkForkSession,
} from '@anthropic-ai/claude-agent-sdk';
import type {
  Query,
  CanUseTool,
  HookCallback,
  HookCallbackMatcher,
  HookEvent,
  McpServerConfig,
  PermissionUpdate,
  PreToolUseHookInput,
  Settings,
} from '@anthropic-ai/claude-agent-sdk';
import { discoverSubagentDefinitions } from './subagent-definitions.js';
import { spawnObservedClaudeProcess } from './local-process-spawn.js';
import { claudeMcpServerToolsReport, type ClaudeMcpServerStatusEntry } from './mcp-server-tools.js';
import {
  reportSubagentModelDiagnostics,
  resolveSubagentModelDefault,
  type ResolveSubagentModelDefaultResult,
} from './subagent-model-default.js';
import {
  buildClaudeSubagentModelGuardHooks,
  claudeSubagentModelWithContextWindow,
  normalizeClaudeSubagentModel,
} from './subagent-model-access.js';
import Anthropic, { APIError } from '@anthropic-ai/sdk';

import {
  BaseAgent,
  LOCAL_AGENT_CLIENT,
  OneShotError,
  AgentNotAuthenticatedError,
  AgentStartupStoppedError,
  AgentStartupCleanupPendingError,
  TurnPermissionPolicyUnsupportedError,
  PINNED_SKILL_INVOCATION,
  ASYNC_QUESTION_ANSWER,
  DEVICE_HOSTED_GUEST_ROUTE_HEADER,
  type AgentSessionHandle,
  type AgentDeps,
  type StartSessionOptions,
  type OneShotOptions,
  type RefreshLocalModelsOptions,
  type SendOptions,
  type TurnPermissionPolicy,
} from '../base-agent.js';
import { preparePinnedClaudeSkillInvocation } from './pinned-skill-invocation.js';
import { isBotMcpServerAllowed } from '../shared/bot-runtime-policy.js';
import { SYSTEM_PROMPT_APPEND as MAKER_SYSTEM_PROMPT_APPEND } from './system-prompt-append.js';
import { MAKER_MEMORY_RULES } from '../../memory/system-prompt.js';
import {
  CONTACTS_RULES_DISABLED,
  CONTACTS_RULES_ENABLED,
} from '../../contacts/system-prompt.js';
import { MemoryFlushController } from '../../memory/flush-controller.js';
import { resolveMemoryScopeKey } from '../../memory/scope-resolver.js';
import type {
  Capabilities,
  EffortDescriptor,
  PermissionModeDescriptor,
} from '../../types/capabilities.js';
import type {
  AgentEvent,
  InteractionResolver,
  InteractionRequest,
  InteractionDecision,
  InteractionDismissedEvent,
  AskUserQuestionItem,
  UsageSnapshot,
  RewindFilesResult,
  RewindCommitOptions,
  ForkSdkSessionOptions,
  ForkSdkSessionResult,
} from '../../types/events.js';
import { isTerminalAgentErrorEvent } from '../../types/events.js';
import type { UserMessage } from '../../types/common.js';
import {
  capabilitySelectionAddedByPlanEdit,
  findClaudeMcpCapabilityRoute,
  isCapabilityRouteInvocationAllowed,
} from '../../types/capability-routing.js';
import { createAsyncQueue, type AsyncQueue } from '../shared/async-queue.js';
import { AutoCompactController, isDeterministicHostCompactFailure } from '../shared/auto-compact-controller.js';
import { resolveMcpToolTarget } from '../shared/mcp-tool-target.js';
import { scanClaudeAtResources, scanClaudeSlashCommands } from '../shared/palette-scanner.js';
import { scanRemoteClaudeSkills } from '../shared/remote-skill-scanner.js';
// scanClaudeSlashCommands 仍是 listAgentSkills 的实际数据源, 名字保留(它扫的是 commands+skills 两类)。
import { UsageTracker } from '../shared/usage-tracker.js';
import { getDefaultImageResizer } from '../shared/image-resizer.js';
import { formatManagedImageReferences } from '../shared/managed-image-reference.js';
import { pickTurnStartStatus, type OneShotState } from '../shared/turn-start-phrases.js';
import { ToolLoopGuard } from '../shared/loop-guard.js';
import {
  ToolLoopMonitor,
  type HardToolLoopVerdict,
  type ToolLoopReviewBudget,
} from '../shared/tool-loop-review.js';
import {
  applyExploreInheritCapEnv,
  applyClaudeDesktopEntrypoint,
  applySubagentModelEnv,
  buildClaudeEnv,
  applyClaudeContextWindow,
  exploreInheritCapEnvNeedsSync,
  REMOTE_ROUTE_OVERRIDE_ENV_KEYS,
} from './env-builder.js';
import {
  findWorkspaceSettingsOverride,
  workspaceConfigChangeBlockReason,
  workspaceSettingsOverrideMessage,
} from './workspace-settings-guard.js';
import { buildClaudeFlagSettings } from './flag-settings.js';
import {
  buildClaudeAskUserQuestionCallerProvenanceHooks,
  buildClaudeDisallowedTools,
  buildClaudeOrcaCallerProvenanceHooks,
  buildClaudeLocalToolGuardHooks,
  buildClaudeRemoteOrcaCallerGuards,
  buildClaudeRemoteRootOnlyToolGuards,
  buildClaudeRemoteToolGuards,
  mergeClaudeHookSets,
} from './capability-routing.js';
import { normalizeBuiltinToolForAutoReview } from './auto-review-policy.js';
import {
  annotatePermissionRequestForAutoReview,
  composeAutoReviewIntentWithApprovedPlan,
  composeAutoReviewIntentWithClarification,
  createAutoReviewConfirmUndeliveredNotice,
  createAutoReviewUnavailableNotice,
  extractAutoReviewUserIntent,
  appendAutoReviewUserIntent,
  normalizeAutoReviewUserIntent,
  createAutoReviewActionContext,
  type AutoReviewUserIntent,
  isAutoReviewUnavailableMetadata,
  isSystemPermissionDenialReason,
  formatPermissionDenial,
  resolveAutoReviewDecision,
  withAutoReviewContext,
  toolAutoReviewAction,
  type AutoReviewDecision,
} from '../shared/auto-review-decision.js';
import type { ReviewableAction } from '../shared/auto-review.js';
import {
  resolveAgentCredentialMode,
  resolveEffectiveCredentialModeFromAuthSource,
} from '../credential-mode.js';
import { repairForkedClaudeSessionJsonl, type RepairForkedClaudeJsonlResult } from './fork-jsonl-repair.js';
import { ensureClaudeTranscriptInWorkingDir } from './transcript-relocation.js';
import { findClaudeSessionJsonl } from './claude-projects-fs.js';
import { normalizeClaudeSessionJsonlToolIds } from './jsonl-tool-id-normalize.js';
import { isClaudeResumeSessionNotFound } from './invalid-resume.js';
import { translateSdkMessage, newRuntimeState, type TurnState, type RuntimeState } from './translator.js';
import { resetClaudeGenerationTiming } from './generation-timing.js';
import type { Effort, PermissionMode } from '../../types/common.js';
import { clampEffortToSupported } from '@cindy/model-providers/effort-resolution';
import type {
  ScanAtResourcesOptions,
  ScanAtResourcesResult,
  AgentBuiltinCommand,
  ListAgentSkillsOptions,
  ListAgentSkillsResult,
  ListRuntimeSkillsOptions,
} from '../../types/palette.js';
import { CLAUDE_CODE_AGENT_COMMANDS } from './commands.js';
import type {
  ListCustomizationsOptions,
  ListCustomizationsResult,
} from '../../types/customizations.js';
import type {
  MemoryStatus,
  MemorySetResult,
  MemoryResetResult,
} from '../../types/memory.js';
import type { McpProviderContext } from '../../interfaces/mcp-provider.js';
import { claudeDisabledSkillOverrides, snapshotDisabledSkillLaunch, currentDisabledSkillLaunchPaths } from '../shared/skill-activation.js';
import { scanClaudeCustomizations, scanClaudeRuntimeSkills } from './customization-scanner.js';
import { prepareManagedSkillPlugins } from './managed-skill-plugins.js';
import { resolveAllowedManagedSkills, snapshotManagedSkillGrants } from '../shared/managed-skill-policy.js';
import {
  REVIEW_SENSITIVE_CREDENTIAL_GLOB_PATTERNS,
  isReviewSensitiveCredentialSelector,
} from '../shared/sensitive-credential-paths.js';
import {
  assertReviewMessageContentPaths,
  buildReviewReadGrants,
  resolveReviewReadPath,
  type ReviewReadGrant,
} from '../shared/review-read-scope.js';

import {
  DEVICE_HOSTED_DISALLOWED_CLAUDE_TOOLS,
  DEVICE_HOSTED_EXEC_MCP_SERVER,
  DEVICE_HOSTED_GUEST_CLAUDE_TOOLS,
  deviceHostedBuiltinToolName,
  deviceHostedClaudeNote,
  deviceHostedGuestAgentDenial,
  deviceHostedGuestClaudeMdExcludes,
  deviceHostedMcpUrl,
  deviceHostedSubagentAllows,
  parseClaudeAgentToolRule,
  type DeviceHostedAgentToolRule,
} from '../shared/device-hosted.js';
import { isSensitiveCredentialPath } from '../shared/sensitive-credential-paths.js';
import { classifyShellCommand } from '../shared/auto-review.js';

type ClaudeSdkEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';

export function buildClaudeSystemPromptAppend(parts: {
  makerMemoryRules?: string;
  contactsRules?: string;
  ghostRosterPrompt?: string;
  hostSystemPrompt?: string;
  makerMemoryIndex?: string;
  botProfilePrompt?: string;
  botProfileContextPrompt?: string;
  botUserProfilePrompt?: string;
  userPrompt?: string;
  answerDeliveryPrompt?: string;
  /** 设备托管:项目在哪台电脑、文件与命令工具是哪些。 */
  deviceHostedNote?: string;
}): string {
  return [
    parts.botProfilePrompt,
    parts.answerDeliveryPrompt,
    MAKER_SYSTEM_PROMPT_APPEND,
    parts.deviceHostedNote,
    parts.makerMemoryRules,
    parts.contactsRules,
    parts.ghostRosterPrompt,
    parts.botProfileContextPrompt,
    parts.hostSystemPrompt,
    parts.makerMemoryIndex,
    parts.botUserProfilePrompt,
    parts.userPrompt,
  ]
    .filter((part): part is string => !!part && part.trim().length > 0)
    .join('\n\n');
}

/**
 * 公开短 ID → Claude SDK 实际接受的字符串。
 * SDK 需要 [1m] beta 通道后缀,这是 SDK 细节,不外泄给调用方。
 *
 * haiku 不再重写成日期快照 id:目录短 id(claude-haiku-4-5)就是 Anthropic 官方别名,
 * 上游(订阅直连 / 网关)均接受;带版本号的别名不存在跨代漂移,同号新快照跟随即可。
 *
 * [1m] 后缀的唯一决策依据是目录(providers.json)的 contextWindow:
 *   - 窗口已知且 ≥1M → 带 [1m];已知且 <1M → 绝不带(已带的强制剥掉)。
 *     窗口 <1M 却带 [1m] 会让 cc-code 的 has1mContext 把窗口判成 1M,撑大
 *     auto-compact 阈值 → 对话冲过上游真实上限后空转,会话"假死"(折扣 GPT 实踩)。
 *     真实窗口口径已由 catalog 经 env-builder(XDT_MAKER_MODEL_CONTEXT_WINDOWS,
 *     id 与 id[1m] 双键)注入 cc,[1m] 不再承担窗口语义,只是 wire 串的一部分。
 *   - 窗口未知(目录外模型 / 未传窗口的老调用方)→ 回落下方硬编码映射链,行为不变。
 *     这样"新增模型要不要 [1m]"只改 OSS 目录即可,不必发版。
 *
 * 一律走显式版本号,不要用 'opus' / 'sonnet' 这类别名:
 * cc-code 二进制升级后别名指针会漂移到下一代模型(例如 'opus' 从 4.6 跳到 4.7),
 * 导致调用方明明选了 4.6 却实际命中 4.7,且只有"上一代"模型踩这个坑。
 */
export function toSdkModelString(model: string, contextWindow?: number | null): string {
  if (typeof contextWindow === 'number' && Number.isFinite(contextWindow) && contextWindow > 0) {
    const bare = model.endsWith('[1m]') ? model.slice(0, -'[1m]'.length) : model;
    return contextWindow >= 1_000_000 ? `${bare}[1m]` : bare;
  }
  return legacyToSdkModelString(model);
}

/** 目录窗口未知时的兜底映射链(与窗口规则引入前一致;haiku 日期重写已移除,见函数头)。 */
function legacyToSdkModelString(model: string): string {
  // #3764:含命名空间前缀(provider/…)的 id 是自定义/网关 Provider 的路由键,不属于
  // 本兜底链的官方裸 id 知识范围 —— 除下面显式列出的已知命名空间条目外一律逐字透传。
  // 此前 includes('sonnet') 的含糊匹配会把 `cindy/claude-sonnet-5` 改写成 `…[1m]`,
  // 而 `cindy/claude-opus-5` 透传:同一自定义 Provider 的两个模型 wire id 形态不
  // 对称,被上游按白名单逐一 403(官方 Claude Code CLI 对同上游是逐字发送、两个
  // 模型均可用)。窗口已知的路径不经过本函数,不受影响。
  if (model.includes('/')) {
    // 折扣GPT(codex/* 经折扣网关)真实上下文上限远低于 1M(catalog cc 侧 = 272k),
    // 绝不能带 [1m]: cc-code 的 has1mContext 只要在 model 串里见到 [1m] 就把窗口判成
    // 1M(getContextWindowForModel 直接 return 1_000_000), 撑大 auto-compact 阈值 →
    // 对话冲过折扣网关真实上限(~24 万 token)后空转, 用户侧表现为会话"假死"。
    // 路由不依赖 [1m]: isAnthropicWireModel 只按 claude-/sonnet/opus/haiku/fable 前缀
    // 判定, codex/ 前缀始终走 provider 网关, 去掉 [1m] 不改变路由判定;
    // 真实窗口由 catalog 经 translator 窗口口径注入(=272k)。
    if (model === 'codex/gpt-5.5' || model === 'codex/gpt-5.4') return model;
    if (model === 'codex/gpt-5.6-sol' || model === 'codex/gpt-5.6-terra') return model;
    // DeepSeek / GLM 的 [1m] 是历史兼容路由后缀; 上下文大小另走 maker capabilities。
    if (model === 'deepseek/deepseek-v4-pro' || model === 'deepseek/deepseek-v4-flash') {
      return `${model}[1m]`;
    }
    if (model === 'z-ai/glm-5.2') return `${model}[1m]`;
    return model;
  }
  if (model === 'claude-opus-5') return 'claude-opus-5[1m]';
  if (model.includes('opus-4-8')) return 'claude-opus-4-8[1m]';
  if (model.includes('opus-4-7')) return 'claude-opus-4-7[1m]';
  if (model.includes('opus-4-6')) return 'claude-opus-4-6[1m]';
  // fable-5 比照 Opus 走 1M beta 通道; 显式版本号, 不用别名。
  if (model === 'claude-fable-5') return 'claude-fable-5[1m]';
  // sonnet 同样必须显式版本号:曾经的裸 'sonnet[1m]' 在 Sonnet 5 上线后仍被二进制
  // 解析成 claude-sonnet-4-6,用户选 Sonnet 5 实际命中 4.6(2026-07 实踩)。
  // 目录内 sonnet 系列均为 1M 窗口(catalog providers.json),统一走 [1m] beta 通道。
  if (model === 'claude-sonnet-5') return 'claude-sonnet-5[1m]';
  if (model === 'claude-sonnet-4-6') return 'claude-sonnet-4-6[1m]';
  // 兜底:未来新增裸 sonnet 型号在此映射更新前,也透传显式 id 而非裸别名。
  if (model.includes('sonnet')) return `${model}[1m]`;
  // 官方 gpt-5.5 / gpt-5.4 真实支持 1M, 走 [1m] beta 通道。
  if (model === 'gpt-5.5' || model === 'gpt-5.4') return `${model}[1m]`;
  // DeepSeek 裸 id 的 [1m] 同上为历史兼容路由后缀。
  if (model === 'deepseek-v4-flash') return `${model}[1m]`;
  return model;
}

function isProviderRoutedModel(model: string): boolean {
  return !model.startsWith('claude-');
}

/** URL → host(路由决策日志用,失败返回 undefined,不抛)。 */
function hostOfUrl(url: string | undefined): string | undefined {
  if (!url) return undefined;
  try {
    return new URL(url).host;
  } catch {
    return undefined;
  }
}

/**
 * Resolve the path that a Claude structured write will actually follow. New files
 * inherit the real path of their nearest existing ancestor, so symlinks/junctions
 * inside an authorized root cannot hide an out-of-root target. A lexically existing
 * but unresolvable ancestor is evidence failure, not permission to skip upward.
 */
async function resolveClaudeFileWriteTarget(
  workingDir: string,
  targetPath: string | undefined,
): Promise<string | null> {
  if (!targetPath) return null;
  const absoluteTarget = path.resolve(workingDir, targetPath);
  try {
    return await fs.realpath(absoluteTarget);
  } catch {
    try {
      await fs.lstat(absoluteTarget);
      return null;
    } catch (lstatError) {
      const code = (lstatError as NodeJS.ErrnoException).code;
      if (code !== 'ENOENT' && code !== 'ENOTDIR') return null;
    }
    let ancestor = path.dirname(absoluteTarget);
    for (let depth = 0; depth < 64; depth += 1) {
      try {
        return path.join(await fs.realpath(ancestor), path.relative(ancestor, absoluteTarget));
      } catch {
        try {
          await fs.lstat(ancestor);
          return null;
        } catch (lstatError) {
          const code = (lstatError as NodeJS.ErrnoException).code;
          if (code !== 'ENOENT' && code !== 'ENOTDIR') return null;
        }
        const parent = path.dirname(ancestor);
        if (parent === ancestor) return null;
        ancestor = parent;
      }
    }
    return null;
  }
}

async function resolveClaudeWritableRoots(roots: readonly string[]): Promise<string[]> {
  const resolved = await Promise.all(roots.map(async (root) => {
    try {
      return await fs.realpath(path.resolve(root));
    } catch {
      return null;
    }
  }));
  return [...new Set(resolved.filter((root): root is string => root !== null))];
}

function bindClaudeFileWriteTarget(
  toolName: string,
  input: Record<string, unknown>,
  resolvedPath: string | null | undefined,
): Record<string, unknown> {
  if (typeof resolvedPath !== 'string') return input;
  const pathField = toolName === 'NotebookEdit' ? 'notebook_path' : 'file_path';
  return { ...input, [pathField]: resolvedPath };
}

/**
 * 已知的 Claude 内置只读工具白名单(纯读、无本地写 / 无命令执行 / 无外部发送副作用)。
 *
 * 仅用于 canUseTool 在**没有** interactionResolver 这一异常分支下做 fail-closed 判定:
 * 命中白名单才放行, 其它工具(含未知工具、写文件 / 跑命令 / MCP 外发类)一律 deny。
 * 用**白名单**而非黑名单是刻意的安全设计 —— 未知 / 未来新增的工具默认落到 deny,
 * 不会因为"忘记把新危险工具登记进黑名单"而退回 fail-open。
 *
 * 注意边界: 这只影响 resolver 缺失(misconfiguration / 裸 handle 直用)时的**运行时准入**,
 * 不改变正常流程下送进模型的工具定义 / 可用性声明, 也不参与 system prompt 组装。
 * WebFetch / WebSearch 虽只读但会发起外部网络请求, 保守起见不列入白名单(缺 resolver 时 deny)。
 */
const READ_ONLY_CLAUDE_TOOLS: ReadonlySet<string> = new Set([
  'Read',
  'Glob',
  'Grep',
  'LS',
  'NotebookRead',
]);

/** canUseTool fail-closed 分支用: 判断工具是否属于已知只读工具(见上方白名单注释)。 */
function isReadOnlyClaudeTool(toolName: string): boolean {
  return READ_ONLY_CLAUDE_TOOLS.has(toolName);
}

function reviewGlobPatternEscapesScope(pattern: string): boolean {
  const value = pattern.trim();
  if (!value) return false;
  if (path.isAbsolute(value) || path.win32.isAbsolute(value)) return true;
  // Backslash escapes and character classes can spell a parent segment without
  // a literal "..". Reject those ambiguous forms, then inspect brace/extglob
  // branches for rooted paths while keeping common {ts,tsx} patterns usable.
  if (/[\\[\]]/.test(value) || value.includes('..')) return true;
  return /(^|[{(,|])(?:\/|[a-zA-Z]:\/)/.test(value);
}

function reviewFileSelectorIsAllowed(selector: unknown): selector is string {
  return (
    typeof selector === 'string' &&
    !reviewGlobPatternEscapesScope(selector) &&
    !isReviewSensitiveCredentialSelector(selector)
  );
}

async function resolveReviewReadToolInput(params: {
  toolName: string;
  toolInput: Record<string, unknown> | undefined;
  workingDir: string;
  grants: readonly ReviewReadGrant[];
}): Promise<Record<string, unknown> | null> {
  if (params.toolName === 'Glob') {
    if (!reviewFileSelectorIsAllowed(params.toolInput?.pattern)) return null;
  }
  if (
    params.toolName === 'Grep' &&
    params.toolInput?.glob !== undefined &&
    !reviewFileSelectorIsAllowed(params.toolInput.glob)
  ) {
    return null;
  }
  const keyByTool: Partial<Record<string, string>> = {
    Read: 'file_path',
    Glob: 'path',
    Grep: 'path',
    LS: 'path',
    NotebookRead: 'notebook_path',
  };
  const key = keyByTool[params.toolName];
  if (!key) return null;
  const raw = params.toolInput?.[key];
  const candidate =
    typeof raw === 'string' && raw.trim()
      ? path.resolve(params.workingDir, raw)
      : params.workingDir;
  const resolved = await resolveReviewReadPath(candidate, params.workingDir, params.grants);
  if (!resolved) return null;
  // The permission decision and the SDK tool execution must address the same
  // filesystem object. In particular, never hand a validated symlink back to
  // Read/Glob/Grep: it could be retargeted after this hook returns.
  return { ...(params.toolInput ?? {}), [key]: resolved };
}

/**
 * 把 maker-core 的 Effort clamp 到 Claude SDK 支持的档位 (ClaudeSdkEffort)。
 * Claude 没有 'minimal'(→ 'low') 与 'ultra'(→ 'max'; ultra 是 Codex GPT-5.6 专属档)。
 */
function isLoopbackEndpoint(value: string | undefined): boolean {
  if (!value) return false;
  try {
    const host = new URL(value).hostname.toLowerCase();
    return host === '127.0.0.1' || host === 'localhost' || host === '::1';
  } catch {
    return false;
  }
}

function clampEffortForClaude(e: Effort): ClaudeSdkEffort {
  if (e === 'minimal') return 'low';
  if (e === 'ultra') return 'max';
  return e;
}

function isUnsupportedClaudeEffortError(error: unknown): boolean {
  const message =
    error instanceof Error
      ? error.message
      : typeof error === 'string'
        ? error
        : '';
  return (
    /effort(?:Level|[ _-]level)/i.test(message) &&
    /\b(?:invalid|unsupported|not supported|unknown|unrecognized)\b/i.test(message)
  );
}

async function applyClaudeEffortFlagSettings(
  q: Query,
  effort: ClaudeSdkEffort,
  maxFallback: Exclude<ClaudeSdkEffort, 'max'>,
): Promise<ClaudeSdkEffort> {
  // Claude Code 2.1.219 accepts session-scoped `max` through apply_flag_settings.
  // Only an explicit effort-level rejection is compatibility evidence; transport
  // and process failures must keep their original failure semantics.
  try {
    await q.applyFlagSettings({ effortLevel: effort } as Settings);
    return effort;
  } catch (error) {
    if (effort !== 'max' || !isUnsupportedClaudeEffortError(error)) throw error;
    await q.applyFlagSettings({ effortLevel: maxFallback } as Settings);
    return maxFallback;
  }
}

function rawMentionText(block: { path: string; kind?: 'file' | 'dir' | 'agent' }): string {
  const suffix = block.kind === 'dir' && !block.path.endsWith('/') ? '/' : '';
  return `@${block.path}${suffix}`;
}

function quotedMentionText(block: { path: string; kind?: 'file' | 'dir' | 'agent' }): string {
  const suffix = block.kind === 'dir' && !block.path.endsWith('/') ? '/' : '';
  return `@"${(block.path + suffix).replace(/"/g, '\\"')}"`;
}

function hasMentionText(existingText: string, block: { path: string; kind?: 'file' | 'dir' | 'agent' }): boolean {
  return existingText.includes(rawMentionText(block)) || existingText.includes(quotedMentionText(block));
}

type ClaudeImageMediaType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';

type ClaudeSdkContentBlock =
  | {
      type: 'image';
      source: {
        type: 'base64';
        media_type: ClaudeImageMediaType;
        data: string;
      };
    }
  | { type: 'text'; text: string };

interface ClaudeInputImageResizer {
  process(absPath: string): Promise<string>;
  validateBuffer(data: Buffer): Promise<boolean>;
}

const CLAUDE_INLINE_IMAGE_MAX_ENCODED_BYTES = 5 * 1024 * 1024;

function base64EncodedByteLength(rawByteLength: number): number {
  return Math.ceil(rawByteLength / 3) * 4;
}

function detectClaudeImageMediaType(data: Buffer): ClaudeImageMediaType | null {
  if (
    data.length >= 8
    && data.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))
  ) {
    return 'image/png';
  }
  if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) {
    return 'image/jpeg';
  }
  if (data.length >= 6) {
    const signature = data.toString('ascii', 0, 6);
    if (signature === 'GIF87a' || signature === 'GIF89a') return 'image/gif';
  }
  if (
    data.length >= 12
    && data.toString('ascii', 0, 4) === 'RIFF'
    && data.toString('ascii', 8, 12) === 'WEBP'
  ) {
    return 'image/webp';
  }
  return null;
}

async function toClaudeImageBlock(
  imagePath: string,
  validateBuffer: (data: Buffer) => Promise<boolean>,
): Promise<ClaudeSdkContentBlock | null> {
  let handle: Awaited<ReturnType<typeof fs.open>> | undefined;
  try {
    handle = await fs.open(imagePath, 'r');
    const stat = await handle.stat();
    if (
      !stat.isFile()
      || stat.size <= 0
      || base64EncodedByteLength(stat.size) > CLAUDE_INLINE_IMAGE_MAX_ENCODED_BYTES
    ) {
      return null;
    }
    const data = await handle.readFile();
    if (
      data.length === 0
      || base64EncodedByteLength(data.length) > CLAUDE_INLINE_IMAGE_MAX_ENCODED_BYTES
    ) return null;
    const mediaType = detectClaudeImageMediaType(data);
    if (!mediaType) return null;
    if (!(await validateBuffer(data))) return null;
    const encodedData = data.toString('base64');
    return {
      type: 'image',
      source: {
        type: 'base64',
        media_type: mediaType,
        data: encodedData,
      },
    };
  } catch {
    return null;
  } finally {
    await handle?.close().catch(() => undefined);
  }
}

/**
 * 把 maker-core 的 UserMessage content 装配成 Claude SDK 接受的形式。
 * 图片按需压缩后统一发送为原生 image block;无法安全内联时回退为原有路径引用。
 */
export async function toClaudeSdkContent(
  content: UserMessage['content'],
  imageResizer: ClaudeInputImageResizer = getDefaultImageResizer(),
  readImagePathsLocally = true,
): Promise<string | ClaudeSdkContentBlock[]> {
  if (typeof content === 'string') return content;

  const textParts = content
    .filter((b) => b.type === 'text')
    .map((b) => b.text);
  const existingText = textParts.join('\n');
  const refs: string[] = [];

  const imageBlockPromises = new Map<
    number,
    Promise<{ block: ClaudeSdkContentBlock | null; finalPath: string }>
  >();
  content.forEach((block, idx) => {
    if (block.type === 'image' && readImagePathsLocally) {
      imageBlockPromises.set(
        idx,
        imageResizer.process(block.path).then(async (finalPath) => {
          return {
            block: await toClaudeImageBlock(
              finalPath,
              (data) => imageResizer.validateBuffer(data),
            ),
            finalPath,
          };
        }),
      );
    }
  });
  const resolvedImages = new Map<
    number,
    { block: ClaudeSdkContentBlock | null; finalPath: string }
  >();
  for (const [idx, promise] of imageBlockPromises) {
    resolvedImages.set(idx, await promise);
  }

  content.forEach((block, idx) => {
    if (block.type !== 'image' && block.type !== 'file' && block.type !== 'mention') return;
    let mentionBlock: { path: string; kind?: 'file' | 'dir' | 'agent' };
    if (block.type === 'mention') {
      mentionBlock = { path: block.path, kind: block.kind };
    } else if (block.type === 'image') {
      const resolvedImage = resolvedImages.get(idx);
      if (resolvedImage?.block) return;
      mentionBlock = { path: resolvedImage?.finalPath ?? block.path, kind: 'file' as const };
    } else {
      mentionBlock = { path: block.path, kind: 'file' as const };
    }
    if (!hasMentionText(existingText, mentionBlock)) {
      refs.push(quotedMentionText(mentionBlock));
    }
  });

  const prefix = refs.length > 0 ? `${refs.join(' ')} ` : '';
  const managedImageReferences = formatManagedImageReferences(content);
  const textBody = managedImageReferences
    ? [...textParts, managedImageReferences].join('\n')
    : textParts.join('\n');
  const text = `${prefix}${textBody}`.trim();
  const imageBlocks = [...resolvedImages.values()].flatMap(({ block }) => (block ? [block] : []));
  if (imageBlocks.length === 0) return text || prefix.trim();
  return text ? [...imageBlocks, { type: 'text', text }] : imageBlocks;
}

function userMessageTextForCapabilityRouting(content: UserMessage['content']): string {
  if (typeof content === 'string') return content;
  return content
    .flatMap((block) => (block.type === 'text' ? [block.text] : []))
    .join('\n');
}

function isUserSettingsMcpScope(scope: unknown): boolean {
  return scope === 'user' || scope === 'project' || scope === 'local';
}

/**
 * Anthropic Messages SDK 错误 → OneShotError 分类映射。
 * 参考自 apps/desktop/src/main/skillReview/claudeSdkReviewer.ts:mapApiError,
 * 收敛到 maker-core 后,所有 oneShot 调用方都按统一 reason 接错。
 */
/**
 * upstream-response-idle watchdog 阈值 — maker 侧端到端"最后一道兜底", 默认 30min
 * (1_800_000ms), 通过 env XDT_CC_SSE_IDLE_TIMEOUT_MS (毫秒, 历史命名沿用) 覆盖;
 * 设为 0 关闭。
 *
 * **分层 (2026-05 起)**: 上游网络层断流 (SSE 流中途静默) 现已交给 cc-code 子进程
 * 内置的原生 inactivity watchdog 透明自愈 —— 由 env-builder 注入
 * CLAUDE_ENABLE_STREAM_WATCHDOG=true (300s 无 chunk → 降级非流式) +
 * API_TIMEOUT_MS=900000 (兜底非流式 fallback 请求), cc 内部 withRetry 在同一个
 * SDK query 里恢复, 对 maker 完全无感, 不再中断 turn / 不再提示用户。
 * (详见 env-builder.ts buildClaudeEnv 与 cc-code claude.ts:1874/2310/2470)
 *
 * 因此 maker 这层 watchdog **退居二线**, 只兜 cc-code 结构上抓不到的场景:
 * cc 的 watchdog 活在子进程内、盯的是自己那条 HTTP socket; 若是**非网络层卡死**
 * (cc 子进程自身死锁 / SDK↔子进程 stdio 传输管道 wedge —— 整个子进程对 maker
 * 哑火), 只有活在外面的 maker 能发现。30min 阈值刻意设在 cc 恢复预算
 * (300s watchdog + 900s fallback ≈ 最多 20min) 之上, 保证正常自愈永远先发生、
 * 不被 maker 抢跑; 只有真的 30min 零进展才触发。
 *
 * **计时语义** (不变): 一次 turn 是 N 次上游 API 请求被工具调用隔开的。watchdog
 * 只在"客户端把 ball 交给上游、等上游回话"期间计时:
 *  - assistant message 含 tool_use → 客户端执行工具, 上游已交还 ball, 停 timer
 *  - tool_result 提交、pending 工具全部配对完 → ball 又交回上游, 立即起 timer
 *  - 期间 stream_event / assistant text → reset timer
 * 这避免 Bash 长 build / MCP 拉大表 / 子 agent / AskUserQuestion 发呆等本地操作
 * 被误伤 (这些场景 SDK 不发新 API 请求, 不算 idle 配额)。
 *
 * 历史背景: 无 watchdog 时上游 SSE 挂死实测可挂 57 分钟+
 * 旧默认 300s 现已下沉到 cc-code 原生 watchdog 承担。
 *
 * 触发后走 q.interrupt() (与用户手动 stop 同路径), 而不是 abortController.abort()
 * —— 后者会让整个 SDK Query 进黑洞 session, 后续 send 全部失败 (见 handle.abort)。
 */
function parseIdleTimeoutMs(raw: string | undefined): number {
  const DEFAULT = 1_800_000;
  if (raw === undefined || raw === '') return DEFAULT;
  const n = Number(raw);
  if (!Number.isFinite(n) || n < 0) return DEFAULT;
  return Math.floor(n);
}

/** upstream-response-idle 看门狗的计时分片长度(见 armUpstreamResponseIdleSlice)。 */
const CC_UPSTREAM_IDLE_SLICE_MS = 60_000;

/** 分片实际耗时超出片长这么多 → 判为进程被系统挂起过,该片不计入额度。 */
const CC_UPSTREAM_IDLE_SUSPEND_GAP_MS = 30_000;


function mapAnthropicError(err: unknown): OneShotError {
  if (err instanceof APIError) {
    if (err.status === 401 || err.status === 403) {
      return new OneShotError('auth', `Anthropic ${err.status}: ${err.message}`);
    }
    if (err.status === 408 || err.status === 504) {
      return new OneShotError('timeout', `Anthropic ${err.status}: ${err.message}`);
    }
    return new OneShotError('network', `Anthropic ${err.status}: ${err.message}`);
  }
  const msg = err instanceof Error ? err.message : String(err);
  if (
    msg.includes('fetch') ||
    msg.includes('ECONNREFUSED') ||
    msg.includes('ENOTFOUND') ||
    msg.includes('ETIMEDOUT') ||
    msg.includes('network')
  ) {
    return new OneShotError('network', msg);
  }
  return new OneShotError('malformed', msg);
}

function isInvalidCompactPreservedSegmentForkError(err: unknown): boolean {
  const msg = err instanceof Error ? err.message : String(err);
  return msg.includes('invalid compact preservedSegment reference');
}

/**
 * 会持续调模型的后台任务类型(SDK task_started.task_type),用户 Stop 时需要
 * 连带 stopTask 的白名单 —— 与 renderer makerChatStore 的 WAKE_AGENT_TASK_TYPES
 * 折算口径保持一致。刻意排除:local_bash(不调模型,dev server 等长驻进程不能
 * 被 Stop 误杀)、remote_agent(云端生命周期不受本进程控制)、未知类型(宁可
 * 少停不误停,启发式后台活动检测兜底)。
 */
const WAKE_BACKGROUND_TASK_TYPES: ReadonlySet<string> = new Set(['local_agent', 'local_workflow']);
/**
 * Wake 契约对账宽限:claim 内全部 wake 任务到终态(completed/failed)后,留给 SDK
 * 启动自动续跑段的窗口。健康路径里 dequeue → 顶层活动只需数秒;宽限内没有任何
 * 激活即判定契约失守(CLI 在「子代理于主 turn 运行中完成」时会把通知当 mid-turn
 * 附件消费,续跑段永远不会来),取消 claim 收口产品 turn。只影响终态低频路径。
 */
export const WAKE_CONTRACT_GRACE_MS = 60_000;

// ── 能力声明 ──────────────────────────────────────────────────────────────────

// 模型清单 SSoT 已迁至目录 packages/model-providers/catalog/providers.json。
// availableModels 起始为空,由 host 从 BUNDLED_CATALOG 派生后经 capabilityAdditions 注入
// (见 apps/desktop/src/main/maker-host/catalog-to-descriptors.ts)。

const CLAUDE_EFFORTS: EffortDescriptor[] = [
  { id: 'low',    displayName: 'Low',        description: 'Most efficient, with lower token use' },
  { id: 'medium', displayName: 'Medium',     description: 'Balanced capability and token use' },
  { id: 'high',   displayName: 'High',       description: 'High capability for complex work' },
  { id: 'xhigh',  displayName: 'Extra High', description: 'Extended capability for long-horizon work' },
  { id: 'max',    displayName: 'Maximum',   description: 'Maximum capability with unconstrained token use' },
];

// 注: plan 不再作为权限档暴露 —— 计划模式已独立成 Capabilities.planMode 一级开关
/**
 * Anthropic 模型清单动态发现的 host 捕获回调(2026-07-19 模型列表统一重构)。
 * host(apps/desktop maker-host/model-discovery/anthropic)注入监听器,agent 在
 * 每次会话首个 Query 建立后 fire-and-forget 调 SDK `supportedModels()` 上报。
 * 纯附加能力:不阻塞 send / 不进事件热路径 / 不改 prompt 组装(缓存前缀零影响);
 * 失败静默(发现通道有 HTTP + 磁盘缓存互补,见 host 侧)。
 */
let supportedModelsListener: ((models: unknown[]) => void) | null = null;

/** 主动清单探测(ClaudeCodeAgent.refreshLocalModels)的上限:CLI 冷启动通常几秒内应答。 */
const SUPPORTED_MODELS_PROBE_TIMEOUT_MS = 30_000;

/** host 注入 SDK supportedModels 捕获回调;传 null 解除。 */
export function setClaudeSupportedModelsListener(
  listener: ((models: unknown[]) => void) | null,
): void {
  supportedModelsListener = listener;
}

/**
 * Claude 订阅会话的额度快照回调。订阅会话不经本地 proxy,host 看不到响应头,
 * 5h / 7d 余量改由 CLI 自己上报的 SDK `rate_limit_event` 提供。只对本机订阅会话
 * (nativeCliAuth)转发;listener 抛错不影响会话。
 */
let rateLimitInfoListener: ((info: unknown) => void) | null = null;

/** host 注入订阅会话 rate_limit_event 捕获回调;传 null 解除。 */
export function setClaudeRateLimitInfoListener(listener: ((info: unknown) => void) | null): void {
  rateLimitInfoListener = listener;
}

function notifyRateLimitInfo(rawMsg: unknown): void {
  if (!rateLimitInfoListener) return;
  const info = (rawMsg as { rate_limit_info?: unknown } | null)?.rate_limit_info;
  if (!info || typeof info !== 'object') return;
  try {
    rateLimitInfoListener(info);
  } catch {
    /* listener 异常不得打断事件循环 */
  }
}

/** fire-and-forget 捕获(远端 RemoteQuery 无 supportedModels 方法时静默跳过)。 */
function notifySupportedModels(q: Query): void {
  if (!supportedModelsListener) return;
  const fn = (q as { supportedModels?: () => Promise<unknown[]> }).supportedModels;
  if (typeof fn !== 'function') return;
  void fn.call(q).then(
    (models) => {
      try {
        if (Array.isArray(models)) supportedModelsListener?.(models);
      } catch {
        /* listener 异常不得外溢成 unhandled rejection */
      }
    },
    () => {
      /* 捕获失败静默:发现是附加能力,不影响会话 */
    },
  );
}

// (与目标模式同级的 UI 入口), agent 内部仍用 SDK permissionMode='plan' 实现。
const CLAUDE_PERMISSION_MODES: PermissionModeDescriptor[] = [
  { id: 'ask',               displayName: 'Ask permissions',     description: 'Always ask before making changes' },
  { id: 'acceptEdits',       displayName: 'Auto accept edits',   description: 'Automatically accept all file edits' },
  { id: 'auto',              displayName: 'Auto',                description: 'Auto-approve safe in-workspace actions; ask before out-of-workspace or risky ones' },
  { id: 'bypassPermissions', displayName: 'Bypass permissions',  description: 'Accepts all permissions' },
];

const CAPABILITIES: Capabilities = {
  // Stage 2 B: runtime 切换接通 (Query.setModel / applyFlagSettings / setPermissionMode)
  switchModel: { supported: true },
  availableModels: [],
  // Fast 模式由 cc 二进制经 flag settings `fastMode` + beta 头 fast-mode-2026-02-01 落地
  // (官方 only / Opus only / firstParty / org 级开关由二进制自身把关)。这里只声明 agent
  // 具备该能力;实际可用还要叠 per-(provider, model) 的 supportsFastMode(目录,唯一真相)。
  hasFastMode: true,
  effort: { supported: true },
  effortLevels: CLAUDE_EFFORTS,
  reasoningDisplay: ['off', 'summarized', 'full'],
  permissionModes: CLAUDE_PERMISSION_MODES,
  setPermissionModeMidSession: { supported: true },
  turnPermissionPolicy: {
    supported: { supported: true },
    // Both modes can execute mutations without invoking canUseTool. Reject the
    // combination instead of presenting a false forced-confirmation promise.
    unsupportedPermissionModes: ['acceptEdits', 'bypassPermissions'],
  },
  // 计划模式一级开关: SDK plan mode + ExitPlanMode → plan_review 审批, 批准后自动退出
  planMode: { supported: true },
  multimodal: {
    text: { supported: true },
    image: { supported: true },
    file: { supported: true },
  },
  fork: { supported: true },
  rewind: { supported: true },
  abort: { supported: true },
  sameTurnSteer: { supported: true },
  memory: {
    supported: { supported: true },
    displayName: 'Auto Memory',
    description: '自动从对话中沉淀长期记忆并在后续对话中召回 (后台 auto-dream 一并联动)',
    stage: 'stable',
    defaultEnabled: true,
    resettable: true,
    // applyFlagSettings 是 per-Query, BaseAgent 不追踪 active sessions 主动 push;
    // 所以 setMemory 只更新 memoryOverride, 影响下次 buildQuery, 当前 live Query 不受影响
    setEnabledMidSession: {
      supported: false,
      reason: 'not-implemented',
      message: 'setMemory 影响下次 startSession; 当前 live session 需 close 重起才生效',
    },
  },
  // SDK additionalDirectories 在 Query 创建时冻结。setExtraDirs 只改 closure;
  // 代际不一致时下一次 send 走 rewind 同款 resume+fork 重建,不用 fresh:true。
  extraDirs: { supported: true },
  writableDirs: { supported: true },
};

// ── Agent 实现 ────────────────────────────────────────────────────────────────

export class ClaudeCodeAgent extends BaseAgent {
  readonly kind = 'claude-code' as const;
  readonly capabilities: Capabilities;

  constructor(deps: AgentDeps) {
    super(deps);
    this.capabilities = this.buildCapabilities(CAPABILITIES);
  }

  /**
   * 目标路由声明的档位。availableModels 按 ID 跨来源去重,同名模型的档位可能来自别的来源;
   * 有 host 解析器时按实际来源取,来源未知或不唯一返回 null(调用方不得借用首见 descriptor)。
   * 主档位收窄与 max 兼容回退共用这一判据。
   */
  private routeEffortsForModel(model: string, providerId?: string | null): readonly Effort[] | null {
    if (this.deps.resolveModelEfforts) return this.deps.resolveModelEfforts(providerId, model);
    return this.capabilities.availableModels.find((m) => m.id === model)?.efforts ?? null;
  }

  private sdkEffortForModel(
    model: string,
    effort: Effort,
    providerId?: string | null,
  ): ClaudeSdkEffort | undefined {
    const descriptor = this.capabilities.availableModels.find((m) => m.id === model);
    // 来源不明(null)时不收窄,只保留原有的「无档位模型不下发」判断。
    const routeEfforts = this.routeEffortsForModel(model, providerId);
    if ((routeEfforts ?? descriptor?.efforts)?.length === 0) return undefined;
    // 会话档位可能来自上一个模型(如 Claude 的 xhigh),原样下发会被只认目录档位的
    // 上游拒绝(GLM-5.3 收到 xhigh 回 400/1210,#5402)。按目标来源声明的档位收窄。
    return clampEffortForClaude((clampEffortToSupported(effort, routeEfforts ?? undefined) as Effort | undefined) ?? effort);
  }

  private sdkMaxEffortFallbackForModel(
    model: string,
    providerId?: string | null,
  ): Exclude<ClaudeSdkEffort, 'max'> {
    const efforts = this.routeEffortsForModel(model, providerId);
    if (!efforts) return 'xhigh';
    const supported = new Set(efforts.map(clampEffortForClaude));
    for (const candidate of ['xhigh', 'high', 'medium', 'low'] as const) {
      if (supported.has(candidate)) return candidate;
    }
    return 'high';
  }

  /**
   * catalog id → SDK wire 串,[1m] 由目录 contextWindow 驱动(见 toSdkModelString)。
   * 模型不在 capabilities(目录外/host 未注入)时窗口传 undefined → 走 legacy 兜底链。
   */
  private sdkModelFor(model: string): string {
    const descriptor = this.capabilities.availableModels.find((m) => m.id === model);
    const window =
      descriptor && Number.isFinite(descriptor.contextWindow) && descriptor.contextWindow > 0
        ? descriptor.contextWindow
        : undefined;
    return toSdkModelString(model, window);
  }

  /**
   * 订阅 token 401 强刷 —— 本地 SDK getOAuthToken 回调与远端 onOAuthRefresh 共用。
   *
   * env.CLAUDE_CODE_OAUTH_TOKEN 是该会话持有 token 的**单一事实源**:作为失败基线传给
   * host(库已被后台预续期换代时直接返回库值,不再消耗一次轮换);拿到新 token 后原地
   * 写回 env —— rewind/fork/重连重建复用同一 env 引用,新子进程直接以最新 token spawn,
   * 不会拿旧 token 起跑立即 401 再白白强刷一枚好 token。失败返回 null(cc 侧 surface
   * 鉴权错误),绝不上抛。
   */
  private async refreshSubscriptionTokenInPlace(env: Record<string, string>): Promise<string | null> {
    try {
      const fresh = env.CINDY_CLAUDE_ACCOUNT_PROVIDER_ID
        ? await this.deps.auth.getFreshSubscriptionToken!(env.CLAUDE_CODE_OAUTH_TOKEN, env.CINDY_CLAUDE_ACCOUNT_PROVIDER_ID)
        : await this.deps.auth.getFreshSubscriptionToken!(env.CLAUDE_CODE_OAUTH_TOKEN);
      if (fresh) env.CLAUDE_CODE_OAUTH_TOKEN = fresh;
      return fresh ?? null;
    } catch (e) {
      this.deps.logger
        .child('claude-code/oauth-refresh')
        .warn('subscription token refresh failed; returning null (cc will surface auth error)', {
          error: e instanceof Error ? e.message : String(e),
        });
      return null;
    }
  }

  /**
   * Agent 内置 command —— ChatInput palette 'agent-builtin' 类目数据源。
   * 是硬编码白名单(见 ./commands.ts), 不从 SDK 自动派生。
   * 当前 live: /compact。
   */
  override listAgentCommands(): AgentBuiltinCommand[] {
    return CLAUDE_CODE_AGENT_COMMANDS;
  }

  /**
   * 主动读取 Claude 订阅的模型清单:用本机 CLI 自己的登录起一个空闲 Query,只调
   * SDK `supportedModels()`,不发送任何消息、不产生模型调用,读完立即关闭。
   * 结果交给调用方的 onSupportedModels(host 据此核对发起时的登录代际);未提供时经
   * setClaudeSupportedModelsListener 交给 host,与会话 init 捕获同一入口。
   * 未登录订阅、无接收方、项目设置被改写或探测任一阶段失败时返回 false,不抛错。
   */
  override async refreshLocalModels(options?: RefreshLocalModelsOptions): Promise<boolean> {
    const deliver = options?.onSupportedModels ?? supportedModelsListener;
    if (!deliver) return false;
    const log = this.deps.logger.child('claude-code/supportedModels');
    let probeDir: string | null = null;
    let q: Query | null = null;
    let timer: ReturnType<typeof setTimeout> | undefined;
    const abortController = new AbortController();
    const idleInput = createAsyncQueue<never>();
    try {
      // oauth-bearer 形态下 auth adapter 只按本机 Claude Code 订阅登录作答。
      const authState = await this.deps.auth.getState({ credentialMode: 'oauth-bearer' });
      if (!authState.authenticated) return false;
      // 独立的新建空目录:不继承共享临时目录里可能存在的项目级设置;仍按订阅会话同一
      // 规则检查,能改写上游 / 鉴权 / TLS 的设置一律拒绝。
      probeDir = await fs.mkdtemp(path.join(os.tmpdir(), 'cindy-claude-models-'));
      const override = await findWorkspaceSettingsOverride(probeDir);
      if (override) {
        log.warn('probe skipped', { reason: workspaceSettingsOverrideMessage(override) });
        return false;
      }
      const env = await buildClaudeEnv(this.deps.auth, this.deps.runtimeConfig, {
        credentialMode: 'oauth-bearer',
        nativeCliAuth: true,
        subagentModel: null,
      });
      q = sdkQuery({
        prompt: idleInput as unknown as Parameters<typeof sdkQuery>[0]['prompt'],
        options: {
          abortController,
          cwd: probeDir,
          pathToClaudeCodeExecutable: this.deps.binaryPath,
          env,
        },
      });
      const query = q;
      const models = await Promise.race([
        query.supportedModels(),
        new Promise<never>((_, reject) => {
          timer = setTimeout(
            () => reject(new Error('supportedModels probe timed out')),
            SUPPORTED_MODELS_PROBE_TIMEOUT_MS,
          );
        }),
      ]);
      if (!Array.isArray(models)) return false;
      deliver(models);
      return true;
    } catch (error) {
      log.warn('probe failed', { error: String(error) });
      return false;
    } finally {
      if (timer) clearTimeout(timer);
      idleInput.end();
      try {
        q?.close();
      } catch {
        /* 探测进程已退出 */
      }
      abortController.abort();
      if (probeDir) await fs.rm(probeDir, { recursive: true, force: true }).catch(() => undefined);
    }
  }

  /**
   * Skill 扫描 —— 走 scanClaudeSlashCommands (扫 ~/.claude/{commands,skills}),
   * 包装成新的 AgentSkillCommand 形状(kind='agent-skill')。
   */
  private async managedSkillCommands(nativeNames: readonly string[] = []) {
    const managed = await this.deps.getManagedSkills?.() ?? [];
    const counts = new Map<string, number>();
    for (const name of [...nativeNames, ...managed.map((skill) => skill.name)]) {
      counts.set(name, (counts.get(name) ?? 0) + 1);
    }
    return managed.map(({ claudeCommandName, ...skill }) => ({
      ...skill,
      // Preserve user commands and distinguish plugins with the same skill name.
      name: (counts.get(skill.name) ?? 0) > 1 ? claudeCommandName : skill.name,
      runtimeCommandName: claudeCommandName,
    }));
  }

  override async listAgentSkills(opts: ListAgentSkillsOptions): Promise<ListAgentSkillsResult> {
    if (opts.remoteHostId) {
      const fileOps = this.deps.getRemoteAgentFileOps?.(opts.remoteHostId);
      if (!fileOps) throw new Error('Claude Code remote Skill discovery requires remote file operations');
      return scanRemoteClaudeSkills({ fileOps, workingDir: opts.workingDir });
    }
    const raw = await scanClaudeSlashCommands(opts.workingDir);
    return {
      skills: [...await this.managedSkillCommands(raw.map((item) => item.name)), ...raw.map((c) => ({
        kind: 'agent-skill' as const,
        name: c.name,
        description: c.description,
        source: c.source,
        path: c.path,
        scope: c.scope,
        enabled: c.enabled,
      }))],
    };
  }

  override async listRuntimeSkills(opts: ListRuntimeSkillsOptions): Promise<ListAgentSkillsResult> {
    if (opts.remoteHostId) return this.listAgentSkills(opts);
    if (!opts.workingDir) return { skills: [] };
    let result: Awaited<ReturnType<typeof scanClaudeRuntimeSkills>>;
    try {
      result = await scanClaudeRuntimeSkills(opts.workingDir, opts.runtimeConfigDir);
    } catch (error) {
      return {
        skills: [],
        errors: [{
          path: opts.workingDir,
          message: error instanceof Error ? error.message : String(error),
        }],
      };
    }
    return {
      skills: [...await this.managedSkillCommands(result.items.map((item) => item.name)), ...result.items.map((item) => ({
        kind: 'agent-skill' as const,
        name: item.name,
        description: item.description,
        source: item.kind === 'skill' ? 'skill' as const : 'user' as const,
        path: item.mdPath,
        scope: item.scope === 'project' ? 'project' as const : 'global' as const,
        enabled: true,
      }))],
      ...(result.errors.length > 0 ? { errors: result.errors } : {}),
    };
  }

  async scanAtResources(opts: ScanAtResourcesOptions): Promise<ScanAtResourcesResult> {
    return scanClaudeAtResources(opts.workingDir, opts.cap, opts.query);
  }

  /**
   * 扫 Claude Code 的 skill / command / agent 三类 customization。
   * scanClaudeSlashCommands 是这条 pipeline 的"过滤视图"(只取 skill+command, drop agent,
   * 按 name 去重), 二者共享 ~/.claude/{...} 扫盘事实, 但消费者不同。
   */
  async listCustomizations(opts: ListCustomizationsOptions): Promise<ListCustomizationsResult> {
    const result = await (this.deps.scanLocalCustomizations
      ? this.deps.scanLocalCustomizations('claude-code', opts)
      : scanClaudeCustomizations(opts));
    if (!opts.kinds || opts.kinds.includes('skill')) {
      result.items.push(...(await this.deps.getManagedSkills?.() ?? []).filter((skill) => skill.path).map((skill) => ({
        engine: 'claude-code' as const, kind: 'skill', scope: 'user', name: skill.name,
        description: skill.description, absolutePath: path.dirname(skill.path!), mdPath: skill.path,
        enabled: skill.enabled,
      })));
    }
    return result;
  }

  /**
   * 一次性 LLM 调用 —— 直连 Anthropic Messages API (复用 host 端的 proxy URL + API key)。
   *
   * 历史: 之前走 sdkQuery + Claude Code binary 子进程, spawn 1-3s + 大段 preset
   * system prompt, 起标题 / skillReview 这种 "纯文本 → 文本" 的轻任务严重浪费。
   * skillReview 已先行迁移成直连 (apps/desktop/src/main/skillReview/claudeSdkReviewer.ts),
   * 实测快 3-10 倍; 这里把同款方式收敛到 maker-core, 让 skillReview 也改成调 maker.oneShot。
   *
   * 鉴权: Claude AuthAdapter 是纯 API key 模式 (auth-adapters.ts), getAuthEnv() 只放
   * ANTHROPIC_API_KEY, 没有 OAuth 路径 —— 直接抠出来用即可。
   *
   * baseURL: 复用 runtimeConfig.endpoint (host 已经配成网关 endpoint),
   * 跟 startSession 同一接入点; 不另外硬编码。
   *
   * 失败: 抛 OneShotError (reason: timeout/auth/network/malformed); 宽容调用方
   * (如起标题 IPC) 自己 try/catch 返空串, 不在 agent 里 swallow。
   */
  async oneShot(prompt: string, opts?: OneShotOptions): Promise<string> {
    const log = this.deps.logger.child('claude-code/oneShot');
    const model = opts?.model ?? 'claude-haiku-4-5';
    const maxTokens = opts?.maxTokens ?? 100;
    const timeoutMs = opts?.timeoutMs ?? 30_000;
    const instructions = [opts?.systemPrompt, opts?.responseInstructions]
      .filter((value): value is string => typeof value === 'string' && value.trim().length > 0)
      .join('\n');

    // Auth gate:与 startSession 对齐 — 未授权直接拒,不让 Anthropic 请求带空 key 跑出去
    // (避免被 fallback 到用户系统级 ~/.claude/.credentials.json 之类的别处 OAuth)
    const authState = await this.deps.auth.getState();
    if (!authState.authenticated) {
      throw new AgentNotAuthenticatedError(
        'claude-code',
        `claude-code not authenticated: ${authState.errorReason ?? 'no_key'}`,
      );
    }
    // oneShot 凭证优先走 getOneShotAuth()(host 侧直连专用,与子进程 env 正交):
    // 连了 Claude 订阅时订阅只归 CLI 子进程,host 直连请求不得使用,host 通过
    // getOneShotAuth 固定回 gateway key +
    // gateway endpoint。不实现该方法的 adapter(或回 null)→ 回退旧逻辑(getAuthEnv 里的 key + runtimeConfig.endpoint)。
    let apiKey: string | undefined;
    let baseURL = this.deps.runtimeConfig.endpoint;
    const oneShotAuth = this.deps.auth.getOneShotAuth
      ? await this.deps.auth.getOneShotAuth()
      : null;
    if (oneShotAuth?.apiKey) {
      apiKey = oneShotAuth.apiKey;
      if (oneShotAuth.baseURL) baseURL = oneShotAuth.baseURL;
    } else {
      const authEnv = await this.deps.auth.getAuthEnv();
      apiKey = authEnv.ANTHROPIC_API_KEY;
    }
    if (!apiKey) {
      throw new OneShotError('auth', 'no API key available for oneShot (getOneShotAuth / getAuthEnv both empty)');
    }

    // 自家超时 controller —— 跟外部 signal 合并 (任一触发都 abort)
    let timedOut = false;
    const timeoutController = new AbortController();
    const timeoutId = setTimeout(() => {
      timedOut = true;
      timeoutController.abort();
    }, timeoutMs);
    const onExternalAbort = () => timeoutController.abort();
    opts?.signal?.addEventListener('abort', onExternalAbort);

    const startedAt = Date.now();
    try {
      const client = new Anthropic({
        apiKey,
        baseURL,
        // 自家有 timeoutMs, 不让 SDK 内部重试再叠一倍
        maxRetries: 0,
      });

      // Auth and host setup can await asynchronous work. Re-check the caller's
      // ownership fence immediately before the paid provider request, matching
      // Codex oneShot's thread/start guard.
      if (opts?.beforeDispatch && !(await opts.beforeDispatch())) {
        throw new OneShotError('network', 'Claude oneShot dispatch guard rejected');
      }

      const resp = await client.messages.create(
        {
          model,
          max_tokens: maxTokens,
          ...(instructions ? { system: instructions } : {}),
          messages: [{ role: 'user', content: prompt }],
        },
        { signal: timeoutController.signal },
      );

      const text = resp.content
        .filter((b): b is Anthropic.TextBlock => b.type === 'text')
        .map((b) => b.text)
        .join('')
        .trim();

      log.info('oneShot done', {
        model,
        elapsedMs: Date.now() - startedAt,
        inputTokens: resp.usage?.input_tokens,
        outputTokens: resp.usage?.output_tokens,
        chars: text.length,
      });

      if (!text) {
        throw new OneShotError('malformed', 'Empty response from model');
      }
      return text;
    } catch (err) {
      log.error('oneShot failed', {
        model,
        elapsedMs: Date.now() - startedAt,
        timedOut,
        externalAborted: opts?.signal?.aborted ?? false,
        error: String(err),
      });
      if (err instanceof OneShotError) throw err;
      // 自家超时优先, 不依赖 SDK 抛 abort 类型
      if (timedOut) {
        throw new OneShotError('timeout', `oneShot timed out after ${timeoutMs}ms`);
      }
      // 外部 abort: 不归类成 OneShotError, 直接把原 error 抛回 (调用方按自己 signal 判取消)
      if (opts?.signal?.aborted) throw err;
      throw mapAnthropicError(err);
    } finally {
      clearTimeout(timeoutId);
      opts?.signal?.removeEventListener('abort', onExternalAbort);
    }
  }

  async startSession(opts: StartSessionOptions): Promise<AgentSessionHandle> {
    let runtimeStartAttempted = false;
    try {
      return await this.startSessionInternal(opts, () => { runtimeStartAttempted = true; });
    } catch (error) {
      // Preparation failures cannot leave a CLI writer behind. Once a local SDK
      // query or remote start is dispatched, only explicit exit evidence can
      // release the workdir; a rejected factory alone does not prove termination.
      if (!runtimeStartAttempted
        && !(error instanceof AgentNotAuthenticatedError)
        && !(error instanceof AgentStartupCleanupPendingError)
        && !(error instanceof AgentStartupStoppedError)) {
        throw new AgentStartupStoppedError(error);
      }
      throw error;
    }
  }

  private async startSessionInternal(
    opts: StartSessionOptions,
    onRuntimeStartAttempted: () => void,
  ): Promise<AgentSessionHandle> {
    // scope 带完整 s:<sessionId> 前缀 → host logger 落盘时提取 business sessionId,
    // 路由到 sessions/<id>/<date>.ndjson (logger.ts extractSessionId / sessionAgentSlot)。
    const sid = opts.sessionId ?? '';
    const log = this.deps.logger.child(sid ? `s:${sid}/claude-code` : 'claude-code');
    const reviewMode = opts.reviewMode === true;
    if (reviewMode && opts.remoteHostId) {
      throw new Error('Cindy Review currently supports local Claude Code sessions only');
    }
    // 设备托管:Claude Code 在本机运行(本机的登录、订阅与供应商),项目、文件与命令在任务所在
    // 电脑上。自带的文件与命令工具关掉,改用经隧道回到那台电脑的 Cindy 工具(cindy_exec);
    // Cindy 自己的工具也都经隧道。opts.workingDir 是本机影子目录(只放项目说明)。
    const hosted = opts.deviceHosted && !opts.remoteHostId && !reviewMode ? opts.deviceHosted : undefined;
    // 受邀者(另一个账号)只能用分享给它的那一个供应商:host 必须给出供应商边界(含本机 proxy 的
    // 路由令牌),且启动来源就是它。缺了就不启动,请求不能按本机默认规则落到本机用户的其它供应商上。
    const guestProvider = hosted?.guest ? hosted.guestProvider : undefined;
    if (hosted?.guest && !guestProvider) {
      throw new Error('[REMOTE_AGENT_UNSUPPORTED] shared users need a provider boundary on this computer');
    }
    if (guestProvider && guestProvider.providerId !== opts.providerId) {
      throw new Error('[REMOTE_AGENT_PROVIDER_NOT_ALLOWED] this provider is not allowed for remote use on this computer');
    }
    let reviewReadGrants: Awaited<ReturnType<typeof buildReviewReadGrants>> = [];
    if (reviewMode) {
      try {
        reviewReadGrants = await buildReviewReadGrants(opts.workingDir, opts.reviewReadPaths ?? []);
      } catch (error) {
        // Claude has not spawned a CLI process before review grants are validated.
        throw new AgentStartupStoppedError(error);
      }
    }
    // 开 debug 时让每个 session 的 cc 子进程写到各自 session 目录的 raw 文件 (host 注入
    // resolveCcDebugFile 拼路径 + mkdir); 没注入则回退全局 XDT_CC_DEBUG_FILE。
    const ccDebugFile = process.env.XDT_CC_DEBUG_NET === '1'
      ? (this.deps.resolveCcDebugFile?.(opts.sessionId) ?? process.env.XDT_CC_DEBUG_FILE)
      : undefined;

    // Auth gate(对齐 codex/index.ts:572): 未授权 → 拒绝 spawn,不让 CC CLI 子进程
    // 在 ANTHROPIC_API_KEY 为空时启动 — 否则 CC 会按它内部的鉴权回退链去找
    // process.env 里其他字段(已被 boot strip 兜底) / `~/.claude/.credentials.json`
    // (用户单独装过 Claude Code 时存在),用上别人的 OAuth 通道 → 既泄漏隔离,也
    // 让用户莫名其妙"用上了不属于本 app 的 key"。
    // renderer 接到 AgentNotAuthenticatedError 后据 reason 引导用户补齐当前来源的鉴权。
    // 远端路由 materialization(必须先于凭证形态推导):本地按模型分流的逻辑活在 loopback
    // proxy,远端够不到,由 host 在 spawn 前把「该会话真实上游 + 鉴权 + 定制头」解析成 cc
    // env(见 base-agent.ts AgentDeps.resolveRemoteClaudeRoute)。
    //   - 返回 route:native OAuth 订阅 / 自定义 Claude Code 供应商 —— 下方覆盖 endpoint + 鉴权;
    //   - 返回 null / resolver 未注入(旧 host):有效路由是 XD 网关 —— credentialMode 必须
    //     回落 'gateway-key'(与升级前「远端恒用网关」逐字节一致)。不回落的话,getAuthEnv
    //     会按本地 fallback 注入订阅 token / provider 占位 key,与 buildClaudeEnv 写入的网关
    //     endpoint 并存:订阅 token 被发往网关(凭证泄漏)或网关收到占位 key(401)。
    //   - throw:显式选定的供应商在远端无法表达(自定义 requestPath / modelIdRewrite 等),
    //     透传报错,不静默错路由。
    const remoteRoute =
      opts.remoteHostId && this.deps.resolveRemoteClaudeRoute
        ? await this.deps.resolveRemoteClaudeRoute({
            sessionId: opts.sessionId,
            providerId: opts.providerId,
            model: opts.model,
          })
        : null;
    // 凭证形态:本地按会话来源推导;远端仅在 materialize 出 route 时用来源形态(route.env
    // 是远端鉴权的唯一事实源,来源形态只影响 auth gate 与 behaviorFlags),网关路径(route
    // 为 null / 旧 host)维持「远端恒用网关 key」。
    const credentialMode =
      opts.remoteHostId && !remoteRoute
        ? 'gateway-key'
        : resolveAgentCredentialMode({
            agentKind: 'claude-code',
            providerId: opts.providerId,
            model: opts.model,
          });
    const authOptions = credentialMode
      ? {
          credentialMode,
          ...(credentialMode !== 'gateway-key' && opts.providerId ? { providerId: opts.providerId } : {}),
        }
      : { model: opts.model };
    const authState = await this.deps.auth.getState(authOptions);
    if (!authState.authenticated) {
      throw new AgentNotAuthenticatedError(
        'claude-code',
        `claude-code not authenticated: ${authState.errorReason ?? 'no_key'}`,
      );
    }
    const effectiveCredentialMode = resolveEffectiveCredentialModeFromAuthSource(
      credentialMode,
      authState.authSource,
    );
    // Claude 订阅(含 adapter 把隐式来源解析成订阅的情形)由 CLI 用自己的登录直连,
    // host 不接管连接、不经手凭证(见 env-builder nativeCliAuth)。远端会话不适用。
    const nativeCliAuth = !opts.remoteHostId && effectiveCredentialMode === 'oauth-bearer';
    // 订阅会话不设 host 接管标记,CLI 会直接应用工作区设置里的 env:能改写上游 / 鉴权 /
    // TLS 信任的项目级设置会让订阅请求带着登录凭证发往别处,启动前拒绝(见 workspace-settings-guard)。
    if (nativeCliAuth) {
      const override = await findWorkspaceSettingsOverride(opts.workingDir);
      if (override) throw new Error(workspaceSettingsOverrideMessage(override));
    }

    // 箭头别名捕获 this —— 下方 replayRuntimeDrift(普通 function)与 handle 对象
    // 字面量方法里没有类实例 this,统一经它取 wire 串。
    const sdkModelFor = (model: string): string => this.sdkModelFor(model);
    const resolveRemoteClaudeRoute = this.deps.resolveRemoteClaudeRoute?.bind(this.deps);
    const getAuthEnv = this.deps.auth.getAuthEnv.bind(this.deps.auth);
    const sdkModel = sdkModelFor(opts.model);
    const initialSdkEffort = this.sdkEffortForModel(opts.model, opts.effort ?? 'high', opts.providerId);
    // 任务级工作上下文预算(tokens):host 已按目录上限与模型级上限收敛。
    // 本任务热切模型时 host 会随 setModel 下新值;缺席保持当前值。
    // 必须早于下面的 configuredWindows (窗口表在 buildQuery 之前就要用它,
    // 否则会撞 TDZ)。
    let mutableContextWindowBudget: number | null = opts.contextWindowBudget ?? null;
    const binaryPath = this.deps.binaryPath;
    const providerRoutedModels = this.capabilities.availableModels.filter((model) =>
      isProviderRoutedModel(model.id),
    );
    // #3661:扁平表按「CC 内建 resolver 认识 Anthropic 名」排除了 claude-*,但
    // 中转/自定义来源上的 claude 模型窗口以用户配置为准(如 1M);CLI 内建
    // resolver 会按 Anthropic 缺省收敛(~200K)并过早判满/auto-compact。显式
    // 来源会话把「该路由已核实」的窗口(resolveVerifiedContextWindow:多来源
    // 歧义或未核实返回 null,fail-open 回落 CLI 自解析)按本会话模型单点注入;
    // 不做 [1m] 镜像 —— claude 的 [1m] 是真实 1M 通道,不是同窗口路由别名。
    // 会话中途 setModel 到其它 claude 模型时该 env 键不覆盖新模型,行为与
    // 修复前一致(CLI 自解析),无回归面。
    const sessionRouteWindowEntry = ((): {
      id: string;
      contextWindow: number;
      mirrorOneMillionSuffix: false;
    } | null => {
      if (!opts.providerId) return null;
      if (!opts.model.startsWith('claude-')) return null;
      const verified = this.deps.resolveVerifiedContextWindow?.(opts.providerId, opts.model);
      if (typeof verified !== 'number' || verified <= 0) return null;
      return {
        id: sdkModelFor(opts.model),
        contextWindow: verified,
        mirrorOneMillionSuffix: false,
      };
    })();
    const configuredWindows = [...new Set([...this.capabilities.availableModels.map((model) => model.id), opts.model])]
      .flatMap((model) => {
        // 任务级预算优先于模型级上限:本任务的窗口就是预算(host 已收敛),
        // 其余模型条目保持目录/上限口径。
        const limit = model === opts.model && mutableContextWindowBudget !== null
          ? mutableContextWindowBudget
          : this.deps.resolveModelContextLimit?.(opts.providerId, model);
        return typeof limit === 'number' && Number.isSafeInteger(limit) && limit > 0
          ? [{ id: sdkModelFor(model), contextWindow: limit, mirrorOneMillionSuffix: false as const }]
          : [];
      });
    const modelContextWindows = [...new Map([
      ...providerRoutedModels,
      ...(sessionRouteWindowEntry ? [sessionRouteWindowEntry] : []),
      // The host resolves this route’s user budget or current catalog default.
      // Never reuse another provider’s working-window policy.
      ...configuredWindows,
    ].map((entry) => [entry.id, entry])).values()];
    // #3557:会话模型 id 带命名空间前缀(anthropic/... 等网关目录形态)时,CLI
    // 内部小模型调用(bash 前缀判定/标题/摘要)不能用它内置的裸名默认值 ——
    // 网关白名单字面比对,裸名必 403。钉到会话自身 wire 模型(唯一确定已授权);
    // 裸名会话(订阅直连/自定义中继)不传,CLI 默认行为零变化。
    // 受邀者会话的内部小模型调用同样钉到会话模型:本机 proxy 只放行分享供应商提供的模型,
    // CLI 内置的裸名默认值(haiku)不一定在其中。
    const smallFastModel = opts.model.includes('/') || guestProvider ? sdkModel : undefined;
    const companionEnvironment = opts.botRuntimeProfile && !opts.remoteHostId && opts.sessionId
      ? await this.deps.resolveSessionEnvironment?.(opts.sessionId) : undefined;
    const env = await buildClaudeEnv(this.deps.auth, this.deps.runtimeConfig, {
      credentialMode,
      nativeCliAuth,
      authModel: opts.model,
      sessionProviderId: opts.providerId ?? null,
      activeModel: sdkModel,
      modelContextWindows,
      smallFastModel,
      // 先按「不设」建好 env(顺带删掉可能从 process.env 继承来的残留),真正的判定在下面
      // 拿到这份 env 之后做 —— 扫描需要 env 里的 CLAUDE_CONFIG_DIR 才能找对目录。
      subagentModel: null,
    });

    // 「Subagent 模型」设置的默认值语义(见 subagent-model-default.ts):
    // 平台的 CLAUDE_CODE_SUBAGENT_MODEL 是最高优先级**强制覆盖**,会静默盖掉用户手写
    // agent 的 `model:`。这里先扫一遍用户手写定义再决定:没人声明 model → 照旧设 env
    // (内置 agent 也吃到默认值);有人声明 → 不设 env,让那些声明生效。
    //
    // 必须放在 buildClaudeEnv **之后**:host 若经 auth adapter 重定向 cc 的配置目录
    // (旧版 dev 多实例曾用 `<userData>/claude-home`),那个 CLAUDE_CONFIG_DIR 只存在于
    // **子进程 env**里(boot 期已从 process.env 剥离)。拿 process.env 去扫会扫到
    // `~/.claude/agents`,和 cc 实际读的目录不是同一个 → 判定失真,声明照旧被覆盖。
    //
    // 只在会话启动时解析一次 —— env 要在 spawn 前定好,会话中途变动 tools/system 会破坏
    // prompt 缓存(见 docs/dev-rules/maker-core-and-agent-behavior.md §3.1)。
    // 诊断只落日志与 host 回调,**不进模型上下文**(理由见 subagent-model-default.ts 模块头)。
    // 扫描失败(含触发 IO 预算)一律降级成「照旧设 env」= 本改动前的行为,绝不阻断会话启动。
    //
    // 候选默认值从路由感知入口取:子代理请求跑在父会话来源上,覆写在**该来源**下不可
    // 路由(被停用)时 host 返回 undefined = 不注入(PR #744 review 第十九/二十轮)。
    // 缺席 subagentModelForRoute 时退回静态 subagentModel(旧 host / CLI 行为不变)。
    // 订阅会话(含隐式来源交给本机登录的情形)按生效形态判定:子代理请求跟着 CLI 直连
    // Anthropic,不经 proxy 按模型路由。
    // 受邀者会话不套用本机用户的「Subagent 模型」设置(那个模型可能来自本机的其它供应商):
    // 子代理沿用会话模型或自己声明的模型,且都只能在分享的供应商内(本机 proxy 拒绝其它模型)。
    const configuredSubagentDefault = guestProvider
      ? undefined
      : (this.deps.runtimeConfig.subagentModelForRoute
        ? this.deps.runtimeConfig.subagentModelForRoute(
            opts.providerId ?? null,
            nativeCliAuth ? 'oauth-bearer' : credentialMode,
          )
        : this.deps.runtimeConfig.subagentModel
      )?.trim() || undefined;
    let subagentDefault: ResolveSubagentModelDefaultResult = {
      envSubagentModel: configuredSubagentDefault,
      diagnostics: [],
    };
    // 远端(SSH)会话**不做**本地扫描:opts.workingDir 是远端机器上的路径(本地不存在),
    // `~/.claude/agents` 也是本地用户的而非远端的 —— 拿本地结果去决定远端行为会误判
    // 「有没有人声明 model」。远端因此沿用既有 env 语义(设置值照旧强制覆盖),
    // 即上面 subagentDefault 的初值。受邀者没有要套用的默认值,也不扫描。
    if (!opts.remoteHostId && !guestProvider) {
      try {
        const discovered = await discoverSubagentDefinitions({
          workingDir: opts.workingDir,
          // 子进程真正会用的那份 env —— CLAUDE_CONFIG_DIR 在里面。
          env,
        });
        subagentDefault = resolveSubagentModelDefault({
          configuredDefault: configuredSubagentDefault,
          discovered,
          // 校验 agent 声明的 model 是否真的可用 —— 清单就是 host 从目录派生的那份。
          availableModelIds: this.capabilities.availableModels.map((m) => m.id),
        });
        for (const d of subagentDefault.diagnostics) {
          log.warn('subagent model diagnostic', { ...d });
        }
        // 同步 throw 与 async reject 都在里面接住(host 可能传 async 回调)。
        reportSubagentModelDiagnostics(
          this.deps.runtimeConfig.onSubagentModelDiagnostics,
          subagentDefault.diagnostics,
        );
      } catch (e) {
        log.warn('discover subagent definitions failed; falling back to env override', {
          error: e instanceof Error ? e.message : String(e),
        });
      }
    }
    // 每次 Agent/Task 调用都重新读取 host 的当前账号与路由事实。静态 capabilities
    // 只负责展示,不参与 deny;账号切换时 resolver 会立即看到新快照或 unknown。
    const resolveSubagentModelAccess = this.deps.resolveClaudeSubagentModelAccess
      ? (model: string) => this.deps.resolveClaudeSubagentModelAccess!({
          providerId: opts.providerId ?? null,
          parentModel: opts.model,
          credentialMode: effectiveCredentialMode,
          model,
        })
      : undefined;
    const resolveSubagentModelContextWindow = (model: string): number | undefined => {
      const normalized = normalizeClaudeSubagentModel(model);
      const resolveVerified = this.deps.resolveVerifiedContextWindow;
      if (resolveVerified) {
        try {
          const verified = resolveVerified(opts.providerId ?? null, normalized);
          if (typeof verified === 'number' && Number.isFinite(verified) && verified > 0) {
            return verified;
          }
        } catch {
          // Fall back to catalog metadata when route verification is unavailable.
        }
      }
      const descriptor = this.capabilities.availableModels.find(
        (item) => normalizeClaudeSubagentModel(item.id) === normalized,
      );
      return descriptor && Number.isFinite(descriptor.contextWindow) && descriptor.contextWindow > 0
        ? descriptor.contextWindow
        : undefined;
    };
    // Claude Code only recognizes the 1M wire suffix for native context-window
    // accounting. Normalize the process-level default too; explicit Agent/Task
    // calls are normalized by the PreToolUse hook below.
    const wireSubagentDefault = subagentDefault.envSubagentModel
      ? claudeSubagentModelWithContextWindow(
        subagentDefault.envSubagentModel,
        resolveSubagentModelContextWindow(subagentDefault.envSubagentModel),
      )
      : null;
    // 判定落到 env(唯一写入点,见 env-builder.applySubagentModelEnv)。
    applySubagentModelEnv(env, wireSubagentDefault);
    // 受邀者会话:每个请求带上路由令牌,本机 proxy 据此认出这条会话(托管会话不在活跃会话表里),
    // 只经分享的供应商出站、拒绝它不提供的模型。订阅会话由 CLI 用自己的登录直连 Anthropic,不经 proxy。
    // 内部小模型调用钉到会话模型(覆盖本机设置里的取值)。
    const guestRouteHeader = guestProvider && !nativeCliAuth
      ? `${DEVICE_HOSTED_GUEST_ROUTE_HEADER}: ${guestProvider.routeToken}`
      : undefined;
    if (guestProvider) env.ANTHROPIC_SMALL_FAST_MODEL = sdkModel;
    // Input handoff askpass for this owner's own local tasks only.
    if (!opts.remoteHostId && !hosted && !reviewMode && opts.sessionId) {
      Object.assign(env, this.deps.runtimeConfig.taskShellEnv?.({ sessionId: opts.sessionId }));
    }
    if (guestRouteHeader) {
      env.ANTHROPIC_CUSTOM_HEADERS = env.ANTHROPIC_CUSTOM_HEADERS
        ? `${env.ANTHROPIC_CUSTOM_HEADERS}\n${guestRouteHeader}`
        : guestRouteHeader;
    }
    // 远端单独一份 env:用 'remote' 模式从空字典起(不继承 desktop OS env),否则
    // Windows HOME=C:\Users\Lizi 之类污染远端 cc CLI 的 ~ 展开(session/memory
    // 落怪路径)。详见 env-builder.ts buildClaudeEnv 文档。
    const remoteEnv = opts.remoteHostId
      ? await buildClaudeEnv(this.deps.auth, this.deps.runtimeConfig, {
          credentialMode,
          sessionProviderId: opts.providerId ?? null,
          mode: 'remote',
          activeModel: sdkModel,
          modelContextWindows,
          smallFastModel,
          // 远端不做本地扫描(见上),这里的值就是路由感知后的设置值 —— 保持 env 强制覆盖语义。
          subagentModel: wireSubagentDefault,
        })
      : null;
    // 远端 route 覆盖(route 解析见上方 credentialMode 前的 remoteRoute):
    // 先剥掉 buildClaudeEnv 经 getAuthEnv/endpoint 写入的鉴权/上游字段(订阅 token /
    // provider-oauth 占位 key / 网关 endpoint),再让 route.env 成为唯一事实源,避免两套
    // 鉴权字段并存。route 为 null 时 credentialMode 已回落 'gateway-key',remoteEnv 保持
    // buildClaudeEnv 写入的网关 key + 网关 endpoint(remoteEndpoint),不进本块。
    if (remoteEnv && remoteRoute) {
      for (const key of REMOTE_ROUTE_OVERRIDE_ENV_KEYS) delete remoteEnv[key];
      Object.assign(remoteEnv, remoteRoute.env);
      remoteEnv.ANTHROPIC_BASE_URL = remoteRoute.endpoint;
      // route.env 只决定路由和认证;入口身份继续与 Desktop Code 对齐。
      applyClaudeDesktopEntrypoint(remoteEnv);
    }
    // 远端路由决策日志(排障还原「为什么这个会话走网关/直连/自定义上游」)。只打安全
    // 字段:endpoint 只取 host,凭证形态与接线布尔量;绝不打 token / header 值。
    if (remoteEnv) {
      log.info('remote claude route decision', {
        remoteHostId: opts.remoteHostId,
        providerId: opts.providerId?.trim() || null,
        routeMaterialized: remoteRoute !== null,
        credentialMode: credentialMode ?? null,
        endpointHost: hostOfUrl(remoteEnv.ANTHROPIC_BASE_URL),
        oauthRefreshWired: Boolean(
          remoteEnv.CLAUDE_CODE_OAUTH_TOKEN && this.deps.auth.getFreshSubscriptionToken,
        ),
      });
    }
    // A Bot has its own Profile prompt. The Cindy host identity/custom prompt
    // belongs to ordinary Sessions and must not be layered into every Bot.
    const hostSystemPrompt = opts.botRuntimeProfile
      ? undefined
      : this.deps.runtimeConfig.systemPrompt;
    // 受邀者(另一个账号)的托管会话不带本机的插件清单(本机用户安装与启用的插件)。
    const ghostRosterPrompt = opts.remoteHostId || reviewMode || opts.botRuntimeProfile || hosted?.guest
      ? ''
      : (this.deps.getGhostRosterPrompt?.({ workingDir: opts.workingDir }) ?? '');

    // mutable closure — setVendorOptions 在 handle 上对外暴露,**原地合并** patch。
    // 关键: 不能用 `vo = {...vo, ...patch}` 重赋值 — Claude SDK 在 startSession 时
    // 一次性 buildQuery + buildMcpServers, MCP server instance 里 tool handler 闭包
    // 捕获的是当时构造的 ctx 对象 (ctx.vendorOptions 指向这个 vo)。若重赋值 vo,
    // 旧 ctx.vendorOptions 仍指向旧对象, MCP 工具永远读到老值 → 表现为"toggle 关
    // 再开后 Lead 工具仍指向第一次的 workflow / worker"的 bug。必须用 Object.assign
    // 原地改, 让所有持有这个 ref 的闭包共享同一份最新状态。
    const vo: Record<string, unknown> = { ...(opts.vendorOptions ?? {}) };
    const requireNativeResume = vo._cindyRequireNativeResume === true && !!opts.resumeSessionId;

    log.info('startSession', {
      model: sdkModel,
      providerId: opts.providerId ?? null,
      credentialMode: credentialMode ?? 'fallback',
      effort: opts.effort ?? 'default',
      sdkEffort: initialSdkEffort ?? '<none>',
      workDir: opts.workingDir,
      resume: opts.resumeSessionId ?? 'new',
      resumeSessionAt: (vo.resumeSessionAt as string | undefined) ?? 'none',
      forkSession: (vo.forkSession as boolean | undefined) ?? false,
      claudeCodePath: binaryPath ?? 'default',
      mcpProvidersCount: this.deps.mcpProviders?.length ?? 0,
      // 网络排查标记: 让海外用户第一眼能确认 endpoint 和 debug 开关状态
      endpoint: env.ANTHROPIC_BASE_URL ?? '<sdk-default>',
      debugNet: env.ANTHROPIC_LOG ? `on (ANTHROPIC_LOG=${env.ANTHROPIC_LOG})` : 'off',
    });

    // ── Maker Memory: 启动时预拉 MEMORY.md 索引 + 写入规范段 ────────────────
    // 跟 userPrompt 同语义 — 启动时快照, rewind 重启时仍用本快照, 跨 session 不实时同步。
    // 失败 (manager 没注入 / store init 抛错) 静默跳过, agent 仍能跑。
    let makerMemoryRules = '';
    let makerMemoryIndex = '';
    let memoryFlushController: MemoryFlushController | null = null;
    let mutableModel = opts.model;
    let mutableProviderId = opts.providerId ?? null;
    const getAutoCompactThresholdPct = (
      model = mutableModel,
      provider = mutableProviderId,
    ): number | undefined =>
      this.deps.resolveModelCompactionPct?.(provider, model)
        ?? this.deps.runtimeConfig.autoCompactThresholdPct;
    const autoCompactController =
      getAutoCompactThresholdPct() === undefined
        ? null
        : new AutoCompactController({
            logger: log.child('auto-compact'),
            workdir: opts.workingDir,
            agentKind: 'claude-code',
            getThresholdPct: getAutoCompactThresholdPct,
            compactWhenFull: Boolean(opts.remoteHostId),
          });
    // opts.makerMemoryEnabled 优先 (per-session, renderer 透传); fallback 到 runtimeConfig
    // (host 静态配置, 一般 undefined)。manager 没注入视为禁用。
    const makerMemoryFlag = reviewMode
      ? false
      : opts.makerMemoryEnabled ?? this.deps.runtimeConfig.makerMemoryEnabled ?? false;
    const makerMemory = this.deps.makerMemory;
    const makerMemoryEnabled = makerMemoryFlag === true && !!makerMemory;
    // SSH remote 的 workingDir 是远端路径 — store 定位统一经 scope key;
    // 本地会话额外做 git worktree 归一化 (#2379)。已注入的 makerMemoryScopeKey
    // (含 bot:) 原样透传。Maker Memory 关闭时跳过 git 探测 (Codex #2399 P1):
    // 解析结果本就不会被用, 失败还能空耗 3s timeout。
    const memoryScopeKey = makerMemoryEnabled
      ? (opts.makerMemoryScopeKey ?? (await resolveMemoryScopeKey(opts.workingDir, opts.remoteHostId)))
      : (opts.makerMemoryScopeKey ?? opts.workingDir);
    // This per-session injection flag must not mutate the shared manager.
    if (makerMemoryEnabled && makerMemory) {
      try {
        // 设备托管:记忆在任务所在电脑上,只用随启动选项带来的快照,不打开本机记忆库。
        const store = hosted ? null : await makerMemory.getStore(memoryScopeKey);
        makerMemoryRules = opts.makerMemoryScopeKey?.startsWith('bot:')
          ? ''
          : MAKER_MEMORY_RULES;
        makerMemoryIndex = opts.makerMemoryIndexSnapshot ?? (store ? await store.getIndex() : '');
        memoryFlushController = new MemoryFlushController({
          logger: log.child('memory-flush'),
          workdir: memoryScopeKey,
          agentKind: 'claude-code',
        });
        log.debug('maker memory loaded for session', {
          rulesBytes: makerMemoryRules.length,
          indexBytes: makerMemoryIndex.length,
        });
      } catch (e) {
        log.warn('maker memory load failed at session start (skipping injection)', {
          error: String(e),
        });
      }
    }

    const mcpProviders = reviewMode ? [] : this.deps.mcpProviders ?? [];
    // host-owned 只读白名单在 session 启动时快照; 与 hooks / MCP 注册同样保持整条
    // 会话稳定, 避免中途改数组导致 CLI 权限规则与 prompt cache 前缀漂移。
    const claudeAllowedTools = reviewMode
      ? [...READ_ONLY_CLAUDE_TOOLS]
      : this.deps.claudeAllowedTools?.length
        ? [...this.deps.claudeAllowedTools]
        : undefined;
    // 与 Cindy 重复且结果在 Cindy 里看不到的 Claude 自带工具(host 路由表决定),
    // 加上设备托管时交给 cindy_exec 顶替的本机工具。启动时快照, 整条会话不变。
    const claudeDisallowedTools = [...new Set([
      ...(hosted ? DEVICE_HOSTED_DISALLOWED_CLAUDE_TOOLS : []),
      ...buildClaudeDisallowedTools(reviewMode ? undefined : this.deps.capabilityRouting),
    ])];
    /**
     * 本 session 实际注册进 SDK 的 MCP server 名, 由 buildMcpServers 写入。
     * canUseTool 用它把 `mcp__<server>__<tool>` 归属到唯一 server; 空集合时
     * 一律解析失败 → MCP 策略不参与判定, 维持原权限链。
     */
    let registeredMcpServerNames: ReadonlySet<string> = new Set();
    let hostMcpServerNames: ReadonlySet<string> = new Set();
    let nonHarnessMcpServerNames: ReadonlySet<string> = new Set();
    const noteSdkInitMcpServerNames = (message: unknown): boolean => {
      if (!message || typeof message !== 'object') return false;
      const record = message as Record<string, unknown>;
      if (
        record.type !== 'system' ||
        record.subtype !== 'init' ||
        !Array.isArray(record.mcp_servers)
      ) {
        return false;
      }
      const finalNames = record.mcp_servers
        .map((server) => {
          if (!server || typeof server !== 'object') return undefined;
          const serverRecord = server as Record<string, unknown>;
          if (serverRecord.status !== 'connected') return undefined;
          const name = serverRecord.name;
          return typeof name === 'string' && name.length > 0 ? name : undefined;
        })
        .filter((name): name is string => name !== undefined);
      // The init payload is the SDK's authoritative post-settings registry.
      // Replace instead of unioning so a query rebuild cannot retain a server
      // removed from user/project/local settings and disable a guard forever.
      registeredMcpServerNames = new Set(finalNames);
      return true;
    };
    const refreshSdkMcpProvenance = async (currentQ: Query): Promise<void> => {
      const fallbackNames = new Set(hostMcpServerNames);
      const queryWithStatus = currentQ as Query & {
        mcpServerStatus?: () => Promise<Array<{
          name: string;
          status: string;
          scope?: string;
        }>>;
      };
      if (typeof queryWithStatus.mcpServerStatus !== 'function') {
        if (currentQ === q) nonHarnessMcpServerNames = fallbackNames;
        return;
      }
      try {
        const statuses = await queryWithStatus.mcpServerStatus();
        const connectedNonHarnessNames = new Set<string>();
        for (const server of statuses) {
          if (
            server.status === 'connected' &&
            typeof server.name === 'string' &&
            server.name.length > 0 &&
            (
              hostMcpServerNames.has(server.name) ||
              isUserSettingsMcpScope(server.scope)
            )
          ) {
            connectedNonHarnessNames.add(server.name);
          }
        }
        if (currentQ === q) nonHarnessMcpServerNames = connectedNonHarnessNames;
        return;
      } catch (error) {
        // Init names have no provenance. On status failure, preserve only
        // host-injected MCPs and keep settings/plugin routing fail-closed.
        log.warn('failed to read scoped MCP status for capability routing', {
          error: error instanceof Error ? error.message : String(error),
        });
      }
      if (currentQ === q) nonHarnessMcpServerNames = fallbackNames;
    };
    const buildMcpServers = (): Record<string, McpServerConfig> | undefined => {
      const client = opts[LOCAL_AGENT_CLIENT];
      if (client && (!hosted || client.hostToolsOnly)) {
        hostMcpServerNames = new Set([client.mcpName ?? 'client']);
        registeredMcpServerNames = hostMcpServerNames;
        nonHarnessMcpServerNames = hostMcpServerNames;
        return { [client.mcpName ?? 'client']: { type: 'http', url: client.url, headers: { Authorization: `Bearer ${client.token}` } } };
      }
      if (hosted) {
        // 设备托管:只用经隧道的服务——cindy_exec(文件与命令)+ 任务所在电脑提供的 Cindy 工具。
        const headers = { Authorization: `Bearer ${hosted.tunnelToken}` };
        const out: Record<string, McpServerConfig> = Object.create(null);
        for (const name of [DEVICE_HOSTED_EXEC_MCP_SERVER, ...hosted.mcpServers]) {
          if (Object.prototype.hasOwnProperty.call(out, name)) continue;
          out[name] = { type: 'http', url: deviceHostedMcpUrl(hosted, name), headers } as McpServerConfig;
        }
        hostMcpServerNames = new Set(Object.keys(out));
        registeredMcpServerNames = hostMcpServerNames;
        nonHarnessMcpServerNames = hostMcpServerNames;
        return { ...out };
      }
      const providers = mcpProviders;
      if (providers.length === 0) {
        hostMcpServerNames = new Set();
        registeredMcpServerNames = hostMcpServerNames;
        nonHarnessMcpServerNames = hostMcpServerNames;
        return undefined;
      }
      const context: McpProviderContext = {
        agentKind: 'claude-code' as const,
        workingDir: opts.workingDir,
        ...((makerMemoryEnabled || opts.makerMemoryScopeKey) ? { memoryScopeKey } : {}),
        vendorOptions: vo,
        // business sessionId 由 maker.createSession 通过 opts.sessionId 注入
        // (见 maker.ts: agent.startSession({...opts, sessionId: id}))。MCP server
        // 工厂闭包绑定此值, 控制类工具 (如 start_team / create_worker) 用它把回调路由
        // 到对应 session 的业务函数。host 直接调 startSession 而没透 sessionId
        // 时此处为 undefined, 工具按"无 session 绑定"语义处理。
        sessionId: opts.sessionId,
        mcpCallerKind: 'root',
        mcpCallerAttested: true,
        ...(opts.sessionInstanceId ? { sessionInstanceId: opts.sessionInstanceId } : {}),
        getSessionContext: () => context,
      };
      // null-prototype: server 名来自用户可控的自定义 MCP id, 而 id 正则允许下划线,
      // `__proto__` 是合法 id。用普通 `{}` 时 `out['__proto__'] = config` 命中的是原型
      // 访问器 —— 不产生自有属性(hasOwnProperty / Object.keys 都看不见, 去重与归属判定
      // 一起失效), 反而把这个 map 的原型换成了 config。null-prototype 让这类名字退化成
      // 普通字符串键。
      const out: Record<string, McpServerConfig> = Object.create(null);
      for (const provider of providers) {
        // cindy_memory: per-session flag 关 → 不注册; remote → in-process sdk 实例
        // 不可序列化, 这里跳过, 由 host 的 remoteCcQueryFactory 按同一 flag 以
        // http 形态经 bridge 注入 (见 cc-remote-mcp.ts)。
        if (provider.name === 'cindy_memory' && (!makerMemoryEnabled || opts.remoteHostId)) continue;
        if (!isBotMcpServerAllowed(opts.botRuntimeProfile?.mcpPolicy, provider.name)) continue;
        if (provider.isEnabled && !provider.isEnabled(context)) continue;
        // 同名 provider 先注册者胜 —— host 把用户自定义 MCP **追加**在内置之后, 后写
        // 覆盖会让一个 id 取名 `cindy_browser` 的自定义远程端点顶替内置 server:
        // 既悄悄换掉了内置能力, 又让审批策略(只看 serverName)把第三方端点的所有工具
        // 当第一方静默放行。host 侧也拦了这类保留名, 这里是纵深防御。
        if (Object.prototype.hasOwnProperty.call(out, provider.name)) {
          log.warn('duplicate MCP server name; keeping the first registration', {
            serverName: provider.name,
          });
          continue;
        }
        const config = provider.toClaudeSdkConfig?.(context);
        if (!config) continue;
        out[provider.name] = config as McpServerConfig;
      }
      // canUseTool 只认这批真实注册过的 server 名, 不靠 `mcp__` 工具名切分猜归属
      // (见 resolveMcpToolTarget: 自定义 server id 可以含 `__`, 盲切会被冒名顶替)。
      hostMcpServerNames = new Set(Object.keys(out));
      registeredMcpServerNames = hostMcpServerNames;
      nonHarnessMcpServerNames = hostMcpServerNames;
      // 交回普通对象: SDK / RPC 序列化路径按普通对象处理(有的实现会调 obj.hasOwnProperty)。
      // spread 走 CreateDataProperty, 不触发 `__proto__` setter, 所以这一步是安全的。
      return Object.keys(out).length > 0 ? { ...out } : undefined;
    };

    // ── userMessageStream + permission callback 准备 ────────────────────────
    // 类型对齐 Claude Code streaming-input 协议: 必须有 message: {role, content}
    // 包装层(老链路 agentManager.ts:850-867 makeUserMessage 同结构)。
    // uuid 字段可选 — 调用方传 sendOpts.messageUuid 时注入, SDK 透传当作 file
    // checkpoint snapshot 的 messageId (cli.js:7086382), rewind preview 反查同款 uuid。
    type SdkUserInput = {
      type: 'user';
      message: { role: 'user'; content: string | ClaudeSdkContentBlock[] };
      parent_tool_use_id: null;
      uuid?: string;
    };
    // mutable 引用 — rewind 重启时整个换一份新的:
    //   - 老 abortController 在 q.close() 时被 SDK 标记为 aborted (虽然我们没显式调
    //     .abort(), 但 close() 内部会让信号变 aborted 状态), 复用它启动新 sdkQuery 会
    //     立刻被识别为 aborted → forward loop 抛 "aborted by user"。
    //   - 老 inputQueue 的 generator 在 q.close 后仍可能挂在 await waiter, 重建避免
    //     新 sdkQuery 跟老 generator 抢 push 进来的消息 (createAsyncQueue 是
    //     单消费者设计, 多 generator 会分摊事件)。
    // handle.send / abort / close 都通过 closure 引用最新的实例。
    let inputQueue = createAsyncQueue<SdkUserInput>();
    let abortController = new AbortController();
    let interactionResolver: InteractionResolver | null = null;
    // Keep the policy across Claude task_notification auto-continue turns,
    // which do not call handle.send again. The next explicit send replaces it.
    let activeTurnPermissionPolicy: TurnPermissionPolicy | null = null;
    let activeToolsDisabled = false;
    const denyTextOnlyTool = () => ({
      continue: true,
      hookSpecificOutput: {
        hookEventName: 'PreToolUse' as const,
        permissionDecision: 'deny' as const,
        permissionDecisionReason: 'Tools are disabled for this host-owned text-only turn.',
      },
    });
    let activeCapabilitySelectionText = '';
    const appendActiveCapabilitySelectionText = (text: string | undefined): void => {
      if (!text) return;
      activeCapabilitySelectionText = [activeCapabilitySelectionText, text]
        .filter(Boolean)
        .join('\n');
    };
    // 设备托管:子代理定义(影子目录里同步过来的项目 / 个人子代理)里的工具限制,按需读一次。
    let hostedAgentRules: Promise<Map<string, DeviceHostedAgentToolRule>> | null = null;
    const loadHostedAgentRules = (): Promise<Map<string, DeviceHostedAgentToolRule>> => {
      hostedAgentRules ??= (async () => {
        const rules = new Map<string, DeviceHostedAgentToolRule>();
        const dir = path.join(opts.workingDir, '.claude', 'agents');
        const entries = await fs.readdir(dir, { recursive: true }).catch(() => [] as string[]);
        for (const entry of entries) {
          if (typeof entry !== 'string' || !entry.endsWith('.md')) continue;
          const parsed = parseClaudeAgentToolRule(await fs.readFile(path.join(dir, entry), 'utf8').catch(() => ''));
          if (parsed) rules.set(parsed.name, parsed.rule);
        }
        return rules;
      })();
      return hostedAgentRules;
    };
    const turnChangeCaptureHook: HookCallback = async (input) => {
      if (input.hook_event_name === 'PreToolUse' && activeToolsDisabled) return denyTextOnlyTool();
      // 设备托管:改动发生在任务所在电脑上,由那边的执行器在写之前抓取。子代理的工具限制在这里
      // 按子代理定义判(顶替工具是 MCP 工具,SDK 不按名字收窄)。
      if (hosted) {
        if (input.hook_event_name === 'PreToolUse') {
          const pre = input as PreToolUseHookInput & { agent_id?: string; agent_type?: string };
          // 受邀者:子代理不能用隔离选项(在本机建 worktree,或用本机用户的 claude.ai 账号开云端任务)。
          const guestDenial = hosted.guest ? deviceHostedGuestAgentDenial(pre.tool_name, pre.tool_input) : null;
          if (guestDenial) {
            return {
              continue: true,
              hookSpecificOutput: {
                hookEventName: 'PreToolUse' as const,
                permissionDecision: 'deny' as const,
                permissionDecisionReason: guestDenial,
              },
            };
          }
          const builtin = deviceHostedBuiltinToolName(pre.tool_name);
          // 参数化规则(Bash(git diff:*) 之类)要按本次命令判范围,不能当成整个工具放行。
          const toolInput = pre.tool_input as Record<string, unknown> | undefined;
          const command = typeof toolInput?.command === 'string' ? toolInput.command : undefined;
          if (builtin && pre.agent_id && pre.agent_type
            && !deviceHostedSubagentAllows(pre.agent_type, builtin, await loadHostedAgentRules(),
              command !== undefined ? { command } : undefined)) {
            return {
              continue: true,
              hookSpecificOutput: {
                hookEventName: 'PreToolUse' as const,
                permissionDecision: 'deny' as const,
                permissionDecisionReason: `The ${pre.agent_type} agent cannot use ${builtin}.`,
              },
            };
          }
        }
        return { continue: true };
      }
      const captureCwd = opts.workingDir;
      const captureSessionId = opts.sessionId;
      if (!this.deps.turnChangeCapture || !captureCwd || !captureSessionId) {
        return { continue: true };
      }
      if (input.hook_event_name === 'PreToolUse') {
        const pre = input as PreToolUseHookInput;
        const toolInput = pre.tool_input as Record<string, unknown> | undefined;
        const targetPath = ['file_path', 'path', 'notebook_path']
          .map((key) => toolInput?.[key])
          .find((value): value is string => typeof value === 'string' && value.length > 0);
        if (targetPath && ['Write', 'Edit', 'MultiEdit', 'NotebookEdit'].includes(pre.tool_name)) {
          const captureTargetPath = opts.remoteHostId
            ? targetPath
            : await resolveClaudeFileWriteTarget(captureCwd, targetPath);
          if (captureTargetPath) {
            await this.deps.turnChangeCapture.beforeKnownFileWrite({
              sessionId: captureSessionId,
              provider: 'claude-code',
              cwd: captureCwd,
              targetPath: captureTargetPath,
              ...(opts.remoteHostId ? { remote: true } : {}),
            });
          } else {
            this.deps.turnChangeCapture.noteOpaqueWrite({
              sessionId: captureSessionId,
              provider: 'claude-code',
              cwd: captureCwd,
            });
          }
        }
      } else if (
        input.hook_event_name === 'PostToolUse'
        || input.hook_event_name === 'PostToolUseFailure'
      ) {
        const toolName = (input as { tool_name?: unknown }).tool_name;
        if (typeof toolName !== 'string' || (toolName !== 'Bash' && !toolName.startsWith('mcp__'))) {
          return { continue: true };
        }
        this.deps.turnChangeCapture.noteOpaqueWrite({
          sessionId: captureSessionId,
          provider: 'claude-code',
          cwd: captureCwd,
          ...(opts.remoteHostId ? { remote: true } : {}),
        });
      }
      return { continue: true };
    };
    const reviewReadOnlyHook: HookCallback = async (input) => {
      if (input.hook_event_name !== 'PreToolUse') return { continue: true };
      if (activeToolsDisabled) return denyTextOnlyTool();
      const pre = input as PreToolUseHookInput;
      const toolName = pre.tool_name;
      const updatedInput = isReadOnlyClaudeTool(toolName)
        ? await resolveReviewReadToolInput({
          toolName,
          toolInput: pre.tool_input as Record<string, unknown> | undefined,
          workingDir: opts.workingDir,
          grants: reviewReadGrants,
        })
        : null;
      if (updatedInput) {
        return {
          continue: true,
          hookSpecificOutput: {
            hookEventName: 'PreToolUse',
            permissionDecision: 'allow',
            updatedInput,
          },
        };
      }
      return {
        continue: true,
        hookSpecificOutput: {
          hookEventName: 'PreToolUse',
          permissionDecision: 'deny',
          permissionDecisionReason:
            'Cindy Review only permits read-only access to this task and its explicit artifacts.',
        },
      };
    };
    // 订阅会话运行中的工作区设置守门(启动与重建时的检查见 buildQuery):
    //   - CLI 热加载项目级设置前经 ConfigChange 问这里,命中就阻止这次变更;
    //   - 但被拒的文件还在磁盘上,之后任何一次全量重载(别的设置文件变更、flag settings、
    //     CLI 回写权限)都会读到它 —— 所以命中即判会话已污染:结束当前 CLI 进程并以终态
    //     错误收尾,下一次发送重建时 buildQuery 的检查拒绝启动;
    //   - EnterWorktree 会把 CLI 的项目根挪到守门没检查过、设置 watcher 也不监视的目录,
    //     订阅会话不允许。
    let workspaceSettingsTainted = false;
    const taintWorkspaceSettings = (reason: string): void => {
      if (workspaceSettingsTainted) return;
      workspaceSettingsTainted = true;
      log.warn('workspace settings would redirect a Claude subscription session; ending it', { reason });
      setTimeout(() => {
        if (closed) return;
        eventQueue.push({
          type: 'error',
          data: { message: reason, isTerminal: true, reason: 'claude_subscription_workspace_override' },
          source: 'claude-code',
        });
        if (turnInFlight) emitTurnBoundary('claude_subscription_workspace_override');
        teardownDeadHandle('workspace settings override');
      }, 0);
    };
    const workspaceSettingsConfigChangeHooks: Partial<Record<HookEvent, HookCallbackMatcher[]>> = {
      ConfigChange: [{
        hooks: [async (input) => {
          const reason = await workspaceConfigChangeBlockReason(
            input as { source?: string; file_path?: string },
            opts.workingDir,
          );
          if (!reason) return { continue: true };
          taintWorkspaceSettings(reason);
          return { decision: 'block', reason };
        }],
      }],
      PreToolUse: [{
        matcher: 'EnterWorktree',
        hooks: [async () => ({
          continue: true,
          hookSpecificOutput: {
            hookEventName: 'PreToolUse',
            permissionDecision: 'deny',
            permissionDecisionReason:
              'This task runs on the Claude subscription, which only uses the settings of its own working directory. ' +
              'Switching worktrees mid-task is not available here; start a new task in the other worktree instead.',
          },
        })],
      }],
    };
    // Native Claude Auto skips canUseTool. Hand back only the calls Cindy itself must decide;
    // everything else stays with the native classifier so no call is reviewed twice.
    const nativeAutoPolicyHook: HookCallback = async (input) => {
      if (input.hook_event_name !== 'PreToolUse') return { continue: true };
      if (
        mutablePermissionMode !== 'auto' || mutablePlanMode || planTurnActive
        || !usesNativeClaudeAutoReview()
      ) return { continue: true };
      const pre = input as PreToolUseHookInput;
      const toolName = pre.tool_name;
      const decide = (permissionDecision: 'allow' | 'ask', reason: string) => ({
        continue: true,
        hookSpecificOutput: { hookEventName: 'PreToolUse' as const, permissionDecision, permissionDecisionReason: reason },
      });
      const isMcp = resolveMcpToolTarget(toolName, registeredMcpServerNames) !== null;
      const mcpPolicy = isMcp ? classifyMcpApprovalPolicy(toolName, pre.tool_input) : null;
      // Requester authority (owner / group guest) and forceConfirmToolCall are only known to
      // Cindy, and a channel policy outranks trusted-MCP approval: route every call to canUseTool.
      if (activeTurnPermissionPolicy) return decide('ask', 'Cindy reviews tool calls in channel turns.');
      // Trusted MCP still goes through canUseTool: the Host shortcut allows it without a model call,
      // but a plugin-delegated task must be re-checked against its live delegation scope first.
      if (mcpPolicy === 'auto-approve') return decide('ask', 'Trusted Cindy tool: Host shortcut and delegation check.');
      if (mcpPolicy === 'prompt-each-time') return decide('ask', 'This tool requires Cindy confirmation.');
      return { continue: true };
    };
    const localClaudeHooks = reviewMode
      ? mergeClaudeHookSets(
          { PreToolUse: [{ hooks: [reviewReadOnlyHook] }] },
          nativeCliAuth ? workspaceSettingsConfigChangeHooks : undefined,
        )
      : mergeClaudeHookSets(
          buildClaudeLocalToolGuardHooks(
            this.deps.capabilityRouting,
            () => activeCapabilitySelectionText,
            (toolName, route) => {
              log.warn('downstream MCP source denied by host PreToolUse route', {
                toolName,
                capabilityId: route.capabilityId,
                replacement: route.replacement?.id,
              });
            },
            () => nonHarnessMcpServerNames,
          ),
          {
            PreToolUse: [{ hooks: [turnChangeCaptureHook] }],
            PostToolUse: [{ hooks: [turnChangeCaptureHook] }],
            PostToolUseFailure: [{ hooks: [turnChangeCaptureHook] }],
          },
          // Keep the existing local routing/capture hooks first: callers and tests
          // rely on their observable order. The exact-match Orca provenance guard
          // still runs for send_to_lead after those hooks and denies descendants.
          // 账号/模型准入是执行前提,不是用户工具权限。仍放在 PreToolUse,确保
          // Full access 也无法绕过;它排在既有捕获/路由 hook 后,不改变既有顺序。
          buildClaudeSubagentModelGuardHooks(
            resolveSubagentModelAccess,
            wireSubagentDefault ?? undefined,
            (model) => {
              log.warn('subagent model denied by account access preflight', { model });
            },
            resolveSubagentModelContextWindow,
          ),
          buildClaudeOrcaCallerProvenanceHooks(),
          buildClaudeAskUserQuestionCallerProvenanceHooks(),
          nativeCliAuth ? workspaceSettingsConfigChangeHooks : undefined,
          this.deps.claudeHooks,
          // Last: earlier guards may deny; this only routes what remains.
          { PreToolUse: [{ hooks: [nativeAutoPolicyHook] }] },
        );
    const deniedCapabilityRoute = (toolName: string) => {
      const route = findClaudeMcpCapabilityRoute(
        this.deps.capabilityRouting,
        toolName,
        nonHarnessMcpServerNames,
      );
      return route &&
        !isCapabilityRouteInvocationAllowed(route, activeCapabilitySelectionText)
        ? route
        : undefined;
    };
    const forceTurnConfirmation = (toolName: string, input: unknown): boolean => {
      const policy = activeTurnPermissionPolicy;
      if (!policy || mutablePermissionMode === 'bypassPermissions') return false;
      try {
        return policy.forceConfirmToolCall(toolName, input) === true;
      } catch (error) {
        // A safety classifier failure cannot become an approval bypass.
        log.error('turn permission policy threw -> force confirmation', {
          toolName,
          origin: policy.origin,
          error: error instanceof Error ? error.message : String(error),
        });
        return true;
      }
    };
    // 事件队列预先声明 —— canUseTool 路径要 push interaction_dismissed 事件
    const eventQueue = createAsyncQueue<AgentEvent>();
    // Cancellation closes a provider continuation with a queued terminal done.
    // Keep the handle busy until the single Session consumer has processed that
    // exact event, otherwise a new send can enter ahead of the queued boundary.
    const continuationTerminalBoundaryEvents = new WeakSet<AgentEvent>();
    let pendingContinuationTerminalBoundaries = 0;

    // ── Pending interaction 跟踪 ───────────────────────────────────────────
    // setPermissionMode 切换 / close session 时, 用此 Map 找到所有挂着的 interaction
    // 强制 resolve 它们 + emit interaction_dismissed, 以便 UI 关闭对话框。
    type PendingEntry = {
      kind: InteractionRequest['kind'];
      resolve: (d: InteractionDecision) => void;
      settled: boolean;
      /** Auto 审阅故障降级来的确认:系统收口不能当成用户点了拒绝。 */
      unavailableHandoff?: boolean;
      /** 目录授权变化会使这次文件读写审批的根快照失效。 */
      directorySensitive?: boolean;
    };
    const pendingInteractions = new Map<string, PendingEntry>();

    function safeDefaultDecision(kind: InteractionRequest['kind'], reason: string): InteractionDecision {
      if (kind === 'ask_user_question') return { kind: 'ask_user_question', answers: {} };
      return { kind, behavior: 'deny', reason } as InteractionDecision;
    }

    /**
     * 把 InteractionRequest 派发给 host resolver, 同时登记进 pendingInteractions。
     * 任一时刻可由 dismissAllPending 强制提前 resolve(走 settled flag 防止 host 后续回调
     * 又 resolve 一次)。
     */
    async function dispatchInteraction(
      req: InteractionRequest,
      opts?: { directorySensitive?: boolean },
    ): Promise<InteractionDecision> {
      if (!interactionResolver) {
        return safeDefaultDecision(req.kind, 'no_resolver_attached');
      }
      const resolver = interactionResolver;
      return new Promise<InteractionDecision>((resolve) => {
        const entry: PendingEntry = {
          kind: req.kind,
          resolve,
          settled: false,
          ...(opts?.directorySensitive ? { directorySensitive: true } : {}),
          ...(req.kind === 'permission' && isAutoReviewUnavailableMetadata(req.metadata)
            ? { unavailableHandoff: true }
            : {}),
        };
        pendingInteractions.set(req.requestId, entry);
        const finalize = (d: InteractionDecision) => {
          if (entry.settled) return;
          entry.settled = true;
          pendingInteractions.delete(req.requestId);
          resolve(d);
        };
        resolver(req)
          .then(finalize)
          .catch((e) => {
            log.warn('interaction resolver threw', { kind: req.kind, requestId: req.requestId, error: String(e) });
            finalize(safeDefaultDecision(req.kind, 'resolver_threw'));
          });
      });
    }

    /**
     * 强制 resolve 所有 pending interaction + emit dismissed 事件。
     * 用于 setPermissionMode 切换(Phase B)/ close session。resolveAs 决定剩余 pending 怎么处理:
     * - 'allow' 用于切到 bypassPermissions 时, ask 类自动放过
     * - 'deny' 用于切到更严的 mode / 关闭时
     */
    function dismissAllPending(reason: string, resolveAs: 'allow' | 'deny'): void {
      if (pendingInteractions.size === 0) return;
      const entries = Array.from(pendingInteractions.entries());
      for (const [requestId, entry] of entries) {
        if (entry.settled) continue;
        const decision = resolveAs === 'allow' && entry.kind !== 'ask_user_question'
          ? ({ kind: entry.kind, behavior: 'allow' } as InteractionDecision)
          : safeDefaultDecision(entry.kind, reason);
        if (resolveAs === 'deny' && entry.unavailableHandoff) {
          autoReviewConfirmUndeliveredNotice.notify();
        }
        entry.settled = true;
        pendingInteractions.delete(requestId);
        entry.resolve(decision);
        const dismissedPayload: InteractionDismissedEvent = {
          requestId,
          reason,
          resolvedAs: resolveAs,
        };
        eventQueue.push({ type: 'interaction_dismissed', data: dismissedPayload, source: 'claude-code' });
      }
    }

    function dismissSinglePending(requestId: string, reason: string): void {
      const entry = pendingInteractions.get(requestId);
      if (!entry || entry.settled) return;
      if (entry.unavailableHandoff) autoReviewConfirmUndeliveredNotice.notify();
      entry.settled = true;
      pendingInteractions.delete(requestId);
      entry.resolve(safeDefaultDecision(entry.kind, reason));
      const resolvedAs = entry.kind === 'ask_user_question' ? 'allow' : 'deny';
      eventQueue.push({ type: 'interaction_dismissed', data: { requestId, reason, resolvedAs }, source: 'claude-code' });
    }

    function dismissDirectorySensitivePending(reason: string): void {
      for (const [requestId, entry] of pendingInteractions) {
        if (entry.directorySensitive) dismissSinglePending(requestId, reason);
      }
    }

    /**
     * MCP 工具的 host 审批档位 —— 与 Codex 的 mcpServerElicitation 同一个
     * deps.getMcpToolApprovalPolicy 真源。两端共用后, 同一个第一方 MCP 不会出现
     * "Codex 静默执行 / Claude 每次调用都弹窗"的分叉(浏览器自动化这类高频 server
     * 一次调研能攒出上百个权限请求)。
     *   auto-approve      → 静默放行, 不打扰用户
     *   prompt-each-time  → Ask 逐次确认且不持久化授权;Auto 交统一审阅器;
     *                       Full access 不弹窗,已挂起的普通审批也随新档位结算
     *   prompt / 未注入   → 完全维持原有权限链
     * 策略抛错或返回非法值时按最保守的 prompt-each-time 处理(与 Codex 侧一致)。
     *
     * 本地 canUseTool 与远端 onApprovalRequest 都走这里 —— 否则同一套 MCP 配置在
     * SSH 会话里又会退回"逐次弹窗 + 没有 forced prompt 保护"的老行为。
     *
     * SDK 的 bypassPermissions 原生跳过操作审批;Host 回调同样遵循当前档位,
     * 不通过 hook 或 MCP 风险分类重新引入 Full access 特殊审批。
     */
    const classifyMcpApprovalPolicy = (
      toolName: string,
      input: unknown,
    ): 'auto-approve' | 'prompt' | 'prompt-each-time' => {
      const target = resolveMcpToolTarget(toolName, registeredMcpServerNames);
      const classifier = this.deps.getMcpToolApprovalPolicy;
      if (!target || !classifier) return 'prompt';
      try {
        const policy = classifier({
          serverName: target.serverName,
          toolName: target.toolName,
          toolParams: input,
        });
        if (policy === 'auto-approve' || policy === 'prompt' || policy === 'prompt-each-time') {
          if (policy === 'auto-approve') {
            log.debug('mcp tool auto-approved by host policy', {
              serverName: target.serverName,
              toolName: target.toolName,
            });
          }
          return policy;
        }
        log.error('invalid MCP approval policy -> prompt each time', {
          serverName: target.serverName,
          policy,
        });
      } catch (error) {
        log.error('MCP approval policy threw -> prompt each time', {
          serverName: target.serverName,
          error: error instanceof Error ? error.message : String(error),
        });
      }
      return 'prompt-each-time';
    };

    // canUseTool dispatcher —— 三路分支(参考 agentManager.ts:1054-1162):
    //  1. AskUserQuestion: 模型问问题, 转 ask_user_question kind, decision.answers 拼回 updatedInput
    //  2. ExitPlanMode:   plan 模式提交计划, 转 plan_review kind, decision.editedPlan 覆盖 plan
    //  3. 其他工具:        转 permission kind, allow/deny + 可选 updatedInput
    // 注: destructive guard(agentManager.ts:1054-1065)只在 feishuBot session 启用; chat 默认 OFF,
    // 本轮不在 maker-core 实现; 若未来需要按 session opt-in, 通过 vendorOptions 传入 guard 函数。
    const canUseTool: CanUseTool = async (toolName, input, options) => {
      // SDK 不保证 assistant message 先于 canUseTool yield, 冗余 add (Set 幂等),
      // 顺便覆盖 AskUserQuestion / ExitPlanMode 等用户交互期间不计 idle 配额。
      if (typeof options.toolUseID === 'string' && options.toolUseID.length > 0) {
        pendingToolIds.add(options.toolUseID);
        clearUpstreamResponseIdle();
      }

      // ── 1. AskUserQuestion 分支 ──
      if (toolName === 'AskUserQuestion') {
        const questions = (input as { questions?: AskUserQuestionItem[] }).questions;
        if (!questions || questions.length === 0) {
          return { behavior: 'allow', updatedInput: input };
        }
        const decision = await dispatchInteraction({
          kind: 'ask_user_question',
          requestId: options.toolUseID,
          toolUseId: options.toolUseID,
          questions,
        });
        if (decision.kind !== 'ask_user_question') {
          log.warn('AskUserQuestion got mismatched decision', { decKind: decision.kind });
          return { behavior: 'deny', message: 'resolver kind mismatch' };
        }
        // 澄清答案同样改变本轮授权范围(用户把范围从 src/ 收窄到 build/ 后,后续 `rm -rf src` 必须按
        // 澄清后的意图裁决)→ 并入有界 review intent 并清空决策缓存,否则 reviewer 仍按原含糊请求
        // 裁决、可能静默 allow(codex 报)。
        setAutoReviewIntent(composeAutoReviewIntentWithClarification(
          currentAutoReviewIntent,
          Object.entries(decision.answers ?? {}).map(([question, answer]) => ({ question, answer })),
        ));
        // 把用户回答拼回 SDK 让模型读 (老链路 agentManager.ts:1097-1106 把 answers 当 updatedInput.answers)
        return {
          behavior: 'allow',
          updatedInput: { ...(input as Record<string, unknown>), answers: decision.answers } as Record<string, unknown>,
        };
      }

      // ── 2. ExitPlanMode 分支 ──
      if (toolName === 'ExitPlanMode') {
        const planInput = input as { plan?: string; planFilePath?: string };
        const plan = typeof planInput.plan === 'string' ? planInput.plan : '';
        const planFilePath = typeof planInput.planFilePath === 'string' ? planInput.planFilePath : undefined;
        if (!plan.trim()) {
          // 空 plan 直接放过(老链路 agentManager.ts:1118-1120 同样处理)
          return { behavior: 'allow', updatedInput: input };
        }
        // 计划审批期间用户可能继续发消息(currentAutoReviewIntent 会被覆盖);实施阶段的审查意图
        // 必须是"发起计划时的原始请求 + 最终获批计划",不能掺进审批期间的内部跟进消息(codex 报)。
        const planRequestAutoReviewIntent = currentAutoReviewIntent;
        const decision = await dispatchInteraction({
          kind: 'plan_review',
          requestId: options.toolUseID,
          toolUseId: options.toolUseID,
          plan,
          planFilePath,
        });
        if (decision.kind !== 'plan_review') {
          log.warn('ExitPlanMode got mismatched decision', { decKind: decision.kind });
          return { behavior: 'deny', message: 'resolver kind mismatch' };
        }
        if (decision.behavior === 'deny') {
          if (!decision.dismissed) {
            appendActiveCapabilitySelectionText(decision.reason);
            if (decision.reason?.trim()) setAutoReviewIntent(appendAutoReviewUserIntent(planRequestAutoReviewIntent, decision.reason));
          }
          return { behavior: 'deny', message: decision.reason ?? 'plan rejected by user' };
        }
        appendActiveCapabilitySelectionText(
          capabilitySelectionAddedByPlanEdit(
            this.deps.capabilityRouting,
            'claude-code',
            plan,
            decision.editedPlan,
          ),
        );
        // 计划批准 → 本轮 plan 循环结束: SDK 切回底层权限档。武装态正常已在 send
        // 消耗(plan_mode_changed 已广播), 这里兜底处理"未经 send 直接批准"的路径。
        // 不能在 canUseTool 里 await SDK 控制请求(SDK 正等本回调返回),
        // fire-and-forget 即可 —— CLI 在 ExitPlanMode 批准后本来就会离开 plan mode,
        // 这里只是把落点确定性地钉在用户所选档位。
        if (mutablePlanMode || planTurnActive) {
          planTurnActive = false;
          if (mutablePlanMode) {
            mutablePlanMode = false;
            eventQueue.push({ type: 'plan_mode_changed', data: { enabled: false }, source: 'claude-code' });
          }
          sdkInPlanMode = false;
          void q.setPermissionMode(effectiveSdkPermissionMode()).catch((e) => {
            log.warn('post-plan-approval setPermissionMode failed', { error: String(e) });
          });
        }
        const finalPlan = decision.editedPlan ?? plan;
        // 计划获批后,后续实施动作要按"原始意图 + 获批计划"审查 —— 否则轻量 reviewer 仍按批准前的
        // 过期意图裁决,计划里明确授权的动作会被误 block(或反之)。
        setAutoReviewIntent(composeAutoReviewIntentWithApprovedPlan(
          planRequestAutoReviewIntent,
          finalPlan,
        ));
        return {
          behavior: 'allow',
          updatedInput: { ...(input as Record<string, unknown>), plan: finalPlan } as Record<string, unknown>,
        };
      }

      // ── 3. 其他工具 → permission kind ──
      const capabilityRoute = deniedCapabilityRoute(toolName);
      if (capabilityRoute) {
        log.warn('downstream MCP source denied by host capability route', {
          toolName,
          capabilityId: capabilityRoute.capabilityId,
          replacement: capabilityRoute.replacement?.id,
        });
        return {
          behavior: 'deny',
          message: capabilityRoute.replacement
            ? `This downstream source was not selected. Use Cindy capability ${capabilityRoute.replacement.id}.`
            : 'This downstream source was not selected.',
        };
      }
      if (isPlanToolBlocked(toolName)) {
        return { behavior: 'deny', message: 'The current Plan turn is read-only.' };
      }
      if (mutablePermissionMode === 'bypassPermissions' && !forceTurnConfirmation(toolName, input)) {
        return { behavior: 'allow', updatedInput: input };
      }
      // Auto can resolve allow/block without a UI. Other modes retain the
      // existing fail-closed behavior when no interaction surface is attached.
      const canReviewWithoutUi = mutablePermissionMode === 'auto';
      if (!interactionResolver && !canReviewWithoutUi) {
        if (isReadOnlyClaudeTool(toolName)) {
          return { behavior: 'allow', updatedInput: input };
        }
        log.warn('canUseTool without interactionResolver → fail-closed deny', { tool: toolName });
        return { behavior: 'deny', message: 'no interaction resolver attached; denying non-read-only tool (fail-closed)' };
      }

      // 3a. MCP 工具过 host 审批策略(本地与远端会话共用 classifyMcpApprovalPolicy)。
      const turnPolicyForcePrompt = forceTurnConfirmation(toolName, input);
      const mcpApprovalPolicy = classifyMcpApprovalPolicy(toolName, input);
      let forcePrompt = mutablePermissionMode !== 'auto' && turnPolicyForcePrompt;
      let unavailableHandoff = false;
      let autoReviewAskReason: string | undefined;
      let reviewedWritePath: string | null | undefined;
      let executionInput = input;
      const normalizedAction = normalizeBuiltinToolForAutoReview(toolName, input);
      const builtinReviewAction = normalizedAction.kind === 'other'
        ? toolAutoReviewAction(toolName, input)
        : normalizedAction;
      const directorySensitivePermission = builtinReviewAction?.kind === 'read'
        || builtinReviewAction?.kind === 'file-write';
      const reviewPermissionMode = mutablePermissionMode;
      if (reviewPermissionMode === 'auto' || (mcpApprovalPolicy === 'auto-approve' && !turnPolicyForcePrompt)) {
        // 设备托管:路径都在任务所在电脑上,以那台电脑的真实工作目录为准。
        const reviewWorkingDir = hosted?.workingDir ?? opts.workingDir;
        const workspaceRoots = [reviewWorkingDir, ...mutableExtraDirs, ...mutableWritableDirs].filter(
          (d): d is string => typeof d === 'string' && d.length > 0,
        );
        const writableRoots = [reviewWorkingDir, ...mutableWritableDirs].filter(
          (d): d is string => typeof d === 'string' && d.length > 0,
        );
        const action = builtinReviewAction!;
        if (action.kind === 'exec' && (opts.remoteHostId || hosted)) {
          action.destructivePathResolution = 'unavailable';
        }
        if (action.kind === 'file-write') {
          const resolutionDirectoryGeneration = autoReviewDirectoryGeneration;
          // SSH paths belong to the remote filesystem. Until the remote manager can
          // attest a real path, never use a same-named controller path as evidence.
          // 设备托管同理:路径在任务所在电脑上,本机文件系统不能作证。
          const [resolvedPath, resolvedWritableRoots] = (opts.remoteHostId || hosted)
            ? [null, null] as const
            : await Promise.all([
                resolveClaudeFileWriteTarget(opts.workingDir, action.path),
                resolveClaudeWritableRoots(writableRoots),
              ]);
          reviewedWritePath = resolvedPath;
          // The old roots are no longer authoritative. Retry against the new scope.
          if (resolutionDirectoryGeneration !== autoReviewDirectoryGeneration) {
            return { behavior: 'deny', message: 'Directory permissions changed; retry with the current scope.' };
          }
          action.resolvedPath = reviewedWritePath;
          action.resolvedWritableRoots = resolvedWritableRoots;
          executionInput = bindClaudeFileWriteTarget(toolName, input, reviewedWritePath);
        }
        const autoDecision = await reviewAutoAction(
          turnPolicyForcePrompt ? toolAutoReviewAction(toolName, input, undefined, action) : action,
          workspaceRoots,
          writableRoots,
          hosted ? hosted.platform : opts.remoteHostId ? 'linux' : process.platform,
          mcpApprovalPolicy === 'auto-approve' && !turnPolicyForcePrompt,
          reviewPermissionMode !== 'auto',
        );
        // 热切换收口:reviewAutoAction 是 async,期间 setPermissionMode 可能收紧(Auto→Ask)
        // 或放宽(→Full)。必须按**最新**档位决策,否则进入审查前的旧 auto 档 allow 会绕过用户
        // 刚通过 setPermissionMode 要求的确认(codex review P1;与已修复的 Pi 线程同口径)。
        // cast 破 TS 收窄:TS 不建模 await 期间经 setPermissionMode 闭包的重赋值,会把此处
        // mutablePermissionMode 仍视为 'auto';运行期它确实可能已变,故按 union 类型现读。
        const modeAfterReview = mutablePermissionMode as PermissionMode;
        if (isPlanToolBlocked(toolName)) {
          return { behavior: 'deny', message: 'The current Plan turn is read-only.' };
        }
        if (modeAfterReview === 'bypassPermissions') {
          return { behavior: 'allow', updatedInput: executionInput };
        }
        if (modeAfterReview !== reviewPermissionMode) {
          // 已收紧到 Ask/更严:不吃 auto 裁决,强制走用户确认(下方 forcePrompt 流程)。
          forcePrompt = true;
        } else if (!forcePrompt && autoDecision.verdict === 'allow') {
          return { behavior: 'allow', updatedInput: executionInput };
        } else if (!forcePrompt && reviewPermissionMode === 'auto' && autoDecision.verdict === 'block') {
          // 模型判定动作有更安全的做法 —— 按 Auto 本意保持静默,只把 reason 喂给模型。
          // (审阅器故障已在 resolveAutoReviewDecision 降级成 ask,不会走到这条分支。)
          return {
            behavior: 'deny',
            message: formatPermissionDenial('auto', autoDecision.reason),
          };
        } else {
          // AI `ask` and deterministic red-line verdicts are never persisted.
          // 审阅器故障降级来的 ask 额外发一条会话级提示:用户需要知道自己为什么
          // 突然开始被问,否则 Auto 档看起来像坏了。
          if (autoDecision.unavailable) {
            autoReviewUnavailableNotice.notify();
            unavailableHandoff = true;
          } else {
            autoReviewAskReason = autoDecision.reason;
          }
          forcePrompt = true;
        }
      } else {
        forcePrompt = forcePrompt || mcpApprovalPolicy === 'prompt-each-time';
      }
      const permissionRequest = {
        kind: 'permission' as const,
        requestId: options.toolUseID,
        toolUseId: options.toolUseID,
        toolName,
        input: executionInput as Record<string, unknown>,
        title: options.title,
        displayName: options.displayName,
        description: options.description,
        // prompt-each-time 的语义是"每次都要人过目", 因此不把会话级 suggestion 交给
        // UI —— 否则用户点一次"总是允许"就把逐次确认的高风险 action 永久放行了。
        suggestions: forcePrompt
          ? undefined
          : this.normalizeSessionPermissionSuggestions(options.suggestions),
        metadata: {
          ...(options.blockedPath ? { blockedPath: options.blockedPath } : {}),
          ...(options.decisionReason ? { decisionReason: options.decisionReason } : {}),
          ...(options.agentID ? { agentID: options.agentID } : {}),
        },
      };
      const decision = await dispatchInteraction(
        annotatePermissionRequestForAutoReview(permissionRequest, {
          unavailable: unavailableHandoff,
          reason: autoReviewAskReason,
        }),
        { directorySensitive: directorySensitivePermission },
      );
      notifyIfAutoReviewConfirmUndelivered(unavailableHandoff, decision);
      if (isPlanToolBlocked(toolName)) {
        return { behavior: 'deny', message: 'The current Plan turn is read-only.' };
      }
      if (decision.kind !== 'permission') {
        log.warn('permission got mismatched decision', { tool: toolName, decKind: decision.kind });
        return { behavior: 'deny', message: 'resolver kind mismatch' };
      }
      if (decision.behavior === 'allow') {
        const out: {
          behavior: 'allow';
          updatedInput: Record<string, unknown>;
          updatedPermissions?: PermissionUpdate[];
        } = {
          behavior: 'allow',
          updatedInput: bindClaudeFileWriteTarget(
            toolName,
            (decision.updatedInput ?? executionInput) as Record<string, unknown>,
            reviewedWritePath,
          ),
        };
        // Pass-through vendor-specific permission rule updates. BaseAgent owns
        // the session-scope normalization; Claude SDK validates the final shape.
        // PermissionUpdate shapes; we don't validate — SDK throws on bad shape.
        //
        // forcePrompt 下必须在**消费决策**这一侧丢弃, 不能只靠不下发 suggestion:
        // hook-control/interactions.ts 与 IM 卡片流会自己拼 permissionUpdates(不看
        // request.suggestions), 原样转给 SDK 就等于给逐次确认的高风险 action 落了
        // 一条会话规则, 之后的 canUseTool 全被跳过。本次调用仍按用户意愿放行。
        if (forcePrompt) {
          if (decision.permissionUpdates && decision.permissionUpdates.length > 0) {
            log.warn('dropping session permission grant for prompt-each-time MCP tool', {
              tool: toolName,
            });
          }
        } else if (decision.permissionUpdates && decision.permissionUpdates.length > 0) {
          out.updatedPermissions = decision.permissionUpdates as PermissionUpdate[];
        }
        return out;
      }
      return { behavior: 'deny', message: formatPermissionDenial(isSystemPermissionDenialReason(decision.reason) ? 'system' : 'user', decision.reason) };
    };

    // 设备托管:cindy_exec 工具按对应的自带工具名走同一套权限判断(确认卡、会话规则、自动审查、
    // IM 等每轮策略看到的都是 Bash / Read 等原名);本机任务里 Claude Code 自己就免确认的操作
    // (工作区内读取、静态可证只读的命令、自动接受编辑档下的工作区写入)这里同样免确认。
    // 工具参数是 Agent 主机上的虚拟路径;执行命令的语法仍按 hosted.platform 判断。
    const hostedPath = hosted?.pathPlatform === 'win32' ? path.win32 : path.posix;
    const hostedInside = (target: unknown, roots: readonly string[]): boolean => {
      if (!hosted || typeof target !== 'string' || !target) return false;
      const resolved = hostedPath.resolve(hosted.workingDir, target);
      if (isSensitiveCredentialPath(resolved)) return false;
      return roots.some((root) => {
        const relative = hostedPath.relative(root, resolved);
        return relative === '' || (!relative.startsWith('..') && !hostedPath.isAbsolute(relative));
      });
    };
    const hostedAutoAllowed = (builtin: string, input: Record<string, unknown>): boolean => {
      if (!hosted) return false;
      const readRoots = [hosted.workingDir, ...mutableExtraDirs, ...mutableWritableDirs];
      switch (builtin) {
        case 'Read':
          return hostedInside(input.file_path, readRoots);
        case 'BashOutput':
        case 'KillShell':
          return true;
        case 'Bash':
          return typeof input.command === 'string'
            && classifyShellCommand(input.command, readRoots, { cwd: hosted.workingDir, platform: hosted.platform }) === 'auto-approve';
        case 'Write':
        case 'Edit':
          return mutablePermissionMode === 'acceptEdits'
            && hostedInside(input.file_path, [hosted.workingDir, ...mutableWritableDirs]);
        case 'NotebookEdit':
          return mutablePermissionMode === 'acceptEdits'
            && hostedInside(input.notebook_path, [hosted.workingDir, ...mutableWritableDirs]);
        default:
          return false;
      }
    };
    const remapHostedRules = (value: unknown, from: string, to: string): unknown => {
      if (!Array.isArray(value)) return value;
      return value.map((update) => {
        if (!update || typeof update !== 'object') return update;
        const rules = (update as { rules?: unknown }).rules;
        if (!Array.isArray(rules)) return update;
        return {
          ...(update as Record<string, unknown>),
          rules: rules.map((rule) => (rule && typeof rule === 'object' && (rule as { toolName?: unknown }).toolName === from
            ? { ...(rule as Record<string, unknown>), toolName: to }
            : rule)),
        };
      });
    };
    const sdkCanUseTool: CanUseTool = !hosted ? canUseTool : async (toolName, input, options) => {
      const builtin = deviceHostedBuiltinToolName(toolName);
      if (!builtin) return canUseTool(toolName, input, options);
      const record = (input ?? {}) as Record<string, unknown>;
      if (
        mutablePermissionMode !== 'bypassPermissions'
        && !isPlanToolBlocked(builtin)
        && !forceTurnConfirmation(builtin, record)
        && hostedAutoAllowed(builtin, record)
      ) {
        return { behavior: 'allow', updatedInput: record };
      }
      const result = await canUseTool(builtin, input, {
        ...options,
        suggestions: remapHostedRules(options.suggestions, toolName, builtin) as typeof options.suggestions,
      });
      if (result?.behavior === 'allow' && result.updatedPermissions) {
        result.updatedPermissions = remapHostedRules(result.updatedPermissions, builtin, toolName) as typeof result.updatedPermissions;
      }
      return result;
    };

    // ── thinking display 配置(与 vendor/claude/runtime.ts:121-126 等价) ─────
    const thinkingOpts = opts.displayReasoning === 'summarized'
      ? { thinking: { type: 'adaptive', display: 'summarized' } as unknown as { type: 'adaptive' } }
      : {};
    const showThinkingSummaries = opts.displayReasoning === 'summarized';

    // Claude Code 把 availableModels 当成组织白名单。目录 + 当前/目标模型都走同一
    // 个 catalog-id → wire-string 映射,启动与热切共用,后加载的网关模型(如
    // x-ai/grok-4.6)也能进名单。
    // 受邀者会话只列分享的供应商为 Claude Code 提供的模型(子代理可选的模型也受这份名单约束)。
    const currentAvailableSdkModels = (selectedModel: string): string[] => [
      ...new Set([
        ...(guestProvider
          ? guestProvider.modelIds.map((id) => sdkModelFor(id))
          : this.capabilities.availableModels.map(({ id }) => sdkModelFor(id))),
        sdkModelFor(selectedModel),
      ]),
    ];
    const resolveModelContextWindow = (model: string, providerId = mutableProviderId): number | undefined => {
      // 任务级预算优先:本任务的工作窗口由用户显式选定,host 已收敛到目录上限内。
      if (mutableContextWindowBudget !== null && Number.isFinite(mutableContextWindowBudget) && mutableContextWindowBudget > 0) {
        return mutableContextWindowBudget;
      }
      const configured = this.deps.resolveModelContextLimit?.(providerId, model);
      if (configured && Number.isFinite(configured) && configured > 0) return configured;

      // 核实窗口按会话实际来源取。host 注入了 resolver 时,null = 不要收敛
      // (同 id 多来源 / 未核实兜底),采信 SDK 上报,不能再拿扁平目录首见值覆盖。
      // 只有未注入 resolver 的路径(测试 / 无 host)才退回扁平目录。
      const resolveVerified = this.deps.resolveVerifiedContextWindow;
      if (resolveVerified) {
        const verified = resolveVerified(providerId, model);
        return typeof verified === 'number' && verified > 0 ? verified : undefined;
      }
      const descriptor = this.capabilities.availableModels.find((item) => item.id === model);
      return descriptor && Number.isFinite(descriptor.contextWindow) && descriptor.contextWindow > 0
        ? descriptor.contextWindow
        : undefined;
    };

    // SDK settings 对象 (优先级最高, 覆盖 user/project/local 文件层) — 本地分支
    // 和远端分支必须**保持一致** , 否则同 session setting 跨本地 / 远端表现不同
    // (eg. summarized reasoning UI 本地有 remote 没)。getter 让 memOverride /
    // mutableFastMode 读最新值 (setMemory / setFastMode 运行时改) 而不是 buildQuery
    // 时快照。装配逻辑(含 apiKeyHelper 恒置空的鉴权防线)在 flag-settings.ts。
    const managedSkillGrants = snapshotManagedSkillGrants(opts.botRuntimeProfile?.skillPolicy);
    // 受邀者(另一个账号)的托管会话不读本机用户的技能偏好。
    const launchDisabledSkillPaths = opts.remoteHostId || reviewMode || hosted?.guest
      ? [] : [...(this.deps.getDisabledSkillPaths?.() ?? [])];
    const managedDisabledSkillLaunch = snapshotDisabledSkillLaunch(launchDisabledSkillPaths);
    const disabledSkillPaths = opts.botRuntimeProfile ? [] : launchDisabledSkillPaths;
    const disabledSkillLaunch = snapshotDisabledSkillLaunch(disabledSkillPaths);
    const disabledSkillSnapshot = disabledSkillLaunch.identities;
    const disabledSkillOverrides = disabledSkillPaths.length > 0
      ? claudeDisabledSkillOverrides(
        (await scanClaudeRuntimeSkills(opts.workingDir, env.CLAUDE_CONFIG_DIR)).items,
        currentDisabledSkillLaunchPaths(disabledSkillLaunch),
      )
      : {};
    const buildSettings = (): Settings => {
      const settings = buildClaudeFlagSettings({
        showThinkingSummaries,
        availableModels: currentAvailableSdkModels(mutableModel),
        // Bots keep memory in their own Cindy scope, including remote sessions.
        // For ordinary sessions, do not carry native-memory suppression across the
        // SSH boundary: the remote host retains its own Claude memory
        // configuration. Maker Memory on remote sessions is injected via the
        // host bridge (prompt + http MCP), which coexists with — but does not
        // rewrite — the remote machine's native memory settings.
        memoryOverride: reviewMode || opts.botRuntimeProfile ? false : opts.remoteHostId ? undefined : this.memoryOverride,
        // Fast 模式:进 flag settings 层(= --settings),解锁 cc 二进制在 Agent SDK 通道下的
        // fast(否则二进制按 "Agent SDK 不可用" 拒绝)。是否 Opus/官方/firstParty 由二进制把关,
        // agent 层不重复硬判(规则 9:确定性逻辑就近,但 fast 的最终门槛是二进制 + 配置门控)。
        fastMode: opts.fastModePolicy?.isAllowed() === false ? false : mutableFastMode,
        fastModeAllowed: opts.fastModePolicy?.isRequestAllowed?.() ?? opts.fastModePolicy?.isAllowed(),
        botSkillPolicy: reviewMode ? undefined : opts.botRuntimeProfile?.skillPolicy,
        capabilityRouting: reviewMode ? undefined : this.deps.capabilityRouting,
      });
      if (Object.keys(disabledSkillOverrides).length > 0) {
        settings.skillOverrides = { ...settings.skillOverrides, ...disabledSkillOverrides };
      }
      if (hosted?.guest) {
        // 受邀者(另一个账号)的托管会话:不执行任何设置与插件里的 hooks / 状态栏命令,
        // 不加载会话目录之外(属于本机用户)的 CLAUDE.md 与规则。
        settings.disableAllHooks = true;
        // 本机用户 claude.ai 账号里的连接器、Remote Control,以及技能与命令里的内联 shell
        // (会在本机执行)一律关闭。
        settings.disableClaudeAiConnectors = true;
        settings.disableRemoteControl = true;
        settings.disableSkillShellExecution = true;
        const excludes = deviceHostedGuestClaudeMdExcludes(hosted);
        if (excludes.length > 0) settings.claudeMdExcludes = [...(settings.claudeMdExcludes ?? []), ...excludes];
        // 路由令牌请求头在最高优先级的设置层再写一次:会话中途出现的项目设置不能把它改掉。
        if (guestRouteHeader && env.ANTHROPIC_CUSTOM_HEADERS) {
          settings.env = { ...settings.env, ANTHROPIC_CUSTOM_HEADERS: env.ANTHROPIC_CUSTOM_HEADERS };
        }
      }
      if (!reviewMode) return settings;
      return {
        ...settings,
        permissions: {
          ...(settings.permissions ?? {}),
          // Claude's built-in Grep/Glob implementation translates Read deny
          // rules into trailing negative rg globs. Keep this execution-layer
          // filter in addition to the PreToolUse path/scope gate: a granted
          // directory with no explicit glob must not expose credential files.
          deny: REVIEW_SENSITIVE_CREDENTIAL_GLOB_PATTERNS.map(
            (pattern) => `Read(${pattern})`,
          ),
        },
      };
    };

    // file checkpointing 与 capability 强绑定 —— 声明 rewind 能力时必须开此开关,
    // 否则 SDK rewindFiles() 报 "no checkpoint"。
    const enableFileCheckpointing = this.capabilities.rewind.supported;
    const getSdkEffortForModel = (model: string, effort: Effort, providerId: string | null) =>
      this.sdkEffortForModel(model, effort, providerId);
    const getSdkMaxEffortFallbackForModel = (model: string, providerId: string | null) =>
      this.sdkMaxEffortFallbackForModel(model, providerId);

    // memoryOverride 闭包以前抽过 getter, buildSettings 接管后直接读 this.memoryOverride。

    // ── 运行时切换状态 (Stage 2 B) ──────────────────────────────────────────
    // model / effort / permissionMode 在 setX 后会变, handle 通过 getter 读 mutable 引用;
    // translator ctx 也通过 getter 读, 让 turn start/end 日志反映"当前真实值"而不是创建时的值。
    // 必须在 buildQuery / forward loop 之前声明, 否则 ctx getter 会捕获到 TDZ。
    let mutableAutoReviewCredentialMode = effectiveCredentialMode;
    let nativeAutoReviewUnavailable = false;
    let currentAutoReviewIntent: AutoReviewUserIntent = '';
    let autoReviewIntentInitialized = false;
    const autoReviewActionContext = createAutoReviewActionContext();
    const autoReviewContext = () => activeTurnPermissionPolicy?.autoReviewContext
      ?? (activeTurnPermissionPolicy?.origin.kind === 'im'
        ? { requesterAuthority: 'unknown' as const, source: 'direct' as const }
        : undefined);
    // Authorization belongs to the accepted input, not the foreground policy's lifetime.
    let currentAutoReviewAuthority: ReturnType<typeof autoReviewContext>;
    const priorAutoReviewIntent = () => !autoReviewIntentInitialized ? undefined : JSON.stringify(currentAutoReviewAuthority ?? null) === JSON.stringify(autoReviewContext() ?? null) ? currentAutoReviewIntent : '';
    const autoReviewDecisionCache = new Map<string, Promise<AutoReviewDecision>>();
    // Claude's native OAuth Auto classifier bypasses canUseTool. Local sessions keep it with
    // host MCPs attached: nativeAutoPolicyHook (PreToolUse) still runs for every call and
    // hands Cindy-owned decisions (trusted servers, prompt-each-time, IM turn policies) back
    // to canUseTool, so each call is reviewed once. Remote and device-hosted sessions cannot
    // run that local hook and stay on SDK default whenever an MCP is registered.
    const hasRegisteredMcpServers = (): boolean => registeredMcpServerNames.size > 0;
    const usesNativeClaudeAutoReview = (): boolean =>
      !nativeAutoReviewUnavailable
      && mutableAutoReviewCredentialMode === 'oauth-bearer'
      && !hosted
      && (!opts.remoteHostId || !hasRegisteredMcpServers())
      // Claude native Auto sees additionalDirectories as one undifferentiated scope and
      // bypasses canUseTool. Use the scope frozen into the active Query: after revoke,
      // that Query still carries its broader directory allowlist.
      && !activeQueryHasDirectoryGrants;
    const setAutoReviewIntent = (content: AutoReviewUserIntent, source = { authority: currentAutoReviewAuthority }): void => {
      autoReviewActionContext.advance(typeof content !== 'string' && JSON.stringify(currentAutoReviewAuthority ?? null) === JSON.stringify(source.authority ?? null));
      currentAutoReviewIntent = normalizeAutoReviewUserIntent(content);
      autoReviewIntentInitialized = true;
      currentAutoReviewAuthority = source.authority && { ...source.authority };
      autoReviewDecisionCache.clear();
    // 每条新用户消息 = 新一轮,提示重新武装。ErrorBanner 那份只活到下一条非 error 事件
    // (renderer 的 handleStreamEvent 会清 recoverableError),所以「整个会话只说一次」
    // 会让用户在后续轮次里完全看不到;改为每轮至多一条 —— 不刷屏,又保证每一轮遇到时
    // 都有机会看见。持久呈现需要一条真正的会话级 notice 通道,见 issue 外推。
      autoReviewUnavailableNotice.reset();
      autoReviewConfirmUndeliveredNotice.reset();
    };
    // 「自动审核不可用」的会话级一次性提示(issue #1574)。走既有的非终止 error 事件 +
    // `[CODE]` 约定,不新增事件类型;逐条提示会把 Auto 退化成比 Ask 更烦的东西,所以去重。
    const emitAutoReviewRuntimeNotice = (message: string): void => {
      eventQueue.push({
        type: 'error',
        data: { message, isTerminal: false },
        source: 'claude-code',
      });
    };
    const autoReviewUnavailableNotice = createAutoReviewUnavailableNotice(emitAutoReviewRuntimeNotice);
    const autoReviewConfirmUndeliveredNotice =
      createAutoReviewConfirmUndeliveredNotice(emitAutoReviewRuntimeNotice);
    const notifyIfAutoReviewConfirmUndelivered = (
      unavailableHandoff: boolean,
      decision: InteractionDecision,
    ): void => {
      if (!unavailableHandoff) return;
      if (decision.kind !== 'permission') {
        autoReviewConfirmUndeliveredNotice.notify();
        return;
      }
      if (decision.behavior === 'deny' && isSystemPermissionDenialReason(decision.reason)) {
        autoReviewConfirmUndeliveredNotice.notify();
      }
    };
    const reviewAutoAction = (
      action: ReviewableAction,
      workspaceRoots: string[],
      writableRoots: string[],
      platform: NodeJS.Platform,
      hostAutoApprove = false,
      hostShortcutOnly = false,
    ): Promise<AutoReviewDecision> => {
      const directoryGeneration = autoReviewDirectoryGeneration;
      const request = {
        sessionId: opts.sessionId,
        agentKind: 'claude-code' as const,
        providerId: mutableProviderId,
        model: mutableModel,
        userIntent: currentAutoReviewIntent,
        precedingBlockedActions: autoReviewActionContext.precedingBlockedActions,
        ...(currentAutoReviewAuthority ? { authorizationContext: currentAutoReviewAuthority } : {}),
        action,
        workspaceRoots,
        writableRoots,
        platform,
      };
      let key: string | undefined;
      let pending: Promise<AutoReviewDecision> | undefined;
      return withAutoReviewContext(request, this.deps.reviewAutoPermissionAction, (prepared) => {
        if (request.userIntent !== currentAutoReviewIntent || request.authorizationContext !== (currentAutoReviewAuthority ?? undefined)) {
          return Promise.resolve({ verdict: 'block', reason: 'User instructions changed; retry against the current request.' });
        }
        key = JSON.stringify([prepared, hostAutoApprove, hostShortcutOnly]);
        const cached = autoReviewDecisionCache.get(key);
        pending = cached ?? resolveAutoReviewDecision(
            prepared,
            this.deps.reviewAutoPermissionAction,
            hostAutoApprove,
            hostShortcutOnly,
          );
        if (!cached) autoReviewDecisionCache.set(key, pending);
        return pending;
      }, (decision) => {
        if (!pending || !key) return decision;
        if (request.userIntent !== currentAutoReviewIntent || request.authorizationContext !== (currentAutoReviewAuthority ?? undefined)
            || autoReviewDecisionCache.get(key) !== pending) {
          return { verdict: 'block', reason: 'User instructions changed; retry against the latest authorization.' };
        }
        if (directoryGeneration !== autoReviewDirectoryGeneration) {
          return { verdict: 'block', reason: 'Directory permissions changed; retry with the current scope.' };
        }
        autoReviewActionContext.record(action, decision);
        return decision;
      });
    };
    // All models share the same detector, with independent per-sidechain history.
    const toolLoopMonitors = new Map<string | null, ToolLoopMonitor>();
    // 各 sidechain 的检测轨迹独立,但辅助模型复核次数按整个 turn 共用一份上限。
    let toolLoopReviewBudget: ToolLoopReviewBudget = { used: 0 };
    /**
     * 错误归属用的模型:sidechain 用该 subagent 的实际模型
     * (Agent 异步回执的 resolvedModel 优先,其次 sidechain 流内消息的 model),
     * 两者都未知时回落会话模型(维持旧行为);顶层恒用会话模型。
     * runtimeState 声明在后,仅在 forward loop 回调期调用,无 TDZ 风险。
     */
    const toolLoopGuardModelForScope = (parentToolUseId?: string): string => {
      if (parentToolUseId) {
        const sidechainModel =
          runtimeState.resolvedSubagentModelByParentToolUseId.get(parentToolUseId)
          ?? runtimeState.streamModelByParentToolUseId.get(parentToolUseId);
        if (sidechainModel) return sidechainModel;
      }
      return mutableModel;
    };
    const getToolLoopMonitor = (parentToolUseId?: string): ToolLoopMonitor => {
      const scopeKey = parentToolUseId ?? null;
      const existing = toolLoopMonitors.get(scopeKey);
      if (existing) return existing;
      const monitor: ToolLoopMonitor = new ToolLoopMonitor(new ToolLoopGuard({
        // Different inputs can be legitimate corrections, even when the
        // tool keeps reporting the same error category. Match Pi/Codex:
        // keep exact repetition/rotation guards, not category-only retries.
        contractConsecutiveLimit: Number.POSITIVE_INFINITY,
      }), {
        // 供应商分享受邀者同样复核:与本机自己的任务一样走本机(分享者)的辅助模型链
        // (2026-10-13 用户裁决)。
        reviewer: this.deps.toolLoopReviewer,
        reviewBudget: toolLoopReviewBudget,
        context: () => ({
          sessionId: sid,
          agentKind: 'claude-code',
          model: toolLoopGuardModelForScope(parentToolUseId),
          userIntent: currentAutoReviewIntent,
        }),
        // 复核结果晚到时,guard 可能已随新 turn 重置;只处理仍在位的同一 monitor。
        onReviewedStop: (verdict) => {
          // 与 Pi/Codex 的 toolLoopControlFor 同一前提:等用户确认期间不中断。
          if (closed || toolLoopMonitors.get(scopeKey) !== monitor || !turnInFlight ||
            turnState.interruptRequested || pendingInteractions.size > 0) return;
          // 子代理已结束(其父 Agent/Task 调用已有结果):迟到结论不能中断父 turn。
          if (parentToolUseId && !pendingToolIds.has(parentToolUseId)) return;
          interruptForToolLoop(verdict, parentToolUseId);
        },
        logger: log,
      });
      toolLoopMonitors.set(scopeKey, monitor);
      return monitor;
    };
    /** 清空各 scope 的检测轨迹;复核次数仍计在当前 turn。 */
    const clearToolLoopObservations = (): void => {
      for (const monitor of toolLoopMonitors.values()) monitor.dispose();
      toolLoopMonitors.clear();
    };
    /** turn 边界:清空检测轨迹,并重置本 turn 的复核次数。 */
    const resetToolLoopGuards = (): void => {
      clearToolLoopObservations();
      toolLoopReviewBudget = { used: 0 };
    };
    let mutableEffort: Effort = opts.effort ?? 'high';
    let mutablePermissionMode: PermissionMode =
      reviewMode ? 'ask' : opts.permissionMode ?? 'default';
    // 计划模式(与 permissionMode 正交, **一次性选择**): mutablePlanMode 是 UI 勾选的
    // "武装"态 —— send 消耗它并立即 emit plan_mode_changed(false) 让勾选熄灭;
    // 本轮 plan turn 由 planTurnActive 承载(SDK 保持 plan 档): ExitPlanMode 批准
    // 提前切回底层档, 否则(取消 / 模型没提交计划)在 turn 结束时收尾。
    let mutablePlanMode = !reviewMode && opts.planMode === true;
    let planTurnActive = false;
    // SDK 当前是否处于 plan 档(跟踪我们最后一次 push / buildQuery 的档位)。
    // setPlanMode 在 turn 流式中递延 push(避免改写 in-flight turn 的工具权限),
    // send 消耗武装态时据此判断是否需要补推。
    let sdkInPlanMode = false;
    // SDK PermissionMode union 没有 'ask' (我们对 ChatInput 暴露的统一名字), SDK 侧当 default。
    type SdkPermissionMode = 'default' | 'acceptEdits' | 'plan' | 'auto' | 'bypassPermissions';
    // 官方 Claude OAuth 路由保留 CC 原生 Auto classifier。第三方/网关路由及原生
    // classifier 故障后的会话映射到 default,使 canUseTool 回调进入 Cindy 轻量 fallback。
    const toSdkPermissionMode = (mode: PermissionMode): SdkPermissionMode => {
      if (mode === 'auto') return usesNativeClaudeAutoReview() ? 'auto' : 'default';
      return (mode === 'ask' ? 'default' : mode) as SdkPermissionMode;
    };
    /**
     * SDK 实际起 turn 时应用的权限档: 计划模式武装中(下一 turn arm)或本轮 plan turn
     * 进行中都恒为 plan, 否则跟随底层权限档。**含 arm 态**, 用于 buildQuery 起 turn。
     */
    const effectiveSdkPermissionMode = (): SdkPermissionMode =>
      mutablePlanMode || planTurnActive ? 'plan' : toSdkPermissionMode(mutablePermissionMode);
    // Only queries that actually started in native Auto need the post-init
    // downgrade. A host MCP can already have made a query start in `default`;
    // retrying that no-op and treating a transport failure as fatal would close
    // an otherwise safe session.
    const nativeAutoQueries = new WeakSet<Query>();

    /**
     * **本次 turn** 目标 SDK 权限档: 只看 `planTurnActive`(本轮是否 plan turn), **不含**
     * `mutablePlanMode` arm 态 — arm 态表示"下一次 send 应该以 plan turn 起", 与本轮无关。
     * rebuild 竞态重放要用这个而非 effectiveSdkPermissionMode(), 否则 `await buildQuery` 期间
     * 到达的 setPlanMode(true) 会漂移本 turn 的 SDK 档到 'plan', 让不是 plan turn 的普通 send
     * 意外跑成 plan turn (Codex review 3535660068)。
     */
    const currentTurnSdkPermissionMode = (): SdkPermissionMode =>
      planTurnActive ? 'plan' : toSdkPermissionMode(mutablePermissionMode);
    // Only the current SDK/turn state applies here; arming the next message must
    // not turn an ordinary in-flight turn into a Plan turn. Keep other modes on
    // their existing SDK/MCP approval path; Full Access is not a Plan override.
    const isPlanToolBlocked = (toolName: string): boolean =>
      mutablePermissionMode === 'bypassPermissions'
      && (planTurnActive || sdkInPlanMode) && !isReadOnlyClaudeTool(toolName);
    // Fast 模式运行时态:启动取 opts.fastMode 快照,setFastMode 覆盖。buildSettings 每次读最新值;
    // host 只在「该 model 支持 + 走官方供应商」时才传 true(renderer 配置门控),agent 忠实消费。
    let mutableFastMode = opts.fastMode === true && opts.fastModePolicy?.isAllowed() !== false;
    // 附加只读引用目录: 启动时取 opts.extraDirs 快照, setExtraDirs 覆盖。
    // SDK additionalDirectories 在 Query 创建时冻结;代际不一致时下一次 send
    // 走 rewind 同款 resume+fork 重建,下一 turn 生效,不用 fresh:true。
    let mutableLibraryRoot: string | null | undefined = opts.remoteHostId || reviewMode ? undefined : (opts[LIBRARY_READ_ROOT] ?? undefined);
    let mutableExtraDirs: string[] = Array.isArray(opts.extraDirs) ? [...opts.extraDirs] : [];
    let mutableWritableDirs: string[] = Array.isArray(opts.writableDirs) ? [...opts.writableDirs] : [];
    let autoReviewDirectoryGeneration = 0;
    let activeQueryDirectoryGeneration = autoReviewDirectoryGeneration;
    let activeQueryReadonlyDirs = [...mutableExtraDirs];
    let extraDirsRebuildAttempted = false;
    // 本机热切跨过 Explore inherit-cap 策略后,子进程 env 必须随 Query 重建。
    // 代际与 extraDirs 同款:setModel 只加代,buildQuery 才把当前 Query 标成已吃进
    // 该代。await buildQuery 期间再切一次不会被这次 spawn 误标成已同步。
    let exploreInheritCapEnvGeneration = 0;
    let activeQueryExploreInheritCapGeneration = exploreInheritCapEnvGeneration;
    // 拷贝进工作目录只允许作 Claude resume 不吃新 additionalDirectories 时的临时缺口。
    // 默认关闭;启用条件:extraDirsRebuildAttempted 且下一 Query 代际仍落后。落地后
    // library extraDirs 重建成功即删副本,不得把拷贝写成架构。
    const extraDirsCopyFallbackEnabled = false;
    let activeQueryHasDirectoryGrants = mutableExtraDirs.length > 0 || mutableWritableDirs.length > 0;

    // ── Usage tracker (Stage 2 B') ──────────────────────────────────────────
    // 单 session 共享的 mutable usage state. translator 通过 ctx 注入访问.
    // handle.getUsageSnapshot 也读它, 形成"SDK 原始 usage → tracker → status event / handle snapshot"
    // 单一可信源。预算跟随已应用的进程配置;设置变更等待重建后才反映到用量。
    let appliedContextWindow = resolveModelContextWindow(mutableModel);
    const usageTracker = new UsageTracker();
    usageTracker.setContextWindow(appliedContextWindow ?? 0);

    // ── 跨 turn 共享状态 ───────────────────────────────────────────────────
    let configuredResumeSessionId: string | undefined = opts.resumeSessionId;
    let sdkSessionId: string | undefined = configuredResumeSessionId;
    let durableSdkSessionId: string | undefined = configuredResumeSessionId;
    let publishedSdkSessionId: string | undefined = configuredResumeSessionId;
    let localQueryStarted = false;
    const unacceptedForks = new WeakSet<Query>();
    // 只在首次 resume 尚未被真实内容证明成功前允许自愈;成功一轮后即关闭分类窗口,
    // 避免后续普通 turn 中碰巧出现同文案时误清上下文。
    let resumeValidationPending = !!configuredResumeSessionId;
    let freshSessionValidationPending = !configuredResumeSessionId;
    let resumeRecoveryAttempted = false;
    // 当前 turn 已经交给 SDK 的精确输入。invalid-resume fresh rebuild 只重放这一份,
    // 不重新经过 Session.send/onAccepted,因此不会重复持久化用户消息或渠道 ack。
    let replayableUserInput: SdkUserInput | null = null;
    // 仅用于诊断日志: 调用方 (register.ts) 在每次 send 前从 storage 取最新 title 透传进来,
    // translator 打 SDK ▷ token usage 等行时会一起带上, 不参与任何业务逻辑。
    let lastSendTitle: string | undefined;
    let closed = false;
    // 远端 cc 分支专用 — 记下当前 buildQuery 返的 RemoteQuery, 让 handle.close /
    // U2 兜底能调它的 close() 走 query/close RPC → 远端 cc-mgr SessionRegistry
    // 释放 SDK Query → close ssh exec / nc / RpcClient。漏调这一步会让远端
    // session 继续跑(空耗 token), reattach 时还能撞到 alive 状态。本地 SDK
    // 分支不需要 — sdkQuery 是子进程, abortController.abort() 已经够。
    let activeRemoteQuery: { close: () => Promise<void>; detach?: () => Promise<void> } | null = null;
    // 跨消息累积:一个 turn 内 SDK 会发多个 assistant message,这里把 text 拼起来,
    // 在 result 缺少正文时作为 finalText 兜底。
    const turnState: TurnState = {
      text: '',
      toolUses: 0,
      apiCalls: 0,
      sawCompactBoundary: false,
      hasEmittedText: false,
      uiEmittedText: '',
      pendingApiError: null,
      interruptRequested: false,
      generation: 0,
      interruptGeneration: 0,
      lastAssistantMsgHadSubstance: true,
      nextRequestPriceVariant: 'standard',
    };
    const runtimeState: RuntimeState = newRuntimeState();
    const beginNewTurn = (priceVariant: 'standard' | 'priority' = mutableFastMode ? 'priority' : 'standard'): void => {
      // usageTracker.beginTurn() 只清 usage 桶;translator 的 turnState 也要在新 turn
      // 开始时清掉,避免上一轮 abnormal/abort 没走 result 时污染下一轮状态。
      usageTracker.beginTurn();
      resetClaudeGenerationTiming(runtimeState.generation);
      runtimeState.activeUsageSegmentByParent.clear();
      runtimeState.mainOpenRequest = null;
      runtimeState.activeUsagePriceVariantByParent.clear();
      runtimeState.pendingUsagePriceVariantByParent.clear();
      turnState.nextRequestPriceVariant = priceVariant;
      turnState.text = '';
      turnState.toolUses = 0;
      turnState.apiCalls = 0;
      turnState.sawCompactBoundary = false;
      turnState.hasEmittedText = false;
      turnState.uiEmittedText = '';
      runtimeState.streamStopTokenByKey.clear();
      turnState.pendingApiError = null;
      turnState.lastAssistantRequestId = undefined;
      turnState.lastAssistantMsgHadSubstance = true;
      // 代际前进: 迟到的被打断 result 据此被 translator 识别为已被本 send 接管。
      turnState.generation += 1;
      // interruptRequested **刻意不在这里清**: watchdog / tool-loop guard 先置
      // turnInFlight=false 再 q.interrupt(), 用户立刻 send 会让 beginNewTurn 抢在
      // 被打断的 ResultMessage(error_during_execution) drain 之前执行 —— 在此清掉
      // 唯一的抑制位, 旧 result 会被 translator 当成新 turn 的终态失败双发 banner
      // (PR #485 review)。标记的生命周期: interrupt 置位 → translator 的
      // resetTurnState 随 result 消费清除;q 换代(startForwardLoop)时兜底清
      // (旧 q 的 result 不可能到达新 q)。
    };

    // ── Rewind 状态机 ──────────────────────────────────────────────────────
    // commitRewindFiles 设此标记, 下一次 send 检测到 → close 老 q + buildQuery 拼三件套
    // (resume + resumeSessionAt + forkSession) + startForwardLoop 接到老 eventQueue 上。
    // 对外 (Session / desktop / renderer) 完全透明, 只看到一个 send 调用。
    let pendingRewindTo: string | undefined;
    // turn-in-flight 标记: send 入口设 true, translator 的 result 事件回调清 false。
    // SSE idle watchdog 触发时也会主动清, 防止 SDK drain 期间又起 timer。
    // rewind preview/commit 业务层用 isTurnRunning() 前置守卫, 不在 turn 跑时操作 SDK。
    let turnInFlight = false;
    // send() 处于 beginNewTurn→userInputAccepted 之间时置 true。
    // abort() 在此期间跳过 turnInFlight 清除:并发 send 负责在错误路径上
    // (finishSendBeforeUserInput) 自行清 turnInFlight 并 emit boundary,
    // abort 抢清会让 boundary 丢失、acceptingRebuiltSend 残留(review #485)。
    let sendInAcceptPhase = false;
    /**
     * "桥接 turn"计数器: rebuild 尾部注入的 /compact 是 SDK 独立 turn, 但产品层视角
     * 它是"用户 turn 的一部分" — 该 /compact 的 done / end-status 不能让上层做 turn
     * finalization (idle 调度 / IM handleTurnDoneAsync / snapshot 收尾), 也不能清
     * turnInFlight 让 isTurnRunning 报 false。
     *
     * 之前用 `inputQueue.pending > 0` 反推"是否还有排队 turn", 但 pending 有两个漏窗:
     *  (a) send 里 push /compact 后 `await toClaudeSdkContent(...)` 是 async 空窗
     *      (图片 resize 几百 ms), 期间 SDK 可能已 drain /compact → pending 提前归 0
     *  (b) SDK prompt 是 AsyncIterable, 消费模式无法保证 backpressure — 有 eager
     *      drain 场景 (两条 push 后 SDK 一次性拉完), pending 归 0 但两 turn 都在跑
     * 反馈原型: Codex review 3535259132 / 3535293200 (2026-07-07)。
     *
     * 改用显式计数: 注入 /compact 时 +1 → middle turn 边界事件全程 suppress、
     * turnInFlight 保持;该 /compact turn 的 onTurnEnd 消费 -1;归 0 后下一个真 turn 结束
     * 的边界事件正常放行、清 turnInFlight。计数 = "已注入但 SDK 还没跑完的桥接 turn 数"。
     */
    let queuedBridgeTurns = 0;
    // 用户 turn 结束后由 completeTranslatedTurnEnd / setModel 注入的静默 /compact。
    // 不能复用 queuedBridgeTurns:那会 suppress 终态、并把 isTurnRunning 卡在 true。
    let hostAutoCompactInFlight = false;
    type ActiveBridgeKind = 'rewind' | 'cancellation';
    let activeBridgeKind: ActiveBridgeKind | null = null;
    // Bridge /compact 由 rewind 或 cancellation rebuild 尾部注入。若用户 Stop 打在该 bridge turn
    // 上, 已被 SDK eager-drain 的后续真实用户输入无法再从 inputQueue.clear() 追回;
    // 必须 close 当前 Query, 并在下一次 send 用同一个 resume point 重建, 才能从 SDK
    // 侧取消整条 compact → user 序列。
    let activeBridgeRewindResumeAt: string | undefined;
    let bridgeCompactUsageSnapshot: ReturnType<AutoCompactController['getLatestSnapshot']> = null;
    const bridgeStateActive = (): boolean =>
      queuedBridgeTurns > 0 || activeBridgeKind !== null || activeBridgeRewindResumeAt !== undefined;
    let q: Query;
    // Query-scoped lifecycle fact: modelUsage is cumulative within the SDK
    // process. A query created without a resume id starts that counter at zero;
    // resumed queries may include prior transcript usage and must establish a
    // baseline unless request segments prove the delta independently.
    const modelUsageStartsAtZeroQueries = new WeakSet<Query>();
    function restoreBridgeAutoCompactSnapshot(reason: string): void {
      const snapshot = bridgeCompactUsageSnapshot;
      bridgeCompactUsageSnapshot = null;
      if (!snapshot || !autoCompactController) return;
      autoCompactController.onUsageUpdate(snapshot.contextTokens, snapshot.contextWindow);
      log.debug('bridge rollback restored auto-compact usage snapshot', {
        reason,
        ratio: Number(snapshot.ratio.toFixed(3)),
        contextTokens: snapshot.contextTokens,
        contextWindow: snapshot.contextWindow,
      });
    }

    // ── upstream-response-idle watchdog (按上游 API 请求级) ─────────────────
    // 上游 API 单次响应静默超过阈值 → emit 一条结构化 error 事件 + 调 q.interrupt() 主动
    // 中断当前 turn (与用户手动 stop 同路径)。不调 abortController.abort() —— 那会把
    // 整个 SDK Query 打成黑洞 session, 后续 send 全失败 (见 handle.abort 段注释)。
    //
    // 阈值默认 30min (端到端最后兜底) —— 上游网络断流已由 cc-code 原生 watchdog
    // (env-builder 注入 CLAUDE_ENABLE_STREAM_WATCHDOG, 300s) + 非流式 fallback 透明自愈,
    // 这层只兜 cc 抓不到的非网络卡死 (子进程死锁 / stdio 传输 wedge)。阈值刻意 > cc
    // 恢复预算 (≈20min) 以免抢跑。env XDT_CC_SSE_IDLE_TIMEOUT_MS (历史命名; ms) 覆盖,
    // 设 0 关闭。详见 parseIdleTimeoutMs 上方文档。
    //
    // **timer 只在客户端"等上游回话"期间在走** —— 工具执行 / canUseTool 用户交互期间
    // 上游已交回 ball, 不算 idle 配额。pendingToolIds.size>0 时 arm 短路不起 timer,
    // Bash 长 build / MCP 拉大表 / 子 agent / AskUserQuestion 发呆都不会被误伤; 只有
    // tool_result 全部配对完 (set 归零, ball 回到上游) 之后, 上游真的挂死才触发。
    const upstreamResponseIdleTimeoutMs = parseIdleTimeoutMs(process.env.XDT_CC_SSE_IDLE_TIMEOUT_MS);
    let upstreamResponseIdleTimer: NodeJS.Timeout | null = null;
    let upstreamResponseLastEventType: string | null = null;
    let upstreamResponseLastEventAt = 0;
    /** 还需要"清醒地"静默多久才判上游哑火;按分片递减(见 armUpstreamResponseIdleSlice)。 */
    let upstreamResponseIdleRemainingMs = 0;
    /** 当前分片的起始壁钟时刻;片尾据此识别系统挂起。 */
    let upstreamResponseIdleSliceStartedAt = 0;
    const pendingToolIds: Set<string> = new Set();
    async function withRemoteApprovalIdleGuard(
      rawParams: unknown,
      approve: () => Promise<unknown>,
    ): Promise<unknown> {
      // SSH daemon canUseTool bypasses the local callback. Its requestId is the
      // SDK toolUseID: executable input is available even before full assistant.
      const toolUseId = (rawParams as { requestId?: unknown } | null)?.requestId;
      const generation = turnState.generation;
      const tracked = !closed && turnInFlight && typeof toolUseId === 'string' && toolUseId.length > 0;
      if (tracked) {
        pendingToolIds.add(toolUseId);
        clearUpstreamResponseIdle();
      }
      let awaitingToolResult = false;
      try {
        const result = await approve();
        const decision = result as { kind?: string; behavior?: string } | null;
        awaitingToolResult = decision?.behavior === 'allow' || decision?.kind === 'ask_user_question';
        return result;
      } finally {
        // Allowed tools stay protected until tool_result. Denial / failure may
        // never produce one, so resume idle timing. Never re-add a cleared id or
        // let an old approval remove/reset the next turn's pending tools/budget.
        if (!awaitingToolResult && tracked && turnState.generation === generation && pendingToolIds.delete(toolUseId)) {
          armUpstreamResponseIdle();
        }
      }
    }
    function clearUpstreamResponseIdle(): void {
      if (upstreamResponseIdleTimer) {
        clearTimeout(upstreamResponseIdleTimer);
        upstreamResponseIdleTimer = null;
      }
      upstreamResponseIdleRemainingMs = 0;
      upstreamResponseIdleSliceStartedAt = 0;
    }
    function armUpstreamResponseIdle(): void {
      clearUpstreamResponseIdle();
      if (upstreamResponseIdleTimeoutMs <= 0) return;
      if (closed || !turnInFlight) return;
      // 工具执行 / 用户交互 in-flight 期间 ball 不在上游, 不计 idle 配额。
      if (pendingToolIds.size > 0) return;
      upstreamResponseIdleRemainingMs = upstreamResponseIdleTimeoutMs;
      armUpstreamResponseIdleSlice();
    }
    /**
     * 分片计时,片尾核对真实耗时(壁钟差 ≠ 清醒时间,分层自愈不变量第 6 处;
     * 与 codex 的 armUpstreamIdleSlice、Session 层的 armTurnStallSlice /
     * armAbortRecoverySlice、scheduler 的 absorbSuspendGap、scheduler-host runner
     * 的排队派发上限同源)。不能用一个 30 分钟的长定时器直接判定 —— Electron 被
     * 系统挂起(合盖睡眠)期间没有任何事件,定时器一旦在唤醒后到期就立刻开火,
     * 一次午休就能让看门狗中断一条其实还健康的 turn(SDK 连接可能仍活着)。
     * 片尾判定被冻结过时走**完整重判**(armUpstreamResponseIdle)而不是直接续片:
     * 唤醒后 turn / 工具 / 交互状态可能已经变了。
     */
    function armUpstreamResponseIdleSlice(): void {
      const slice = Math.min(upstreamResponseIdleRemainingMs, CC_UPSTREAM_IDLE_SLICE_MS);
      upstreamResponseIdleSliceStartedAt = Date.now();
      upstreamResponseIdleTimer = setTimeout(() => {
        upstreamResponseIdleTimer = null;
        const elapsed = Date.now() - upstreamResponseIdleSliceStartedAt;
        if (elapsed > slice + CC_UPSTREAM_IDLE_SUSPEND_GAP_MS) {
          log.info('upstream-response-idle watchdog skipped a suspended slice', {
            sdkSessionId,
            sliceMs: slice,
            elapsedMs: elapsed,
          });
          armUpstreamResponseIdle();
          return;
        }
        upstreamResponseIdleRemainingMs -= Math.max(0, elapsed);
        if (upstreamResponseIdleRemainingMs > 0) {
          armUpstreamResponseIdleSlice();
          return;
        }
        onUpstreamResponseIdleTimeout();
      }, slice);
      (upstreamResponseIdleTimer as unknown as { unref?: () => void }).unref?.();
    }
    function onUpstreamResponseIdleTimeout(): void {
      if (closed || !turnInFlight) return;
      const idleMs = upstreamResponseIdleTimeoutMs;
      const msSinceLast = upstreamResponseLastEventAt > 0
        ? Date.now() - upstreamResponseLastEventAt
        : null;
      log.warn('upstream-response-idle watchdog tripped — interrupting current turn', {
        idleMs,
        sdkSessionId,
        lastEventType: upstreamResponseLastEventType,
        msSinceLastEvent: msSinceLast,
        pendingToolIdsSize: pendingToolIds.size,
        turnInFlight,
      });
      // Bridge 消费兜底 (Codex review 3535664420 / 3536509277): 若 watchdog 在
      // bridge /compact turn 内触发(大上下文压缩容易超 idle 阈值), 语义与用户 Stop
      // 一致:取消整条 "compact → real user message" 序列。只 inputQueue.clear()
      // 不够,因为 SDK 可能已经 eager-drain 了后续真实用户输入;只 q.interrupt()
      // 也可能只中断当前 /compact turn,让已 drain 的真实消息继续跑。这里走与
      // abort() 相同的 close-and-rebuild 路径,并保留 rewind resume point 给下一次
      // send 重建。
      if (bridgeStateActive()) {
        const timedOutBridgeKind = activeBridgeKind;
        const timedOutRewindResumeAt = activeBridgeRewindResumeAt;
        log.warn('upstream-idle watchdog fired during bridge — closing query and preserving rewind resume point', {
          queuedBridgeTurns,
          queuedInput: inputQueue.pending,
          activeBridgeRewindResumeAt,
        });
        eventQueue.push({
          type: 'error',
          data: {
            message:
              `上游 API 单次响应已静默 ${Math.round(idleMs / 1000)}s, ` +
              `已自动中断当前 turn 防止卡死。可以直接发下一条消息继续 ` +
              `(已完成的 tool result 都保留)。`,
            isTerminal: true,
            // The bridge precedes the user's input, which is cleared below.
            // It is not an accepted user turn that can receive CONTINUE.
            reason: 'bridge_upstream_response_idle_timeout',
            idleMs,
            sdkSessionId,
            lastEventType: upstreamResponseLastEventType,
            msSinceLastEvent: msSinceLast,
          },
          source: 'claude-code',
        });
        restoreBridgeAutoCompactSnapshot('upstream_response_idle_timeout');
        autoCompactController?.onCompactCanceled('upstream_response_idle_timeout');
        const suppressedDoneData = takeBridgeSuppressedDoneData();
        clearBridgeState();
        inputQueue.clear();
        try {
          inputQueue.end();
        } catch (e) {
          log.warn('upstream-idle watchdog during bridge: inputQueue.end threw', { error: String(e) });
        }
        canceledBridgeQueries.add(q);
        recordCanceledQueryClose(q, 'upstream idle watchdog during bridge');
        turnInFlight = false;
        turnState.interruptRequested = false;
        pendingToolIds.clear();
        preserveBridgeRetryTarget(timedOutBridgeKind, timedOutRewindResumeAt);
        emitTurnBoundary('bridge_upstream_response_idle_timeout', suppressedDoneData);
        return;
      }
      eventQueue.push({
        type: 'error',
        data: {
          message:
            `上游 API 单次响应已静默 ${Math.round(idleMs / 1000)}s, ` +
            `已自动中断当前 turn 防止卡死。可以直接发下一条消息继续 ` +
            `(已完成的 tool result 都保留)。`,
          isTerminal: true,
          reason: 'upstream_response_idle_timeout',
          idleMs,
          sdkSessionId,
          lastEventType: upstreamResponseLastEventType,
          msSinceLastEvent: msSinceLast,
        },
        source: 'claude-code',
      });
      cancelIdleHostAutoCompact('host_auto_compact_idle_timeout');
      // 先关 turn-in-flight + 清 pending 再 interrupt: 这样 SDK drain 出 ResultMessage 时,
      // translator 的 onTurnEnd 还会再清一次 (幂等), 但中间任何 message 都不会重新 arm timer。
      turnInFlight = false;
      pendingToolIds.clear();
      // watchdog 上面已推过带 reason 的 terminal error, interrupt 后 drain 出的
      // is_error result 不能再触发 translator 的失败兜底(双 error banner)。
      turnState.interruptRequested = true;
      turnState.interruptGeneration = turnState.generation;
      void q.interrupt().catch((e) => {
        // interrupt 没发出去 → 不会有被打断的 result 来消费标记, 残留会错误
        // 抑制下一真实 turn 的 is_error 兜底 —— 立即回收。
        turnState.interruptRequested = false;
        log.warn('upstream-response-idle watchdog: interrupt threw', { error: String(e) });
      });
    }
    function noteUpstreamResponseActivity(eventType: string): void {
      upstreamResponseLastEventType = eventType;
      upstreamResponseLastEventAt = Date.now();
      armUpstreamResponseIdle();
    }
    function isCurrentQuery(currentQ: Query): boolean {
      return currentQ === q;
    }

    /**
     * 检查是否需要 auto-compact, 需要时把 /compact push 到 inputQueue。返回是否实际 push。
     * 调用方在 rebuild 尾部的 "compact→user 桥接场景" 中据此把 queuedBridgeTurns++,
     * 让后续中间 turn 边界事件被 suppress、turnInFlight 跨排队 turn 保持。
     * origin=idle 是用户 turn 结束后的静默压缩,失败要 latch/cancel;origin=bridge 由
     * queuedBridgeTurns 分支处理,不要再标 hostAutoCompactInFlight。
     */
    function triggerAutoCompactIfNeeded(origin: 'idle' | 'bridge' = 'idle'): boolean {
      if (closed || turnInFlight) return false;
      if (!autoCompactController?.shouldCompactNow()) return false;
      const snapshot = autoCompactController.getLatestSnapshot();
      const threshold = autoCompactController.getCurrentThresholdPct();
      log.info('auto-compact triggered', {
        threshold,
        ratio: snapshot ? Number(snapshot.ratio.toFixed(3)) : undefined,
        contextTokens: snapshot?.contextTokens,
        contextWindow: snapshot?.contextWindow,
        sdkSessionId,
      });
      beginNewTurn(mutableFastMode ? 'priority' : 'standard');
      resetToolLoopGuards();
      turnInFlight = true;
      if (origin === 'idle') hostAutoCompactInFlight = true;
      inputQueue.push({
        type: 'user',
        message: { role: 'user', content: '/compact' },
        parent_tool_use_id: null,
      });
      armUpstreamResponseIdle();
      return true;
    }

    function noteHostAutoCompactTerminalFailure(message: string): void {
      if (!hostAutoCompactInFlight) return;
      if (!opts.remoteHostId && isDeterministicHostCompactFailure(message)) {
        autoCompactController?.markNeedsRollover('host_auto_compact_failed');
      } else {
        autoCompactController?.onCompactCanceled('host_auto_compact_failed');
      }
    }

    function cancelIdleHostAutoCompact(reason: string): boolean {
      if (!hostAutoCompactInFlight) return false;
      autoCompactController?.onCompactCanceled(reason);
      // 只清 fired。hostAutoCompactInFlight 留给 onTurnEnd,避免取消收尾立刻再注入。
      return true;
    }

    // Rewind preview/commit intentionally skip injecting /compact because they
    // are control operations, not product turns. If a blocked model/window
    // switch crossed the threshold while the old Query was retired, leave the
    // cancellation rebuild tombstone armed so the next send can inject the
    // compact bridge on a fresh Query before accepting user input.
    function shouldRearmAutoCompactAfterRewindControl(): boolean {
      const snapshot = autoCompactController?.getLatestSnapshot();
      const threshold = autoCompactController?.getCurrentThresholdPct();
      return snapshot !== null && snapshot !== undefined &&
        threshold !== undefined &&
        snapshot.ratio >= threshold / 100 &&
        snapshot.ratio < 1 &&
        autoCompactController?.needsRollover() !== true;
    }

    function queueAutoCompactBridge(kind: ActiveBridgeKind, resumeAt?: string): boolean {
      const queued = triggerAutoCompactIfNeeded('bridge');
      if (!queued) return false;
      bridgeCompactUsageSnapshot = autoCompactController?.getLatestSnapshot() ?? null;
      activeBridgeKind = kind;
      if (kind === 'rewind') activeBridgeRewindResumeAt = resumeAt;
      queuedBridgeTurns += 1;
      log.debug('rebuild: bridge /compact injected', {
        bridgeKind: kind,
        queuedBridgeTurns,
        activeBridgeRewindResumeAt,
      });
      return true;
    }

    function preserveBridgeRetryTarget(
      kind: ActiveBridgeKind | null,
      rewindResumeAt: string | undefined,
    ): void {
      if (kind === 'rewind' && rewindResumeAt !== undefined) {
        pendingRewindTo = rewindResumeAt;
      } else if (kind === 'cancellation') {
        continuationCancellationRequiresQueryRebuild = true;
      }
      // Caller may preserve a retry target before clearing this state.
    }

    // 当前 session 的 one-shot tip 状态 (turn-start status 用):
    //  - displayed: id → 已展示次数 (≥ 该 tip 的 guarantees.length 时退出抽样池)
    //  - pity:      id → 自上次展示以来候选轮次 (pickTurnStartStatus 内部自增 / 触发保底)
    // /clear 等价于开新 session → 重建 handle → 状态自然清零, 无需额外重置。
    const oneShotTipState: OneShotState = { displayed: new Map(), pity: new Map() };

    // ── sdkQuery 装配 (可被 rewind 重复调用) ──────────────────────────────────
    // 三件套 (resume + resumeSessionAt + forkSession) 通过 extra 注入。
    // startSession 首次调 buildQuery() 不传 extra, 走 vendorOptions.resumeSessionAt /
    // forkSession 透传 (老链路兼容); rewind 重启时传 extra, 强制三件套。
    const buildQuery = async (extra?: {
      resumeSessionAt?: string;
      forkSession?: boolean;
      permissionMode?: SdkPermissionMode;
      fresh?: boolean;
    }): Promise<Query> => {
      // 会话中途重建(rewind / 追加目录 / resume 恢复等)同样会让新 CLI 进程重读工作区设置。
      if (nativeCliAuth) {
        const override = await findWorkspaceSettingsOverride(opts.workingDir);
        if (override) throw new Error(workspaceSettingsOverrideMessage(override));
      }
      const currentSdkModel = sdkModelFor(mutableModel);
      const workingWindow = resolveModelContextWindow(mutableModel);
      appliedContextWindow = workingWindow;
      applyClaudeContextWindow(env, workingWindow, getAutoCompactThresholdPct());
      if (remoteEnv) applyClaudeContextWindow(remoteEnv, workingWindow, getAutoCompactThresholdPct());
      const currentSdkEffort = getSdkEffortForModel(mutableModel, mutableEffort, mutableProviderId);
      const baseResumeAt = vo.resumeSessionAt as string | undefined;
      const baseFork = vo.forkSession as boolean | undefined;
      const finalResumeAt = extra?.fresh ? undefined : (extra?.resumeSessionAt ?? baseResumeAt);
      const finalFork = extra?.fresh ? false : (extra?.forkSession ?? baseFork);
      const mcpServers = buildMcpServers();
      // ── 智能通讯录两态段: 紧跟 buildMcpServers 求值, prompt 状态与本次 build
      // 实际生效的工具面对齐(rewind/fresh 重建同步跟随), 三种去向:
      //   host 有效状态 enabled 且 cindy_contacts 真的注册了 → 使用规范段;
      //   disabled(功能未开) → 可选功能告示段(邀请开启);
      //   其余(unavailable/工作区覆盖禁用/注册被跳过/remote/未接线) → 不注入 —
      //   既不指挥模型调不可达工具, 也不邀请用户去开一个已开着的开关。
      const contactsRules = (() => {
        // 受邀者(另一个账号)的托管会话不带本机的通讯录说明。
        if (opts.remoteHostId || opts.botRuntimeProfile || hosted?.guest) return '';
        const state = this.deps.getContactsPromptState?.({ workingDir: opts.workingDir });
        if (state === 'disabled') return CONTACTS_RULES_DISABLED;
        if (state !== 'enabled') return '';
        return registeredMcpServerNames.has('cindy_contacts') ? CONTACTS_RULES_ENABLED : '';
      })();
      // A prebound request id is not a resume source until its input is accepted.
      let resumeSdkSid = durableSdkSessionId ?? configuredResumeSessionId;
      let modelUsageCumulativeStartsAtZero = !resumeSdkSid;

      // ── 远端 cc 分支 (Phase 4.3) ──
      // session 标了 remoteHostId 且 host 注入了 remoteCcQueryFactory → 走远端
      // cc-mgr daemon (NDJSON RPC + RemoteQuery 包装), 而非本地 sdkQuery 起子进程。
      // 详见 AgentDeps.remoteCcQueryFactory 文档 (base-agent.ts)。
      //
      // 关键设计:
      //  - 整套 sdkQuery options (除 callback/path/hooks 等不可序列化字段) 透传给
      //    daemon 端 SDK; JSON.stringify 自动 strip callback, daemon 端默认走
      //    acceptEdits permissionMode (cc-mgr SessionRegistry 默认值)
      //  - inputQueue (maker-core push 的 user 消息) 没法直接给 RemoteQuery
      //    (它走 send RPC 而非 AsyncIterable consume), 这里启动一个 fire-and-forget
      //    forwarder 把 inputQueue 转成 remoteQuery.send 调用
      //  - rewind/fork 字段 MVP 不支持;fresh rebuild 只换 Query + 不带 resume,
      //    沿用普通 start 语义,可用于 invalid-resume 自愈
      if (opts.remoteHostId && this.deps.remoteCcQueryFactory) {
        if (extra?.resumeSessionAt || extra?.forkSession) {
          throw new Error(
            'rewind / forkSession are not supported on remote Claude Code sessions yet (MVP)',
          );
        }
        if (!opts.sessionId) {
          throw new Error('cc remote requires opts.sessionId for cc-mgr SessionRegistry routing');
        }
        log.info('claude-code: routing session to remote cc-mgr daemon', {
          remoteHostId: opts.remoteHostId,
          sessionId: opts.sessionId,
        });
        // 已知覆盖缺口(codex-connector review P1):远端会话的转录在远端 daemon
        // 磁盘、CLI 流量直连远端 endpoint(remoteEnv.ANTHROPIC_BASE_URL),本地
        // jsonl 归一化钩子与本地 compat-proxy 响应流改写都拦不到。remote cc 是
        // MVP(rewind/fork 均 throw,撞车主触发路径在远端不可用),但远端 kimi
        // 会话一旦撞车(如中断后可见数回落)将无法自愈,持续腐蚀到会话结束。
        // 修复需扩展 cc-mgr wire protocol + 跨包共享归一化逻辑,列为 follow-up。
        if (resumeSdkSid) {
          log.warn(
            'claude-code: remote cc session not covered by kimi tool-id normalize/rewrite defenses (transcript on remote daemon, CLI bypasses local proxy); a kimi mint collision on this session cannot self-heal',
            { remoteHostId: opts.remoteHostId, sessionId: opts.sessionId, resumeSdkSid },
          );
        }
        // 网关路径(remoteRoute 为 null,即会话有效路由是 XD 网关)才依赖
        // runtimeConfig.remoteEndpoint:host 定义了该字段但值为空 = 网关凭据尚未就绪 /
        // 已失效,env-builder 会回落到本地 endpoint(下面 loopback guard 虽能拦,但错误
        // 归因成「内部错误」误导排查),这里先按真实原因拒绝。(`!== undefined` 区分未注入
        // 该字段的旧 host,保持其原有回落行为。)
        // route 路径(native OAuth / 自定义供应商)的 endpoint 已由 resolveRemoteClaudeRoute
        // 覆盖成供应商真上游,与网关 endpoint 就绪与否无关,跳过本判。
        if (
          !remoteRoute &&
          this.deps.runtimeConfig.remoteEndpoint !== undefined &&
          !this.deps.runtimeConfig.remoteEndpoint.trim()
        ) {
          throw new Error(
            '[REMOTE_GATEWAY_ENDPOINT_UNAVAILABLE] Remote Claude Code sessions need the XD gateway endpoint issued after sign-in; gateway credentials are not ready on this desktop yet.',
          );
        }
        // Defense-in-depth: a remote machine can't reach the host's local loopback
        // compat-proxy. The host guarantees remote env uses the real upstream gateway
        // via runtimeConfig.remoteEndpoint (see desktop runtime-configs.ts +
        // env-builder.ts remote branch), so this should never fire — if it does, the
        // remote env was assembled wrong; reject rather than let remote cc dial a
        // loopback URL it can't reach.
        if (isLoopbackEndpoint(remoteEnv?.ANTHROPIC_BASE_URL)) {
          throw new Error('[REMOTE_COMPAT_MODE_UNSUPPORTED] Remote Claude Code sessions cannot route through the local compat proxy.');
        }
        // startParams shape 跟 sdkQuery options 同源 (cwd / model / env / mcpServers /
        // permissionMode / systemPrompt / additionalDirectories), JSON 序列化时
        // canUseTool / pathToClaudeCodeExecutable / stderr / hooks 等 callback/path
        // 字段不能序列化。权限回调由反向 RPC 承接;host capability route 则转成
        // 下方 JSON-safe toolGuards,由 daemon 重建 PreToolUse hook,避免远端
        // settings allow 规则或 bypassPermissions 绕过来源选择。
        //
        // mcpServers: 远端 cc MVP 只支持 stdio / sse / http 三种 process-transport
        // server (plain JSON 可跨进程)。in-process SDK MCP (type='sdk' + 闭包 instance)
        // 不可序列化 — instance 里藏 ajv SchemaEnv 循环引用, JSON.stringify 会爆栈。
        // 直接 filter 掉, 让远端 daemon 用 stdio/sse/http MCP 跑; 本地 lizi-* 全套
        // in-process MCP 在远端会话里不可用(远端 cc MVP 的已知限制)。
        const remoteMcpServers = mcpServers
          ? Object.fromEntries(
              Object.entries(mcpServers).reduce<Array<[string, unknown]>>((acc, [name, cfg]) => {
                const c = cfg as { type?: string; command?: unknown };
                const t = c.type;
                if (t === undefined && typeof c.command === 'string') {
                  acc.push([name, { ...cfg, type: 'stdio' }]);
                } else if (t === 'stdio' || t === 'sse' || t === 'http') {
                  acc.push([name, cfg]);
                }
                return acc;
              }, []),
            )
          : undefined;
        if (mcpServers && remoteMcpServers && Object.keys(mcpServers).length !== Object.keys(remoteMcpServers).length) {
          const dropped = Object.keys(mcpServers).filter((k) => !(k in remoteMcpServers));
          log.warn('cc remote: dropping in-process MCP servers (MVP not supported)', { dropped });
        }
        // 远端会话的 server 基线是 remoteMcpServers (被 filter 掉的 in-process server
        // 在远端不存在); 但 factory 还可能注入 host 侧 http server (协同恢复通道),
        // 所以审批归属快照不在此处定稿, 挪到 factory 调用后按 startParams 重算。
        // 计划模式开启时远端 SDK 同样跑 plan; 读 mutable 值让 rewind 重建也拿到当前档。
        const requestedRemotePermissionMode = extra?.permissionMode ?? effectiveSdkPermissionMode();
        const remoteHasMcpServers = Object.keys(remoteMcpServers ?? {}).length > 0;
        // effectiveSdkPermissionMode() is computed from the local registration snapshot,
        // which still includes in-process SDK MCPs that were just filtered out above.
        // Restore native OAuth Auto when the remote query has no serializable MCP surface;
        // the Desktop factory will still downgrade it before opening the query if it later
        // injects a host HTTP MCP (for example the collaboration bridge).
        const remotePermissionMode =
          requestedRemotePermissionMode === 'default'
          && mutablePermissionMode === 'auto'
          && !mutablePlanMode
          && !planTurnActive
          && !nativeAutoReviewUnavailable
          && mutableAutoReviewCredentialMode === 'oauth-bearer'
          && !remoteHasMcpServers
            ? 'auto'
            : requestedRemotePermissionMode;
        sdkInPlanMode = remotePermissionMode === 'plan';
        const remoteToolGuards = [
          ...buildClaudeRemoteToolGuards(this.deps.capabilityRouting),
          ...buildClaudeRemoteRootOnlyToolGuards(),
          ...buildClaudeRemoteOrcaCallerGuards(vo.orcaRole === 'worker'),
        ];

        const startParams: Record<string, unknown> = {
          cwd: opts.workingDir,
          model: currentSdkModel,
          // 关键: 远端必须用 remoteEnv (零 process.env 继承), 不能用本地分支的
          // env。否则 desktop 的 HOME / PATH / APPDATA 等会污染远端 SDK spawn 的
          // cc CLI(典型: Windows HOME=C:\Users\Lizi 透到 mac, 远端 cc CLI
          // 把 ~ 展开成 <cwd>/C:\Users\Lizi/.claude/, session 全落怪目录)。
          // remoteEnv 在 startSession 顶部已经 build (opts.remoteHostId 非空时
          // 才 build), 这里 ! 是合理的 — 走到这分支 remoteCcQueryFactory 也已经
          // gate 过 remoteHostId 非空。
          env: remoteEnv ?? env,
          permissionMode: remotePermissionMode,
          // cc-manager 的 QueryStartParams 已原生支持 allowedTools; 传副本避免 RPC
          // 序列化前后任一侧原地改写 session 快照。
          ...(claudeAllowedTools ? { allowedTools: [...claudeAllowedTools] } : {}),
          ...(claudeDisallowedTools.length > 0
            ? { disallowedTools: [...claudeDisallowedTools] }
            : {}),
          ...(remoteToolGuards.length > 0
            ? { toolGuards: remoteToolGuards }
            : {}),
          systemPrompt: (() => {
            const appendText = buildClaudeSystemPromptAppend({
              answerDeliveryPrompt: reviewMode ? undefined : this.deps.runtimeConfig.answerDeliveryPrompt,
              makerMemoryRules,
              contactsRules,
              ghostRosterPrompt,
              hostSystemPrompt,
              makerMemoryIndex,
              botProfilePrompt: reviewMode ? undefined : opts.botProfilePrompt,
              botProfileContextPrompt:
                reviewMode ? undefined : opts.botProfileContextPrompt,
              botUserProfilePrompt: reviewMode ? undefined : opts.botUserProfilePrompt,
              userPrompt: reviewMode || opts.botRuntimeProfile ? undefined : opts.userPrompt,
              ...(hosted ? { deviceHostedNote: deviceHostedClaudeNote(hosted, opts.workingDir) } : {}),
            });
            return {
              type: 'preset' as const,
              preset: 'claude_code' as const,
              ...(appendText ? { append: appendText } : {}),
            };
          })(),
          // **不透传 extraDirs 到远端**: mutableExtraDirs 由 desktop session/draft
          // 提供, 路径基于 desktop 本地文件系统 (用户拖进来的文件夹), 跟远端机器
          // 上的路径毫无关系。SDK 把 additionalDirectories 当 cwd 之外的允许范围,
          // 用 desktop 路径只会让远端 SDK 报"路径不存在 / 不在允许范围"或者更糟,
          // 误把同名远端路径加进允许范围。远端 cwd 在 startParams.cwd 已传, 别处
          // 想加额外目录要由远端用户在远端机器上配置, 不在本 PR scope。
          ...(remoteMcpServers && Object.keys(remoteMcpServers).length > 0 ? { mcpServers: remoteMcpServers } : {}),
          ...(resumeSdkSid ? { resumeSdkSessionId: resumeSdkSid } : {}),
          // includePartialMessages 必须跟本地分支保持一致 — 否则 daemon 端 SDK
          // 不发 stream_event / message_delta, UsageTracker 拿不到 per-turn cache
          // 数据 (cache hit rate 永远 n/a, 违反规则 19), renderer 也失去增量打字
          // 动效。cache 实际是热的, 只是观测链路断了。
          //
          // 走 extraOptions 通道: QueryStartParams 顶层枚举字段没列 it, daemon
          // destructure 拿不到; 但 daemon 末尾 spread `...extraOptions` 进 SDK
          // options (cc-mgr.ts:106), 所以 extraOptions 是任意 SDK 字段的统一透传出口。
          extraOptions: {
            includePartialMessages: true,
            ...(opts.botRuntimeProfile ? { strictMcpConfig: true } : {}),
            ...thinkingOpts,
            ...(currentSdkEffort ? { effort: currentSdkEffort } : {}),
            // settings 对象跟本地分支同源 — 不透传则远端 SDK 拿不到
            // showThinkingSummaries / autoMemoryEnabled, 远端行为跟本地分歧。
            settings: buildSettings(),
            // settingSources 跟本地分支同源透传:远端 cc CLI 会读用户在远端机器
            // 上的 ~/.claude / 项目 .claude / cwd-local 三层 settings 文件 (slash
            // commands / output styles / hooks / per-project model 等)。不透传
            // SDK 默认不读, 远端会丢用户配置, 跟本地行为分歧。
            settingSources: reviewMode || !!opts.botRuntimeProfile
              ? []
              : ['user', 'project', 'local'],
          },
        };

        onRuntimeStartAttempted();
        const remoteQuery = await this.deps.remoteCcQueryFactory({
          remoteHostId: opts.remoteHostId,
          botSession: !reviewMode && !!opts.botRuntimeProfile,
          sessionId: opts.sessionId,
          ...(opts.sessionInstanceId ? { sessionInstanceId: opts.sessionInstanceId } : {}),
          startParams,
          // 协同身份以 session 自己的 vendorOptions 为准 (worker 首次创建时
          // DB 标记尚未写入, host 现场查库会拿到空角色)。见 base-agent.ts
          // remoteCcQueryFactory 的 vendorOptions 注释。
          vendorOptions: vo,
          // per-session Maker Memory 开关 — host 据此决定是否把 cindy_memory
          // 以 http 形态注进远端 startParams.mcpServers (cc-remote-mcp.ts)。
          makerMemoryEnabled,
          // 同一个 scope key 也必须随注册的 session ctx 走: prompt 段用它读索引
          // (上方 memoryScopeKey), 远端工具侧不给就会回落到 workdir 键。
          ...((makerMemoryEnabled || opts.makerMemoryScopeKey) ? { makerMemoryScopeKey: memoryScopeKey } : {}),
          onApprovalRequest: (rawParams: unknown) => withRemoteApprovalIdleGuard(rawParams, async () => {
            // 110s timeout — must respond before daemon's 120s server-request timeout.
            // On timeout, dismiss the pending interaction (clears UI) and reject to
            // let cc-manager-client return deny to daemon.
            const REMOTE_APPROVAL_TIMEOUT_MS = 110_000;
            async function dispatchWithTimeout(
              req: InteractionRequest,
            ): Promise<InteractionDecision> {
              let timer: NodeJS.Timeout | undefined;
              try {
                return await new Promise<InteractionDecision>((resolve, reject) => {
                  timer = setTimeout(() => {
                    dismissSinglePending(req.requestId, 'approval_timeout');
                    reject(new Error('approval timed out'));
                  }, REMOTE_APPROVAL_TIMEOUT_MS);
                  dispatchInteraction(req).then(resolve, reject);
                });
              } finally {
                if (timer) clearTimeout(timer);
              }
            }
            const params = rawParams as {
              sessionId: string;
              requestId: string;
              kind: 'permission' | 'ask_user_question' | 'plan_review';
              toolName?: string;
              input?: Record<string, unknown>;
              title?: string;
              displayName?: string;
              description?: string;
              suggestions?: unknown[];
              metadata?: Record<string, unknown>;
              questions?: unknown[];
              plan?: string;
              planFilePath?: string;
            };
            if (params.kind === 'ask_user_question') {
              const askInput = (params.input ?? {}) as { questions?: unknown[] };
              const decision = await dispatchWithTimeout({
                kind: 'ask_user_question',
                requestId: params.requestId,
                toolUseId: params.requestId,
                questions: (params.questions ?? askInput.questions ?? []) as AskUserQuestionItem[],
              });
              if (decision.kind !== 'ask_user_question') {
                return { kind: 'ask_user_question', answers: {} };
              }
              // 远端澄清同样改变本轮授权范围(用户把范围从 src/ 收窄到 build/)→ 与本地 AskUserQuestion
              // 分支一致地并入有界 review intent 并清空裁决缓存,否则后续工具仍按澄清前的意图裁决、
              // 越界操作可能被静默允许(codex 报)。
              setAutoReviewIntent(composeAutoReviewIntentWithClarification(
                currentAutoReviewIntent,
                Object.entries(decision.answers ?? {}).map(([question, answer]) => ({ question, answer })),
              ));
              return { kind: 'ask_user_question', answers: decision.answers };
            }
            if (params.kind === 'plan_review') {
              const planInput = (params.input ?? {}) as { plan?: string; planFilePath?: string };
              const plan = params.plan ?? planInput.plan ?? '';
              // 审批等待期间用户可能继续发消息(setAutoReviewIntent 会覆盖 currentAutoReviewIntent),
              // 实施阶段的审查意图必须锚在**发起计划时**的原始请求上,不能掺进审批期间的内部跟进
              // (copilot 报;与本地 ExitPlanMode 分支的 planRequestAutoReviewIntent 同款)。
              const planRequestAutoReviewIntent = currentAutoReviewIntent;
              const decision = await dispatchWithTimeout({
                kind: 'plan_review',
                requestId: params.requestId,
                toolUseId: params.requestId,
                plan,
                planFilePath: params.planFilePath ?? planInput.planFilePath,
              });
              if (decision.kind !== 'plan_review') {
                return { kind: 'plan_review', behavior: 'deny', reason: 'resolver kind mismatch' };
              }
              if (decision.behavior === 'allow') {
                planTurnActive = false;
                sdkInPlanMode = false;
                appendActiveCapabilitySelectionText(
                  capabilitySelectionAddedByPlanEdit(
                    this.deps.capabilityRouting,
                    'claude-code',
                    plan,
                    decision.editedPlan,
                  ),
                );
                // 远端计划获批同样要把审查意图更新成"原始意图 + 最终获批计划"—— 与本地 ExitPlanMode 分支
                // 一致,否则后续实施工具的轻量 reviewer 仍按批准前的过期意图裁决(codex 报)。
                setAutoReviewIntent(composeAutoReviewIntentWithApprovedPlan(
                  planRequestAutoReviewIntent,
                  decision.editedPlan ?? plan,
                ));
              } else if (!decision.dismissed) {
                appendActiveCapabilitySelectionText(decision.reason);
                if (decision.reason?.trim()) setAutoReviewIntent(appendAutoReviewUserIntent(planRequestAutoReviewIntent, decision.reason));
              }
              return {
                kind: 'plan_review',
                behavior: decision.behavior,
                editedPlan: decision.editedPlan,
                reason: decision.reason,
                dismissed: decision.dismissed,
              };
            }
            // permission kind
            const remoteToolName = params.toolName ?? '';
            // Remote cc-manager checks the route with authoritative scoped MCP
            // provenance before forwarding canUseTool. Old managers do not add
            // this attestation, so retain the desktop-side fail-closed fallback.
            const capabilityRoute = params.metadata?.capabilityRoutingChecked === true
              ? undefined
              : deniedCapabilityRoute(remoteToolName);
            if (capabilityRoute) {
              log.warn('cc remote: downstream MCP source denied by host capability route', {
                toolName: remoteToolName,
                capabilityId: capabilityRoute.capabilityId,
                replacement: capabilityRoute.replacement?.id,
              });
              return {
                kind: 'permission',
                behavior: 'deny',
                reason: capabilityRoute.replacement
                  ? `This downstream source was not selected. Use Cindy capability ${capabilityRoute.replacement.id}.`
                  : 'This downstream source was not selected.',
              };
            }
            // Auto allow/block do not need UI, including MCP operations.
            if (isPlanToolBlocked(remoteToolName)) {
              return { kind: 'permission', behavior: 'deny', reason: 'The current Plan turn is read-only.' };
            }
            const canReviewRemoteWithoutUi = mutablePermissionMode === 'auto';
            if (!interactionResolver && !canReviewRemoteWithoutUi) {
              if (isReadOnlyClaudeTool(remoteToolName)) {
                return { kind: 'permission', behavior: 'allow' };
              }
              log.warn('cc remote: approval without interactionResolver → fail-closed deny', {
                tool: remoteToolName || 'unknown',
              });
              return {
                kind: 'permission',
                behavior: 'deny',
                reason: 'no interaction resolver attached; denying non-read-only tool (fail-closed)',
              };
            }
            const remoteTurnPolicyForcePrompt = forceTurnConfirmation(
              remoteToolName || 'unknown',
              params.input ?? {},
            );
            if (mutablePermissionMode === 'bypassPermissions') {
              return { kind: 'permission', behavior: 'allow' };
            }
            // 远端会话走同一份 host MCP 策略 —— 否则 SSH 会话里可信 server 又要逐次
            // 弹窗, prompt-each-time 的"禁止持久化授权"保护也整套缺失。
            const remoteMcpPolicy = classifyMcpApprovalPolicy(remoteToolName, params.input ?? {});
            let remoteForcePrompt = mutablePermissionMode !== 'auto' && remoteTurnPolicyForcePrompt;
            let remoteUnavailableHandoff = false;
            let remoteAutoReviewAskReason: string | undefined;
            const reviewPermissionMode = mutablePermissionMode;
            if (reviewPermissionMode === 'auto' || (remoteMcpPolicy === 'auto-approve' && !remoteTurnPolicyForcePrompt)) {
              const normalizedAction = normalizeBuiltinToolForAutoReview(remoteToolName, params.input ?? {});
              const action = normalizedAction.kind === 'other'
                ? toolAutoReviewAction(remoteToolName, params.input ?? {})
                : normalizedAction;
              if (action.kind === 'exec') action.destructivePathResolution = 'unavailable';
              // The controller cannot prove a path on the SSH filesystem. Mark
              // structured writes unresolved so shared review never grants them
              // from a lexical prefix alone.
              if (action.kind === 'file-write') action.resolvedPath = null;
              const autoDecision = await reviewAutoAction(
                remoteTurnPolicyForcePrompt ? toolAutoReviewAction(remoteToolName, params.input ?? {}, undefined, action) : action,
                [opts.workingDir].filter(
                  (d): d is string => typeof d === 'string' && d.length > 0,
                ),
                [opts.workingDir].filter(
                  (d): d is string => typeof d === 'string' && d.length > 0,
                ),
                'linux',
                remoteMcpPolicy === 'auto-approve' && !remoteTurnPolicyForcePrompt,
                reviewPermissionMode !== 'auto',
              );
              const modeAfterReview = mutablePermissionMode as PermissionMode;
              if (isPlanToolBlocked(remoteToolName)) {
                return { kind: 'permission', behavior: 'deny', reason: 'The current Plan turn is read-only.' };
              }
              if (modeAfterReview === 'bypassPermissions') {
                return { kind: 'permission', behavior: 'allow' };
              }
              if (modeAfterReview === reviewPermissionMode && autoDecision.verdict === 'allow') {
                return { kind: 'permission', behavior: 'allow' };
              }
              if (modeAfterReview === 'auto' && reviewPermissionMode === 'auto' && autoDecision.verdict === 'block') {
                // 与本地分支同口径:模型判定保持静默(审阅器故障已降级成 ask)。
                return {
                  kind: 'permission',
                  behavior: 'deny',
                  reason: formatPermissionDenial('auto', autoDecision.reason),
                };
              }
              // 与本地分支同口径:故障降级来的 ask 提示一次,让用户知道为何开始被问。
              if (autoDecision.unavailable) {
                autoReviewUnavailableNotice.notify();
                remoteUnavailableHandoff = true;
              } else {
                remoteAutoReviewAskReason = autoDecision.reason;
              }
              remoteForcePrompt = true;
            } else {
              remoteForcePrompt = remoteForcePrompt || remoteMcpPolicy === 'prompt-each-time';
            }
            const remotePermissionRequest = {
              kind: 'permission' as const,
              requestId: params.requestId,
              toolUseId: params.requestId,
              toolName: params.toolName ?? 'unknown',
              input: params.input ?? {},
              title: params.title,
              displayName: params.displayName,
              description: params.description,
              suggestions: remoteForcePrompt
                ? undefined
                : this.normalizeSessionPermissionSuggestions(params.suggestions),
              metadata: params.metadata ?? {},
            };
            let decision: InteractionDecision;
            try {
              decision = await dispatchWithTimeout(
                annotatePermissionRequestForAutoReview(remotePermissionRequest, {
                  unavailable: remoteUnavailableHandoff,
                  reason: remoteAutoReviewAskReason,
                }),
              );
            } catch {
              if (remoteUnavailableHandoff) autoReviewConfirmUndeliveredNotice.notify();
              return { kind: 'permission', behavior: 'deny', reason: 'approval_timeout' };
            }
            notifyIfAutoReviewConfirmUndelivered(remoteUnavailableHandoff, decision);
            if (isPlanToolBlocked(remoteToolName)) {
              return { kind: 'permission', behavior: 'deny', reason: 'The current Plan turn is read-only.' };
            }
            if (decision.kind !== 'permission') {
              return { kind: 'permission', behavior: 'deny', reason: 'resolver kind mismatch' };
            }
            if (remoteForcePrompt && decision.permissionUpdates && decision.permissionUpdates.length > 0) {
              log.warn('dropping session permission grant for prompt-each-time MCP tool (remote)', {
                tool: params.toolName,
              });
            }
            return {
              kind: 'permission',
              behavior: decision.behavior,
              updatedInput: decision.updatedInput,
              permissionUpdates: remoteForcePrompt ? undefined : decision.permissionUpdates,
              reason: decision.behavior === 'deny'
                ? formatPermissionDenial(isSystemPermissionDenialReason(decision.reason) ? 'system' : 'user', decision.reason)
                : decision.reason,
            };
          }),
          onSubagentModelAccessRequest: async (rawParams: unknown) => {
            const params = typeof rawParams === 'object' && rawParams !== null
              ? rawParams as Record<string, unknown>
              : {};
            const model = typeof params.model === 'string' ? params.model : '';
            if (!model || !resolveSubagentModelAccess) return { status: 'unknown' };
            try {
              return await resolveSubagentModelAccess(model);
            } catch {
              return { status: 'unknown' };
            }
          },
          // 订阅 token 到期续命(远端版,对齐本地 SDK options 的 getOAuthToken 回调,
          // 见 buildQuery 本地分支):远端 cc 中途 401 → daemon 发 oauth/refresh 反向
          // RPC → 这里向 host 要新 token。接线条件与本地同款:env 实际带订阅 token 且
          // host 实现了强刷 —— 网关 key / 自定义供应商会话绝不接,避免 API-key 401 被
          // 误引导去刷订阅 token。刷新语义(失败基线 / 原地写回单一事实源)与本地共用
          // refreshSubscriptionTokenInPlace。
          ...(remoteEnv?.CLAUDE_CODE_OAUTH_TOKEN && this.deps.auth.getFreshSubscriptionToken
            ? {
                onOAuthRefresh: async (): Promise<unknown> => ({
                  token: await this.refreshSubscriptionTokenInPlace(remoteEnv),
                }),
              }
            : {}),
        });
        // factory 可能注入 host 侧 http server (远端 cc 协同恢复通道的
        // cindy_orca / orca_worker_bridge, 见 maker-host remoteCcQueryFactory),
        // 审批归属快照必须按注入后的最终清单定稿, 否则 canUseTool 的
        // resolveMcpToolTarget 认不出 orca server 名, 归属判定缺失。
        hostMcpServerNames = new Set(
          Object.keys((startParams as { mcpServers?: Record<string, unknown> }).mcpServers ?? {}),
        );
        registeredMcpServerNames = hostMcpServerNames;
        nonHarnessMcpServerNames = hostMcpServerNames;
        // The factory may inject host HTTP MCPs and downgrade OAuth Auto to
        // default before opening cc-manager. Track the post-factory mode so a
        // later SDK init cannot repeat that downgrade and turn a harmless
        // control-RPC failure into a fatal close.
        const finalRemotePermissionMode =
          (startParams.permissionMode as SdkPermissionMode | undefined) ?? remotePermissionMode;
        sdkInPlanMode = finalRemotePermissionMode === 'plan';
        // 记入 closure: handle.close / U2 兜底需要 await remoteQuery.close()。
        activeRemoteQuery = remoteQuery as unknown as { close: () => Promise<void>; detach?: () => Promise<void> };

        // Bridge inputQueue (maker-core push) → remoteQuery.send (RPC)。
        // 失败处理 (round-16 fix #2 P2): 之前只 warn → user message 永远不到
        // daemon, 但 handle.send 已经 armed streaming state, renderer 卡在
        // "thinking..." 直到 idle watchdog (默认数分钟) 才解套。改成主动调
        // activeRemoteQuery.close() 关闭 RemoteQuery → close subscription
        // 让 RemoteQuery iterator 自然结束 → maker-core 主循环 for-await 退出
        // → 复用 U2 兜底 (本文件 line ~1418-1471) emit error + done +
        // dismissAllPending + inputQueue.end + abort, 用户立即看到 "远端连接
        // 中断" 错误能重发, 不再卡 watchdog 时长。break for-await 防后续
        // inputQueue msg 又调死掉的 send 触发同款 warn。
        (async (): Promise<void> => {
          for await (const msg of inputQueue) {
            try {
              await (remoteQuery as unknown as {
                send: (m: unknown) => Promise<void>;
              }).send(msg);
            } catch (e) {
              log.warn('cc remote: forwarding inputQueue → remoteQuery.send failed; closing remote query to surface aborted-turn', {
                error: String((e as Error)?.message ?? e),
              });
              if (activeRemoteQuery) {
                void activeRemoteQuery.close().catch((err) => {
                  log.warn('cc remote: remoteQuery.close after send failure threw (best-effort)', {
                    error: String((err as Error)?.message ?? err),
                  });
                });
              }
              break;
            }
          }
        })().catch(() => undefined);

        if (finalRemotePermissionMode === 'auto') nativeAutoQueries.add(remoteQuery);
        if (modelUsageCumulativeStartsAtZero) modelUsageStartsAtZeroQueries.add(remoteQuery);
        return remoteQuery;
      }

      // ── 本地 SDK 分支 ──
      // resume 转录就位兜底:CLI 只按当前 cwd 的转码目录查找转录,而转录可能因
      // CLI 运行中 cd(worktree 工作流)、rewind fork(新 jsonl 落在源文件旁)等
      // 场景落在其它转码目录(见 transcript-relocation.ts)。spawn 前把 jsonl 归位;
      // projectsRoot 按子进程实际可见的 CLAUDE_CONFIG_DIR 解析(SDK spawn 时
      // {...process.env, ...env} 合并,env 覆盖优先)。best-effort:已在位只花一次
      // stat,失败/缺失只记日志不阻断——CLI 找不到时仍按原行为报错。
      if (resumeSdkSid && opts.workingDir) {
        try {
          const claudeConfigDir =
            env.CLAUDE_CONFIG_DIR ??
            process.env.CLAUDE_CONFIG_DIR ??
            path.join(os.homedir(), '.claude');
          const outcome = await ensureClaudeTranscriptInWorkingDir({
            sdkSessionId: resumeSdkSid,
            workingDir: opts.workingDir,
            projectsRoot: path.join(claudeConfigDir, 'projects'),
          });
          if (outcome === 'restored') {
            log.info('resume transcript restored into cwd project dir', {
              resumeSdkSid,
              workingDir: opts.workingDir,
            });
          }
          // kimi 系 tool_call id 归一化: moonshot 按可见历史铸造 `${name}_${index}`
          // id, rewind/中断造成的可见数回落会让新铸 id 与历史撞车, CLI 的
          // ensureToolResultPairing 随即将重复 id 的 tool exchange 整段丢弃并以
          // "(no content)" 占位 user 消息 —— 模型看到"自己的工具调用被阻止 +
          // 用户连发空消息"进入空转(2026-07-31 kimi-k3 实测)。转录就位后、spawn
          // 前做一次幂等归一化(重复 id 去重 + 数字后缀移出铸造空间), 纯 Anthropic
          // 会话预扫不命中、零解析开销。详见 jsonl-tool-id-normalize.ts 头注。
          // 'target-key-inexact' 时 relocation 无法定位 CLI 转码目录, 但全局扫描
          // 找到的最新副本大概率正是 CLI 要读的转录, 归一化它同样是正收益。
          if (outcome !== 'missing' && resumeSdkSid) {
            const transcriptFile = await findClaudeSessionJsonl(
              resumeSdkSid,
              opts.workingDir,
              path.join(claudeConfigDir, 'projects'),
            );
            if (transcriptFile) {
              const normalized = await normalizeClaudeSessionJsonlToolIds(transcriptFile);
              if (normalized.changed) {
                log.info('resume transcript tool ids normalized', {
                  resumeSdkSid,
                  dedupedBlocks: normalized.dedupedBlockCount,
                  offsetBlocks: normalized.offsetBlockCount,
                  duplicateIds: normalized.duplicateIdCount,
                  backupPath: normalized.backupPath,
                });
              }
            }
          }
          if (outcome === 'missing') {
            const cleared = await clearInvalidResumeSession(resumeSdkSid, 'transcript_preflight');
            if (cleared) {
              // 本地 CLI 没有转录就不可能恢复。spawn 前转 fresh,当前用户消息尚未
              // dispatch,不需要运行期 replay,也不会产生任何失败边界事件。
              // 重置 recovery 标记:后续全新会话是独立生命周期,若首 turn 产生幽灵 id
              // 仍需 runtime 路径清理,不应被 preflight 的一次性消耗阻塞。
              resumeRecoveryAttempted = false;
              freshSessionValidationPending = true;
              resumeSdkSid = undefined;
              modelUsageCumulativeStartsAtZero = true;
            } else {
              log.warn('resume transcript not found in any project dir (CLI resume may fail)', {
                resumeSdkSid,
                workingDir: opts.workingDir,
              });
            }
          }
        } catch (e) {
          log.warn('resume transcript bootstrap failed (continuing)', {
            resumeSdkSid,
            error: e instanceof Error ? e.message : String(e),
          });
        }
      }
      // 计划模式开启时 SDK 跑 plan; 读 mutable 值让 rewind/fork 重建拿到当前档而非创建时快照。
      const additionalDirectories = [...new Set([...mutableExtraDirs, ...mutableWritableDirs])];
      activeQueryHasDirectoryGrants = additionalDirectories.length > 0;
      activeQueryDirectoryGeneration = autoReviewDirectoryGeneration;
      activeQueryReadonlyDirs = [...mutableExtraDirs];
      extraDirsRebuildAttempted = false;
      activeQueryExploreInheritCapGeneration = exploreInheritCapEnvGeneration;
      const sdkStartPermissionMode = extra?.permissionMode ?? effectiveSdkPermissionMode();
      sdkInPlanMode = sdkStartPermissionMode === 'plan';
      // Review 会话不带任何 Bot 身份/能力(与 botSkillPolicy 同口径)。
      companionEnvironment?.assertCurrent?.();
      // Re-read at each Query boundary: plugin uninstall/disable may remove the
      // previous projection while the conversation itself remains open.
      // 受邀者(另一个账号)的托管会话不带本机安装的托管技能(属于本机用户与其组织)。
      const managedSkills = !reviewMode && !hosted?.guest && !opts[LOCAL_AGENT_CLIENT]?.hostToolsOnly && this.deps.getManagedSkills
        ? await this.deps.getManagedSkills() : [];
      const managedDisabledPaths = currentDisabledSkillLaunchPaths(managedDisabledSkillLaunch);
      const allowedManagedSkills = resolveAllowedManagedSkills(managedSkills, managedSkillGrants, managedDisabledPaths);
      const managedPlugins = allowedManagedSkills.length
        ? await prepareManagedSkillPlugins(allowedManagedSkills, (name) => {
          log.warn('managed skill disappeared before Query startup; skipping', { skill: name });
        }) : undefined;
      const releaseManagedPlugins = () => {
        void managedPlugins?.dispose().catch((error) => log.warn('managed skill plugin cleanup failed', { error: String(error) }));
      };
      const querySignal = abortController.signal;
      if (managedPlugins) querySignal.addEventListener('abort', releaseManagedPlugins, { once: true });
      const botOwnSkillPluginRoots = reviewMode
        ? []
        : [...new Set([...(managedPlugins?.roots ?? []), ...(opts.botRuntimeProfile?.skillPolicy.ownSkillPluginRoots ?? [])])];
      // Bind the native request id before the first HTTP request, not after SDK init.
      // A fork keeps its resume source but must publish a new destination id.
      const newSdkSessionId = !resumeSdkSid || finalFork ? randomUUID() : undefined;
      const previousSdkSessionId = sdkSessionId;
      const createLocalQueryArgs = (): Parameters<typeof sdkQuery>[0] => ({
        prompt: inputQueue as unknown as Parameters<typeof sdkQuery>[0]['prompt'],
        options: {
          abortController,
          cwd: opts.workingDir,
          // 附加目录在 Query 创建时冻结;运行时 setter 立即收紧 Cindy 审核,后续 Query
          // 重建再取最新 closure。空数组省略字段,让 SDK 走默认。
          // 设备托管:附加目录在任务所在电脑上,由 cindy_exec 工具访问。
          ...(additionalDirectories.length > 0 && !hosted ? { additionalDirectories } : {}),
          // Bot 自有技能和已按启用状态/白名单过滤的 Cindy 托管技能,
          // 只通过本次 Query 的本地插件加载,不写用户共用技能目录。
          // 与 additionalDirectories 同理:路径是本机的,远端 cc-mgr 分支不透传。
          ...(botOwnSkillPluginRoots.length > 0
            ? { plugins: botOwnSkillPluginRoots.map((root) => ({ type: 'local' as const, path: root })) }
            : {}),
          model: currentSdkModel,
          ...(currentSdkEffort ? { effort: currentSdkEffort } : {}),
          permissionMode: sdkStartPermissionMode,
          includePartialMessages: true,
          ...thinkingOpts,
          pathToClaudeCodeExecutable: binaryPath,
          // systemPrompt 八段拼接(含 SDK 内嵌 preset)— SDK 先输出 preset, 再追加 append 字段。
          //   [1] cc preset                  — Claude SDK 自带 (内嵌不可见)
          //   [2] opts.botProfilePrompt      — Bot SOUL identity only (main/DB authority)
          //   [3] MAKER_SYSTEM_PROMPT_APPEND — maker engine (system-prompt-append.md)
          //   [4] makerMemoryRules           — maker memory 写入规范 (条件式: makerMemoryEnabled
          //                                    且 manager 注入成功才注入)
          //   [5] contactsRules              — 智能通讯录两态段 (条件式: host 注入了
          //                                    getContactsPromptState 才有, 开/关各一份静态文案)
          //   [6] opts.botProfileContextPrompt — stable active-profile marker, kept outside SOUL
          //   [7] hostSystemPrompt           — host runtime (runtimeConfig.systemPrompt)
          //   [8] makerMemoryIndex           — 当前 workdir MEMORY.md 内容 (条件式, 紧邻 userPrompt
          //                                    高优先级, 启动时快照 — 跟 userPrompt 同语义)
          //   [9] opts.userPrompt            — per-call 用户级 (renderer 本地 storage,
          //                                    每次 startSession 透传, 优先级最高)
          // 空段被 .filter 跳过 (.md 文件为空 / userPrompt 为空 = 不 append).
          systemPrompt: (() => {
            const appendText = buildClaudeSystemPromptAppend({
              answerDeliveryPrompt: reviewMode ? undefined : this.deps.runtimeConfig.answerDeliveryPrompt,
              makerMemoryRules,
              contactsRules,
              ghostRosterPrompt,
              hostSystemPrompt,
              makerMemoryIndex,
              botProfilePrompt: reviewMode ? undefined : opts.botProfilePrompt,
              botProfileContextPrompt:
                reviewMode ? undefined : opts.botProfileContextPrompt,
              botUserProfilePrompt: reviewMode ? undefined : opts.botUserProfilePrompt,
              userPrompt: reviewMode || opts.botRuntimeProfile ? undefined : opts.userPrompt,
              ...(hosted ? { deviceHostedNote: deviceHostedClaudeNote(hosted, opts.workingDir) } : {}),
            });
            return {
              type: 'preset' as const,
              preset: 'claude_code' as const,
              ...(appendText ? { append: appendText } : {}),
            };
          })(),
          ...(resumeSdkSid ? { resume: resumeSdkSid } : {}),
          ...(newSdkSessionId ? { sessionId: newSdkSessionId } : {}),
          // 设备托管:文件改在任务所在电脑上,Claude Code 的文件检查点看不到。
          enableFileCheckpointing: enableFileCheckpointing && !hosted,
          ...(finalResumeAt ? { resumeSessionAt: finalResumeAt } : {}),
          ...(finalFork ? { forkSession: true } : {}),
          env,
          ...(this.deps.registerLocalAgentProcess || this.deps.trackCcDebugFile
            ? {
                spawnClaudeCodeProcess: (spawnOptions) =>
                  spawnObservedClaudeProcess({
                    spawnOptions,
                    registerProcess: (pid) =>
                      this.deps.registerLocalAgentProcess?.({
                        pid,
                        kind: 'claude',
                        role: 'task-host',
                        sessionId: opts.sessionId ?? null,
                      }),
                    trackDebugFile: process.env.XDT_CC_DEBUG_NET === '1' && ccDebugFile
                      ? () => this.deps.trackCcDebugFile?.(ccDebugFile, opts.sessionId) ?? (() => {})
                      : undefined,
                    onStderr: vo.onStderrLine as ((line: string) => void) | undefined,
                  }),
              }
            : {}),
          // 订阅 token 到期续命回调 —— 仅当本次 spawn 实际注入了订阅 OAuth token
          // (oauth-spawn, 见 desktop auth-adapters getAuthEnv)且 host 实现了强刷时接线。
          // cc 侧 turn 中途 401 会发 oauth_token_refresh control 请求, SDK 调本回调向
          // host 要新 token (SDK 检测到回调存在时自动注入 CLAUDE_CODE_SDK_HAS_OAUTH_REFRESH=1
          // 告知 CLI)。gateway-key 模式 env 里没有 CLAUDE_CODE_OAUTH_TOKEN, 不接 —— 避免
          // API-key 401 被误引导去刷订阅 token。回调字段 SDK Options 类型未声明但运行时
          // 支持 (sdk.mjs oauth_token_refresh 分支), 经 spread 注入绕过 excess property 检查。
          // ⚠️ 本回调生效有两个前提, 缺一即静默失效: (a) SDK 注入的 SDK_HAS_OAUTH_REFRESH;
          // (b) CLAUDE_CODE_ENTRYPOINT 在 cc 的白名单内 —— 由 env-builder 在 oauth-spawn
          // 时强制设为 claude-desktop。cc 的 401 恢复有两条路: 先走本回调
          // (tengu_oauth_401_sdk_callback_refreshed), 回调超时/失败后还会直接重读系统
          // 凭证库兜底 (tengu_oauth_401_recovered_from_disk) —— host 刷新总是写回凭证库,
          // 所以即使回调超时返回 null, 第二条路仍能捡到新 token, 排障时两条都要看。
          ...(env.CLAUDE_CODE_OAUTH_TOKEN && this.deps.auth.getFreshSubscriptionToken
            ? {
                getOAuthToken: (): Promise<string | null> =>
                  this.refreshSubscriptionTokenInPlace(env),
              }
            : {}),
          // 第一方只读工具由 host 精确列名, 直接走 SDK public allowlist, 避免
          // permissionMode=auto 时再调用远程安全分类器。动态聚合入口不在列表中。
          ...(claudeAllowedTools ? { allowedTools: [...claudeAllowedTools] } : {}),
          canUseTool: sdkCanUseTool,
          // Bot MCP selection is explicit; native delegation remains available.
          // 设备托管:只用经隧道的 MCP(本机用户 / 项目里的 MCP 启动命令会在本机执行)。
          ...(opts.botRuntimeProfile || hosted || opts[LOCAL_AGENT_CLIENT] ? { strictMcpConfig: true } : {}),
          ...(opts[LOCAL_AGENT_CLIENT]?.hostToolsOnly ? { tools: [] } : {}),
          // 设备托管:自带文件与命令工具只能操作本机,关掉,由 cindy_exec 顶替;
          // 另含 host 路由表关闭的自带工具(见 claudeDisallowedTools)。
          ...(claudeDisallowedTools.length > 0
            ? { disallowedTools: [...claudeDisallowedTools] }
            : {}),
          // 受邀者(另一个账号):自带工具只开白名单里的,其余都作用于本机或本机用户的账号。
          ...(hosted?.guest && !opts[LOCAL_AGENT_CLIENT]?.hostToolsOnly
            ? { tools: [...DEVICE_HOSTED_GUEST_CLAUDE_TOOLS] } : {}),
          // 设备托管:个人配置(用户级设置、hooks)属于任务所在电脑,不加载本机用户级设置;
          // 项目级设置来自同步过来的影子目录(只保留权限规则)。
          settingSources: reviewMode || !!opts.botRuntimeProfile || opts[LOCAL_AGENT_CLIENT]?.hostToolsOnly
            ? []
            : hosted ? ['project', 'local'] : ['user', 'project', 'local'],
          // Settings (SDK "flag settings" 层, 优先级最高 — 覆盖 user/project/local 文件层):
          //  - showThinkingSummaries        : reasoning summary 展示开关
          //  - autoMemoryEnabled / autoDream: memory 联动 (host 通过 runtimeConfig.memoryEnabled 或
          //    BaseAgent.setMemory 控制; this.memoryOverride === undefined 时不传, 让 SDK 走默认)
          // **同一对象远端分支也透传 (extraOptions.settings)**, 别在两边漂移。
          settings: buildSettings(),
          allowDangerouslySkipPermissions:
            !reviewMode,
          stderr: vo.onStderrLine as ((line: string) => void) | undefined,
          // SDK debug 等同 --debug CLI flag, 让 cc 子进程吐 verbose 日志。
          // - debug: true 触发 verbose 模式
          // - debugFile (可选): 直接写到指定文件, 绕过 stderr 这条对 SEA 二进制不一定通的路
          // host 在开 debug 时通过 resolveCcDebugFile 把 debugFile 指到该 session 的
          // sessions/<id>/cc-debug.raw.log (见上 ccDebugFile); 没注入则回退全局
          // XDT_CC_DEBUG_FILE, 都没有就只开 debug:true 走 stderr 兜底。
          ...(process.env.XDT_CC_DEBUG_NET === '1'
            ? {
                debug: true,
                ...(ccDebugFile ? { debugFile: ccDebugFile } : {}),
              }
            : {}),
          ...(mcpServers ? { mcpServers } : {}),
          // Host hooks keep their normal behavior, while the harness adapter
          // prepends its narrow capability-route guard. Both run in-process
          // before Claude's permission mode (including Full access).
          ...(Object.keys(localClaudeHooks).length > 0
            ? { hooks: localClaudeHooks }
            : {}),
        },
      });
      let query: Query;
      try {
        companionEnvironment?.assertCurrent?.();
        if (managedPlugins && querySignal.aborted) throw new Error('Claude session closed before skill plugins were loaded');
        const queryArgs = createLocalQueryArgs();
        if (newSdkSessionId) sdkSessionId = newSdkSessionId;
        onRuntimeStartAttempted();
        query = sdkQuery(queryArgs);
      } catch (error) {
        if (sdkSessionId === newSdkSessionId) sdkSessionId = previousSdkSessionId;
        querySignal.removeEventListener('abort', releaseManagedPlugins);
        if (managedPlugins) await managedPlugins.dispose();
        throw error;
      }
      if (newSdkSessionId && finalFork && resumeSdkSid) {
        unacceptedForks.add(query);
      } else if (newSdkSessionId) {
        durableSdkSessionId = newSdkSessionId;
      }
      if (managedPlugins) {
        const closeQuery = query.close.bind(query);
        query.close = () => {
          try { return closeQuery(); }
          finally {
            querySignal.removeEventListener('abort', releaseManagedPlugins);
            releaseManagedPlugins();
          }
        };
      }
      if (sdkStartPermissionMode === 'auto') nativeAutoQueries.add(query);
      if (modelUsageCumulativeStartsAtZero) modelUsageStartsAtZeroQueries.add(query);
      if (nativeCliAuth && typeof query.applyFlagSettings === 'function') {
        // 切模型 / effort / fast 走 applyFlagSettings,CLI 会借机全量重读设置(不经 ConfigChange):
        // 先复查工作区,命中就结束会话而不是把设置应用进去。
        const applyFlagSettings = query.applyFlagSettings.bind(query);
        query.applyFlagSettings = async (settings) => {
          const override = await findWorkspaceSettingsOverride(opts.workingDir);
          if (override) {
            const message = workspaceSettingsOverrideMessage(override);
            taintWorkspaceSettings(message);
            throw new Error(message);
          }
          return applyFlagSettings(opts.fastModePolicy?.isAllowed() === false ? { ...settings, fastMode: false } : settings);
        };
      }
      if (newSdkSessionId && localQueryStarted && !unacceptedForks.has(query)) {
        publishedSdkSessionId = newSdkSessionId;
        eventQueue.push({ type: 'session_id', data: newSdkSessionId, source: 'claude-code' });
      }
      localQueryStarted = true;
      return query;
    };

    // ── 死 handle 终结器 —— U2 (远端 daemon 突死) 与 crash (SDK 流异常) 共用 ──
    // 底层 query 已死且不会有新 q 接管时, 必须执行等同 handle.close() 的全套副作用,
    // 否则 handle 对外装活: closed 不置位 → finally 不 end eventQueue → Session.runEventLoop
    // 挂着不退出 → session.ts 的自然结束兜底 setStatus('closed') 永不触发 → Maker
    // activeSessions 一直复用死 Session → 下次 send 把消息 push 进无消费者的 inputQueue,
    // 用户看到"排队但无运行态、无法停止"的黑洞会话 (2026-07-05 fork resume 失败实踩)。
    // closed=true 后 finally 的 eventQueue.end() 收尾 → Session 自动 close → 下次 send
    // 走 IPC lazy create-session 重建 handle。
    function teardownDeadHandle(logLabel: string): void {
      // Provider death is not a successful user cancellation. Session status
      // and the queued terminal error/done must decide observer settlement.
      resetClaudeGenerationTiming(runtimeState.generation);
      discardActiveContinuation(logLabel);
      turnInFlight = false;
      // handle 死透 → 后续没有排队 turn 可跑, counter 归零避免残留污染下一 handle 重建
      // (虽然 closed=true + inputQueue.end 已经让新消息进不来, 归零是防御性一致)
      clearBridgeState();
      pendingToolIds.clear();
      runningBackgroundTasks.clear();
      terminalBackgroundTaskIds.clear();
      closed = true;
      try { dismissAllPending('session_closed', 'deny'); } catch (e) {
        log.warn(`${logLabel}: dismissAllPending threw`, { error: String(e) });
      }
      try { inputQueue.end(); } catch (e) {
        log.warn(`${logLabel}: inputQueue.end threw`, { error: String(e) });
      }
      try { abortController.abort(); } catch (e) {
        log.warn(`${logLabel}: abortController.abort threw`, { error: String(e) });
      }
      // remoteQuery.close 是 async + 可能已经死了 (RpcClient closed), 调它会走
      // 兜底 catch (best-effort)。fire-and-forget 不 await — startForwardLoop
      // 里同步路径不能阻塞 finally。
      if (activeRemoteQuery) {
        void (activeRemoteQuery.detach ?? activeRemoteQuery.close)().catch((e) => {
          log.warn(`${logLabel}: remoteQuery.detach threw (best-effort)`, {
            error: String(e),
          });
        });
      }
    }

    let bridgeSuppressedDoneData: Record<string, unknown> | undefined;
    function clearBridgeState(): void {
      queuedBridgeTurns = 0;
      hostAutoCompactInFlight = false;
      activeBridgeKind = null;
      activeBridgeRewindResumeAt = undefined;
      bridgeCompactUsageSnapshot = null;
      bridgeSuppressedDoneData = undefined;
    }
    function takeBridgeSuppressedDoneData(): Record<string, unknown> | undefined {
      const data = bridgeSuppressedDoneData;
      bridgeSuppressedDoneData = undefined;
      return data;
    }
    function rememberBridgeSuppressedDoneData(data: unknown): void {
      if (!data || typeof data !== 'object' || Array.isArray(data)) return;
      bridgeSuppressedDoneData = { ...(data as Record<string, unknown>) };
    }

    function emitTurnBoundary(
      reason: string,
      doneData?: Record<string, unknown>,
      trackContinuationTerminal = false,
    ): boolean {
      eventQueue.push({
        type: 'status',
        data: { status: 'Done', ...usageTracker.snapshot(), isRunning: false },
        source: 'claude-code',
      });
      const doneEvent: AgentEvent = {
        type: 'done',
        data: { ...(doneData ?? {}), reason },
        source: 'claude-code',
      };
      if (trackContinuationTerminal) {
        continuationTerminalBoundaryEvents.add(doneEvent);
        pendingContinuationTerminalBoundaries += 1;
      }
      const accepted = eventQueue.push(doneEvent);
      if (trackContinuationTerminal) {
        if (!accepted) {
          continuationTerminalBoundaryEvents.delete(doneEvent);
          pendingContinuationTerminalBoundaries = Math.max(
            0,
            pendingContinuationTerminalBoundaries - 1,
          );
        }
      }
      return accepted;
    }

    const canceledBridgeQueries = new WeakSet<Query>();
    // RemoteQuery.close() is asynchronous. User Stop records the in-flight
    // close promise here so an immediate send/rewind can wait for the remote
    // session to become dead before creating its replacement Query.
    const canceledQueryClosePromises = new WeakMap<Query, Promise<void>>();
    function recordCanceledQueryClose(query: Query, reason: string): void {
      let closePromise: Promise<void>;
      try {
        closePromise = Promise.resolve(query.close());
      } catch (error) {
        log.warn(`${reason}: q.close threw`, { error: String(error) });
        closePromise = Promise.reject(error);
      }
      canceledQueryClosePromises.set(query, closePromise);
      // Attach a handler immediately so a remote close rejection cannot
      // become unhandled before rebuild awaits the recorded promise.
      void closePromise.catch((error) => {
        log.warn(`${reason}: q.close rejected`, { error: String(error) });
      });
    }
    // Despite the historical name, this per-query fence also marks an old
    // Query closed after user Stop cancels an awaiting continuation. Its
    // forward loop must silently discard any buffered tail until the next
    // fresh Query is installed.
    // Rewind commit 会 close 当前 Query,但它的 forward loop 可能晚于下一次 send 的
    // rebuild 完成才退出。pendingRewindTo 是共享状态,会在新 q 接管后清掉;旧 q 自身仍
    // 需要一个 per-query 标记,否则迟到的 stream_end/abort 会被误判为当前新 q 的崩溃。
    const rewindTransitionQueries = new WeakSet<Query>();

    // ── 后台任务追踪(用户 Stop 的确定性全停,2026-07-16 Lizi 拍板)──────────
    // 产品语义:用户点 Stop = 本会话所有模型调用停止,不允许残留。q.interrupt()
    // 只中断当前 turn;跨 turn 存活的后台 wake 任务(subagent / workflow)会继续
    // 调模型烧用量(2026-07-13 事故形态),abort 时必须逐个 q.stopTask()。
    // 数据源:translator 产出的 agent_task_update(running 进表 / 终态出表)。
    // taskType 只保证在 task_started 携带,后续 task_updated 补丁可能缺失 ——
    // 一旦见过 wake 型就锁存,补丁不会把 wake 降级。
    // 只停 wake 型(local_agent / local_workflow,与 renderer 折算口径一致):
    // local_bash 不调模型(dev server 等长驻进程不能被 Stop 误杀);remote_agent
    // 生命周期不在本进程。q.close() 会连 CLI 子进程一起杀(任务随之死亡),
    // 换代 / teardown / close 时清表。
    // 元数据(taskType / toolUseId / title / outputFile)与 wake 同口径锁存:task_started 全量携带,
    // 后续 task_updated 补丁可能缺失,补丁不得把已知字段冲掉 —— listBackgroundTasks
    // 快照(renderer 挂载/重载后重新水合任务卡)依赖这些字段还原展示。
    const runningBackgroundTasks = new Map<
      string,
      { wake: boolean; taskType?: string; toolUseId?: string; title?: string; outputFile?: string }
    >();
    // SDK task progress can race behind its terminal notification. Once a task
    // is terminal within the current Query generation, a late running/progress
    // patch must not resurrect it into runningBackgroundTasks and manufacture
    // a fresh continuation claim at the next done.
    const terminalBackgroundTaskIds = new Set<string>();
    const ignoredLateTerminalTaskEvents = new WeakSet<AgentEvent>();

    type ContinuationTaskState = 'running' | 'completed' | 'failed' | 'stopped';
    type ContinuationClaim = {
      id: number;
      tasks: Map<string, ContinuationTaskState>;
      state: 'awaiting' | 'active' | 'cancelled';
      /** Number of claim-bearing done events not yet processed by Session. */
      pendingBoundaryEvents: number;
      /** A later natural/synthetic done has closed the product turn. */
      settled: boolean;
      /** An async answer or waiting-turn steer accepted by the SDK input queue. */
      asyncAnswer?: boolean;
    };
    // Claims are created synchronously when the provider enqueues a `done`.
    // The id is attached to that exact event, so a fast task_notification or
    // result-only continuation cannot change what the host later observes.
    let nextContinuationId = 1;
    // Claude coalesces input queued before the next SDK segment into one turn.
    let queuedAsyncAnswer = false;
    let activeContinuationId: number | null = null;
    // User Stop can close an awaiting product continuation while the provider
    // still has buffered activity. Suppress that cancelled tail until its
    // Query is replaced before the next explicit user turn.
    let continuationCancellationGeneration: number | null = null;
    /**
     * 本次 Stop 已经发过终态 boundary 的那一代。
     *
     * accept 阶段的 foreground 终态归 send 的 finishSendBeforeUserInput 发, 但
     * abort 若同时取消了一个 awaiting continuation, 它已经先发过
     * turn_continuation_cancelled —— 同一次 Stop 再补一个 done 就是双终态,
     * Session 不按 generation 去重, 所有监听方都会收到两条。
     *
     * 单独记一个代次而不是复用 continuationCancellationGeneration: 后者在关
     * query 分支里**无条件**设置(哪怕那一轮根本没发 boundary), 拿它当去重依据
     * 会把 send 该发的那个终态一起吞掉。
     */
    let stopTerminalEmittedGeneration: number | null = null;
    let continuationCancellationRequiresQueryRebuild = false;
    // Wake 契约对账定时器:见 WAKE_CONTRACT_GRACE_MS。claim 激活 / 取消 / 结算 /
    // 丢弃 / query 换代时必须清掉,防止陈旧定时器误杀后继 claim。
    let wakeContractReconcileTimer: NodeJS.Timeout | null = null;
    const clearWakeContractReconciliation = (): void => {
      if (!wakeContractReconcileTimer) return;
      clearTimeout(wakeContractReconcileTimer);
      wakeContractReconcileTimer = null;
    };
    const continuationClaims = new Map<number, ContinuationClaim>();
    const continuationListeners = new Set<(
      continuationId: number,
      state: 'awaiting' | 'active' | 'cancelled',
    ) => void>();
    const emitContinuationState = (
      continuationId: number,
      state: 'awaiting' | 'active' | 'cancelled',
    ): void => {
      for (const listener of [...continuationListeners]) {
        try {
          listener(continuationId, state);
        } catch (e) {
          log.warn('turn continuation listener threw', { error: String(e) });
        }
      }
    };
    const activeContinuationClaim = (): ContinuationClaim | null =>
      activeContinuationId === null
        ? null
        : continuationClaims.get(activeContinuationId) ?? null;
    // A foreground result can leave the same product waiting on background work.
    // Its live SDK input queue still accepts corrections during that interval.
    const hasSteerableTurn = (): boolean =>
      !closed && !turnState.interruptRequested && continuationCancellationGeneration === null &&
      (turnInFlight || activeContinuationClaim()?.state === 'awaiting');
    const releaseSettledContinuationClaim = (claim: ContinuationClaim): void => {
      if (!claim.settled || claim.pendingBoundaryEvents > 0) return;
      continuationClaims.delete(claim.id);
    };
    const retireContinuationTasks = (claim: ContinuationClaim): void => {
      for (const taskId of claim.tasks.keys()) {
        runningBackgroundTasks.delete(taskId);
        terminalBackgroundTaskIds.add(taskId);
      }
    };
    const cancelActiveContinuation = (reason: string): ContinuationClaim | null => {
      queuedAsyncAnswer = false;
      const claim = activeContinuationClaim();
      if (!claim || claim.state !== 'awaiting') return null;
      claim.state = 'cancelled';
      claim.settled = true;
      activeContinuationId = null;
      clearWakeContractReconciliation();
      log.info('turn continuation cancelled', { reason, continuationId: claim.id });
      emitContinuationState(claim.id, 'cancelled');
      releaseSettledContinuationClaim(claim);
      return claim;
    };
    const settleActiveContinuation = (reason: string): void => {
      const claim = activeContinuationClaim();
      if (!claim || claim.state !== 'active') return;
      claim.settled = true;
      activeContinuationId = null;
      clearWakeContractReconciliation();
      log.info('turn continuation settled without a follow-up turn', {
        reason,
        continuationId: claim.id,
      });
      releaseSettledContinuationClaim(claim);
    };
    const discardActiveContinuation = (reason: string, forceRelease = false): void => {
      queuedAsyncAnswer = false;
      clearWakeContractReconciliation();
      if (continuationClaims.size > 0) {
        log.debug('discarding turn continuation claims', {
          reason,
          continuationIds: [...continuationClaims.keys()],
        });
      }
      activeContinuationId = null;
      for (const claim of continuationClaims.values()) {
        claim.settled = true;
        releaseSettledContinuationClaim(claim);
      }
      if (forceRelease) continuationClaims.clear();
    };
    const consumeTaskNotificationsForActiveSegment = (claim: ContinuationClaim): void => {
      // The SDK may merge several task notifications that arrived before the
      // first continuation activity into one automatic segment. Consume that
      // whole terminal snapshot at activation; notifications arriving after
      // the claim becomes active remain for the following segment.
      for (const [taskId, state] of claim.tasks) {
        if (state === 'completed' || state === 'failed') claim.tasks.delete(taskId);
      }
    };
    const captureContinuationBoundary = (event: AgentEvent): boolean => {
      if (event.type !== 'done') return false;
      const existing = activeContinuationClaim();
      const interruptedGeneration =
        turnState.interruptRequested &&
        turnState.interruptGeneration === turnState.generation;
      if (interruptedGeneration && existing?.state === 'awaiting') {
        // A real provider terminal can beat the interrupt ACK. It is the
        // product terminal for this Stop, so retire the snapshotted awaiting
        // claim instead of attaching it (or minting a successor) to this done.
        retireContinuationTasks(existing);
        existing.settled = true;
        activeContinuationId = null;
        releaseSettledContinuationClaim(existing);
        return true;
      }
      if (existing?.state === 'awaiting') {
        // Defensive duplicate done for the same boundary: preserve the same
        // claim instead of letting the duplicate terminate host observers.
        event.turnContinuationId = existing.id;
        existing.pendingBoundaryEvents += 1;
        return false;
      }
      const wasActiveContinuation = existing?.state === 'active';
      const carriedTasks = existing?.state === 'active'
        ? new Map(
            [...existing.tasks].filter(([, state]) => state !== 'stopped'),
          )
        : new Map<string, ContinuationTaskState>();
      if (existing?.state === 'active') {
        // This is the automatic continuation's own done. It closes the product
        // turn, so the old claim is no longer needed once its first done has
        // been observed by the host.
        existing.settled = true;
        activeContinuationId = null;
        releaseSettledContinuationClaim(existing);
        // The continuation turn may itself launch another wake task. Preserve
        // the original behavior by scanning the current task table below and
        // attaching a fresh claim to this done when another automatic turn is
        // now expected.
      }
      // A result produced by the generation being interrupted is already a
      // terminal boundary. Even if a wake task remains in the provider table,
      // user Stop has revoked the right to create another automatic segment.
      if (
        interruptedGeneration ||
        continuationCancellationGeneration === turnState.generation
      ) {
        queuedAsyncAnswer = false;
        if (interruptedGeneration && existing) retireContinuationTasks(existing);
        return wasActiveContinuation;
      }
      const wakeTasks = [...runningBackgroundTasks.entries()].filter(([, info]) => info.wake);
      for (const [taskId] of wakeTasks) {
        if (!carriedTasks.has(taskId)) carriedTasks.set(taskId, 'running');
      }
      const asyncAnswer = queuedAsyncAnswer;
      queuedAsyncAnswer = false;
      if (carriedTasks.size === 0 && !asyncAnswer) return wasActiveContinuation;
      const claim: ContinuationClaim = {
        id: nextContinuationId++,
        state: 'awaiting',
        tasks: carriedTasks,
        pendingBoundaryEvents: 1,
        settled: false,
        ...(asyncAnswer ? { asyncAnswer: true } : {}),
      };
      continuationClaims.set(claim.id, claim);
      activeContinuationId = claim.id;
      event.turnContinuationId = claim.id;
      // 从 active 前任 carry 出来的 completed/failed 任务可能已全部终态 —— 下一
      // 个 continuation 段同样受 wake 契约保护,创建即武装对账。
      armWakeContractReconciliation(claim);
      // 探针:claim 创建是「continuation 悬挂」vs「done 未到达」的关键区分点。
      // 只记 id / taskId / state 枚举,不记消息文本与 task prompt(脱敏红线)。
      log.info('turn continuation claim created', {
        continuationId: claim.id,
        carriedTasks: [...carriedTasks.entries()].map(([taskId, state]) => ({
          taskId,
          state,
        })),
        wasActiveContinuation,
      });
      return false;
    };
    const reconcileActiveContinuation = (): ContinuationClaim | null => {
      const claim = activeContinuationClaim();
      if (!claim || claim.state !== 'awaiting') return null;
      const states = [...claim.tasks.values()];
      // A completed/failed wake task still has the SDK continuation contract;
      // only an all-stopped group proves that a second `done` cannot arrive.
      // (All-terminal-but-not-stopped groups fall through here and rely on the
      // timed WAKE_CONTRACT_GRACE_MS reconciliation above: no continuation
      // activity within the grace window means the contract is broken.)
      // Authority model: q.interrupt ACK is required when user Stop has no
      // provider confirmation and must revoke a completed/failed continuation
      // contract itself. An all-stopped snapshot is already provider-confirmed
      // fact: every tracked task can no longer continue, while an awaiting
      // claim has no foreground turn. It therefore settles independently of a
      // concurrent interrupt resolving or rejecting; waiting for that control
      // result would leak the claim when no further provider event can exist.
      if (
        !claim.asyncAnswer &&
        states.length > 0 &&
        states.every((state) => state === 'stopped')
      ) {
        return cancelActiveContinuation('all wake tasks stopped');
      }
      return null;
    };
    const markWakeTasksStopped = (
      taskIds: readonly string[],
      reason: string,
    ): ContinuationClaim | null => {
      const claim = activeContinuationClaim();
      for (const taskId of taskIds) {
        const info = runningBackgroundTasks.get(taskId);
        const claimTracksWakeTask =
          (claim?.state === 'awaiting' || claim?.state === 'active') &&
          claim.tasks.has(taskId);
        if (!info?.wake && !claimTracksWakeTask) continue;
        runningBackgroundTasks.delete(taskId);
        terminalBackgroundTaskIds.add(taskId);
        if (claim?.state === 'awaiting' || claim?.state === 'active') {
          claim.tasks.set(taskId, 'stopped');
        }
      }
      const cancelledClaim = reconcileActiveContinuation();
      if (taskIds.length > 0) {
        log.info('marked wake tasks stopped before provider notification', { reason, taskIds });
      }
      return cancelledClaim;
    };
    function noteBackgroundTaskEvent(e: AgentEvent): ContinuationClaim | null {
      if (e.type !== 'agent_task_update') return null;
      const data = e.data as
        | {
            taskId?: unknown;
            status?: unknown;
            taskType?: unknown;
            parentToolUseId?: unknown;
            title?: unknown;
            outputFile?: unknown;
          }
        | null
        | undefined;
      const taskId = typeof data?.taskId === 'string' ? data.taskId : undefined;
      if (!taskId) return null;
      const status = data?.status;
      if (status === 'running') {
        if (continuationCancellationGeneration !== null) {
          log.debug('ignoring task activity after user-cancelled continuation', {
            taskId,
            cancellationGeneration: continuationCancellationGeneration,
          });
          ignoredLateTerminalTaskEvents.add(e);
          return null;
        }
        if (terminalBackgroundTaskIds.has(taskId)) {
          log.debug('ignoring late running update for terminal background task', { taskId });
          ignoredLateTerminalTaskEvents.add(e);
          return null;
        }
        const prev = runningBackgroundTasks.get(taskId);
        const wake =
          prev?.wake === true ||
          (typeof data?.taskType === 'string' && WAKE_BACKGROUND_TASK_TYPES.has(data.taskType));
        runningBackgroundTasks.set(taskId, {
          wake,
          taskType: typeof data?.taskType === 'string' && data.taskType ? data.taskType : prev?.taskType,
          toolUseId:
            typeof data?.parentToolUseId === 'string' && data.parentToolUseId
              ? data.parentToolUseId
              : prev?.toolUseId,
          title: typeof data?.title === 'string' && data.title ? data.title : prev?.title,
          outputFile:
            typeof data?.outputFile === 'string' && data.outputFile ? data.outputFile : prev?.outputFile,
        });
        const claim = activeContinuationClaim();
        if ((claim?.state === 'awaiting' || claim?.state === 'active') && wake) {
          claim.tasks.set(taskId, 'running');
        }
        return null;
      } else if (status === 'completed' || status === 'failed' || status === 'stopped') {
        const prev = runningBackgroundTasks.get(taskId);
        runningBackgroundTasks.delete(taskId);
        terminalBackgroundTaskIds.add(taskId);
        const claim = activeContinuationClaim();
        if (
          (claim?.state === 'awaiting' || claim?.state === 'active') &&
          (prev?.wake || claim.tasks.has(taskId))
        ) {
          claim.tasks.set(taskId, status);
          if (claim.state === 'awaiting') {
            const cancelledClaim = reconcileActiveContinuation();
            if (!cancelledClaim) armWakeContractReconciliation(claim);
            return cancelledClaim;
          }
        }
      }
      return null;
    }
    const emitCancelledContinuationBoundary = (
      claim: ContinuationClaim,
      reason: string,
    ): void => {
      log.info('emitting terminal boundary for cancelled turn continuation', {
        reason,
        continuationId: claim.id,
      });
      if (emitTurnBoundary('turn_continuation_cancelled', undefined, true)) {
        // 这一代的终态已经出去了 —— accept 阶段的 send 醒来后不要再补一个。
        stopTerminalEmittedGeneration = turnState.generation;
        // Install the cancelled-tail fence at the same enqueue boundary as
        // the synthetic product terminal. stopTask can win before interrupt
        // resolves, so waiting for the interrupt ACK leaves a double-terminal
        // window for a late provider result. A live Query that owns local_bash
        // is always retired by global Stop; the fence remains as a defensive
        // guard until the replacement Query is installed.
        continuationCancellationGeneration = turnState.generation;
        continuationCancellationRequiresQueryRebuild = true;
      }
    };
    const claimTasksAllTerminal = (claim: ContinuationClaim): boolean => {
      if (claim.tasks.size === 0) return claim.asyncAnswer === true;
      for (const state of claim.tasks.values()) {
        if (state === 'running') return false;
      }
      return true;
    };
    /**
     * Wake 契约对账:awaiting claim 的全部任务都到终态后,按 task_notification 续跑
     * 契约顶层 continuation 段应随即开始。起表等待 WAKE_CONTRACT_GRACE_MS,期间
     * claim 激活/结算/取消/换代都会清表;超时仍未激活即判定契约失守,走与用户 Stop
     * 相同的取消路径(合成 turn_continuation_cancelled 终态 + cancelled-tail fence),
     * 让宿主侧收口产品 turn,不再无限等待。
     */
    const armWakeContractReconciliation = (claim: ContinuationClaim): void => {
      if (claim.state !== 'awaiting' || !claimTasksAllTerminal(claim)) return;
      clearWakeContractReconciliation();
      wakeContractReconcileTimer = setTimeout(() => {
        wakeContractReconcileTimer = null;
        const current = activeContinuationClaim();
        if (
          !current ||
          current.id !== claim.id ||
          current.state !== 'awaiting' ||
          !claimTasksAllTerminal(current)
        ) {
          return;
        }
        log.info('wake contract unfulfilled: all wake tasks terminal without continuation activity', {
          continuationId: current.id,
          tasks: [...current.tasks.entries()],
        });
        cancelActiveContinuation('wake_contract_unfulfilled');
        emitCancelledContinuationBoundary(current, 'wake_contract_unfulfilled');
      }, WAKE_CONTRACT_GRACE_MS);
      (wakeContractReconcileTimer as unknown as { unref?: () => void }).unref?.();
    };

    const releaseEventAccounting = (event: AgentEvent): void => {
      if (event.turnContinuationId !== undefined) {
        const claim = continuationClaims.get(event.turnContinuationId);
        if (claim) {
          claim.pendingBoundaryEvents = Math.max(0, claim.pendingBoundaryEvents - 1);
          releaseSettledContinuationClaim(claim);
        }
      }
      if (continuationTerminalBoundaryEvents.delete(event)) {
        pendingContinuationTerminalBoundaries = Math.max(
          0,
          pendingContinuationTerminalBoundaries - 1,
        );
      }
    };
    const pushForwardedEvent = (event: AgentEvent): boolean => {
      const accepted = eventQueue.push(event);
      if (!accepted) releaseEventAccounting(event);
      return accepted;
    };

    const consumedEventStream = async function* (): AsyncGenerator<AgentEvent> {
      try {
        for await (const event of eventQueue) {
          try {
            yield event;
          } finally {
            // Code after yield runs when Session asks for the next event, i.e.
            // after its synchronous fan-out (including Hook/Scheduler queries).
            releaseEventAccounting(event);
          }
        }
      } finally {
        activeContinuationId = null;
        continuationClaims.clear();
        continuationListeners.clear();
        pendingContinuationTerminalBoundaries = 0;
        clearWakeContractReconciliation();
      }
    };
    // 逐个发起 stopTask,但不在这里等待 RPC:interrupt 必须先按控制通道顺序发出。
    // 返回每个 RPC 的 promise,供 interrupt ACK 后只退休真正成功的任务;失败任务
    // 仍留在本地账中,等待 provider 的真实 completed/stopped 事件继续记账。
    const runningWakeTaskIds = (): string[] =>
      [...runningBackgroundTasks.entries()]
        .filter(([, info]) => info.wake)
        .map(([taskId]) => taskId);

    function stopRunningWakeBackgroundTasks(
      reason: string,
    ): Array<{ taskId: string; promise: Promise<void> }> {
      if (runningBackgroundTasks.size === 0) return [];
      const wakeIds = runningWakeTaskIds();
      if (wakeIds.length === 0) return [];
      // 远端老 daemon / 老 SDK 没有 stopTask:退化为原行为(interrupt-only),
      // proxy 活动检测 + 「全部停止」兜底仍在。
      if (typeof q.stopTask !== 'function') {
        log.warn('stopTask unavailable on current query; background wake tasks left running', {
          reason,
          wakeIds,
        });
        return [];
      }
      log.info('stopping running background wake tasks', { reason, wakeIds });
      const requests: Array<{ taskId: string; promise: Promise<void> }> = [];
      for (const taskId of wakeIds) {
        let stopTaskPromise: Promise<void>;
        try {
          stopTaskPromise = Promise.resolve(q.stopTask(taskId));
        } catch (error) {
          stopTaskPromise = Promise.reject(error);
        }
        const promise = stopTaskPromise.then(
          () => {
            log.debug('background wake task stop acknowledged', {
              reason,
              taskId,
            });
          },
          (e: unknown) => {
            // 两类预期失败:任务恰好已自然结束;远端老 daemon 不认识 query/stopTask
            // (RemoteQuery 恒有本地方法,老 daemon 差异只会在这里以 RPC 错误暴露)。
            log.warn('stopTask failed (task already finished, or remote daemon predates query/stopTask)', {
              taskId,
              error: String(e),
            });
            throw e;
          },
        );
        // The rejection handler above preserves the rejected status needed by
        // Promise.allSettled, while this immediate noop handler prevents an
        // unhandled-rejection report before interrupt ACK attaches allSettled.
        void promise.catch(() => undefined);
        requests.push({ taskId, promise });
      }
      return requests;
    }

    async function settleWakeStopRequests(
      requests: Array<{ taskId: string; promise: Promise<void> }>,
    ): Promise<{ fulfilledWakeIds: string[]; rejectedWakeIds: string[] }> {
      const settled = await Promise.allSettled(requests.map(({ promise }) => promise));
      const fulfilledWakeIds: string[] = [];
      const rejectedWakeIds: string[] = [];
      requests.forEach(({ taskId }, index) => {
        if (settled[index]?.status === 'fulfilled') fulfilledWakeIds.push(taskId);
        else rejectedWakeIds.push(taskId);
      });
      return { fulfilledWakeIds, rejectedWakeIds };
    }

    async function waitForGracefulStopStep<T>(
      promise: Promise<T>,
      signal?: AbortSignal,
    ): Promise<T> {
      if (!signal) return promise;
      if (signal.aborted) throw new DOMException('aborted', 'AbortError');
      return new Promise<T>((resolve, reject) => {
        const onAbort = () => {
          cleanup();
          reject(new DOMException('aborted', 'AbortError'));
        };
        const cleanup = () => signal.removeEventListener('abort', onAbort);
        signal.addEventListener('abort', onAbort, { once: true });
        void promise.then(
          (value) => {
            cleanup();
            resolve(value);
          },
          (error) => {
            cleanup();
            reject(error);
          },
        );
      });
    }

    // ── Middle-turn 事件过滤 (Codex review 3534925347 / 3535259132 / 3535293200) ──
    // rewind rebuild 尾部注入的 /compact 是 SDK 独立 turn, 但从产品层看它是"用户 turn
    // 的一部分" (预压缩) — 该 turn 的 done / status(isRunning=false) 不能让 register.ts
    // 上层做 turn finalization (idle 调度 / turn 结束回写 / IM handleTurnDoneAsync /
    // snapshot 收尾), 否则用户回答会被上游当作"第二个 turn"。
    //
    // 判定用显式 `queuedBridgeTurns` 计数, 不用 `inputQueue.pending`:
    //  - pending 只反映 maker-core 侧未被消费者取走的 item 数, SDK 侧一旦拉走 pending 就
    //    归 0, 但对应 turn 可能还在 SDK 内部跑; 而且 send 中的 `await toClaudeSdkContent(...)`
    //    是几百 ms 的 async 空窗, /compact push 之后到 user message push 之前, pending 已经
    //    可能被 SDK drain 变 0 → 靠 pending 的判定会漏窗。
    //  - 显式计数在"push /compact"时 +1, 在对应 result 的 onTurnEnd 里 -1, 严格反映"还有
    //    多少已注入的桥接 turn 没跑完"。
    //
    // 只拦截 turn 边界事件 (done + isRunning=false 的 status + terminal error), 内容事件
    // (text / thinking / tool_use / running-status 等) 全部放行 — UI 看到就是一个连贯 turn。
    // 计数归 0 后真正的用户 turn 结束时事件正常放行, 下游做一次 finalization。
    //
    // Terminal error 也必须 suppress (Codex review 3535545481):
    //  bridge /compact turn 内部 SDK 失败 (API 错 / 上下文超限 / empty-response 等) 会走 is_error
    //  result → translator push `type:'error', isTerminal:true`。register.ts 上层拿 isTerminal
    //  做 turn finalization / abort 副作用, 泄漏出去会和 done 泄漏一样把用户消息当作"第二 turn"。
    //  UI 上损失一次错误提示可接受: 若 SDK 真死, 后续用户 turn 也会失败并走真正的错误路径;
    //  bridge 期间的 compact 失败静默恢复(warn 日志保留供排查)是最安全的语义。
    // CLI 的 missing-conversation 事故形态可能是「先给无详情 is_error result,紧接着
    // iterator 抛带详情的 exit error」。首个 resumed turn 对这种 result 暂存 50ms,
    // 给紧随其后的精确错误一个关联窗口;只延迟失败边界,不碰正常 token 热路径。
    const RESUME_ERROR_CORRELATION_MS = 50;
    let deferResumeFailureBoundary = false;
    let deferredResumeFailureEvents: AgentEvent[] = [];
    let deferredResumeTurnEnd = false;
    let deferredResumeFailureTimer: NodeJS.Timeout | null = null;
    function flushDeferredResumeFailure(): void {
      if (deferredResumeFailureTimer) {
        clearTimeout(deferredResumeFailureTimer);
        deferredResumeFailureTimer = null;
      }
      const events = deferredResumeFailureEvents;
      const shouldFinishTurn = deferredResumeTurnEnd;
      deferredResumeFailureEvents = [];
      deferredResumeTurnEnd = false;
      deferResumeFailureBoundary = false;
      for (const event of events) forwardEventSink.push(event);
      if (shouldFinishTurn) completeTranslatedTurnEnd();
    }
    function discardDeferredResumeFailure(): void {
      if (deferredResumeFailureTimer) {
        clearTimeout(deferredResumeFailureTimer);
        deferredResumeFailureTimer = null;
      }
      deferredResumeFailureEvents = [];
      deferredResumeTurnEnd = false;
      deferResumeFailureBoundary = false;
    }
    let pendingTerminalStatusEvent: AgentEvent | undefined;
    const forwardEventSink: AsyncQueue<AgentEvent> = {
      // Claude's translator emits `status(isRunning=false)` immediately before
      // the matching `done`. Hold that status long enough to copy the
      // provider continuation claim from `done`; otherwise every generic
      // consumer sees an unclaimed idle event and finalizes the product turn
      // before the continuation starts.
      push(e: AgentEvent) {
        if (deferResumeFailureBoundary) {
          deferredResumeFailureEvents.push(e);
          return true;
        }
        // 后台任务表旁路观察(O(1) type check,task 事件低频,不碰热路径逻辑)。
        const cancelledContinuation = noteBackgroundTaskEvent(e);
        if (ignoredLateTerminalTaskEvents.delete(e)) return true;
        if (e.type === 'error' && isTerminalAgentErrorEvent(e)) queuedAsyncAnswer = false;
        if (queuedBridgeTurns > 0) {
          if (e.type === 'done') {
            rememberBridgeSuppressedDoneData(e.data);
            log.debug('suppress middle-turn done event (bridge turn active)', {
              reason: (e.data as { reason?: unknown } | null | undefined)?.reason,
              queuedBridgeTurns,
            });
            return true;
          }
          if (e.type === 'status') {
            const running = (e.data as { isRunning?: unknown } | null | undefined)?.isRunning;
            if (running === false) {
              log.debug('suppress middle-turn end-status (bridge turn active)', {
                queuedBridgeTurns,
              });
              return true;
            }
          }
          if (e.type === 'error' && isTerminalAgentErrorEvent(e)) {
            log.warn('suppress middle-turn terminal error (bridge /compact turn failed, user turn will continue)', {
              reason: (e.data as { reason?: unknown } | null | undefined)?.reason,
              message: (e.data as { message?: unknown } | null | undefined)?.message,
              queuedBridgeTurns,
            });
            restoreBridgeAutoCompactSnapshot('bridge_compact_failed');
            const compactError =
              typeof (e.data as { message?: unknown }).message === 'string'
                ? (e.data as { message: string }).message
                : '';
            if (!opts.remoteHostId && isDeterministicHostCompactFailure(compactError)) {
              autoCompactController?.markNeedsRollover('bridge_compact_failed');
            } else {
              autoCompactController?.onCompactCanceled('bridge_compact_failed');
            }
            return true;
          }
        }
        if (hostAutoCompactInFlight && e.type === 'error' && isTerminalAgentErrorEvent(e)) {
          const compactError =
            typeof (e.data as { message?: unknown }).message === 'string'
              ? (e.data as { message: string }).message
              : '';
          log.warn('host auto-compact turn failed', {
            reason: (e.data as { reason?: unknown } | null | undefined)?.reason,
            message: compactError,
          });
          noteHostAutoCompactTerminalFailure(
            compactError || 'Error during compaction: unknown host auto-compact failure',
          );
        }
        if (e.type === 'status') {
          const data = e.data as { isRunning?: unknown } | null | undefined;
          if (data?.isRunning === false) {
            if (pendingTerminalStatusEvent) {
              pushForwardedEvent(pendingTerminalStatusEvent);
            }
            pendingTerminalStatusEvent = e;
            return true;
          }
        }
        if (e.type !== 'done' && pendingTerminalStatusEvent) {
          pushForwardedEvent(pendingTerminalStatusEvent);
          pendingTerminalStatusEvent = undefined;
        }
        const continuationBeforeCapture = activeContinuationClaim();
        const isContinuationTerminalDone = captureContinuationBoundary(e);
        const continuationAfterCapture = activeContinuationClaim();
        const createdContinuationClaim =
          e.type === 'done' &&
          e.turnContinuationId !== undefined &&
          continuationAfterCapture?.id === e.turnContinuationId &&
          continuationBeforeCapture?.id !== continuationAfterCapture.id
            ? continuationAfterCapture
            : null;
        if (e.type === 'done' && pendingTerminalStatusEvent) {
          const statusEvent = pendingTerminalStatusEvent;
          pendingTerminalStatusEvent = undefined;
          if (e.turnContinuationId !== undefined) {
            statusEvent.turnContinuationId = e.turnContinuationId;
            const claim = continuationClaims.get(e.turnContinuationId);
            if (claim) claim.pendingBoundaryEvents += 1;
          }
          pushForwardedEvent(statusEvent);
        }
        if (isContinuationTerminalDone) {
          continuationTerminalBoundaryEvents.add(e);
          pendingContinuationTerminalBoundaries += 1;
        }
        if (e.type === 'text' && turnInFlight && !turnState.interruptRequested) {
          const data = e.data as { text?: unknown; isFinal?: unknown } | undefined;
          const text = data?.text;
          const parent = e.agentMeta?.parentUuid;
          if (typeof text === 'string') {
            getToolLoopMonitor(typeof parent === 'string' && parent ? parent : undefined).onAssistantText(text, data?.isFinal === true);
          }
        }
        const accepted = pushForwardedEvent(e);
        if (!accepted && createdContinuationClaim) {
          // A claim minted for a boundary that the host can never observe has
          // no continuation contract. Retire it after rolling back the done's
          // own ledger entry; an accepted paired status keeps the claim object
          // alive only until that status is acknowledged.
          createdContinuationClaim.settled = true;
          if (activeContinuationId === createdContinuationClaim.id) {
            activeContinuationId = null;
          }
          releaseSettledContinuationClaim(createdContinuationClaim);
        }
        // A stopped notification is part of the visible turn history. Preserve
        // its order, then append a real product-turn boundary so Session can
        // close the current generation even though the SDK will not emit a
        // second result for a cancelled wake continuation.
        if (accepted && cancelledContinuation) {
          emitCancelledContinuationBoundary(cancelledContinuation, 'task_notification_stopped');
        }
        return accepted;
      },
      end: () => {
        if (pendingTerminalStatusEvent) {
          eventQueue.push(pendingTerminalStatusEvent);
          pendingTerminalStatusEvent = undefined;
        }
        eventQueue.end();
      },
      clear: () => {
        pendingTerminalStatusEvent = undefined;
        eventQueue.clear();
      },
      get pending() { return eventQueue.pending; },
      [Symbol.asyncIterator]: () => eventQueue[Symbol.asyncIterator](),
    };

    // ── 事件 forward loop(SDK 原始事件 → maker-core AgentEvent) ─────────────
    // (eventQueue 已在上方 canUseTool 段提前声明, 用于 emit interaction_dismissed)
    // !! 关键: 仅在 closed=true 时才 end eventQueue。rewind 路径下旧 q.close() 会让
    //         本 loop 退出, 但 eventQueue 不能关 —— 新 buildQuery 后还要继续 push 事件。
    //
    // 每条 SDK message 都通知 watchdog (受 pendingToolIds 守卫不起 timer 那段见上方注释)。
    const registerClaudeSubagentTask = this.deps.registerClaudeSubagentTask;
    const getClaudeSubagentTaskUsage = this.deps.getClaudeSubagentTaskUsage;
    function completeTranslatedTurnEnd(): void {
      pendingToolIds.clear();
      const endingHostAutoCompact = hostAutoCompactInFlight;
      hostAutoCompactInFlight = false;
      if (queuedBridgeTurns > 0) {
        queuedBridgeTurns -= 1;
        log.debug('onTurnEnd: consumed one bridge turn, keeping turnInFlight + plan state', {
          queuedBridgeTurns,
          planTurnActive,
          sdkInPlanMode,
        });
        armUpstreamResponseIdle();
        return;
      }
      resumeValidationPending = false;
      freshSessionValidationPending = false;
      replayableUserInput = null;
      if (planTurnActive) {
        planTurnActive = false;
        if (!mutablePlanMode) {
          sdkInPlanMode = false;
          void q.setPermissionMode(effectiveSdkPermissionMode()).catch((e) => {
            log.warn('plan turn end setPermissionMode failed', { error: String(e) });
          });
        }
      }
      turnInFlight = false;
      clearUpstreamResponseIdle();
      // 本轮已经是静默 /compact。瞬时失败由 onCompactCanceled 打开重试,等下一轮用户
      // turn 结束再压;这里立刻再注入会把 401/过载打成紧循环。
      if (!endingHostAutoCompact) triggerAutoCompactIfNeeded();
    }
    /** 工具循环判定成立(直接判定或复核 stop):推终态错误并中断当前 turn。 */
    function interruptForToolLoop(verdict: HardToolLoopVerdict, parentToolUseId?: string): void {
      const loopHint = verdict.reason === 'consecutive'
        ? `连续 ${verdict.count} 次发起完全相同的 ${verdict.toolName} 调用`
        : verdict.reason === 'contract'
          ? `连续 ${verdict.count} 次 ${verdict.toolName} 调用因同类参数错误`
            + `(${verdict.contractCategory ?? 'contract'})被拒`
          : `最近 ${verdict.count} 次工具调用一直在极少数几种(含 ${verdict.toolName})之间反复打转`;
      // 报错归属:sidechain 命中时报 subagent 实际模型,不冤枉会话模型。
      const loopModel = toolLoopGuardModelForScope(parentToolUseId);
      // 与 upstream-idle watchdog 同款兜底: tool-loop 中断 = "整个 turn 序列已死",
      // bridge counter 归零避免 filter 吞掉本条 error / counter 永久停在 >0。
      // 实践上 bridge /compact turn 不用 tool, 该分支难以触发, 归零是防御性一致。
      if (bridgeStateActive()) {
        const interruptedBridgeKind = activeBridgeKind;
        const interruptedRewindResumeAt = activeBridgeRewindResumeAt;
        log.warn('tool-loop hard interrupt fired during bridge — clearing bridge state', {
          queuedBridgeTurns,
          activeBridgeKind,
          activeBridgeRewindResumeAt,
        });
        restoreBridgeAutoCompactSnapshot('tool_loop_hard_interrupt');
        autoCompactController?.onCompactCanceled('tool_loop_hard_interrupt');
        clearBridgeState();
        preserveBridgeRetryTarget(interruptedBridgeKind, interruptedRewindResumeAt);
      }
      eventQueue.push({
        type: 'error',
        data: {
          message:
            `上游模型 ${loopModel} ${loopHint},疑似陷入死循环,` +
            `已自动中断当前 turn。可以直接发下一条消息继续,` +
            `已完成的 tool result 都保留。`,
          isTerminal: true,
          reason: 'tool_use_loop_detected',
          toolLoop: {
            kind: verdict.reason,
            count: verdict.count,
          },
          loopKind: verdict.reason,
          loopCount: verdict.count,
          model: loopModel,
        },
        source: 'claude-code',
      });
      turnInFlight = false;
      pendingToolIds.clear();
      // 复核 stop 晚于最后一个 tool_result 到达时,空闲看门狗可能已重新起表。
      clearUpstreamResponseIdle();
      // 上面已推过带 reason 的 terminal error, interrupt 后 SDK drain 出的
      // is_error result 不能再触发 translator 的失败兜底(双 error banner),
      // 与 watchdog / abort 的置位对齐。
      turnState.interruptRequested = true;
      turnState.interruptGeneration = turnState.generation;
      void q.interrupt().catch((e) => {
        // interrupt 失败 → 无 result 消费标记, 回收防误抑制(同 watchdog)。
        turnState.interruptRequested = false;
        log.warn('tool loop guard: interrupt threw', { error: String(e) });
      });
    }

    function startForwardLoop(currentQ: Query): void {
      // q 换代: 上一代 q 的 pending interrupted result 不可能从新 q drain 出来,
      // 残留的 interruptRequested 会错误抑制新 q 首个真实 is_error 终态 —— 兜底清。
      turnState.interruptRequested = false;
      continuationCancellationGeneration = null;
      // Any successfully installed replacement Query isolates the cancelled
      // provider tail. This also covers rewind / invalid-resume rebuilds, so a
      // later send must not create a redundant intermediate Query.
      continuationCancellationRequiresQueryRebuild = false;
      discardActiveContinuation('query_replaced');
      // q 换代 = 旧 CLI 子进程已死,其后台任务全部随之终止 —— 清表防 stale 条目
      // 让下次 abort 对不存在的任务空发 stopTask。
      runningBackgroundTasks.clear();
      terminalBackgroundTaskIds.clear();
      void (async () => {
        try {
          for await (const rawMsg of currentQ) {
            if (closed) break;
            const rawType = (rawMsg as { type?: string } | null)?.type;
            const rawSubtype = (rawMsg as { subtype?: string } | null)?.subtype;
            const rawStatus = (rawMsg as { status?: string } | null)?.status;
            // 只旁路取值,消息照常往下走(与改动前的处理顺序一致)。
            if (rawType === 'rate_limit_event' && nativeCliAuth) notifyRateLimitInfo(rawMsg);
            const isTerminalTaskNotification =
              rawType === 'system' &&
              rawSubtype === 'task_notification' &&
              (rawStatus === 'completed' || rawStatus === 'failed' || rawStatus === 'stopped');
            if (
              (canceledBridgeQueries.has(currentQ) || rewindTransitionQueries.has(currentQ)) &&
              !(canceledBridgeQueries.has(currentQ) && isTerminalTaskNotification)
            ) {
              continue;
            }
            if (activeBridgeKind !== null && queuedBridgeTurns === 0) {
              log.debug('bridge follow-up turn started — clearing bridge rewind resume point', {
                bridgeKind: activeBridgeKind,
                activeBridgeRewindResumeAt,
              });
              clearBridgeState();
            }
            if (
              continuationCancellationGeneration !== null &&
              (rawType === 'assistant' || rawType === 'stream_event' || rawType === 'result')
            ) {
              log.debug('ignoring provider activity from cancelled continuation query', {
                rawType,
                cancellationGeneration: continuationCancellationGeneration,
              });
              continue;
            }
            if (noteSdkInitMcpServerNames(rawMsg)) {
              // User/project/local settings MCPs are only revealed by the SDK init
              // payload, after the query has already started. Native OAuth Auto skips
              // canUseTool, so immediately hand later turns back to Cindy when that
              // payload reports any connected MCP server. Do this before the optional
              // provenance RPC below: a slow status call must not prolong native Auto.
              if (
                mutablePermissionMode === 'auto'
                && !mutablePlanMode
                && !planTurnActive
                && mutableAutoReviewCredentialMode === 'oauth-bearer'
                && !usesNativeClaudeAutoReview()
                && nativeAutoQueries.has(currentQ)
              ) {
                try {
                  await currentQ.setPermissionMode(effectiveSdkPermissionMode());
                  nativeAutoQueries.delete(currentQ);
                } catch (error) {
                  // Keeping this query alive would leave connected MCP tools under the
                  // native classifier, which bypasses Cindy's canUseTool policy. Close
                  // and surface a terminal stream failure instead of failing open.
                  log.error('failed to downgrade native Auto after SDK settings MCP init', {
                    error: String(error),
                  });
                  try {
                    await currentQ.close();
                  } catch (closeError) {
                    log.warn('failed to close query after native Auto downgrade failure', {
                      error: String(closeError),
                    });
                  }
                  throw new Error(
                    `[MCP_APPROVAL_MODE_DOWNGRADE_FAILED] ${
                      error instanceof Error ? error.message : String(error)
                    }`,
                  );
                }
              }
              await refreshSdkMcpProvenance(currentQ);
            }
            const expectedResumeSessionId = resumeValidationPending ? configuredResumeSessionId : undefined;
            const inBandInvalidConversationId =
              expectedResumeSessionId ?? (freshSessionValidationPending ? sdkSessionId : undefined);
            const rawRecord = rawMsg as { type?: unknown; is_error?: unknown; error?: unknown } | null;
            const isResumeErrorCandidate =
              (rawType === 'result' && rawRecord?.is_error === true) ||
              (rawType === 'assistant' && typeof rawRecord?.error === 'string');
            if (inBandInvalidConversationId && isResumeErrorCandidate &&
                isClaudeResumeSessionNotFound(rawMsg, inBandInvalidConversationId)) {
              if (await recoverInvalidResume(currentQ, inBandInvalidConversationId, rawMsg)) return;
              surfaceUnrecoverableInvalidResume(rawMsg);
              return;
            }
            if (deferredResumeFailureEvents.length > 0 || deferredResumeTurnEnd) {
              flushDeferredResumeFailure();
            }
            // 自动续跑 turn 的 in-flight 补登记:后台 subagent 完成后 SDK 经
            // task_notification 自动续跑新 turn,**不经过 handle.send**,turnInFlight
            // 停留在 false → isTurnRunning() 误报空闲,session.send 的 SESSION_RUNNING
            // 守卫失守(scheduler 心跳曾借此把 prompt 注入运行中的 turn)、tool-loop
            // guard / upstream-idle watchdog 也整段失效。这里以"turn 内才会出现的
            // 消息"(assistant / stream_event)为证据补登记;若 provider 已给上一
            // done 锁存 continuation claim,result-only 也能证明自动续 turn 已开始。
            // 随后镜像 send 入口的
            // per-turn 状态重置(beginNewTurn + resetToolLoopGuards),否则 guard
            // 会带着上一轮的陈旧计数误判。
            // 排除两种非新 turn 场景:
            //  - interruptRequested:watchdog / tool-loop 已 q.interrupt(),SDK 残留
            //    的 assistant 消息仍会 drain 到这里;此时 beginNewTurn 的 generation++
            //    会让 translator 把随后的 interrupted result 当作"已被新 send 接管"
            //    而吞掉终态,turn 永远收不了尾。
            //  - queuedBridgeTurns > 0:桥接 /compact 序列里 turnInFlight 本就被
            //    onTurnEnd 保持,不会走进本分支;计数守卫只是防御性一致。
            // 子 Agent 的 sidechain assistant/stream_event 也会穿过同一 Query,且
            // 常在它自己的 task_notification 之前到达。它只证明后台任务仍在跑,
            // 不能证明顶层自动 continuation 已开始;否则会过早把 awaiting claim
            // 转 active,随后同一任务的 completed 会被误当成“active 段期间完成的
            // 下一任务”,让第二个顶层 result 再铸造一个永远等不到后续活动的 claim。
            const rawParentToolUseId = (
              rawMsg as { parent_tool_use_id?: unknown } | null
            )?.parent_tool_use_id;
            const isTopLevelProviderActivity =
              typeof rawParentToolUseId !== 'string' || rawParentToolUseId.length === 0;
            if (
              !turnInFlight &&
              !turnState.interruptRequested &&
              queuedBridgeTurns === 0 &&
              (
                ((rawType === 'assistant' || rawType === 'stream_event') &&
                  isTopLevelProviderActivity) ||
                (activeContinuationClaim()?.state === 'awaiting' && rawType === 'result')
              )
            ) {
              const claim = activeContinuationClaim();
              if (claim?.state === 'awaiting') {
                // Each task notification queues one SDK continuation segment.
                // Consume only the notification that activated this segment;
                // other terminal tasks must keep the next boundary claimed.
                consumeTaskNotificationsForActiveSegment(claim);
                claim.state = 'active';
                emitContinuationState(claim.id, 'active');
                clearWakeContractReconciliation();
              }
              log.debug('SDK ▶ turn activity without send — marking auto-continued turn in-flight', {
                rawType,
                sdkSessionId,
              });
              beginNewTurn(mutableFastMode ? 'priority' : 'standard');
              resetToolLoopGuards();
              turnInFlight = true;
            }
            noteUpstreamResponseActivity(typeof rawType === 'string' ? rawType : 'unknown');
            const shouldCorrelateResumeFailure =
              rawType === 'result' && (rawMsg as { is_error?: unknown } | null)?.is_error === true &&
              (resumeValidationPending ||
                (freshSessionValidationPending && !!sdkSessionId && isClaudeResumeSessionNotFound(rawMsg, sdkSessionId)));
            if (shouldCorrelateResumeFailure) deferResumeFailureBoundary = true;
            translateSdkMessage(rawMsg, forwardEventSink, {
              rt: runtimeState,
              turn: turnState,
              log,
              getModel: () => mutableModel,
              getProviderId: () => mutableProviderId,
              getModelContextWindow: () => appliedContextWindow,
              getEffort: () => mutableEffort,
              getPermissionMode: () => mutablePermissionMode,
              getFastMode: () => mutableFastMode,
              getSdkSessionId: () => sdkSessionId,
              modelUsageCumulativeStartsAtZero: () =>
                modelUsageStartsAtZeroQueries.has(currentQ),
              getLogTitle: () => lastSendTitle,
              tracker: usageTracker,
              onSessionId: (sid) => {
                if (sid && unacceptedForks.has(currentQ)) {
                  sdkSessionId = sid;
                  return;
                }
                if (sid && sid !== publishedSdkSessionId) {
                  sdkSessionId = sid;
                  durableSdkSessionId = sid;
                  publishedSdkSessionId = sid;
                  eventQueue.push({ type: 'session_id', data: sid, source: 'claude-code' });
                }
              },
              onSubagentTaskLaunched: (task) => {
                registerClaudeSubagentTask?.(task);
              },
              getSubagentTaskUsage: (taskId) => {
                const usage = getClaudeSubagentTaskUsage?.(taskId);
                return usage ? { totalTokens: usage.totalTokens } : undefined;
              },
              onTurnEnd: () => {
                if (deferResumeFailureBoundary) {
                  deferredResumeTurnEnd = true;
                  return;
                }
                completeTranslatedTurnEnd();
              },
              onToolUseStart: (
                id: string,
                toolName?: unknown,
                input?: unknown,
                parentToolUseId?: string,
                inputStreaming?: boolean,
              ) => {
                getToolLoopMonitor(parentToolUseId).onToolUse(id, toolName, input);
                // content_block_start precedes input_json_delta: the model still
                // owns the response until the complete tool input is delivered.
                // canUseTool independently pauses the watchdog during approval.
                if (!inputStreaming) {
                  pendingToolIds.add(id);
                  clearUpstreamResponseIdle();
                }
              },
              onToolResultDone: (
                id: string,
                output: string,
                parentToolUseId?: string,
                isError?: boolean,
                toolResultBatchId?: string,
              ) => {
                pendingToolIds.delete(id);
                if (turnInFlight) {
                  const verdict = getToolLoopMonitor(parentToolUseId).onToolResult(
                    id,
                    output,
                    isError === true,
                    toolResultBatchId,
                  );
                  if (verdict.kind === 'hard') {
                    interruptForToolLoop(verdict, parentToolUseId);
                    return;
                  }
                }
                // 归零立即 arm: ball 回上游, 不等下一条 SDK message 起表 (会留 idle 窗口)。
                if (pendingToolIds.size === 0) armUpstreamResponseIdle();
              },
              ...(memoryFlushController || autoCompactController
                ? {
                    onUsageUpdate: (used, window) => {
                      memoryFlushController?.onUsageUpdate(used, window);
                      autoCompactController?.onUsageUpdate(used, window);
                    },
                    onCompactBoundary: () => {
                      hostAutoCompactInFlight = false;
                      memoryFlushController?.onCompactBoundary();
                      autoCompactController?.onCompactBoundary();
                    },
                  }
                : {}),
            });
            if (shouldCorrelateResumeFailure) {
              deferResumeFailureBoundary = false;
              deferredResumeFailureTimer = setTimeout(
                flushDeferredResumeFailure,
                RESUME_ERROR_CORRELATION_MS,
              );
            }
          }
          flushDeferredResumeFailure();
          log.debug('event loop done (stream_end)');
          if (closed) {
            eventQueue.push({ type: 'done', data: { reason: 'stream_end' }, source: 'claude-code' });
          } else if (pendingRewindTo || rewindTransitionQueries.has(currentQ) || canceledBridgeQueries.has(currentQ)) {
            // 非 closed 退出 = rewind/bridge cancel 期间旧 q 被 close, 不发 done (新 q 即将接管,
            // 或 bridge cancel 已由 abort/watchdog 直接推过 terminal 事件)。
            if (isCurrentQuery(currentQ) && queuedBridgeTurns > 0 && canceledBridgeQueries.has(currentQ)) {
              log.warn('event loop stream_end during canceled bridge — clearing bridge counter', {
                queuedBridgeTurns,
                pendingRewindTo,
                activeBridgeRewindResumeAt,
                rewindTransition: rewindTransitionQueries.has(currentQ),
                canceledBridge: canceledBridgeQueries.has(currentQ),
              });
              clearBridgeState();
            }
            if (isCurrentQuery(currentQ)) {
              pendingToolIds.clear();
            }
          } else if (activeBridgeKind !== null) {
            // Bridge /compact query 自发结束(非 Stop/watchdog 主动 close)说明底层 SDK
            // stream 已死;不能当 rewind transition 静默,否则 queuedBridgeTurns/turnInFlight
            // 会污染下一条真实用户 turn。
            log.warn('event loop ended unexpectedly during bridge turn');
            clearBridgeState();
            eventQueue.push({
              type: 'error',
              data: {
                message: 'Claude Code stream ended during bridge turn. Turn ended — please resend.',
                reason: 'bridge_stream_closed',
                isTerminal: true,
              },
              source: 'claude-code',
            });
            if (turnInFlight) {
              emitTurnBoundary('bridge_stream_closed');
            }
            teardownDeadHandle('bridge stream_end teardown');
          } else {
            // U2: stream 自然结束但 ClaudeCodeAgent 自己没主动 close, 也不是 rewind →
            // 远端 cc-mgr daemon 主动关 (用户点了升级 / daemon SIGTERM / 网络断 /
            // 用户手动 pkill daemon)。
            //
            // 之前只 push events + set closed, 但 inputQueue 没 end / abortController
            // 没 abort / remoteQuery 没 close —— forwarder loop (for await msg of
            // inputQueue) 还在跑, maker session.status 也保持 'active' (runEventLoop
            // 自然退出不切 status, 见 session.ts), 导致下次 user 发消息 maker 还
            // 复用老 Session → handle.send → inputQueue.push → forwarder 拿到后
            // 调死 remoteQuery.send 报 "RemoteQuery is closed" → 只 warn 吞掉 →
            // 用户看到"发了没反应"。
            //
            // 现在 U2 兜底等同 handle.close() 全套: end inputQueue + abort + close
            // 远端 query + dismiss pending interactions。U5a 在 session.ts 加了
            // runEventLoop 自然结束兜底 setStatus('closed'), 二者合起来让 maker
            // activeSessions 自动 delete, 下次 send 走 IPC lazy create-session
            // 重建新 handle / RemoteQuery / ssh channel。
            //
            // 本地 SDK Query 路径不会跑到这里 (本地 SDK iterator 正常结束必有 result
            // event, closed 才会主动 set; 本地无远端 SESSION_CLOSED 概念), 所以只
            // 影响远端 cc 场景, 不影响缓存率 / 性能 (规则 19)。
            log.warn('event loop ended unexpectedly (likely remote daemon shutdown)');
            eventQueue.push({
              type: 'error',
              data: {
                message: '[REMOTE_DAEMON_CLOSED] Remote connection interrupted (daemon may be upgrading/restarting). Turn ended — please resend.',
                reason: 'remote_daemon_closed',
              },
              source: 'claude-code',
            });
            eventQueue.push({ type: 'done', data: { reason: 'remote_daemon_closed' }, source: 'claude-code' });
            // 完整 close 副作用 — 跟 handle.close() 保持一致 (见 teardownDeadHandle 文档)。
            teardownDeadHandle('U2 fallback');
          }
        } catch (e) {
          // 三种 abort 路径都会让 for-await 抛 "Claude Code process aborted by user":
          //   ① handle.close() → closed=true        — push done + end queue
          //   ② commitRewindFiles → pendingRewindTo — 静音, 新 q 即将接管同一个 eventQueue
          //   ③ 真异常 (子进程崩 / SDK bug 等)       — push error 给 UI
          //
          // 注: upstream-response-idle watchdog 触发走的是 q.interrupt(), 不会让 for-await
          // 抛 abort — SDK 会继续 drain 出 ResultMessage(error_during_execution), 走正常
          // result 路径进 translator.onTurnEnd; 不在这里识别 watchdog 状态。
          const expectedResumeSessionId = resumeValidationPending ? configuredResumeSessionId : undefined;
          // fresh-session self-reference:全新会话(无 resume)首个 turn 在转录落盘前就崩,
          // CLI 会把 SDK 刚回填、已落库的 sdk_session_id 报成 "No conversation found"。此时
          // expectedResumeSessionId 为空,若不识别就会 surface 原始终态报错、并把这个幽灵 id
          // 留在库里,下一次 send resume 同一死会话反复失败(把 Codex 会话切成全新 Claude 会话
          // 即触发此路径)。只在首个 turn 尚未成功前兜底匹配自身 sdkSessionId,成功一轮后关
          // 闭窗口,避免已建立的会话中途丢失时被静默重建而丢上下文。
          const invalidConversationId =
            expectedResumeSessionId ??
            (freshSessionValidationPending ? sdkSessionId : undefined);
          if (!closed && invalidConversationId &&
              isClaudeResumeSessionNotFound(e, invalidConversationId)) {
            if (await recoverInvalidResume(currentQ, invalidConversationId, e)) return;
            surfaceUnrecoverableInvalidResume(e);
          } else if (closed) {
            flushDeferredResumeFailure();
            log.debug('event loop exited (closed)', { reason: String(e) });
          } else if (pendingRewindTo || rewindTransitionQueries.has(currentQ) || canceledBridgeQueries.has(currentQ)) {
            flushDeferredResumeFailure();
            log.debug('event loop exited (rewind/canceled bridge transition)', {
              reason: String(e),
              pendingRewindTo,
              activeBridgeRewindResumeAt,
              rewindTransition: rewindTransitionQueries.has(currentQ),
              canceledBridge: canceledBridgeQueries.has(currentQ),
            });
            if (isCurrentQuery(currentQ) && queuedBridgeTurns > 0 && canceledBridgeQueries.has(currentQ)) {
              log.warn('event loop exited during canceled bridge — clearing bridge counter', {
                queuedBridgeTurns,
                pendingRewindTo,
                activeBridgeRewindResumeAt,
                rewindTransition: rewindTransitionQueries.has(currentQ),
                canceledBridge: canceledBridgeQueries.has(currentQ),
              });
              clearBridgeState();
            }
            // rewind/bridge cancel 过渡: 老 q 留下的 pending tool_use_id 不能跨到新 q, 否则新 turn
            // 起来 armUpstreamResponseIdle 被旧 id 短路, watchdog 永久失效。
            if (isCurrentQuery(currentQ)) {
              pendingToolIds.clear();
            }
          } else if (activeBridgeKind !== null) {
            flushDeferredResumeFailure();
            log.error('event loop crashed during bridge turn', {
              error: String(e),
              activeBridgeRewindResumeAt,
              queuedBridgeTurns,
            });
            clearBridgeState();
            eventQueue.push({
              type: 'error',
              data: { message: String(e), isTerminal: true, reason: 'bridge_sdk_stream_crashed' },
              source: 'claude-code',
            });
            if (turnInFlight) {
              emitTurnBoundary('bridge_sdk_stream_crashed');
            }
            teardownDeadHandle('bridge crash teardown');
          } else {
            flushDeferredResumeFailure();
            // ③ 真异常: SDK 流抛错 = 底层 q 已死且没有新 q 接管。本地路径也会走到这里 ——
            // 典型: resume 失败时 CLI 先吐 is_error result 再以非零码退出, SDK readMessages
            // 把 exit error 替换成 "Claude Code returned an error result: ..." 抛进流里。
            // 此前只推 error + 清 turnInFlight, 不置 closed / 不 end inputQueue → handle
            // 对外装活, 下次 send 进无消费者的 inputQueue 黑洞 (2026-07-05 fork resume 实踩),
            // 现在与 U2 同款走 teardownDeadHandle 全套收尾。
            log.error('event loop crashed', { error: String(e) });
            // teardownDeadHandle 会清 turnInFlight, 先快照: turn 是否还没收尾
            // (translator 已 drain 过 result 正常收尾时为 false, 不重复补收尾事件)。
            const turnWasInFlight = turnInFlight;
            eventQueue.push({
              type: 'error',
              data: { message: String(e), isTerminal: true, reason: 'sdk_stream_crashed' },
              source: 'claude-code',
            });
            if (turnWasInFlight) {
              // turn 中途崩 (没有 result 走 translator 收尾) → 补齐与 translator 失败
              // 序列同构的收尾 (error → status Done → done), renderer 的 running 态和
              // main 的 turn 终止链路才能闭合。done 不带 usage 字段, 记账 sink 读不到
              // 数不会双计 (与 U2 的 done data 同款语义)。
              emitTurnBoundary('sdk_stream_crashed');
            }
            teardownDeadHandle('crash teardown');
          }
        } finally {
          if (closed || isCurrentQuery(currentQ)) {
            clearUpstreamResponseIdle();
            pendingToolIds.clear();
          }
          if (closed) eventQueue.end();
        }
      })();
    }

    async function clearInvalidResumeSession(
      expectedResumeSessionId: string,
      source: 'transcript_preflight' | 'sdk_runtime',
    ): Promise<boolean> {
      // Transferred history belongs to the host switch transaction. It must
      // choose/confirm fallback; the adapter cannot silently erase that history.
      if ((requireNativeResume && resumeValidationPending)
        || resumeRecoveryAttempted || !opts.onInvalidResumeSession) return false;
      try {
        const cleared = await opts.onInvalidResumeSession(expectedResumeSessionId);
        if (!cleared) {
          log.warn('invalid resume CAS did not match; refusing to overwrite concurrent session id', {
            expectedResumeSessionId, source,
          });
          return false;
        }
        resumeRecoveryAttempted = true;
        resumeValidationPending = false;
        freshSessionValidationPending = false;
        configuredResumeSessionId = undefined;
        sdkSessionId = undefined;
        durableSdkSessionId = undefined;
        log.warn('invalid resume id cleared; switching to a fresh Claude conversation', {
          expectedResumeSessionId, source,
        });
        return true;
      } catch (error) {
        log.error('invalid resume CAS failed', {
          expectedResumeSessionId, source,
          error: error instanceof Error ? error.message : String(error),
        });
        return false;
      }
    }
    async function recoverInvalidResume(
      currentQ: Query,
      expectedResumeSessionId: string,
      evidence: unknown,
    ): Promise<boolean> {
      // gate 必须在任何 await 之前装上:CAS(onInvalidResumeSession)可能很慢,期间新进入
      // 的 send 若不被拦在入口,消息会在 Session.send 的 onAccepted 持久化后撞进稍后的
      // 队列交替窗口(desktop 只对 SESSION_RUNNING 前缀 requeue → 已落库但从未送达)。
      // 两个分支都持有 gate 直到重建完成或放弃;所有出口 releaseGate。
      let releaseIdleResumeGate: (() => void) | undefined;
      idleResumeRebuildGate = new Promise<void>((resolve) => { releaseIdleResumeGate = resolve; });
      const releaseGate = (): void => {
        if (!releaseIdleResumeGate) return;
        idleResumeRebuildGate = null;
        releaseIdleResumeGate();
        releaseIdleResumeGate = undefined;
      };
      // 先停 deferred-failure 定时器,再进慢速 CAS:两步失败形态(先 is_error result 后精确
      // throw)下 50ms 计时器可能在 CAS await 期间先到,把本该被静默恢复吞掉的终态错误漏给
      // UI。CAS 失败放弃恢复时由 surfaceUnrecoverableInvalidResume 推全新终态错误,不丢反馈。
      discardDeferredResumeFailure();
      // 清失效 resume id 优先于一切:无论有没有可重放的 turn,不存在的 sdk_session_id
      // 都必须清掉,否则下一次 send 仍会 resume 同一个死会话反复失败。CAS 不匹配
      // (并发改了 id)才放弃并交回调用方 surface。
      if (!(await clearInvalidResumeSession(expectedResumeSessionId, 'sdk_runtime'))) {
        releaseGate();
        return false;
      }
      // replayableUserInput 为空 = resume 失败发生在任何用户 turn 之前(eager bootstrap /
      // 重启恢复 / agent 切换后的立即重建:CLI 在收到首条消息前就判定 resume 会话不存在)。
      // 此时没有任何 turn 会因此失败,surface 终态错误只会让用户看到一条无谓红条并被迫
      // 手动重试(切到 Claude 的偶发 "No conversation found" 即源于此)。与 spawn 前 'missing'
      // 预检同一取向:静默重建全新会话,让用户的首条真实消息直接在新会话上跑。
      const replayInput = replayableUserInput;
      log.warn(
        replayInput
          ? 'recovering invalid resume with one fresh retry'
          : 'recovering invalid resume before any user turn; rebuilding fresh idle session',
        {
          expectedResumeSessionId,
          evidence: evidence instanceof Error ? evidence.message : String(evidence),
        },
      );
      clearUpstreamResponseIdle();
      pendingToolIds.clear();
      // A fresh invalid-resume recovery must not inherit a half-consumed
      // compact bridge from the dead query. There is no rewind target to
      // preserve here: the replacement query intentionally starts fresh.
      restoreBridgeAutoCompactSnapshot('invalid_resume_recovery');
      autoCompactController?.onCompactCanceled('invalid_resume_recovery');
      clearBridgeState();
      try { inputQueue.end(); } catch (error) {
        log.debug('invalid resume recovery: old input queue end failed', { error: String(error) });
      }
      try { await Promise.resolve(currentQ.close()); } catch (error) {
        log.debug('invalid resume recovery: old query close failed', { error: String(error) });
      }
      if (closed) {
        // close 赢了竞态:handle.close 已 end 队列 / abort controller,这里不能再重建,
        // 否则会留下无 handle 管理的本地 CLI 进程或远端 cc-manager 会话(空耗 + 下次
        // attach 误连)。失效 id 已清,直接收手;forward loop 的 finally 会按 closed
        // end 掉 eventQueue。
        releaseGate();
        log.debug('invalid resume recovery aborted: handle closed while old query was closing');
        return true;
      }
      inputQueue = createAsyncQueue<SdkUserInput>();
      abortController = new AbortController();
      runtimeState.lastResultUsageAggregate = null;
      // 快照 rebuild 起点档位 — 与 rewind rebuild 同款:await buildQuery 期间到达的
      // runtime setter 会被 controlRequestsBlocked() 短路成只改闭包(远端分支的
      // remoteCcQueryFactory RPC 往返是真实窗口),重建后按快照 diff 回放漂移,
      // 避免新 query 带旧 model/flags 起跑而 handle getter 报新值。
      const runtimeSnapshot: QueryRuntimeSnapshot = {
        model: mutableModel,
        providerId: mutableProviderId,
        effort: mutableEffort,
        fastMode: mutableFastMode,
        sdkPermissionMode: currentTurnSdkPermissionMode(),
      };
      // 只有真正重放一个 turn 时才登记 turn 状态;idle 重建(无 replay)绝不能置
      // turnInFlight,否则 isTurnRunning() 会在没有 turn 运行时误报为忙。无 replay 的
      // 全新 query + startForwardLoop 等价于 startSession 首次起 q 的空闲态。
      if (replayInput) {
        beginNewTurn(runtimeSnapshot.fastMode ? 'priority' : 'standard');
        resetToolLoopGuards();
        turnInFlight = true;
      }
      try {
        q = await buildQuery({ permissionMode: runtimeSnapshot.sdkPermissionMode, fresh: true });
        if (closed) {
          // close 在 buildQuery 期间赢了竞态:teardown 只拆得到当时存在的 query,刚建的
          // 替换 query 必须在这里立即关掉,不 startForwardLoop。
          releaseGate();
          try { inputQueue.end(); } catch (endError) {
            log.debug('invalid resume recovery: replacement queue end after close failed', { error: String(endError) });
          }
          try { q.close(); } catch (closeError) {
            log.warn('invalid resume recovery: closing replacement query after handle close failed', { error: String(closeError) });
          }
          log.debug('invalid resume recovery aborted: handle closed during rebuild');
          return true;
        }
        startForwardLoop(q);
        await replayRuntimeDrift(runtimeSnapshot, 'invalid resume rebuild');
        releaseGate();
        if (replayInput) {
          if (!inputQueue.push(replayInput)) throw new Error('fresh retry input queue rejected replay');
          armUpstreamResponseIdle();
        }
        return true;
      } catch (error) {
        releaseGate();
        log.error('invalid resume fresh retry failed to start', {
          expectedResumeSessionId,
          error: error instanceof Error ? error.message : String(error),
        });
        eventQueue.push({
          type: 'error',
          data: {
            message: `Claude 会话已失效,自动创建新会话时失败:${error instanceof Error ? error.message : String(error)}`,
            isTerminal: true,
            reason: 'resume_session_recovery_failed',
          },
          source: 'claude-code',
        });
        if (turnInFlight) emitTurnBoundary('resume_session_recovery_failed');
        teardownDeadHandle('invalid resume recovery failed');
        return true;
      }
    }
    function surfaceUnrecoverableInvalidResume(evidence: unknown): void {
      discardDeferredResumeFailure();
      eventQueue.push({
        type: 'error',
        data: {
          message: evidence instanceof Error
            ? evidence.message
            : 'Claude 会话已失效,且本地会话 ID 已被并发更新,未执行自动覆盖。请重试。',
          isTerminal: true,
          reason: 'resume_session_not_found',
        },
        source: 'claude-code',
      });
      if (turnInFlight) emitTurnBoundary('resume_session_not_found');
      teardownDeadHandle('unrecoverable invalid resume');
    }

    // ── 首次起 q + 启动 forward loop ─────────────────────────────────────────
    q = await buildQuery();
    startForwardLoop(q);
    // Anthropic 清单动态发现:init 后 fire-and-forget 捕获 supportedModels(见文件顶注)。
    notifySupportedModels(q);

    // ── AgentSessionHandle 包装 ─────────────────────────────────────────────
    // Rewind rebuild 已创建新 q、但本次 send 尚未登记 turnInFlight / bridge state 的短窗口。
    // 这个窗口里的 runtime setter 只能更新闭包,不能直接写新 q:否则 plan arm / auto-compact
    // 可能污染当前正在接受的普通 send。send 登记 turn state 后再解除。
    let acceptingRebuiltSend = false;
    // invalid-resume 恢复期间的门禁(从 CAS 清 id 起、到重建完成或放弃为止):这段
    // 窗口里旧 inputQueue 会被 end、q 被替换,send 会把消息推进死队列或未连接的新队列。
    // 非 null = 恢复进行中。send / rewind 入口 await 它而不是抛错 —— Session.send 的
    // onAccepted 已持久化/ack 消息,抛普通 Error 会把瞬时重建变成孤儿用户消息(desktop
    // 只对 SESSION_RUNNING 前缀 requeue)。恢复结束(成功或失败)后 resolve 放行。
    let idleResumeRebuildGate: Promise<void> | null = null;
    // Idle-resume recovery and cancelled-continuation rebuilds have independent gates.
    let cancellationRebuildGate: Promise<void> | null = null;
    // runtime control request 可写性判定: commitRewindFiles 后旧 Query 已 close、新 Query
    // 等下一次 send 重建;或 bridge Stop/watchdog 已 close 当前 Query、等待下一次
    // send 从同一 rewind point 重建。这些窗口里对 q 发 control request 会抛
    // "ProcessTransport is not ready for writing"。
    //
    // 注意: activeBridgeRewindResumeAt **单独存在**不代表 q 不可写。正常 bridge
    // /compact 运行期间当前 Query 仍然活着,运行时设置必须继续发给 q,否则长 compact
    // 窗口里用户切模型/权限档只会改闭包,不会影响当前和后续 turn。只有当前 q 已被
    // 主动 close 并登记到 canceledBridgeQueries 时才阻塞 control request。
    const controlRequestsBlocked = (): boolean =>
      pendingRewindTo !== undefined ||
      acceptingRebuiltSend ||
      idleResumeRebuildGate !== null ||
      continuationCancellationRequiresQueryRebuild ||
      canceledBridgeQueries.has(q);
    type QueryRuntimeSnapshot = {
      model: string;
      providerId: string | null;
      effort: Effort;
      fastMode: boolean;
      sdkPermissionMode: SdkPermissionMode;
    };
    /**
     * 按目标路由收窄档位并写入当前 Query。effortLevel 是 sticky flag,且旧 runtime 拒绝
     * max 时实际生效的是回退档,与 mutableEffort 不一定相同;因此切模(含重建回放)后一律
     * 重下发,不按「新旧档位相同」跳过,否则上一个模型的 xhigh 会打给 GLM-5.3(1210,#5402)。
     */
    async function applyRouteEffort(model: string, effort: Effort, providerId: string | null): Promise<void> {
      const sdkEffort = getSdkEffortForModel(model, effort, providerId);
      if (!sdkEffort) return;
      const appliedEffort = await applyClaudeEffortFlagSettings(
        q, sdkEffort, getSdkMaxEffortFallbackForModel(model, providerId),
      );
      log.debug('applied route effort', { model, effort, sdk: appliedEffort, downgraded: appliedEffort !== sdkEffort });
    }
    async function replayRuntimeDrift(snapshot: QueryRuntimeSnapshot, label: string): Promise<void> {
      for (let pass = 0; pass < 5; pass += 1) {
        let replayed = false;
        if (mutableModel !== snapshot.model) {
          replayed = true;
          const targetModel = mutableModel;
          try {
            // 与 live setModel 同序:先扩白名单再切。buildQuery await 期间切到的
            // 目录外模型,新 Query 的启动名单还是旧快照,直接 setModel 会撞组织限制。
            await q.applyFlagSettings({
              availableModels: currentAvailableSdkModels(targetModel),
            });
            await q.setModel(sdkModelFor(targetModel));
            snapshot.model = targetModel;
            log.debug(`${label}: replayed setModel`, { model: targetModel });
            // 新 Query 的档位按旧模型构建;切模漂移时同 live setModel 一样按目标路由重下发。
            const targetEffort = mutableEffort;
            const targetProviderId = mutableProviderId;
            await applyRouteEffort(targetModel, targetEffort, targetProviderId);
            snapshot.effort = targetEffort;
            snapshot.providerId = targetProviderId;
          } catch (e) {
            log.warn(`${label}: replay setModel failed`, { error: String(e) });
          }
        }
        // 同一 model ID 换来源(受阻 setModel 只改 mutableProviderId)时档位能力也可能不同。
        if (mutableEffort !== snapshot.effort || mutableProviderId !== snapshot.providerId) {
          replayed = true;
          const targetEffort = mutableEffort;
          const targetProviderId = mutableProviderId;
          try {
            await applyRouteEffort(mutableModel, targetEffort, targetProviderId);
            log.debug(`${label}: replayed setEffort`, { effort: targetEffort });
          } catch (e) {
            log.warn(`${label}: replay setEffort failed`, { error: String(e) });
          }
          snapshot.effort = targetEffort;
          snapshot.providerId = targetProviderId;
        }
        if (mutableFastMode !== snapshot.fastMode) {
          replayed = true;
          const targetFastMode = mutableFastMode;
          try {
            await q.applyFlagSettings({ fastMode: targetFastMode });
            log.debug(`${label}: replayed setFastMode`, { fastMode: targetFastMode });
          } catch (e) {
            log.warn(`${label}: replay setFastMode failed`, { error: String(e) });
          }
          snapshot.fastMode = targetFastMode;
        }
        const sdkMode = currentTurnSdkPermissionMode();
        if (sdkMode !== snapshot.sdkPermissionMode) {
          replayed = true;
          const targetSdkMode = sdkMode;
          try {
            await q.setPermissionMode(targetSdkMode);
            sdkInPlanMode = targetSdkMode === 'plan';
            snapshot.sdkPermissionMode = targetSdkMode;
            log.debug(`${label}: replayed setPermissionMode`, { sdkMode: targetSdkMode });
          } catch (e) {
            log.warn(`${label}: replay setPermissionMode failed`, { error: String(e) });
          }
        }
        if (!replayed) return;
      }
      log.warn(`${label}: runtime drift kept changing while replaying; leaving remaining drift to the next setter/rebuild`);
    }
    async function rebuildCancelledContinuationQuery(
      signal?: AbortSignal,
      options?: { queueCompactBridge?: boolean },
    ): Promise<boolean> {
      while (cancellationRebuildGate) {
        await cancellationRebuildGate;
      }
      if (!continuationCancellationRequiresQueryRebuild) return false;

      let releaseCancellationRebuildGate: (() => void) | undefined;
      cancellationRebuildGate = new Promise<void>((resolve) => {
        releaseCancellationRebuildGate = resolve;
      });
      try {
        const staleQuery = q;
        const runtimeSnapshot: QueryRuntimeSnapshot = {
          model: mutableModel,
          providerId: mutableProviderId,
          effort: mutableEffort,
          fastMode: mutableFastMode,
          sdkPermissionMode: currentTurnSdkPermissionMode(),
        };
        acceptingRebuiltSend = true;
        inputQueue.end();
        inputQueue = createAsyncQueue<SdkUserInput>();
        abortController = new AbortController();
        runtimeState.lastResultUsageAggregate = null;
        rewindTransitionQueries.add(staleQuery);
        const recordedClose = canceledQueryClosePromises.get(staleQuery);
        if (recordedClose) {
          try {
            await recordedClose;
          } catch (error) {
            log.warn('cancelled continuation query close rejected before rebuild', { error: String(error) });
          }
        } else {
          try {
            await Promise.resolve(staleQuery.close());
          } catch (e) {
            log.warn('cancelled continuation query close threw before rebuild', { error: String(e) });
          }
        }
        try {
          q = await buildQuery({
            permissionMode: runtimeSnapshot.sdkPermissionMode,
            fresh: true,
          });
          if (signal?.aborted) {
            inputQueue.end();
            rewindTransitionQueries.add(q);
            try {
              await Promise.resolve(q.close());
            } catch (e) {
              log.warn('cancelled continuation rebuild close threw after send cancellation', {
                error: String(e),
              });
            }
            throw new Error('Claude send cancelled before acceptance');
          }
          startForwardLoop(q);
          notifySupportedModels(q);
          await replayRuntimeDrift(runtimeSnapshot, 'cancelled continuation rebuild');
          // Cancellation rebuilds used by send need the compact→user bridge for deferred
          // model/window drift. Rewind preview/commit use the same fresh-query isolation but
          // must not start a product turn or inject /compact before rewindFiles runs.
          const skipCompactBridge = options?.queueCompactBridge === false;
          const bridgeCompactQueued = skipCompactBridge
            ? false
            : queueAutoCompactBridge('cancellation');
          // Preview/commit must not generate, but a deferred compact caused by a
          // blocked model/window switch must survive until the next send. Keep
          // the tombstone only for that case; otherwise the fresh Query is ready
          // and the cancellation rebuild state can be cleared normally.
          continuationCancellationRequiresQueryRebuild = skipCompactBridge
            ? shouldRearmAutoCompactAfterRewindControl()
            : false;
          return bridgeCompactQueued;
        } finally {
          acceptingRebuiltSend = false;
        }
      } finally {
        cancellationRebuildGate = null;
        releaseCancellationRebuildGate?.();
      }
    }
    const warnIfRemoteDesktopAttachment = (content: UserMessage['content']): void => {
      if (!opts.remoteHostId || !Array.isArray(content)) return;
      const hasDesktopLocalAttachment = content.some(
        (block) => block.type === 'file'
          || block.type === 'mention'
          || (block.type === 'image' && block.pathOrigin === 'desktop-host'),
      );
      if (!hasDesktopLocalAttachment) return;
      log.warn('cc remote: local attachment not accessible on remote session', {
        sessionId: opts.sessionId,
        hostId: opts.remoteHostId,
      });
      eventQueue.push({
        type: 'error',
        data: {
          message: '[REMOTE_LOCAL_ATTACHMENT_UNSUPPORTED] Local file attachments are not accessible on remote sessions. Paste content directly instead.',
          isTerminal: false,
        },
        source: 'claude-code',
      });
    };
    const handle: AgentSessionHandle = {
      disabledSkillPaths: disabledSkillSnapshot,
      // IM turn policies carry requester authority the native classifier cannot see.
      getAutoReviewOwner: () => usesNativeClaudeAutoReview() && !activeTurnPermissionPolicy ? 'native' : 'cindy',
      reviewAutoPermissionAction: async (action) => {
        const decision = await reviewAutoAction(
          action,
          [opts.workingDir, ...mutableExtraDirs, ...mutableWritableDirs],
          [opts.workingDir, ...mutableWritableDirs],
          opts.remoteHostId ? 'linux' : process.platform,
        );
        if (decision.unavailable) autoReviewUnavailableNotice.notify();
        return decision;
      },
      get id() { return durableSdkSessionId ?? '<pending>'; },
      get requestSessionId() { return sdkSessionId ?? '<pending>'; },
      agentKind: 'claude-code',
      get model() { return mutableModel; },

      validateSendOptions(sendOpts: SendOptions) {
        if (sendOpts.toolsDisabled && opts.remoteHostId) {
          throw new Error('Host text-only turns require a local Claude runtime with execution hooks.');
        }
        if (
          sendOpts.turnPermissionPolicy &&
          (mutablePermissionMode === 'acceptEdits' ||
            mutablePermissionMode === 'bypassPermissions')
        ) {
          throw new TurnPermissionPolicyUnsupportedError(
            'claude-code',
            mutablePermissionMode,
          );
        }
      },

      async send(message: UserMessage, sendOpts?: SendOptions) {
        // idle resume fallback 正在重建(亚秒窗):等它完成再走正常受理。重建成功时
        // 消息透明跑在新会话上;重建失败/close 竞态时 push 撞上已 end 的队列,由下方
        // userInputAccepted 兜底干净收尾。不抛错 —— 见 idleResumeRebuildGate 声明处。
        while (idleResumeRebuildGate) {
          await idleResumeRebuildGate;
        }
        if (
          activeQueryDirectoryGeneration !== autoReviewDirectoryGeneration
          && !pendingRewindTo
          && !activeBridgeRewindResumeAt
          && durableSdkSessionId
        ) {
          pendingRewindTo = durableSdkSessionId;
          extraDirsRebuildAttempted = true;
        } else if (
          activeQueryExploreInheritCapGeneration !== exploreInheritCapEnvGeneration
          && !pendingRewindTo
          && !activeBridgeRewindResumeAt
          && durableSdkSessionId
        ) {
          pendingRewindTo = durableSdkSessionId;
        } else if (
          extraDirsCopyFallbackEnabled
          && extraDirsRebuildAttempted
          && activeQueryDirectoryGeneration !== autoReviewDirectoryGeneration
        ) {
          log.warn('Claude extraDirs copy fallback is gated off; resume+fork rebuild remains the only path');
        }
        if (sendOpts?.signal?.aborted) {
          throw new Error('Claude send cancelled before acceptance');
        }
        if (sendOpts) handle.validateSendOptions?.(sendOpts);
        let bridgeCompactQueued = false;
        // 保持普通 send / rewind send 原有的同步前置语义:即使 async helper 立即
        // return,裸 await 也会让出一个 microtask,导致调用方在 Query rebuild 真正
        // 开始前观察到半初始化窗口。只有确实存在 cancellation tombstone 时才进入
        // 异步重建。
        if (
          continuationCancellationRequiresQueryRebuild &&
          pendingRewindTo === undefined &&
          activeBridgeRewindResumeAt === undefined
        ) {
          bridgeCompactQueued = await rebuildCancelledContinuationQuery(sendOpts?.signal);
        }
        const nextToolsDisabled = sendOpts?.toolsDisabled === true;
        if (turnInFlight && activeToolsDisabled !== nextToolsDisabled) {
          throw new Error('Cannot change the tool policy while a Claude turn is active.');
        }
        activeTurnPermissionPolicy = sendOpts?.turnPermissionPolicy ?? null;
        activeToolsDisabled = nextToolsDisabled;
        // 仅用于诊断日志: 调用方每次 send 都可以带 logTitle (取自 storage 的最新值);
        // 缺省时保留上一次的值 (没传不等于"清空")。
        if (sendOpts?.logTitle !== undefined) lastSendTitle = sendOpts.logTitle;
        // 计划模式一次性语义: send 消耗武装态 → 本轮 plan turn 开始(SDK 已在 plan 档),
        // UI 勾选立即熄灭(host 收 plan_mode_changed 持久化 false + 广播)。
        // 若上一轮 planTurnActive 异常残留(事件循环崩溃没走 onTurnEnd), 这里先收尾。
        if (planTurnActive) {
          planTurnActive = false;
          if (!mutablePlanMode) {
            sdkInPlanMode = false;
            // rewind 窗口期旧 q 不可写, 跳过 — 档位由下方重建的 buildQuery 决定。
            if (!controlRequestsBlocked()) {
              void q.setPermissionMode(effectiveSdkPermissionMode()).catch((e) => {
                log.warn('stale plan turn cleanup setPermissionMode failed', { error: String(e) });
              });
            }
          }
        }
        // 本条消息的计划意图:sendOpts.planMode 是点击发送瞬间的快照(排队行透传),
        // 对已存活会话是权威;undefined 走旧语义(消耗当前武装态)。见 SendOptions.planMode。
        const requestedPlanTurn = sendOpts?.planMode ?? mutablePlanMode;
        if (requestedPlanTurn) {
          planTurnActive = true;
          if (mutablePlanMode && sendOpts?.planMode !== false) {
            mutablePlanMode = false;
            eventQueue.push({ type: 'plan_mode_changed', data: { enabled: false }, source: 'claude-code' });
          }
          // 武装发生在上一 turn 流式中(setPlanMode 递延了 SDK 切档)或该行意图来自
          // 排队快照(武装态已被改走) → 此刻补推。失败降级为普通 turn(warn 留痕)。
          // control request 被阻塞时旧 q 已 close, 跳过补推 — 下方重建的 buildQuery 会以
          // effectiveSdkPermissionMode()(planTurnActive 已置 true → 'plan') 起档。
          if (!sdkInPlanMode && !controlRequestsBlocked()) {
            try {
              await q.setPermissionMode('plan');
              sdkInPlanMode = true;
            } catch (e) {
              log.warn('deferred plan-mode SDK switch failed — sending as a normal turn', { error: String(e) });
            }
          }
        } else if (sdkInPlanMode) {
          // 显式普通消息(排队快照 false)但 SDK 还停在 plan 档(idle 武装时推过):
          // 本 turn 需要底层档;武装态保留给未来消息(下次消耗时经 !sdkInPlanMode 补推)。
          // control request 被阻塞时同上: 只改本地标记, 档位由重建的 buildQuery 决定。
          sdkInPlanMode = false;
          if (!controlRequestsBlocked()) {
            try {
              await q.setPermissionMode(toSdkPermissionMode(mutablePermissionMode));
            } catch (e) {
              log.warn('plan-armed SDK downgrade for explicit normal turn failed', { error: String(e) });
            }
          }
        }
        // turn 入口先打一行参数快照, 让日志能从一句 "send" 看清这轮是用哪个 model/effort/mode 跑的;
        // 不打消息全文 (Session.send 已经打过 summary 了, 这里只补 runtime params)
        log.debug('send ▶ user message', {
          model: mutableModel,
          effort: mutableEffort,
          permissionMode: mutablePermissionMode,
          sdkSessionId,
          logTitle: lastSendTitle,
          pendingRewindTo: pendingRewindTo ?? '<none>',
          activeBridgeRewindResumeAt: activeBridgeRewindResumeAt ?? '<none>',
        });

        // ── Rewind 三件套重启 ──────────────────────────────────────────────
        // commitRewindFiles 只设标记, 真正的 SDK Query 重起延迟到这里 —— 老 agentManager
        // 同款设计 (CLI 拿到 input 才会发 init, 避免"无 input → 30s timeout"死锁)。
        let runtimeReplaySnapshot: QueryRuntimeSnapshot | undefined;
        let rollbackUnacceptedFork: (() => void) | undefined;
        const finishSendBeforeUserInput = (reason: string, error?: unknown): void => {
          if (
            bridgeCompactQueued &&
            !canceledBridgeQueries.has(q) &&
            bridgeStateActive()
          ) {
            log.warn('send failed after bridge /compact injection — canceling bridge query and preserving rewind resume point', {
              error: error === undefined ? undefined : String(error),
              queuedBridgeTurns,
              activeBridgeRewindResumeAt,
            });
            const abandonedBridgeKind = activeBridgeKind;
            const abandonedRewindResumeAt = activeBridgeRewindResumeAt;
            restoreBridgeAutoCompactSnapshot('bridge_send_abandoned');
            autoCompactController?.onCompactCanceled('bridge_send_abandoned');
            const suppressedDoneData = takeBridgeSuppressedDoneData();
            clearBridgeState();
            inputQueue.clear();
            try {
              inputQueue.end();
            } catch (endError) {
              log.warn('send failed after bridge /compact injection: inputQueue.end threw', { error: String(endError) });
            }
            canceledBridgeQueries.add(q);
            recordCanceledQueryClose(q, 'bridge send abandoned');
            turnInFlight = false;
            sendInAcceptPhase = false;
            turnState.interruptRequested = false;
            pendingToolIds.clear();
            acceptingRebuiltSend = false;
            preserveBridgeRetryTarget(abandonedBridgeKind, abandonedRewindResumeAt);
            emitTurnBoundary('bridge_send_abandoned', suppressedDoneData);
            rollbackUnacceptedFork?.();
            return;
          }
          if (!turnInFlight) {
            rollbackUnacceptedFork?.();
            return;
          }
          log.debug('send cancelled before user input was accepted — closing synthetic turn', {
            reason,
            error: error === undefined ? undefined : String(error),
          });
          turnInFlight = false;
          sendInAcceptPhase = false;
          turnState.interruptRequested = false;
          pendingToolIds.clear();
          acceptingRebuiltSend = false;
          clearUpstreamResponseIdle();
          // 同一次 Stop 只发一个终态: abort 若已为被取消的 continuation 发过
          // turn_continuation_cancelled(同一代), 这里只清状态、不再补 done。
          if (stopTerminalEmittedGeneration !== turnState.generation) {
            emitTurnBoundary(reason);
          }
          rollbackUnacceptedFork?.();
        };
        if (pendingRewindTo || activeBridgeRewindResumeAt) {
          const resumeAt = pendingRewindTo ?? activeBridgeRewindResumeAt;
          if (!resumeAt) {
            throw new Error('Claude rewind rebuild missing resume target');
          }
          const directoryGrantRebuild = pendingRewindTo === durableSdkSessionId;
          log.debug('send ▶ pendingRewindTo detected — rebuilding sdkQuery with 三件套', {
            resumeSessionAt: directoryGrantRebuild ? undefined : resumeAt,
            resumeSdkSid: durableSdkSessionId,
            directoryGrantRebuild,
          });
          // 关键: 重建 abortController + inputQueue。老的两个在 q.close() 时已经污染
          // (controller 进 aborted 状态, queue 的 generator 还在等 waiter), 复用会让
          // 新 sdkQuery 立刻报 aborted 或抢不到新 push 的消息。先 end 老 queue 让老
          // generator 退出, 再整体换新。
          inputQueue.end();
          inputQueue = createAsyncQueue<SdkUserInput>();
          abortController = new AbortController();
          // QueryEngine 的 result.usage 是单个 SDK query 内的累计值。rewind 会重建
          // query 并从 0 重新累计, 因此必须清掉旧 query 的 aggregate 基线。
          runtimeState.lastResultUsageAggregate = null;
          // 快照 rebuild 起点的运行时档位 — buildQuery 的同步头部读的就是此刻的
          // 闭包值; await 期间若有切换到达(被 controlRequestsBlocked() 短路成"只更新闭包"),
          // 下方 diff 重放据此识别漂移项。
          const snapModel = mutableModel;
          const snapProviderId = mutableProviderId;
          const snapEffort = mutableEffort;
          const snapFastMode = mutableFastMode;
          // 用 turn-scoped 档快照 (planTurnActive + mutablePermissionMode), 不含 mutablePlanMode
          // arm 态。await buildQuery 期间到达的 setPlanMode(arm) 不会影响本 turn — arm 是下一次
          // send 的意图, 本 send 已在头部按 requestedPlanTurn 决定了自己的 SDK 档 (Codex review
          // 3535660068 / 3535801840)。该快照既用于 replay diff,也会显式传给 buildQuery 作为
          // 新 Query 的起档 permissionMode,避免 buildQuery 再读包含 arm 态的 effectiveSdkPermissionMode()。
          const snapSdkPermissionMode = currentTurnSdkPermissionMode();
          // 将 turn-scoped permissionMode 显式传给 buildQuery: send 头部已经按
          // sendOpts.planMode / mutablePlanMode 决定了**本 turn**的 plan 意图, rebuild 起档
          // 不能再读包含 arm 态的 effectiveSdkPermissionMode()。否则 rewind 窗口里用户 arm
          // 了下一 turn 的 plan,但当前排队行显式 planMode:false 时,新 Query 会先以 plan
          // 起跑且 replay 看不到 diff,导致普通 turn 误跑成 plan turn (Codex review 3535801840)。
          // extraDirs 中途授权复用这条重建,但不把 session id 当 resumeSessionAt。
          // rewind 已在 commitRewindFiles 关过旧 q;directory grant 这条补 close。
          if (directoryGrantRebuild) {
            rewindTransitionQueries.add(q);
            try {
              q.close();
            } catch (e) {
              log.warn('rewind rebuild: q.close threw', { error: String(e) });
            }
          }
          const forkSourceId = durableSdkSessionId;
          q = await buildQuery({
            ...(directoryGrantRebuild ? {} : { resumeSessionAt: resumeAt }),
            forkSession: true,
            permissionMode: snapSdkPermissionMode,
          });
          const rebuiltQuery = q;
          const forkDestinationId = sdkSessionId;
          // Until the user input is accepted, a cancelled fork must retry its source.
          rollbackUnacceptedFork = () => {
            rollbackUnacceptedFork = undefined;
            if (!forkSourceId || q !== rebuiltQuery || sdkSessionId !== forkDestinationId) return;
            canceledBridgeQueries.add(rebuiltQuery);
            recordCanceledQueryClose(rebuiltQuery, 'unaccepted fork');
            inputQueue.end();
            sdkSessionId = forkSourceId;
            unacceptedForks.delete(rebuiltQuery);
            pendingRewindTo = directoryGrantRebuild ? forkSourceId : resumeAt;
            acceptingRebuiltSend = false;
            clearBridgeState();
          };
          if (sendOpts?.signal?.aborted) {
            rollbackUnacceptedFork();
            throw new Error('Claude send cancelled before acceptance');
          }
          startForwardLoop(q);
          acceptingRebuiltSend = true;
          // 标记必须等 q 替换完才清 (不能在 await buildQuery 之前):
          //  - await 期间 runtime 切换 IPC 仍可能到达, controlRequestsBlocked()
          //    提前变 false 会让 setModel / setPermissionMode 打到旧的已 close Query, 复现
          //    "ProcessTransport is not ready for writing" (Codex review P2)。
          //  - buildQuery 抛错时标记保留, 下一次 send 重试 rebuild, 而不是把
          //    后续消息推进已死旧 q 的黑洞。
          // 新 forward loop 是 async 任务, 在本同步段之后才起跑, 不会误读到 true。
          pendingRewindTo = undefined;
          clearBridgeState();
          runtimeReplaySnapshot = {
            model: snapModel,
            providerId: snapProviderId,
            effort: snapEffort,
            fastMode: snapFastMode,
            sdkPermissionMode: snapSdkPermissionMode,
          };
          await replayRuntimeDrift(runtimeReplaySnapshot, 'rewind rebuild');
          if (sendOpts?.signal?.aborted) {
            rollbackUnacceptedFork();
            throw new Error('Claude send cancelled before acceptance');
          }
          // 补触发 auto-compact (Codex review P2):
          // 窗口期 setModel 大窗 → 小窗切换时跳过了 triggerAutoCompactIfNeeded (旧
          // inputQueue 会被丢, 触发无意义)。此刻 inputQueue / q 都已换新, 且用户消息
          // 还没 push, 是补触发的正确时机 — 未越阈值时 controller.shouldCompactNow()
          // 返回 false, 完全 no-op。触发时 /compact 会先于用户消息进新 inputQueue,
          // SDK 先压缩再处理用户消息, 与 idle setModel 的语义等价, 避免小窗切换后首
          // 轮直接撞上下文上限。
          // 桥接 turn 计数: 实际 push /compact 时 +1, 让后续 middle-turn suppress /
          // onTurnEnd 保持 turnInFlight 靠精确计数, 不受 SDK prompt 消费模式影响。
          bridgeCompactQueued = queueAutoCompactBridge('rewind', resumeAt);
          // 本次 send 的 bridge state 已注册;guard 继续保持到下面 turnInFlight=true,
          // 防止 runtime setter 在 user turn 尚未登记时把 /compact 注入成未标记 turn。
        }

        // 兜底重置 currentTurn —— 上一 turn 异常 / abort 时 endTurn 可能没跑,
        // 防止 currentTurn 残留累加到下一 turn (lastApi / contextWindow / cost 跨 turn 保留)
        beginNewTurn(mutableFastMode ? 'priority' : 'standard');
        resetToolLoopGuards();
        // 标记 turn 进入 in-flight 态 (translator.onTurnEnd 在 result 事件回调时清);
        // rewind preview/commit 守卫读 isTurnRunning() 决定能否操作。
        sendInAcceptPhase = true;
        turnInFlight = true;
        // 对齐老 agentManager.ts:1623 — send 入口立刻 emit "Thinking...", 让 renderer 的
        // RunningStatusBar 一发就亮; 否则从 send 到 SDK message_start 之间的几百 ms~几秒 gap
        // statusbar 一直 hidden, 用户体感上"只有 Done 才闪一下"。SDK 回 message_start 时
        // translator 会自动覆盖成 Generating...
        // 数值带 tracker.snapshot() —— contextTokens/contextWindow 跨 turn 保留, costUsd 累计;
        // tokenUsage 此时已被 beginTurn 清零, 0 是正确值。
        // status 文案带用户名 — 从 phrase 池抽样 (含 one-shot 引导 + 阶梯 pity 保底)。
        // 命中 one-shot 后推进展示次数, 并清 pity 计数让下一档保底独立累计。
        const turnStartPick = pickTurnStartStatus(sendOpts?.userName, oneShotTipState);
        if (turnStartPick.oneShotId) {
          const id = turnStartPick.oneShotId;
          oneShotTipState.displayed.set(id, (oneShotTipState.displayed.get(id) ?? 0) + 1);
          oneShotTipState.pity.delete(id);
        }
        eventQueue.push({
          type: 'status',
          data: {
            status: turnStartPick.text,
            ...usageTracker.snapshot(),
            isRunning: true,
          },
          source: 'claude-code',
        });
        if (acceptingRebuiltSend) {
          acceptingRebuiltSend = false;
          if (runtimeReplaySnapshot) {
            await replayRuntimeDrift(runtimeReplaySnapshot, 'rewind accept');
          }
          if (sendOpts?.signal?.aborted) {
            finishSendBeforeUserInput('send_cancelled_before_acceptance');
            throw new Error('Claude send cancelled before acceptance');
          }
        }
        let userInputAccepted = false;
        try {
          if (reviewMode) {
            await assertReviewMessageContentPaths(
              message.content,
              opts.workingDir,
              reviewReadGrants,
            );
          }
          const pinnedSkill = sendOpts?.[PINNED_SKILL_INVOCATION];
          let providerContent = message.content;
          if (pinnedSkill) {
            if (typeof providerContent !== 'string') {
              throw new Error('Pinned Claude Skill invocation must be text-only.');
            }
            providerContent = await preparePinnedClaudeSkillInvocation(
              providerContent,
              pinnedSkill,
            );
          }
          // SSH 图片路径属于远端主机,不能在桌面端压缩或读取;保留路径引用交给远端 SDK。
          const content = await toClaudeSdkContent(
            withLibraryNativeReadContext(providerContent, mutableLibraryRoot, activeQueryReadonlyDirs),
            undefined,
            !opts.remoteHostId,
          );
          if (sendOpts?.signal?.aborted) {
            throw new Error('Claude send cancelled before acceptance');
          }
          // **Remote attachment guard (MVP)**: 远端 session 走 cc 进程在 SSH host 上跑,
          // 本地文件附件转出来的 `@"<desktop-local-path>"` 引用在远端找不到文件,
          // 模型看不见 → silent context loss。完整修法是 upload 文件到远端 (follow-up),
          // 这里 MVP 检测到附件就 emit warn event 让用户知道,实际请求里把附件 ref 留着
          // (daemon 端 SDK 读不到就跳过, 不会 crash)。
          warnIfRemoteDesktopAttachment(message.content);
          // Claude Code streaming-input 协议要求 message 包装层,漏掉会 exit code 1。
          // sendOpts.messageUuid 注入到 SDK input.uuid — SDK 透传当作 file checkpoint
          // snapshot 的 messageId, rewind preview 拿同款 uuid 调 rewindFiles dryRun。
          const sdkInput: SdkUserInput = {
            type: 'user',
            message: { role: 'user', content },
            parent_tool_use_id: null,
            ...(sendOpts?.messageUuid ? { uuid: sendOpts.messageUuid } : {}),
          };
          const accepted = inputQueue.push(sdkInput);
          if (!accepted) {
            // close() can win while content conversion is still preparing files or
            // images. Renderer now treats send resolve as "agent accepted"; so a
            // closed input queue must reject just like steer, otherwise queue rows
            // get persisted and removed even though Claude never received them.
            throw new Error('Claude input queue is closed');
          }
          userInputAccepted = true;
          rollbackUnacceptedFork = undefined;
          if (unacceptedForks.delete(q) && sdkSessionId) {
            durableSdkSessionId = sdkSessionId;
            if (publishedSdkSessionId !== sdkSessionId) {
              publishedSdkSessionId = sdkSessionId;
              eventQueue.push({ type: 'session_id', data: sdkSessionId, source: 'claude-code' });
            }
          }
          activeCapabilitySelectionText = userMessageTextForCapabilityRouting(message.content);
          setAutoReviewIntent(appendAutoReviewUserIntent(priorAutoReviewIntent(), message.content, sendOpts), { authority: autoReviewContext() });
          replayableUserInput = sdkInput;
          sendInAcceptPhase = false;
          // upstream-response-idle watchdog 起表 — 放在 inputQueue.push 之后, 避免把
          // client 端的 toClaudeSdkContent (多模态 image-resizer 同步等几秒) 算进上游
          // 响应配额。否则 warn 日志里 lastEventType=null + msSinceLast=null 会指错方向
          // (看上去像"上游一句话没回", 实际是 send 还没真发出去)。
          armUpstreamResponseIdle();
        } catch (e) {
          if (
            bridgeCompactQueued &&
            !canceledBridgeQueries.has(q) &&
            bridgeStateActive()
          ) {
            finishSendBeforeUserInput('bridge_send_abandoned', e);
          } else if (sendOpts?.signal?.aborted) {
            finishSendBeforeUserInput('send_cancelled_before_acceptance', e);
          } else if (!userInputAccepted) {
            // 用户输入从未进入队列(附件转换失败,或 push 撞上 invalid-resume 无 replay
            // 重建「旧队列已 end、新队列未替换」的交替窗口返回 false):必须回收本 send
            // 已登记的 turn 状态。否则 turnInFlight 悬置 true 且永无终态事件,Session 层
            // 后续 send 一律 SESSION_RUNNING、renderer 静默排队重试,会话被永久卡成 busy。
            finishSendBeforeUserInput('send_failed_before_user_input', e);
          }
          throw e;
        }
      },
      async steer(message: UserMessage, sendOpts?: SendOptions) {
        if (sendOpts?.signal?.aborted) {
          throw new Error('Claude steer cancelled before acceptance');
        }
        if (sendOpts?.logTitle !== undefined) lastSendTitle = sendOpts.logTitle;
        if (!hasSteerableTurn()) {
          throw new Error('No active Claude turn to steer');
        }
        log.debug('steer ▶ user message', {
          model: mutableModel,
          effort: mutableEffort,
          permissionMode: mutablePermissionMode,
          sdkSessionId,
          logTitle: lastSendTitle,
        });

        if (reviewMode) {
          await assertReviewMessageContentPaths(
            message.content,
            opts.workingDir,
            reviewReadGrants,
          );
        }
        // steer 与 send 保持同一来源边界:SSH 图片路径只由远端 SDK 读取。
        const content = await toClaudeSdkContent(
          message.content,
          undefined,
          !opts.remoteHostId,
        );
        if (sendOpts?.signal?.aborted) {
          throw new Error('Claude steer cancelled before acceptance');
        }
        if (!hasSteerableTurn()) {
          // Image resizing can take long enough for a fast turn to finish. Do not
          // silently route a stale "插话" into the next send path; the renderer
          // keeps the original queue/composer content and lets the user retry.
          throw new Error('No active Claude turn to steer');
        }
        warnIfRemoteDesktopAttachment(message.content);
        // Same-turn steering deliberately does NOT call beginTurn(), reset the
        // tool-loop guard, or emit a new running status. Those are turn-start
        // side effects; doing them here would corrupt usage attribution and make
        // the UI believe a fresh turn started even though Claude is still inside
        // the existing streaming-input query.
        const accepted = inputQueue.push({
          type: 'user',
          message: { role: 'user', content },
          parent_tool_use_id: null,
          ...(sendOpts?.messageUuid ? { uuid: sendOpts.messageUuid } : {}),
        });
        if (!accepted) {
          // close() ends the streaming input queue. Before push returned a
          // delivery signal this race looked successful to IPC, so renderer
          // removed the queued row / optimistic bubble even though Claude never
          // received it.
          throw new Error('No active Claude turn to steer: input queue is closed');
        }
        const awaitingClaim = activeContinuationClaim();
        if (awaitingClaim?.state === 'awaiting') {
          // This input belongs to the already claimed next segment, not another
          // successor. Stopping its last background task must not discard it.
          awaitingClaim.asyncAnswer = true;
        } else if (sendOpts?.[ASYNC_QUESTION_ANSWER]) queuedAsyncAnswer = true;
        appendActiveCapabilitySelectionText(
          userMessageTextForCapabilityRouting(message.content),
        );
        setAutoReviewIntent(appendAutoReviewUserIntent(priorAutoReviewIntent(), message.content, sendOpts));
        armUpstreamResponseIdle();
      },

      async requestGracefulStop(stopOpts) {
        if (canceledBridgeQueries.has(q)) {
          throw new Error('Claude query is no longer active');
        }
        const awaitingContinuation = activeContinuationClaim();
        if (!turnInFlight && awaitingContinuation?.state !== 'awaiting') {
          throw new Error('No active Claude turn to stop');
        }
        const generation = turnState.generation;
        turnState.interruptRequested = true;
        turnState.interruptGeneration = generation;
        autoReviewDecisionCache.clear();
        cancelIdleHostAutoCompact('host_auto_compact_graceful_stop');
        dismissAllPending('graceful_stop', 'deny');
        // A parent result can leave the foreground idle while wake tasks still
        // own an awaiting continuation. Interrupting that idle Query alone does
        // not revoke the task-triggered follow-up turn. Share the same stopTask
        // accounting as hard Stop, but keep graceful-stop fail-safe semantics:
        // only confirmed task stops may close the local continuation contract,
        // and any unsupported/rejected control request remains unconfirmed
        // without closing the provider process.
        const wakeIds = runningWakeTaskIds();
        const stopRequests = stopRunningWakeBackgroundTasks('graceful_stop');
        try {
          await waitForGracefulStopStep(Promise.resolve().then(() => q.interrupt()), stopOpts?.signal);
          const { fulfilledWakeIds, rejectedWakeIds } = await waitForGracefulStopStep(
            settleWakeStopRequests(stopRequests),
            stopOpts?.signal,
          );
          if (turnState.generation !== generation) return;
          const fulfilledWakeIdSet = new Set(fulfilledWakeIds);
          const unconfirmedWakeIds = runningWakeTaskIds().filter(
            (taskId) => !fulfilledWakeIdSet.has(taskId),
          );
          if (
            stopRequests.length !== wakeIds.length ||
            rejectedWakeIds.length > 0 ||
            unconfirmedWakeIds.length > 0
          ) {
            throw new Error('Claude graceful stop could not confirm all background task stops');
          }
          const stoppedClaim = markWakeTasksStopped(fulfilledWakeIds, 'graceful_stop');
          const cancelledContinuation =
            stoppedClaim ?? cancelActiveContinuation('graceful_stop');
          if (cancelledContinuation) {
            retireContinuationTasks(cancelledContinuation);
            emitCancelledContinuationBoundary(cancelledContinuation, 'graceful_stop');
          }
        } catch (error) {
          if (turnState.generation === generation) turnState.interruptRequested = false;
          throw error;
        }
      },

      async abort() {
        // 只 interrupt 当前 turn, 不能 abortController.abort() ——
        // 那会杀掉整个 SDK Query, 让 streaming-input 流断开 (for await 抛
        // 'aborted by user' → eventQueue.end()), 后续 send 进黑洞 session 卡死。
        // abortController 只在 close() 里打。
        // 先清 pending 避免后续 message 被旧 id 短路 arm (onTurnEnd 会再清一次, 幂等)。
        clearUpstreamResponseIdle();
        pendingToolIds.clear();
        if (canceledBridgeQueries.has(q)) {
          log.debug('abort ignored because bridge query was already canceled');
          return;
        }
        // 用户主动 Stop 若发生在 rebuild 注入的 bridge /compact turn 中,语义是取消整条
        // "compact → real user message"序列,不是只停 /compact 后继续跑真实消息。
        // inputQueue.clear() 只能丢 maker-core 本地尚未被拉取的 item;SDK 可能已经 eager-drain
        // 了真实用户消息。此时必须 close 当前 Query 并保留 activeBridgeRewindResumeAt,让下一次
        // send 从同一个 rewind resume point 重建,从 SDK 侧取消已 drain 的后续输入。
        if (turnInFlight && bridgeStateActive()) {
          const abortedBridgeKind = activeBridgeKind;
          const abortedRewindResumeAt = activeBridgeRewindResumeAt;
          log.info('abort during bridge turn — closing query and preserving rewind resume point', {
            queuedBridgeTurns,
            queuedInput: inputQueue.pending,
            activeBridgeRewindResumeAt,
          });
          restoreBridgeAutoCompactSnapshot('bridge_aborted');
          autoCompactController?.onCompactCanceled('bridge_aborted');
          const suppressedDoneData = takeBridgeSuppressedDoneData();
          clearBridgeState();
          inputQueue.clear();
          try {
            inputQueue.end();
          } catch (e) {
            log.warn('abort during bridge turn: inputQueue.end threw', { error: String(e) });
          }
          canceledBridgeQueries.add(q);
          recordCanceledQueryClose(q, 'bridge aborted');
          // close 本地会连 CLI 子进程一起杀(远端为 daemon 侧 interrupt + 输入流收口,
          // SDK 退出前有极窄残留窗口,由下次 q 换代清表兜底),后台任务随之终止,清表即可。
          const cancelledContinuation = cancelActiveContinuation('bridge_aborted');
          if (!cancelledContinuation) settleActiveContinuation('bridge_aborted');
          runningBackgroundTasks.clear();
          terminalBackgroundTaskIds.clear();
          turnInFlight = false;
          // 本分支自己发 bridge_aborted 终态, send 的收尾责任就此交接完毕 ——
          // 一并清 sendInAcceptPhase。不清的话: send 醒来走进
          // finishSendBeforeUserInput, 入口守卫见 turnInFlight=false 直接返回,
          // sendInAcceptPhase 悬置 true, 后续每次 abort 都被 accept 让位守卫
          // 错误短路。boundary 只从这里发一次, send 那侧早退不再补发。
          sendInAcceptPhase = false;
          turnState.interruptRequested = false;
          preserveBridgeRetryTarget(abortedBridgeKind, abortedRewindResumeAt);
          emitTurnBoundary(
            'bridge_aborted',
            suppressedDoneData,
            cancelledContinuation !== null,
          );
          return;
        }
        // 用户主动停止: SDK 被 interrupt 后会 drain 出 error_during_execution 的
        // is_error result, 打标记让 translator turn-end 跳过"失败兜底 error",
        // 否则用户点停止会被误报成"执行失败"通知。
        // 前台仍在跑或 provider continuation 正在 awaiting 时都要锁定本代 Stop。
        // 后者的 turnInFlight 已经是 false,但 interrupt ACK 前的迟到 result 同样
        // 不得重新铸造 continuation claim。
        cancelIdleHostAutoCompact('host_auto_compact_aborted');
        const awaitingContinuationAtUserStop = activeContinuationClaim();
        if (turnInFlight || awaitingContinuationAtUserStop?.state === 'awaiting') {
          turnState.interruptRequested = true;
          turnState.interruptGeneration = turnState.generation;
        }
        // 保持 turnInFlight 为 true 直到 interrupt 返回(或超时关 query):
        // 提前清掉会让 Session.isTurnRunning() 报 idle,并发 send 通过守卫后
        // 把用户消息推进旧 q 的 inputQueue,然后在 interrupt 返回后被
        // inputQueue.clear() 抹掉 → 用户消息丢失(review P1-A)。
        // 5s 超时 + catch 兜底保证 turnInFlight 最终一定被清除,不会造成
        // SESSION_RUNNING 永拒。generation 守卫(translator handleResult)保证
        // 旧 q 的迟到 error_during_execution result 被丢弃、不污染新 turn。
        // sendInAcceptPhase 守卫: 并发 send 处于 accept 阶段时, 由 send 自己的
        // finishSendBeforeUserInput 负责清 turnInFlight + emit boundary,
        // abort 不能抢清, 否则 boundary 丢失(review 3541310178)。
        // 快照 turnInFlight 用于后续 close-query 分支判定(下方 foregroundNeedsTerminal
        // 需要旧值)。
        const foregroundWasInFlight = turnInFlight;
        if (!sendInAcceptPhase) {
          pendingToolIds.clear();
        }
        // 用户 Stop 的产品语义 = 本会话所有模型调用停止:先发 stopTask 再 interrupt
        // (同一控制通道按序处理)。interrupt 用 5s 超时防止 SDK retry backoff 死等;
        // 超时或失败时关 query 让下次 send 走 lazy rebuild。
        const stopRequests = stopRunningWakeBackgroundTasks('user_stop');
        const ABORT_INTERRUPT_TIMEOUT_MS = 5_000;
        try {
          await Promise.race([
            q.interrupt(),
            new Promise<void>((_, reject) =>
              setTimeout(() => reject(new Error('INTERRUPT_TIMEOUT')), ABORT_INTERRUPT_TIMEOUT_MS),
            ),
          ]);
          // stopTask and interrupt share an ordered control channel: an
          // interrupt ACK guarantees these earlier stop requests have settled,
          // so allSettled intentionally has no extra timeout here.
          const { fulfilledWakeIds } = await settleWakeStopRequests(stopRequests);
          // interrupt ACK authorizes retiring only wake tasks whose stop RPC
          // also succeeded. Rejected stops remain tracked for provider events,
          // preserving their continuation contract instead of creating an
          // unaccounted auto-continue.
          const stoppedClaim = markWakeTasksStopped(fulfilledWakeIds, 'user_stop');
          // Stop is the authoritative cancellation boundary. An awaiting
          // continuation may already have lost every task from the running
          // table, so neither stopTask nor an idle interrupt is guaranteed to
          // produce another provider result. A rejected stop is likewise
          // unconfirmed even when a completed notification already removed
          // that task from the local table; the old Query must still be closed
          // to prevent a queued automatic continuation from escaping Stop.
          const cancelledContinuation = stoppedClaim ?? cancelActiveContinuation('user_stop');
          const hasUnconfirmedWakeTasks = [...runningBackgroundTasks.values()].some((info) => info.wake);
          // Once Stop has dispatched stopTask for any wake task, the provider
          // Query must be retired regardless of RPC outcome. A fulfilled RPC
          // only acknowledges the cancellation request; it cannot prove that
          // an automatic continuation was not already queued in the provider.
          // Closing the Query is therefore the only boundary that guarantees
          // no later model call. Mixed local_bash tasks intentionally die with
          // this Query; preserving them would reopen the unsafe same-Query path.
          const shouldRetireQuery =
            stopRequests.length > 0 ||
            cancelledContinuation ||
            hasUnconfirmedWakeTasks;
          if (shouldRetireQuery) {
            // All cancellation sources share one terminal state: a cancelled
            // continuation claim, an unconfirmed wake task, or a rejected stop
            // means this Query must be retired. The provider tail is fenced by
            // the per-query marker, then the next send/rewind installs a fresh
            // Query.
            const cancelledQuery = q;
            // 用 Stop 之前的 turnInFlight 快照判定 foreground 是否需要终态。
            // close-query 分支需要旧值决定是否补 boundary。
            canceledBridgeQueries.add(cancelledQuery);
            // Query retirement always leaves a rebuild tombstone, even if the
            // synthetic boundary is rejected because the event queue is
            // already closing. The next explicit send/rewind must never push
            // into this retired query.
            continuationCancellationGeneration = turnState.generation;
            continuationCancellationRequiresQueryRebuild = true;
            if (cancelledContinuation) {
              // The successful Stop revokes the continuation contract. Retire
              // its task ledger before closing the provider process.
              retireContinuationTasks(cancelledContinuation);
              emitCancelledContinuationBoundary(cancelledContinuation, 'user_stop');
            } else {
              log.info('closing Query after user Stop with unconfirmed wake tasks', {
                generation: turnState.generation,
              });
              // close() prevents the interrupted result from arriving. If the
              // foreground turn has not already produced a terminal, replace
              // it with one synthetic boundary; a raced natural result leaves
              // foregroundWasInFlight=false and therefore does not get a duplicate.
              // accept 阶段的 foreground 终态归 send 的 finishSendBeforeUserInput:
              // 它醒来后按 signal.aborted / push 失败走到自己的 boundary。这里
              // 抢发会重复——一次 Stop 冒出两个终态。
              if (foregroundWasInFlight && !sendInAcceptPhase) {
                emitTurnBoundary('user_stop_unconfirmed_wake_tasks');
              }
            }
            inputQueue.clear();
            try {
              inputQueue.end();
            } catch (e) {
              log.warn('user_stop cancellation: inputQueue.end threw', { error: String(e) });
            }
            recordCanceledQueryClose(cancelledQuery, 'user_stop cancellation');
            runningBackgroundTasks.clear();
            terminalBackgroundTaskIds.clear();
            // main 上 #2151 已给 interrupt 成功分支挂了同一守卫; 本 PR 的差异是
            // close-query / 超时 / 抛错 / bridge 分支也一并纳入同一契约。
            if (!sendInAcceptPhase) turnInFlight = false;
          } else {
            // interrupt 成功且无后台任务需要清:被中断的 turn 会收到
            // error_during_execution result → translator 在 onTurnEnd 清
            // turnInFlight。这里显式补清以防 SDK 未 drain result 的极端
            // 情况(确保不会 SESSION_RUNNING 永拒)。
            //
            // accept 阶段除外——finishSendBeforeUserInput 的入口守卫是
            // `if (!turnInFlight) return`,abort 抢清会让它以为已被收口而直接
            // 返回,send_cancelled_before_acceptance 的终态 boundary 从此丢失,
            // isTurnRunning 悬置(review 3541310178 的反馈原型用例钉的就是它)。
            if (!sendInAcceptPhase) turnInFlight = false;
          }
        } catch (e) {
          const errMsg = e instanceof Error ? e.message : String(e);
          if (errMsg === 'INTERRUPT_TIMEOUT') {
            // SDK 长时间不响应 interrupt(在 retry backoff 中) → 关 query 让
            // 下次 send 走 lazy rebuild。
            log.warn('interrupt timed out during user stop — closing query', {
              sdkSessionId,
            });
            const cancelledContinuation = cancelActiveContinuation('user_stop');
            if (cancelledContinuation) {
              retireContinuationTasks(cancelledContinuation);
              emitCancelledContinuationBoundary(cancelledContinuation, 'user_stop');
            }
            continuationCancellationGeneration = turnState.generation;
            continuationCancellationRequiresQueryRebuild = true;
            canceledBridgeQueries.add(q);
            inputQueue.clear();
            try {
              inputQueue.end();
            } catch (ee) {
              log.warn('user_stop cancellation: inputQueue.end threw', { error: String(ee) });
            }
            recordCanceledQueryClose(q, 'user_stop interrupt timeout');
            runningBackgroundTasks.clear();
            terminalBackgroundTaskIds.clear();
            // accept 阶段同上——终态与清理归 send 自己(query 已被关闭, send 的
            // push 会失败并走 finishSendBeforeUserInput)。
            if (!sendInAcceptPhase) turnInFlight = false;
          } else {
            // interrupt 真正抛错(非超时),回收标记防误抑制(同 watchdog)。
            turnState.interruptRequested = false;
            if (!sendInAcceptPhase) turnInFlight = false;
            log.warn('abort threw', { error: String(e) });
          }
        }
      },

      async stopBackgroundTask(taskId: string) {
        // 精确停单个后台任务(UI 对着具体任务卡点停)。与 abort 的全停语义不同:
        // 不碰当前 turn、不限 wake 型 —— local_bash 也允许(用户明确指着它停,
        // 不存在 abort 误杀 dev server 的顾虑)。
        // 幂等:任务已终态 / 未知(UI 点击与 task_notification 天然竞态)→ 静默成功。
        if (closed) return;
        if (!runningBackgroundTasks.has(taskId)) return;
        // 远端老 daemon / 老 SDK 没有 stopTask:明确失败(按钮不该假装成功)。
        if (typeof q.stopTask !== 'function') {
          throw new Error('stopTask is not supported by the current Claude SDK or remote daemon');
        }
        // The foreground `done` may arrive while stopTask is in flight. That is
        // safe: observers first enter provider continuation wait, then this
        // successful stop cancels it. Do not mark before the RPC resolves — a
        // rejected stop must leave the still-running task visible and pending.
        await q.stopTask(taskId);
        // Some older SDK/daemon pairs acknowledge stopTask without echoing a
        // task_notification(stopped). The accepted control action is already
        // authoritative enough to cancel the provider continuation wait.
        const cancelledClaim = markWakeTasksStopped([taskId], 'user_stop_task');
        if (cancelledClaim) {
          emitCancelledContinuationBoundary(cancelledClaim, 'user_stop_task');
        }
      },

      listBackgroundTasks() {
        // 当前仍在运行的后台任务快照(renderer 挂载 / reloadMessages 后重新水合
        // 任务卡与状态栏信号)。事件流才是实时源,这里只补「订阅之前已启动」的存量。
        if (closed) return [];
        return Array.from(runningBackgroundTasks, ([taskId, info]) => ({
          taskId,
          ...(info.taskType ? { taskType: info.taskType } : {}),
          ...(info.toolUseId ? { toolUseId: info.toolUseId } : {}),
          ...(info.title ? { title: info.title } : {}),
          ...(info.outputFile ? { outputFile: info.outputFile } : {}),
        }));
      },

      countPendingWakeContinuations() {
        // 「任务已终态、wake turn 尚未启动或仍在跑」的 continuation claim 数。
        // runningBackgroundTasks 在任务终态时立即出表(noteBackgroundTaskEvent),
        // 因此 listBackgroundTasks() 的空快照**不能**证明后续没有 wake turn ——
        // renderer 的唤醒桥接对账必须以本计数为权威依据(为 0 才允许收口),
        // 而不是把「没有仍在运行的任务」当成「没有待启动的 continuation」。
        // cancelled 不计(不会再有 wake turn 跟进);awaiting / active 都计
        // (active 期间主 turn isRunning 本就为 true,双重保护)。
        if (closed) return 0;
        let n = 0;
        for (const claim of continuationClaims.values()) {
          if (claim.state === 'awaiting' || claim.state === 'active') n += 1;
        }
        return n;
      },

      beginTurnContinuationWait(continuationId?: number) {
        if (continuationId === undefined) return null;
        return continuationClaims.get(continuationId)?.state ?? null;
      },

      onTurnContinuationChange(
        listener: (
          continuationId: number,
          state: 'awaiting' | 'active' | 'cancelled',
        ) => void,
      ) {
        continuationListeners.add(listener);
        return () => continuationListeners.delete(listener);
      },

      async close() {
        if (closed) return;
        // Closing/dead sessions settle through Session status (or their queued
        // terminal event), never through the successful task-stop path.
        resetClaudeGenerationTiming(runtimeState.generation);
        discardActiveContinuation('session_closed');
        clearUpstreamResponseIdle();
        pendingToolIds.clear();
        turnInFlight = false;
        clearBridgeState();
        closed = true;
        try {
          // 任何挂着的 interaction 强制 deny + emit dismissed, 防止 host 卡住等永远不会来的回应
          dismissAllPending('session_closed', 'deny');
          inputQueue.end();
          abortController.abort();
          // close 会终结 CLI 子进程(本地)/ 远端 session,后台任务随之死亡。
          runningBackgroundTasks.clear();
          terminalBackgroundTaskIds.clear();
        } catch (e) {
          log.warn('close threw', { error: String(e) });
        }
        // 远端分支额外清理 — 走 query/close RPC 释放远端 cc-mgr SessionRegistry,
        // RemoteQuery.close 内部还会 unsubscribe + dispose ssh exec / nc / RpcClient
        // (经 openCcManagerSession 的 dispose hook 走完整链)。漏调会导致远端 daemon
        // 上 session 一直 alive, 既空耗 token, 也会让下次 attach 误连到旧 session。
        // 本地 SDK 分支不触发 (activeRemoteQuery 为 null)。
        if (activeRemoteQuery) {
          try {
            await activeRemoteQuery.close();
          } catch (e) {
            log.warn('remoteQuery.close threw (best-effort)', { error: String(e) });
          }
        }
      },

      ...(opts.remoteHostId
        ? {
            async detach() {
              if (closed) return;
              resetClaudeGenerationTiming(runtimeState.generation);
              discardActiveContinuation('session_detached', true);
              clearUpstreamResponseIdle();
              pendingToolIds.clear();
              turnInFlight = false;
              clearBridgeState();
              closed = true;
              try {
                dismissAllPending('session_closed', 'deny');
                inputQueue.end();
                abortController.abort();
                runningBackgroundTasks.clear();
                terminalBackgroundTaskIds.clear();
              } catch (e) {
                log.warn('detach threw', { error: String(e) });
              }
              if (activeRemoteQuery) {
                try {
                  await (activeRemoteQuery.detach ?? activeRemoteQuery.close)();
                } catch (e) {
                  log.warn('remoteQuery.detach threw (best-effort)', { error: String(e) });
                }
              }
            },
          }
        : {}),

      events(): AsyncIterable<AgentEvent> {
        return consumedEventStream();
      },

      getUsageSnapshot(): UsageSnapshot {
        // 走 tracker —— translator 在 message_delta 时 ingest, result 时 endTurn 锁定;
        // 这里读到的就是最新值 (mid-turn 反映累加, turn end 后 reset 前是 turn aggregate,
        // 下一 turn beginTurn 后 reset 为 0)。
        return {
          ...usageTracker.snapshot(),
          ...(autoCompactController?.needsRollover() ? { needsRollover: true } : {}),
        };
      },

      async getContextUsage() {
        const getContextUsage = (q as {
          getContextUsage?: () => Promise<unknown>;
        }).getContextUsage;
        if (!getContextUsage) {
          throw new Error('Claude Code SDK does not support getContextUsage');
        }
        return await getContextUsage.call(q) as import('../../types/context-usage.js').ContextUsageData;
      },

      async readMcpServerTools(serverName: string) {
        // SSH remote queries do not expose MCP status; report no engine entry.
        const readStatus = (q as {
          mcpServerStatus?: () => Promise<ClaudeMcpServerStatusEntry[]>;
        }).mcpServerStatus;
        if (typeof readStatus !== 'function') return null;
        return claudeMcpServerToolsReport(await readStatus.call(q), serverName);
      },

      setInteractionResolver(resolver: InteractionResolver) {
        interactionResolver = resolver;
      },

      // ── 运行时切换 (Stage 2 B) ─────────────────────────────────────────────
      // 三者都桥到 SDK Query 的 control request, 失败让上层抛 (Session 层会包成
      // NotSupportedError 不会到这, 只剩 SDK 自己的 transport / state 错误)。
      //
      // rewind 窗口期例外: commitRewindFiles 会 close 旧 Query 并设 pendingRewindTo,
      // 新 Query 延迟到下一次 send 才重建 (见 send 的"Rewind 三件套重启")。这个窗口里
      // 对旧 q 发 control request 必抛 "ProcessTransport is not ready for writing"
      // (renderer 端表现为"设置切换失败,未生效" toast)。窗口内只更新闭包状态即可:
      // buildQuery 重建时读的就是 mutableModel / mutableEffort / mutableFastMode /
      // effectiveSdkPermissionMode() 的最新值, 新设置会自然带上。

      requiresModelSwitchRebuild: (model, target) => {
        const provider = target?.providerId !== undefined ? target.providerId : mutableProviderId;
        const window = resolveModelContextWindow(model, provider);
        const expected: Record<string, string> = {};
        // Use the spawn normalizer, including native scaling for windows below 100K.
        applyClaudeContextWindow(expected, window, getAutoCompactThresholdPct(model, provider));
        const liveEnv = opts.remoteHostId ? remoteEnv : env;
        return expected.CLAUDE_CODE_AUTO_COMPACT_WINDOW !== liveEnv?.CLAUDE_CODE_AUTO_COMPACT_WINDOW
          || expected.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE !== liveEnv?.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE;
      },

      async setModel(
        newModel: string,
        setModelOpts?: {
          providerId?: string | null;
          effort?: Effort;
          contextWindowBudget?: number | null;
        },
      ) {
        if (reviewMode) return;
        if (setModelOpts?.contextWindowBudget !== undefined) {
          mutableContextWindowBudget = setModelOpts.contextWindowBudget;
        }
        const targetProviderId = setModelOpts?.providerId !== undefined
          ? setModelOpts.providerId
          : mutableProviderId;
        // 远端会话切换模型/来源:远端 env 在 spawn 时已烤进 daemon,无法热改。若新
        // 模型/来源解析出的路由与当前不一致(路由类型或 env 内容变化),继续用旧
        // env 会以错误 endpoint/凭证打新模型(401/404/错租户)。重新解析比对,
        // 不一致则拒绝并提示重建会话;完全一致才放行。
        // providerId 用调用方给的目标来源(可能正在切 provider),缺省回落会话启动值。
        if (opts.remoteHostId && resolveRemoteClaudeRoute) {
          const nextRoute = await resolveRemoteClaudeRoute({
            sessionId: opts.sessionId,
            providerId: targetProviderId,
            model: newModel,
          });
          const routeChanged =
            (nextRoute === null) !== (remoteRoute === null) ||
            (nextRoute !== null &&
              remoteRoute !== null &&
              (() => {
                // 与「当前生效的 remoteEnv」比对,而不是 spawn 时冻结的 remoteRoute.env:
                // refreshSubscriptionTokenInPlace 会原地写回 remoteEnv,因此它始终是最新
                // 凭证;nextRoute 也是现解析的最新值。
                //
                // 比对规则(四轮 review 的折中):
                // - endpoint + 非 token env 值:任一变化 → 拒绝(真路由/定制头变化);
                // - CLAUDE_CODE_OAUTH_TOKEN(订阅 token,有 oauth/refresh 通道)的**值**:
                //   不比对 —— 后台刷新先更新 nextRoute、远端 daemon 尚未 401 的轮换
                //   窗口会误拒;daemon 撞 401 时经 refresh 拿最新值。
                // - ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN(自定义供应商 key,**无**
                //   refresh 通道)的**值**:仍比对 —— 用户改 key 后远端 daemon 会持续
                //   401,必须拒绝(Greptile 六轮)。存在性(在/不在)同样比对(路由类型)。
                const SUBSCRIPTION_TOKEN_KEY = 'CLAUDE_CODE_OAUTH_TOKEN';
                const PROVIDER_KEY_KEYS = new Set(['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN']);
                // 订阅身份元数据(scopes/subscriptionType/rateLimitTier)与 token 同源,
                // 会在用户零操作下漂移(登录后 backfill 补齐 / 订阅计划变更刷新)——
                // 与 token 同组按存在性比对,不按值(Fable 5 评估 B1:值比对会误拒)。
                const SUBSCRIPTION_METADATA_KEYS = new Set([
                  'CLAUDE_CODE_OAUTH_TOKEN',
                  'CLAUDE_CODE_OAUTH_SCOPES',
                  'CLAUDE_CODE_SUBSCRIPTION_TYPE',
                  'CLAUDE_CODE_RATE_LIMIT_TIER',
                ]);
                const routeKeys = new Set([
                  ...Object.keys(remoteRoute.env),
                  ...Object.keys(nextRoute.env),
                ]);
                // 非订阅字段的值(含自定义供应商 key + 定制头)按全并集比对;
                // 订阅字段(token + 元数据)只按「spawn 时声明过的字段」(remoteRoute.env
                // 的 key 集)比存在性 —— nextRoute 新增的元数据字段(backfill 后才有)
                // 不算变化,remoteEnv 烤的是 spawn 时快照(Fable 5 B1 修正)。
                const nonSubscriptionPick = (env: Record<string, string>): Record<string, string> =>
                  Object.fromEntries(
                    [...routeKeys]
                      .filter((k) => !SUBSCRIPTION_METADATA_KEYS.has(k) && env[k] !== undefined)
                      .map((k) => [k, env[k]]),
                  );
                const spawnDeclares = new Set(Object.keys(remoteRoute.env));
                const subscriptionPresenceOf = (env: Record<string, string>): string[] =>
                  [...spawnDeclares]
                    .filter((k) => SUBSCRIPTION_METADATA_KEYS.has(k) && env[k] !== undefined)
                    .sort();
                return (
                  nextRoute.endpoint !== remoteRoute.endpoint ||
                  JSON.stringify(nonSubscriptionPick(nextRoute.env)) !==
                    JSON.stringify(nonSubscriptionPick(remoteEnv ?? {})) ||
                  JSON.stringify(subscriptionPresenceOf(nextRoute.env)) !==
                    JSON.stringify(subscriptionPresenceOf(remoteEnv ?? {}))
                );
              })()) ||
            // 网关路径(route null):切模时重新读当前网关 key,与 remoteEnv 里 spawn 时
            // 烤进的比对——用户在设置里更新网关 key 后,远端 daemon 仍带旧 key,继续
            // 切模会放行到 401(Greptile 三轮)。
            (nextRoute === null &&
              remoteRoute === null &&
              (async () => {
                const currentAuthEnv = await getAuthEnv({ credentialMode: 'gateway-key' });
                return currentAuthEnv.ANTHROPIC_API_KEY !== remoteEnv?.ANTHROPIC_API_KEY;
              })());
          if (await routeChanged) {
            throw new Error(
              `[REMOTE_MODEL_SWITCH_ROUTE_CHANGE] switching to "${newModel}" requires a different remote route; close and recreate the remote session to apply it`,
            );
          }
          // 放行后**不**更新 remoteRoute:它是「spawn 时的路由指纹」,spawnDeclares
          // 永远用初次 spawn 的 key 集 —— nextRoute 新增的元数据字段(backfill 后
          // 才有)若被当成 spawn 声明,下次切模会与仍烤着旧快照的 remoteEnv 比对
          // 误拒(codex P2 #1035)。
        }
        const sdkModel = sdkModelFor(newModel);
        const isControlBlocked = controlRequestsBlocked();
        const liveEnv = opts.remoteHostId ? remoteEnv : env;
        const exploreInheritCapNeedsRebuild = liveEnv
          ? exploreInheritCapEnvNeedsSync(liveEnv, sdkModel)
          : false;
        if (exploreInheritCapNeedsRebuild && opts.remoteHostId) {
          // 与远端路由变化同码:daemon 烤死 spawn env,热切改不了 Explore cap。
          // host 已把 REMOTE_MODEL_SWITCH_ROUTE_CHANGE 映射成「关闭并重建远程任务」。
          throw new Error(
            `[REMOTE_MODEL_SWITCH_ROUTE_CHANGE] switching to "${newModel}" would desync the remote Explore inherit-cap env; close and recreate the remote session to apply it`,
          );
        }
        log.debug('setModel', {
          from: mutableModel,
          to: newModel,
          sdk: sdkModel,
          controlRequestsBlocked: isControlBlocked,
          exploreInheritCapNeedsRebuild,
        });
        if (!isControlBlocked) {
          // flag settings 只在 Query 创建时写入。热切若只调 setModel,Claude Code
          // 仍按启动时的组织白名单校验,后加载的网关模型会报
          // "restricted by your organization's settings"(2026-08-13)。applyFlagSettings
          // 是 merge,先把当前目录 + 目标模型并进去再切。
          await q.applyFlagSettings({
            availableModels: currentAvailableSdkModels(newModel),
          });
          await q.setModel(sdkModel);
          // 切模已生效:档位重下发失败只 warn,不把整个 setModel 报成失败(同下方 auto 审查重配)。
          await applyRouteEffort(newModel, setModelOpts?.effort ?? mutableEffort, targetProviderId ?? null)
            .catch((e) => {
              log.warn('setModel: effort reapply for target model failed; model switch kept', {
                model: newModel,
                error: String(e),
              });
            });
        }
        if (setModelOpts?.effort) mutableEffort = setModelOpts.effort;
        const usedNativeAutoReview = usesNativeClaudeAutoReview();
        mutableProviderId = targetProviderId ?? null;
        mutableAutoReviewCredentialMode = resolveEffectiveCredentialModeFromAuthSource(
          resolveAgentCredentialMode({
            agentKind: 'claude-code',
            providerId: mutableProviderId,
            model: newModel,
          }),
          authState.authSource,
        );
        mutableModel = newModel;
        autoReviewDecisionCache.clear();
        // 换模型 / 换路由可能正好修掉了审阅器不可用的原因(目录解析失败、provider 被停用
        // 等);若换完又不可用,值得再提醒一次。
        autoReviewUnavailableNotice.reset();
        autoReviewConfirmUndeliveredNotice.reset();
        if (
          !isControlBlocked
          && mutablePermissionMode === 'auto'
          && usedNativeAutoReview !== usesNativeClaudeAutoReview()
        ) {
          // 切模(主操作)已生效、mutableModel/mutableProviderId/credentialMode 已同步为新值。
          // 这里的 auto 审查重配是附带的二次 apply:若它因 transport/SDK 失败仍抛,会把整个
          // setModel 报成失败、上层保留旧持久配置,而运行态其实已在新模型/路由 → 计费/凭证
          // 路由错配。与其它 post-hoc setPermissionMode 调用点(plan 审批后 / plan turn 结束)
          // 同款 best-effort:失败只 warn,不回退已成功的切模,让持久配置与运行态保持一致
          // (codex review)。
          await q.setPermissionMode(toSdkPermissionMode('auto')).catch((e) => {
            log.warn('setModel: auto-review permission-mode reapply failed; model switch kept', {
              model: newModel,
              error: String(e),
            });
          });
        }
        const newContextWindow = resolveModelContextWindow(mutableModel);
        appliedContextWindow = newContextWindow;
        if (newContextWindow === undefined) {
          // setContextWindow(0) 是 no-op —— tracker 会静默沿用旧模型窗口直到下一个
          // result 的 modelUsage 修正。UI 环 / auto-compact 期间按旧窗口算(偏乐观),
          // 打一条 warn 让排查"切模型后窗口不对"时能看出来源陈旧。
          log.warn('setModel: target model contextWindow unknown in capabilities; tracker keeps previous window until next result', {
            model: newModel,
          });
        }
        usageTracker.setContextWindow(newContextWindow ?? 0);
        if (newContextWindow !== undefined) {
          // 大窗口 → 小窗口切换: 用新窗口重算 auto-compact ratio 并立即判定一次,
          // 已越阈值时空闲即触发静默 /compact, 不等下一轮 send 撞小窗口上限。
          // (turnInFlight 时 triggerAutoCompactIfNeeded 内部 no-op, 不打扰 in-flight turn。)
          autoCompactController?.onContextWindowChanged(newContextWindow);
          // control request 被阻塞时的 inputQueue 会在下一次 send 重建时被丢弃, 此时不能注入
          // /compact 或置 turnInFlight; 重建后 forward loop 的 usage 更新会重新判定。
          if (!isControlBlocked) {
            triggerAutoCompactIfNeeded();
          }
        }
        // A model change begins a fresh observation history in every scope,
        // but stays in the same turn: keep this turn's review budget.
        clearToolLoopObservations();
        if (exploreInheritCapNeedsRebuild && liveEnv && !opts.remoteHostId) {
          applyExploreInheritCapEnv(liveEnv, sdkModel, 'replace');
          // 子进程 env 在 spawn 时钉死,Query.setModel 改不了。只改字典并加代,
          // 下一轮 send 再走 extraDirs 同款 resume+fork 重建。这里不碰
          // pendingRewindTo:热切若落在 in-flight turn / rewind 接受窗,提前设标记
          // 会让 forward loop 把当前 Query 当成过渡态静音。
          exploreInheritCapEnvGeneration += 1;
        }
      },

      async setEffort(newEffort: Effort) {
        if (reviewMode) return;
        // maker 的 minimal / ultra 先归一成 Claude 的 low / max;2.1.219 起
        // applyFlagSettings 可原样接收 max,不能再静默降成 xhigh。
        const sdkEffort = getSdkEffortForModel(mutableModel, newEffort, mutableProviderId);
        const isControlBlocked = controlRequestsBlocked();
        log.debug('setEffort', { from: mutableEffort, to: newEffort, sdk: sdkEffort, controlRequestsBlocked: isControlBlocked });
        if (!sdkEffort) {
          mutableEffort = newEffort;
          return;
        }
        if (!isControlBlocked) {
          const appliedEffort = await applyClaudeEffortFlagSettings(
            q,
            sdkEffort,
            getSdkMaxEffortFallbackForModel(mutableModel, mutableProviderId),
          );
          if (appliedEffort !== sdkEffort) {
            log.warn('setEffort: runtime rejected max; applied model-compatible fallback', {
              model: mutableModel,
              requested: sdkEffort,
              applied: appliedEffort,
            });
          }
        }
        mutableEffort = newEffort;
      },

      async setFastMode(enabled: boolean | 'ultrafast') {
        if (reviewMode && opts.fastModePolicy?.isAllowed() !== false) return;
        if (opts.fastModePolicy?.isAllowed() === false) enabled = false;
        if (enabled === 'ultrafast') throw new Error('Ultrafast requires the Codex runtime');
        // 与 setEffort 同款:走 SDK applyFlagSettings 改 flag settings 层 `fastMode`。
        // cc 二进制的 sticky-on latch 负责缓存安全(header 一旦发出整 session 保持,中途 toggle
        // 不破 server 端 cache key)—— 所以这里直接切、不做缓存兜底。是否 Opus/官方/firstParty
        // 由二进制把关(不支持时优雅 no-op),agent 不重复硬判(规则 9 留给配置 + 二进制)。
        const isControlBlocked = controlRequestsBlocked();
        log.debug('setFastMode', { from: mutableFastMode, to: enabled, controlRequestsBlocked: isControlBlocked });
        if (isControlBlocked && opts.fastModePolicy?.isAllowed() === false && mutableFastMode) {
          throw new Error('Subscription Fast policy is waiting for the native runtime to accept settings');
        }
        if (!isControlBlocked) {
          await q.applyFlagSettings({ fastMode: enabled });
        }
        mutableFastMode = enabled;
      },

      getEffort() {
        return mutableEffort;
      },

      getFastMode() {
        return mutableFastMode;
      },

      async setPermissionMode(newMode) {
        if (reviewMode) {
          log.debug('setPermissionMode ignored for host-owned hard read-only session', {
            requested: newMode,
            reviewMode,
          });
          return;
        }
        // 用户自己动过权限档之后,「自动审核不可用」这条一次性提示重新武装:再回到 Auto
        // 又不可用时,他有权再看到一次(否则一个会话里只提示一次会显得像偶发)。
        // 档位变了 → 连**裁决缓存**一起清。缓存 key 不含 permissionMode,切离 Auto 再切回时
        // 会命中先前那条 `unavailable` block —— 审阅器早就恢复了,同一个动作还是被拒
        // (greptile P1 of #1574)。一次性提示同步重新武装:用户既然接管过,之后又不可用
        // 值得再提醒一次。
        if (newMode !== mutablePermissionMode) {
          autoReviewDecisionCache.clear();
          autoReviewUnavailableNotice.reset();
          autoReviewConfirmUndeliveredNotice.reset();
        }
        // 计划模式武装中 / 本轮 plan turn 进行中 SDK 恒在 plan 档: 只记录底层权限档
        // (循环收尾切回时生效), 不 push SDK、不动挂起交互(挂着的多半是 plan_review)。
        if (mutablePlanMode || planTurnActive) {
          log.debug('setPermissionMode (deferred, plan mode active)', { from: mutablePermissionMode, to: newMode });
          mutablePermissionMode = newMode;
          return;
        }
        // 老 agentManager.ts:1850-1893 的"切到更宽松 mode 时挂着的 ask 自动 allow,
        // 切到更严 mode 时 deny" 行为, 复用 dismissAllPending 钩子。
        // **auto 不再算"更宽松"**:Auto-review 语义已从"全放行"变成"区内放行、越界升级",
        // 挂起的授权请求本就是被升级的越界/风险动作,切到 auto 时应 fail-closed(deny),
        // 否则等于把待确认的越界动作橡皮图章掉。只有 bypassPermissions(Full access)才是
        // 真"全开"。与 Codex 侧 #767"切档时挂起请求统一拒绝"对称。
        const moreOpen = newMode === 'bypassPermissions';
        dismissAllPending(`permission_mode_changed_to_${newMode}`, moreOpen ? 'allow' : 'deny');
        // SDK PermissionMode union 没有 'ask' (我们对 ChatInput 暴露的统一名字),
        // SDK 侧把 ask 当 default —— 与 startSession 的处理一致。
        const sdkMode = toSdkPermissionMode(newMode);
        const isControlBlocked = controlRequestsBlocked();
        log.debug('setPermissionMode', { from: mutablePermissionMode, to: newMode, sdk: sdkMode, dismissedAs: moreOpen ? 'allow' : 'deny', controlRequestsBlocked: isControlBlocked });
        if (!isControlBlocked) {
          await q.setPermissionMode(sdkMode);
        }
        mutablePermissionMode = newMode;
      },

      async useCindyAutoReviewFallback() {
        if (nativeAutoReviewUnavailable) return;
        nativeAutoReviewUnavailable = true;
        autoReviewDecisionCache.clear();
        if (
          mutablePermissionMode === 'auto'
          && !mutablePlanMode
          && !planTurnActive
          && !controlRequestsBlocked()
        ) {
          await q.setPermissionMode('default');
        }
        log.warn('Claude native Auto reviewer unavailable; keeping Auto with Cindy fallback', {
          providerId: mutableProviderId,
          model: mutableModel,
        });
      },

      async setPlanMode(enabled: boolean) {
        if (reviewMode) return;
        if (mutablePlanMode === enabled) return;
        mutablePlanMode = enabled;
        // turn 流式中(含 plan turn 本身)只记账武装态、递延 SDK 切档:立即 push 会
        // 改写 in-flight turn 的工具权限,而武装态语义只作用于下一条消息。
        // 补推时机:send 消耗武装态时(!sdkInPlanMode → push plan);disarm 则无需
        // 补推(SDK 本就不在 plan 档,或由 plan turn 收尾逻辑统一切回)。
        if (turnInFlight || planTurnActive) {
          log.debug('setPlanMode (deferred, turn in flight)', { enabled });
          return;
        }
        // 进计划模式 = 收紧(deny 挂起授权); 退出按底层档宽松度决定 —— 与
        // setPermissionMode 的 moreOpen 语义一致(auto 不再算"更宽松",挂起的越界请求
        // 退出 plan 回到 auto 时仍 fail-closed;只有 bypassPermissions 是真"全开")。
        const moreOpen = !enabled && mutablePermissionMode === 'bypassPermissions';
        dismissAllPending(`plan_mode_${enabled ? 'enabled' : 'disabled'}`, moreOpen ? 'allow' : 'deny');
        const sdkMode = effectiveSdkPermissionMode();
        log.debug('setPlanMode', { enabled, sdk: sdkMode, underlying: mutablePermissionMode, controlRequestsBlocked: controlRequestsBlocked() });
        if (controlRequestsBlocked()) {
          // 重建时 buildQuery 以 effectiveSdkPermissionMode() 起档并回写 sdkInPlanMode
          return;
        }
        await q.setPermissionMode(sdkMode);
        sdkInPlanMode = sdkMode === 'plan';
      },

      getPlanMode() {
        return mutablePlanMode;
      },

      getExecutionPlanMode() {
        return mutablePlanMode || planTurnActive || sdkInPlanMode;
      },

      async setExtraDirs(newDirs: string[], libraryRoot?: string | null) {
        if (reviewMode) return;
        // 只覆盖 closure。SDK 没有运行时 setAdditionalDirectories 入口, 但 buildQuery
        // 是 turn-by-turn 装配的 (rewind 重启 / fork 都走 buildQuery), 改完下一 turn
        // 自动用新值。当前 in-flight turn 不会变 (允许的 — 用户在 turn 中加目录
        // 通常意图是"下一 turn 让你看到新目录")。
        mutableLibraryRoot = opts.remoteHostId ? undefined : (libraryRoot ?? (mutableLibraryRoot === undefined ? undefined : null));
        if (
          mutableExtraDirs.length === newDirs.length
          && mutableExtraDirs.every((dir, index) => dir === newDirs[index])
        ) return;
        log.debug('setExtraDirs', { from: mutableExtraDirs.length, to: newDirs.length });
        mutableExtraDirs = [...newDirs];
        autoReviewDirectoryGeneration++;
        extraDirsRebuildAttempted = false;
      },

      async setWritableDirs(newDirs: string[]) {
        if (reviewMode) return;
        if (
          mutableWritableDirs.length === newDirs.length
          && mutableWritableDirs.every((dir, index) => dir === newDirs[index])
        ) return;
        const revoked = mutableWritableDirs.some((dir) => !newDirs.includes(dir));
        log.debug('setWritableDirs', { from: mutableWritableDirs.length, to: newDirs.length, revoked });
        mutableWritableDirs = [...newDirs];
        autoReviewDirectoryGeneration++;
        if (revoked) dismissDirectorySensitivePending('writable_dirs_revoked');
      },

      async setVendorOptions(patch: Record<string, unknown>) {
        // 必须 **in-place 合并**, 见 startSession 里 `const vo` 注释。
        // buildQuery 在 startSession 时跑一次, MCP server 的 tool handler 闭包
        // 捕获了 ctx 引用 (ctx.vendorOptions === 此 vo 对象), 重赋值 vo 会让闭包
        // 永远停留在旧值上。Object.assign 让所有持有 ref 的闭包共享同一份。
        // 当前 in-flight turn 不影响 (与 setExtraDirs 同语义); 后续 turn / 异步
        // tool 调用立即看到新字段。
        const before = JSON.stringify(vo);
        Object.assign(vo, patch);
        log.debug('setVendorOptions', { patch: Object.keys(patch), changed: JSON.stringify(vo) !== before });
      },

      // ── Rewind (Stage 2 C2) ────────────────────────────────────────────────

      isPreparingUserTurn: bridgeStateActive,

      isTurnRunning(): boolean {
        // 前台 result/done 到后台 wake 任务自动续 turn 之间,SDK 会短暂把
        // turnInFlight 清成 false,但从产品/Session 视角 Agent 仍未执行结束。
        // 把 provider 已锁存的 continuation claim 纳入权威 busy 判据,统一阻止
        // 新 send、rewind 与 closeIfIdle 插入该窗口。
        return (
          turnInFlight ||
          activeContinuationClaim()?.state === 'awaiting' ||
          pendingContinuationTerminalBoundaries > 0
        );
      },

      async previewRewindFiles(userUuid: string): Promise<RewindFilesResult> {
        // invalid-resume 重建期间 q 是死掉/半替换的旧 query:与 send 同款等待门禁,
        // 替换 query 就绪后再操作(dryRun 在全新会话上自然返回 canRewind:false 软拒绝)。
        while (idleResumeRebuildGate) {
          await idleResumeRebuildGate;
        }
        if (continuationCancellationRequiresQueryRebuild) {
          // Stop may have already closed the old Query while leaving the
          // cancellation rebuild tombstone for the next explicit turn. A
          // rewind preview is also a valid next control action: install an
          // isolated fresh Query first, but do not inject the send-only
          // /compact bridge or start a product turn.
          await rebuildCancelledContinuationQuery(undefined, { queueCompactBridge: false });
        }
        log.info('previewRewindFiles', { userUuid, sdkSessionId });
        try {
          const result = await q.rewindFiles(userUuid, { dryRun: true });
          log.info('previewRewindFiles result', {
            canRewind: result.canRewind,
            filesCount: result.filesChanged?.length ?? 0,
            insertions: result.insertions,
            deletions: result.deletions,
            error: result.error ?? null,
          });
          return result;
        } catch (err) {
          // SDK 抛错 (老 session 没开 checkpointing 等) 包成软拒绝, UI 走 Empty/Error 态。
          // 业务层 (Dialog) 仍可让用户继续 commit, 由 forkSession=true 兜底。
          const errMsg = err instanceof Error ? err.message : String(err);
          log.warn('previewRewindFiles SDK threw', { error: errMsg });
          return {
            canRewind: false,
            error: errMsg,
            filesChanged: [],
            insertions: 0,
            deletions: 0,
          };
        }
      },

      async commitRewindFiles(
        userUuid: string,
        priorAssistantUuid: string,
        rewindOpts?: RewindCommitOptions,
      ): Promise<undefined> {
        // 同 previewRewindFiles:重建窗口内不得对死掉/半替换的 q 做 rewindFiles/close,
        // 否则 pendingRewindTo 会指向一个已不存在的会话时点。等替换 query 就绪再走。
        while (idleResumeRebuildGate) {
          await idleResumeRebuildGate;
        }
        if (continuationCancellationRequiresQueryRebuild) {
          // See previewRewindFiles: rebuild the fenced Query without the
          // compact bridge so rewindFiles retains its checkpoint semantics.
          await rebuildCancelledContinuationQuery(undefined, { queueCompactBridge: false });
        }
        log.info('commitRewindFiles ▶', { userUuid, priorAssistantUuid, sdkSessionId });
        // ① 立即把文件回滚到 target 时点 (失败 warn + 继续, forkSession=true 兜底)
        try {
          await q.rewindFiles(userUuid, { dryRun: false });
          log.debug('commitRewindFiles: SDK rewindFiles ok');
        } catch (err) {
          if (rewindOpts?.rewindsToNativeThreadStart) {
            // 只回滚文件的路径没有下一次 send 的 forkSession 兜底重试,吞掉错误会让
            // 宿主继续关闭会话、软删消息,用户看到回退成功但文件没恢复。
            log.warn('commitRewindFiles: rewindFiles failed on files-only rewind', {
              error: err instanceof Error ? err.message : String(err),
            });
            throw err;
          }
          log.warn('commitRewindFiles: rewindFiles failed, continuing (forkSession on next send will retry)', {
            error: err instanceof Error ? err.message : String(err),
          });
        }
        if (rewindOpts?.rewindsToNativeThreadStart) {
          // 目标之前没有可续接的 assistant:不设续接点,由宿主关闭会话并清掉原生
          // 会话 id,下次发送开全新原生会话。
          log.info('commitRewindFiles ◀ files only; host restarts the native session');
          return undefined;
        }
        // ② **先**设 rewind transition 再 close —— q.close() 会让正在跑的 forward loop
        //    for-await 抛 "Claude Code process aborted by user", 这是预期行为不是错误。
        //    pendingRewindTo 是共享标记,会在新 q 接管后清掉;因此还要把当前 q 放进
        //    per-query transition 集合,确保旧 forward loop 迟到退出时仍静音,不误关新 q。
        //    顺序很重要 —— catch 是 microtask, q.close() 同步触发, 标记必须先设上。
        pendingRewindTo = priorAssistantUuid;
        rewindTransitionQueries.add(q);
        try {
          q.close();
          log.debug('commitRewindFiles: q.close() ok');
        } catch (err) {
          log.warn('commitRewindFiles: q.close() threw', {
            error: err instanceof Error ? err.message : String(err),
          });
        }
        // turn 没在跑了, 清守卫标记 (rewind 必然在 idle 时调, 但兜底一把)
        turnInFlight = false;
        // bridge counter 兜底: rewind idle 时应该已经归零, 但如果上一轮 bridge 中途异常
        // (SDK 崩 / abort 未 drain result) counter 可能残留, 会污染 rebuild 后的第一 turn。
        clearBridgeState();
        log.info('commitRewindFiles ◀ pendingRewindTo set, awaiting next send to rebuild');
        return undefined;
      },
    };

    if (requireNativeResume) {
      try {
        // query() returns before resume is checked; the CLI rejects a bad resume
        // through initializationResult(), even with no user turn dispatched.
        await q.initializationResult();
        if (closed || sdkSessionId !== opts.resumeSessionId) {
          throw new Error('Native history resume did not restore the transferred session');
        }
      } catch (error) {
        await handle.close();
        throw error;
      }
    }
    return handle;
  }

  // ── Memory 实现 ────────────────────────────────────────────────────────
  // 范围: SDK auto-memory (autoMemoryEnabled) + auto-dream (autoDreamEnabled, 联动)。
  // 数据落盘 ~/.claude/projects/<sanitized-cwd>/memory/ — per-cwd 子目录。
  // 开关本身是全局的 (Settings layer), 所以 reset 也按全局语义清所有项目下的 memory/。
  //
  // applyFlagSettings 是 per-Query 的, BaseAgent 不追踪 active session 引用,
  // 所以 setMemory 只更新 memoryOverride, 影响下次 buildQuery (新 session / rewind 重启);
  // 当前 live Query 仍按旧值跑 — 与 capabilities.memory.setEnabledMidSession.supported=false 对齐。

  async getMemoryStatus(): Promise<MemoryStatus> {
    const stats = await this.collectClaudeMemoryStats().catch((e) => {
      this.deps.logger.warn('getMemoryStatus: stats fs scan failed', { error: String(e) });
      return undefined;
    });
    return {
      // SDK 默认 autoMemoryEnabled=true; 没人覆盖时按默认报真值
      enabled: this.memoryOverride ?? true,
      source: this.memoryOverride === undefined ? 'agent-default' : 'host-runtime',
      ...(stats ? { stats } : {}),
    };
  }

  async setMemory(enabled: boolean): Promise<MemorySetResult> {
    this.deps.logger.info('claude-code: setMemory', { from: this.memoryOverride, to: enabled });
    this.memoryOverride = enabled;
    // 不主动 push 到 live Query (不追踪 active sessions); 下次 buildQuery 自动用新值
    return { effective: 'next-session' };
  }

  /**
   * 全局 reset: 遍历 ~/.claude/projects/*\/memory/ 全删。
   *
   * 与开关的全局语义对称 — autoMemoryEnabled 是 ~/.claude/settings.json 全局设置,
   * 影响所有 cwd, 所以 reset 也清所有 cwd 的 memory 子目录, 不止当前项目。
   *
   * 安全护栏: 严格只删 projectsRoot/<entry>/memory/ 子目录, 不动同级 *.jsonl session 历史,
   * 不递归到 projectsRoot 自己 (那是 Claude SDK 的多项目根)。
   */
  async resetMemory(): Promise<MemoryResetResult> {
    const log = this.deps.logger.child('claude-code/resetMemory');
    const projectsRoot = path.join(os.homedir(), '.claude', 'projects');
    // 安全 assertion: 路径必须落在 ~/.claude/ 下
    const claudeRoot = path.join(os.homedir(), '.claude') + path.sep;
    if (!projectsRoot.startsWith(claudeRoot) || projectsRoot === claudeRoot.slice(0, -1)) {
      throw new Error(`refuse to reset: unsafe projects root "${projectsRoot}"`);
    }

    let removedEntries = 0;
    let removedBytes = 0;
    const projects = await fs.readdir(projectsRoot, { withFileTypes: true }).catch(() => []);
    log.info('resetMemory ▶', { projectsRoot, projectCount: projects.length });

    for (const proj of projects) {
      if (!proj.isDirectory()) continue;
      const memoryDir = path.join(projectsRoot, proj.name, 'memory');
      const stat = await fs.stat(memoryDir).catch(() => null);
      if (!stat?.isDirectory()) continue;

      const dirStat = await statMemoryDir(memoryDir).catch(() => ({ entryCount: 0, sizeBytes: 0 }));
      try {
        await fs.rm(memoryDir, { recursive: true, force: true });
        removedEntries += dirStat.entryCount;
        removedBytes += dirStat.sizeBytes;
      } catch (e) {
        log.warn('failed to remove memory dir, skipping', {
          memoryDir,
          error: e instanceof Error ? e.message : String(e),
        });
      }
    }

    log.info('resetMemory ◀', { removedEntries, removedBytes });
    return { removedEntries, removedBytes };
  }

  /**
   * 扫所有 ~/.claude/projects/*\/memory/ 汇总 stats。
   * 失败/不存在 → 返回 0,0 而不是 throw, getMemoryStatus 自己 catch 兜底。
   */
  private async collectClaudeMemoryStats() {
    const projectsRoot = path.join(os.homedir(), '.claude', 'projects');
    let entryCount = 0;
    let sizeBytes = 0;
    const projects = await fs.readdir(projectsRoot, { withFileTypes: true }).catch(() => []);
    for (const proj of projects) {
      if (!proj.isDirectory()) continue;
      const memoryDir = path.join(projectsRoot, proj.name, 'memory');
      const sub = await statMemoryDir(memoryDir).catch(() => null);
      if (!sub) continue;
      entryCount += sub.entryCount;
      sizeBytes += sub.sizeBytes;
    }
    return {
      entryCount,
      sizeBytes,
      storagePath: projectsRoot,
    };
  }

  /**
   * Fork 一条已有的 Claude SDK session: 文件级 jsonl 截断 + remap uuid。
   * 不依赖 live session, 直接调 SDK 静态函数。
   *
   * 业务流 (调用方 desktop agentFork.ts 编排):
   *   1. 反向找 prior assistant uuid (跳 subagent / 跳 rewind 软删) → 传 upToMessageId
   *   2. 调本方法 → 拿到 newSdkSessionId + uuidMap
   *   3. SQLite 事务: insert 新 sessions row + bulk copy messages (用 uuidMap remap agentMeta)
   *
   * uuidMap 必要性: forkSession 会 remap 新 jsonl 里所有 uuid (SDK sdk.d.ts:539-543);
   * 若不修正 messages.agentMeta 列, 从 fork 出来的会话再 fork (B → C) 时 SDK
   * upToMessageId 拿的是 A 的旧 uuid, 在新 jsonl 找不到 → SDK 报错。
   */
  async forkSdkSession(opts: ForkSdkSessionOptions): Promise<ForkSdkSessionResult> {
    const log = this.deps.logger.child('claude-code/fork');
    const logRepairResult = (
      phase: 'source-preflight' | 'source-retry' | 'forked-post',
      sessionId: string,
      result: RepairForkedClaudeJsonlResult,
    ) => {
      if (result.compactMetadataRepairs.length === 0) return;
      log.warn('forkSdkSession Claude JSONL repair', {
        phase,
        sessionId,
        filePath: result.filePath,
        backupPath: result.backupPath ?? '<none>',
        compactBoundaryCount: result.compactBoundaryCount,
        remappedCompactRefCount: result.remappedCompactRefCount,
        unresolvedCompactRefCount: result.unresolvedCompactRefCount,
        clearedInvalidPreservedSegmentRefCount: result.clearedInvalidPreservedSegmentRefCount,
        compactMetadataRepairs: result.compactMetadataRepairs.map((repair) => ({
          boundaryUuid: repair.boundaryUuid ?? '<missing>',
          invalidRefs: repair.invalidRefs,
          removedPreservedSegment: repair.removedPreservedSegment,
          removedPreservedMessages: repair.removedPreservedMessages,
        })),
      });
    };
    const forkOnce = () => sdkForkSession(opts.sourceSdkSessionId, {
      upToMessageId: opts.upToMessageId,
      title: opts.title,
    });
    log.info('forkSdkSession ▶', {
      sourceSdkSessionId: opts.sourceSdkSessionId,
      upToMessageId: opts.upToMessageId,
      title: opts.title,
      workingDir: opts.workingDir ?? '<none>',
    });
    const sourceRepairResult = await repairForkedClaudeSessionJsonl({
      sessionId: opts.sourceSdkSessionId,
      workingDir: opts.workingDir,
    });
    logRepairResult('source-preflight', opts.sourceSdkSessionId, sourceRepairResult);
    if (sourceRepairResult.invalidPreservedSegmentRefCount > 0) {
      throw new Error(
        `source Claude JSONL has ${sourceRepairResult.invalidPreservedSegmentRefCount} invalid compact preservedSegment reference(s) before fork`,
      );
    }
    let newSdkSessionId: string;
    try {
      ({ sessionId: newSdkSessionId } = await forkOnce());
    } catch (error) {
      if (!isInvalidCompactPreservedSegmentForkError(error)) throw error;
      log.warn('forkSdkSession Claude SDK fork failed; repairing source JSONL and retrying once', {
        sourceSdkSessionId: opts.sourceSdkSessionId,
        error: error instanceof Error ? error.message : String(error),
      });
      const retryRepairResult = await repairForkedClaudeSessionJsonl({
        sessionId: opts.sourceSdkSessionId,
        workingDir: opts.workingDir,
      });
      logRepairResult('source-retry', opts.sourceSdkSessionId, retryRepairResult);
      if (retryRepairResult.invalidPreservedSegmentRefCount > 0) {
        throw new Error(
          `source Claude JSONL has ${retryRepairResult.invalidPreservedSegmentRefCount} invalid compact preservedSegment reference(s) after retry repair`,
        );
      }
      try {
        ({ sessionId: newSdkSessionId } = await forkOnce());
        log.info('forkSdkSession Claude SDK fork retry succeeded', {
          sourceSdkSessionId: opts.sourceSdkSessionId,
          newSdkSessionId,
        });
      } catch (retryError) {
        log.warn('forkSdkSession Claude SDK fork retry failed', {
          sourceSdkSessionId: opts.sourceSdkSessionId,
          error: retryError instanceof Error ? retryError.message : String(retryError),
        });
        throw retryError;
      }
    }
    const repairResult = await repairForkedClaudeSessionJsonl({
      sessionId: newSdkSessionId,
      workingDir: opts.workingDir,
    });
    logRepairResult('forked-post', newSdkSessionId, repairResult);
    if (repairResult.invalidPreservedSegmentRefCount > 0) {
      throw new Error(
        `forked Claude JSONL has ${repairResult.invalidPreservedSegmentRefCount} invalid compact preservedSegment reference(s) after uuid remap`,
      );
    }

    // fork 转录归位:SDK forkSession 把新 jsonl 写在**源转录旁边**,源若因 CLI
    // 运行中 cd 落在别的转码目录(典型:已删除 worktree 的孤儿目录),fork 也会
    // 落在那里,下一次按 workingDir resume 就找不到(2026-07-05 实测事故)。这里
    // 主动复制到 workingDir 的转码目录;projectsRoot 缺省与上方 repair 同源
    // (resolveClaudeProjectsRoot)。best-effort:失败只 warn,resume 侧(buildQuery)
    // 另有同款就位兜底。
    if (opts.workingDir) {
      try {
        const outcome = await ensureClaudeTranscriptInWorkingDir({
          sdkSessionId: newSdkSessionId,
          workingDir: opts.workingDir,
        });
        if (outcome === 'restored') {
          log.info('forkSdkSession transcript relocation', {
            newSdkSessionId,
            workingDir: opts.workingDir,
            outcome,
          });
        } else if (outcome === 'missing' || outcome === 'target-key-inexact') {
          // repair 刚确认过文件存在,这里 missing 意味着 projectsRoot 不一致或竞态,
          // 是异常信号;超长路径放弃归位同理——都走 warn 让生产告警能拦到。
          log.warn('forkSdkSession transcript relocation incomplete (resume-side bootstrap will retry)', {
            newSdkSessionId,
            workingDir: opts.workingDir,
            outcome,
          });
        }
      } catch (e) {
        log.warn('forkSdkSession transcript relocation failed (resume-side bootstrap will retry)', {
          newSdkSessionId,
          workingDir: opts.workingDir,
          error: e instanceof Error ? e.message : String(e),
        });
      }
    }

    log.info('forkSdkSession ◀', {
      newSdkSessionId,
      uuidMapSize: repairResult.uuidMap.size,
      jsonlLineCount: repairResult.lineCount,
      initialContextTokens: repairResult.initialContextTokens,
      compactBoundaryCount: repairResult.compactBoundaryCount,
      remappedCompactRefCount: repairResult.remappedCompactRefCount,
      unresolvedCompactRefCount: repairResult.unresolvedCompactRefCount,
    });
    return {
      newSdkSessionId,
      uuidMap: repairResult.uuidMap,
      ...(repairResult.initialContextTokens > 0
        ? { initialContextTokens: repairResult.initialContextTokens }
        : {}),
    };
  }
}

// SDKMessage → AgentEvent 翻译已搬到 ./translator.ts (translateSdkMessage)。
// 本文件只剩 agent 装配 + 事件 forward loop + canUseTool dispatch。

/**
 * 浅扫一个 memory 目录的 .md 文件数 + 总字节数。
 * - 不递归子目录 (Claude memory dir 是扁平结构: MEMORY.md + *.md)
 * - 不存在/读不到 → throw, 调用方自己 catch 兜默认值
 */
async function statMemoryDir(dir: string): Promise<{ entryCount: number; sizeBytes: number }> {
  const entries = await fs.readdir(dir, { withFileTypes: true });
  let entryCount = 0;
  let sizeBytes = 0;
  for (const ent of entries) {
    if (!ent.isFile()) continue;
    if (!ent.name.endsWith('.md')) continue;
    entryCount += 1;
    const stat = await fs.stat(path.join(dir, ent.name)).catch(() => null);
    if (stat) sizeBytes += stat.size;
  }
  return { entryCount, sizeBytes };
}