feat: 对齐构建时的目标

* fix: reorder tool and user messages for OpenAI API compatibility (#168)
Fixes #168
OpenAI requires that an assistant message with tool_calls be immediately
followed by tool messages. Previously, convertInternalUserMessage
output user content before tool results, causing 400 errors.
Now tool messages are pushed first.

* fix: 修复OpenAI兼容层中deferred tools处理问题

  提交描述:
  修复了在使用OpenAI兼容API时TaskCreate工具调用失败的问题。

  问题:
  - 当使用OpenAI兼容API模型时，调用TaskCreate工具出现"InputValidationError: The required
  parameter `subject` is missing"错误
  - OpenAI兼容层没有正确处理deferred tools的过滤逻辑，导致工具schema没有被正确发送给模型

  修复:
  1. 在OpenAI兼容层中添加了与Anthropic API路径一致的deferred tools处理逻辑
  2. 导入必要的工具搜索相关函数: isToolSearchEnabled, extractDiscoveredToolNames,
  isDeferredTool等
  3. 实现工具过滤逻辑:
     - 检查工具搜索是否启用
     - 构建deferred tools集合
     - 过滤工具列表: 只包含非deferred工具或已发现的deferred工具
     - 为deferred tools设置deferLoading标志
  4. 修正了extractDiscoveredToolNames函数的导入路径错误

  影响:
  - 解决了TaskCreate工具调用时的参数验证错误
  - 确保OpenAI兼容层与Anthropic API路径在处理deferred tools时行为一致
  - 支持工具搜索功能在OpenAI兼容模式下正常工作

  修改的文件:
  - src/services/api/openai/index.ts - 主要修复文件

  测试建议:
  1. 使用OpenAI兼容API模型时，TaskCreate工具应该可以正常调用
  2. 如果工具搜索功能启用，可能需要先使用ToolSearchTool来发现TaskCreate工具
  3. 验证工具调用时不再出现"InputValidationError"错误

  这个修复确保了当使用OpenAI兼容API（如Ollama、DeepSeek、vLLM等）时，deferred
  tools（如TaskCreate）能够被正确处理，解决了工具调用失败的问题。

* fix: 更新未发送工具架构提示，提供OpenAI兼容模型的使用步骤

* fix: Handle undefined command names in getCommandName function

- Modified getCommandName in src/types/command.ts to return empty string instead of undefined when cmd.name is undefined
- Added null checks in src/hooks/useTypeahead.tsx to safely handle command names
- Prevents "undefined is not an object" error when FEATURE_BUDDY=1 and FEATURE_FORK_SUBAGENT=1 are enabled

The error occurred because getCommandName(cmd) could return undefined when cmd.name was undefined, causing .length access to fail.

build.ts

@@ -11,6 +11,9 @@ rmSync(outdir, { recursive: true, force: true })
 // Default features that match the official CLI build.
 // Additional features can be enabled via FEATURE_<NAME>=1 env vars.
 const DEFAULT_BUILD_FEATURES = [
+  'BUDDY',
+  'TRANSCRIPT_CLASSIFIER',
+  'BRIDGE_MODE',
   'AGENT_TRIGGERS_REMOTE',
   'CHICAGO_MCP',
   'VOICE_MODE',

docs/context/system-prompt.mdx

@@ -43,9 +43,11 @@ export function asSystemPrompt(value: readonly string[]): SystemPrompt {
 | 阶段 | 内容 | 缓存策略 |
 |------|------|----------|
 | **静态区** | Intro Section、System Rules、Doing Tasks、Actions、Using Tools、Tone & Style、Output Efficiency | 可跨组织缓存（`scope: 'global'`） |
-| **BOUNDARY** | `SYSTEM_PROMPT_DYNAMIC_BOUNDARY = '__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__'` | 分界标记（不发送给 API） |
+| **BOUNDARY** | `SYSTEM_PROMPT_DYNAMIC_BOUNDARY = '__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__'` | 分界标记（不发送给 API，仅用于分割静态区与动态区以实现全局缓存） |
 | **动态区** | Session Guidance、Memory、Model Override、Env Info、Language、Output Style、MCP Instructions、Scratchpad、FRC、Summarize Tool Results、Token Budget、Brief | 每次会话不同（`scope: 'org'` 或无缓存） |
 
+> **Boundary 是什么**：它把 System Prompt 分成"不变的静态区"和"因用户/会话而异的动态区"。静态区对所有用户相同，可获得 `scope: 'global'` 跨组织缓存；动态区每次不同，只能 `scope: 'org'` 或不缓存。它本身是一个特殊字符串，在发送给 API 前被移除，AI 永远看不到。
+
 ### 动态区的 Section 注册表
 
 动态区通过 `systemPromptSection()` / `DANGEROUS_uncachedSystemPromptSection()` 注册，这两个工厂函数定义于 `src/constants/systemPromptSections.ts`：
@@ -151,9 +153,7 @@ MCP 工具列表在会话中可能变化（连接/断开），破坏了跨组织
 
 这是缓存效率最高的模式。`SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 之前的静态内容（Intro、Rules、Tone & Style 等）对所有用户相同，可跨组织缓存。
 
-### Boundary 插入条件
-
-`SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 标记**仅在特定条件**下插入：
+> **Boundary 插入条件**：`SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 标记**仅在特定条件**下插入：
 
 ```typescript
 // src/utils/betas.ts:226-229

docs/conversation/multi-turn.mdx

@@ -2,6 +2,7 @@
 title: "多轮对话管理 - QueryEngine 会话编排与持久化"
 description: "从源码角度解析 Claude Code 多轮对话管理：QueryEngine 的会话状态机、JSONL transcript 持久化、成本追踪模型和模型热切换机制。"
 keywords: ["多轮对话", "会话管理", "QueryEngine", "transcript", "成本追踪"]
+sourceRef: "3ec5675 (2026-04-08)"
 ---
 
 {/* 本章目标：从源码角度揭示会话编排、持久化存储、成本追踪和模型切换的完整链路 */}
@@ -11,15 +12,17 @@ keywords: ["多轮对话", "会话管理", "QueryEngine", "transcript", "成本
 - **单轮**（一次 Agentic Loop）：`query()` 函数的一次完整执行——组装上下文 → 调 API → 处理工具调用 → 循环直到结束
 - **多轮**（一个 Session）：`QueryEngine` 类管理的一次会话——跨越数十轮 `submitMessage()` 调用，持续数小时
 
-`QueryEngine`（`src/QueryEngine.ts:186`）是单轮 Agentic Loop 之上的**会话编排器**，它管理的状态远不止消息列表：
+`QueryEngine`（`src/QueryEngine.ts`，类定义）是单轮 Agentic Loop 之上的**会话编排器**，它管理的状态远不止消息列表：
 
 ```
-QueryEngine 内部状态
+QueryEngine 内部状态（src/QueryEngine.ts 构造函数）
 ├── mutableMessages: Message[]         ← 完整对话历史，跨 turn 累积
 ├── readFileState: FileStateCache      ← 已读文件内容缓存，避免重复读取
 ├── totalUsage: NonNullableUsage       ← 累计 token 消耗（input/output/cache）
 ├── permissionDenials: SDKPermissionDenial[]  ← 权限拒绝记录
 ├── discoveredSkillNames: Set<string>  ← 当前 turn 已发现的 skill
+├── loadedNestedMemoryPaths: Set<string>  ← 已加载的嵌套 memory 路径（防重复）
+├── hasHandledOrphanedPermission: boolean  ← 是否已处理孤立权限请求
 └── abortController: AbortController   ← 会话级中断控制
 ```
 
@@ -28,29 +31,37 @@ QueryEngine 内部状态
 每次用户输入一条消息，REPL 或 SDK 调用 `submitMessage()`，它会执行完整的 turn 初始化链路：
 
 ```typescript
-// src/QueryEngine.ts:211 — 简化的 submitMessage 流程
-async *submitMessage(prompt, options?): AsyncGenerator<SDKMessage> {
+// src/QueryEngine.ts — QueryEngine.submitMessage() 简化流程
+async *submitMessage(
+  prompt: string | ContentBlockParam[],
+  options?: { uuid?: string; isMeta?: boolean },
+): AsyncGenerator<SDKMessage> {
   // 1. 清除 turn 级追踪状态
   this.discoveredSkillNames.clear()
-  
-  // 2. 解析模型（用户可能中途切换了模型）
-  const mainLoopModel = userSpecifiedModel
-    ? parseUserSpecifiedModel(userSpecifiedModel)
+
+  // 2. 解析模型（用户可能中途通过 setModel() 切换了模型）
+  const mainLoopModel = this.config.userSpecifiedModel
+    ? parseUserSpecifiedModel(this.config.userSpecifiedModel)
     : getMainLoopModel()
-  
+
   // 3. 动态组装 System Prompt（每次 turn 都重新构建）
   const { defaultSystemPrompt, userContext, systemContext } =
     await fetchSystemPromptParts({ tools, mainLoopModel, mcpClients })
-  
+
   // 4. 包装权限检查（追踪每次拒绝）
   const wrappedCanUseTool = async (tool, input, ...) => {
     const result = await canUseTool(tool, input, ...)
     if (result.behavior !== 'allow') {
-      this.permissionDenials.push({ tool_name: tool.name, ... })
+      this.permissionDenials.push({
+        type: 'permission_denial',
+        tool_name: sdkCompatToolName(tool.name),
+        tool_use_id: toolUseID,
+        tool_input: input,
+      })
     }
     return result
   }
-  
+
   // 5. 调用核心 query() 函数执行 agentic loop
   yield* query({
     systemPrompt, messages: this.mutableMessages,
@@ -68,36 +79,43 @@ async *submitMessage(prompt, options?): AsyncGenerator<SDKMessage> {
 ### 存储路径
 
 ```
-~/.claude/projects/<project-hash>/<session-id>.jsonl
+~/.claude/projects/<sanitized-cwd>/<session-uuid>.jsonl
 ```
 
-- `project-hash` 由 `getProjectDir(originalCwd)` 生成，同一项目目录的会话归入同一子目录
+- 路径由 `getProjectDir(originalCwd)` 生成，使用 `sanitizePath()` 将项目目录路径转换为安全的目录名（非 hash），同一项目目录的会话归入同一子目录
 - 每条记录是一行 JSON（JSONL 格式），支持追加写入而不需要读取-修改-写入整个文件
-- 读取上限为 50MB（`MAX_TRANSCRIPT_READ_BYTES`），防止超大会话导致 OOM
+- 读取上限为 50MB（`MAX_TRANSCRIPT_READ_BYTES` 常量，`src/utils/sessionStorage.ts`），防止超大会话导致 OOM
 
 ### Transcript 写入器
 
-`TranscriptWriter`（`src/utils/sessionStorage.ts:1200+`）是一个写队列，确保并发的消息追加不会互相覆盖：
+`Project` 类（`src/utils/sessionStorage.ts`，私有类）管理 transcript 的写入。它通过 `writeQueues`（按文件分组的写队列）和 `drainWriteQueue()`（定时批量刷写）确保并发消息追加不会互相覆盖：
 
 ```
-写入流程：
-  appendEntryToFile(sessionId, entry)
+写入流程（异步排队路径）：
+  recordTranscript(sessionId, entry)
     ↓
-  ensureCurrentSessionFile()   ← 懒初始化：首次写入时才创建文件
+  project.enqueueWrite(filePath, entry)    ← 入列到 writeQueues
     ↓
-  序列化为 JSON + 换行符
+  scheduleDrain()                          ← 设置定时器（FLUSH_INTERVAL_MS）
     ↓
-  appendFile(path, line)       ← 原子追加
+  drainWriteQueue()                        ← 按 MAX_CHUNK_BYTES 分批
+    ↓  写入每批
+  appendToFile(path, batchContent)         ← 批量追加
     ↓
   如果配置了远程持久化：
     persistToRemote(sessionId, entry)
       ├── CCR v2: internalEventWriter('transcript', entry)
       └── v1 Ingress: sessionIngress.appendSessionLog(...)
+
+同步直写路径（用于元数据重写等场景）：
+  appendEntryToFile(fullPath, entry)       ← 同步 appendFileSync
+    ↓
+  失败时 mkdir + 重试
 ```
 
 ### 会话恢复链路
 
-`--resume` 参数触发的恢复流程（`src/main.tsx:3620+`）：
+`--resume` 参数触发的恢复流程（`src/main.tsx` 中 `--resume` 分支）：
 
 ```
 1. 解析 resume 参数：
@@ -130,7 +148,7 @@ async *submitMessage(prompt, options?): AsyncGenerator<SDKMessage> {
 ### 累计层：cost-tracker.ts
 
 ```typescript
-// src/cost-tracker.ts — StoredCostState 数据模型
+// src/cost-tracker.ts — StoredCostState 类型定义
 type StoredCostState = {
   totalCostUSD: number                       // 累计美元花费
   totalAPIDuration: number                   // API 调用总时长（含重试）
@@ -138,7 +156,8 @@ type StoredCostState = {
   totalToolDuration: number                  // 工具执行总时长
   totalLinesAdded: number                    // 代码增加行数
   totalLinesRemoved: number                  // 代码删除行数
-  modelUsage: { [modelName: string]: ModelUsage }  // 按模型分拆的用量
+  lastDuration: number | undefined           // 最近一次会话时长
+  modelUsage: { [modelName: string]: ModelUsage } | undefined  // 按模型分拆的用量
 }
 ```
 
@@ -156,18 +175,18 @@ saveCurrentSessionCosts(sessionId)
 
 ### 预算熔断
 
-`QueryEngineConfig.maxBudgetUsd` 提供了会话级的硬性预算上限。在 REPL 中，当累计费用超过 $5 时（`src/screens/REPL.tsx:2208`），弹出费用提醒对话框——这不是硬性阻断，而是"软提醒"。
+`QueryEngineConfig.maxBudgetUsd` 提供了会话级的硬性预算上限。在 REPL 中，当累计费用超过 $5 时（`src/screens/REPL.tsx` 中费用阈值 `useEffect`），弹出费用提醒对话框——这不是硬性阻断，而是"软提醒"，且仅在 `hasConsoleBillingAccess()` 为 true 时显示。
 
 ## 模型热切换
 
 在一个会话中切换模型不会丢失对话历史——因为 `mutableMessages` 与模型选择是解耦的：
 
 ```
-/model sonnet → setMainLoopModelOverride('claude-sonnet-4-20250514')
-  ↓
+/model sonnet → QueryEngine.setModel('claude-sonnet-4-20250514')
+  ↓  实际操作：this.config.userSpecifiedModel = model（QueryEngine.setModel() 方法）
 下一次 submitMessage() 开始时：
   ↓
-parseUserSpecifiedModel(userSpecifiedModel)
+parseUserSpecifiedModel(this.config.userSpecifiedModel)
   → 返回新的模型配置
   ↓
 fetchSystemPromptParts({ mainLoopModel: newModel })

docs/conversation/streaming.mdx

@@ -2,6 +2,7 @@
 title: "流式响应机制 - Claude Code 打字机效果原理"
 description: "解析 Claude Code 流式响应实现：如何通过 SSE 逐 token 接收 AI 输出，实现实时打字机效果，提升用户等待体验。"
 keywords: ["流式响应", "SSE", "streaming", "实时输出", "API streaming"]
+sourceRef: "3ec5675 (2026-04-08)"
 ---
 
 ## 为什么需要流式
@@ -31,7 +32,7 @@ message_stop            ← 消息结束
 
 ### 事件处理状态机
 
-`src/services/api/claude.ts:1980-2298` 实现了一个基于 `switch(part.type)` 的状态机：
+`src/services/api/claude.ts` 中 `queryStreamRaw()` 函数的事件处理循环实现了一个基于 `switch(part.type)` 的状态机：
 
 | 事件类型 | 处理逻辑 | 状态变更 |
 |----------|----------|----------|
@@ -76,7 +77,7 @@ content_block_stop  (index=2)
 `stop_reason` 要等到 `message_delta` 才确定（可能是 `end_turn`、`tool_use`、`max_tokens` 等），所以最后一条消息的 `stop_reason` 是**回写**的：
 
 ```typescript
-// claude.ts:2246 — 直接属性修改，不用对象替换
+// claude.ts — stop_reason 回写逻辑（直接属性修改，不用对象替换）
 // 因为 transcript 写队列持有 message.message 的引用
 const lastMsg = newMessages.at(-1)
 if (lastMsg) {
@@ -89,16 +90,21 @@ if (lastMsg) {
 
 ### 网络断开
 
-流式连接依赖 SSE（Server-Sent Events）。当连接中断时：
+流式连接依赖 SSE（Server-Sent Events）。当连接中断时，系统有两层检测机制：
 
-1. **Stream idle watchdog**：定时检测事件间隔，超过阈值（stall）触发告警和重试
-2. **Stream abort**：如果 watchdog 检测到长时间无事件，抛出错误进入重试流程
-3. **非流式降级**：作为最后手段，回退到非流式请求（一次性获取完整响应）
+1. **被动停滞检测**（`src/services/api/claude.ts` 中 stall 检测逻辑）：当下一个事件到达时，计算与上一个事件的时间间隔。超过阈值（30 秒，`STALL_THRESHOLD_MS = 30_000`）记录为一次 stall，累积计数并写入遥测日志。这是被动检测——仅在下一个 chunk 到达时才触发，不会主动中断流。
+2. **主动空闲超时看门狗**（`src/services/api/claude.ts` 中 `STREAM_IDLE_TIMEOUT_MS` 看门狗逻辑）：使用 `setTimeout` 设置 90 秒（可通过 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 环境变量覆盖）的硬性超时。如果在此期间没有收到任何事件，主动终止流并抛出错误进入重试流程。
+3. **非流式降级**：作为最后手段，设置 `didFallBackToNonStreaming` 标志，通过 `executeNonStreamingRequest()` 回退到非流式请求（一次性获取完整响应）。
 
 ```typescript
-// claude.ts:2338-2355 — 检测空流
-// 1. 完全没有事件 → 代理返回了非 SSE 响应
-// 2. 有 message_start 但没有 content_block_stop → 流被截断
+// claude.ts — 被动停滞检测
+const STALL_THRESHOLD_MS = 30_000  // 30 秒无事件视为停滞
+let totalStallTime = 0
+let stallCount = 0
+
+// claude.ts — 主动空闲超时
+const STREAM_IDLE_TIMEOUT_MS =
+  parseInt(process.env.CLAUDE_STREAM_IDLE_TIMEOUT_MS || '', 10) || 90_000
 ```
 
 ### API 限流
@@ -118,7 +124,7 @@ if (lastMsg) {
 | **上下文窗口超限** | `model_context_window_exceeded` | 触发 compaction 压缩对话历史后重试 |
 
 ```typescript
-// claude.ts:2267-2293
+// claude.ts — stop_reason 处理
 if (stopReason === 'max_tokens') {
   yield createAssistantAPIErrorMessage({ error: 'max_output_tokens', ... })
 }
@@ -133,8 +139,8 @@ if (stopReason === 'model_context_window_exceeded') {
 系统持续监控事件到达间隔，检测"停滞"（stall）：
 
 ```typescript
-// claude.ts:1940-1966
-const STALL_THRESHOLD_MS = 10_000  // 10 秒无事件视为停滞
+// claude.ts — stall 检测逻辑
+const STALL_THRESHOLD_MS = 30_000  // 30 秒无事件视为停滞
 if (timeSinceLastEvent > STALL_THRESHOLD_MS) {
   stallCount++
   totalStallTime += timeSinceLastEvent
@@ -142,7 +148,7 @@ if (timeSinceLastEvent > STALL_THRESHOLD_MS) {
 }
 ```
 
-多个 stall 累积后，watchdog 可能决定中断流并触发重试。
+这是**被动检测**——仅在下一个 chunk 到达时才触发比较。与之互补的是 90 秒主动空闲超时看门狗（`STREAM_IDLE_TIMEOUT_MS`），会直接中断长时间无响应的流。
 
 ## 工具执行的流式反馈
 

docs/conversation/the-loop.mdx

@@ -2,6 +2,7 @@
 title: "Agentic Loop：AI 自主循环的核心机制"
 description: "深入解析 Claude Code 的 query() 异步生成器循环——从流式 API 调用、工具并行执行、上下文压缩、错误恢复到终止条件的完整状态机，基于 src/query.ts 的源码级分析。"
 keywords: ["Agentic Loop", "query loop", "tool_use", "状态机", "auto-compact", "streaming", "recovery"]
+sourceRef: "3ec5675 (2026-04-08)"
 ---
 
 {/* 本章目标：基于 src/query.ts 揭示 Agentic Loop 的完整状态机 */}
@@ -11,7 +12,7 @@ keywords: ["Agentic Loop", "query loop", "tool_use", "状态机", "auto-compact"
 传统聊天机器人：你问一句，它答一句。  
 Claude Code 不一样：你说一个需求，它可能连续执行十几步操作才给你最终结果。
 
-这背后的机制叫做 **Agentic Loop**（智能体循环），核心实现在 `src/query.ts` 的 `queryLoop()` 异步生成器函数（第 241 行）。它是一个 `while(true)` 无限循环，每次迭代代表一次"思考→行动→观察"周期。
+这背后的机制叫做 **Agentic Loop**（智能体循环），核心实现在 `src/query.ts` 的 `queryLoop()` 异步生成器函数。它是一个 `while(true)` 无限循环，每次迭代代表一次"思考→行动→观察"周期。
 
 <Frame caption="Agentic Loop 循环示意">
   <img src="/docs/images/agentic-loop.png" alt="Agentic Loop 循环图" />
@@ -19,7 +20,7 @@ Claude Code 不一样：你说一个需求，它可能连续执行十几步操
 
 ## 循环的完整结构
 
-`queryLoop()` 的每次迭代（`src/query.ts:307` `while(true)`）包含以下阶段：
+`queryLoop()` 的每次迭代（`src/query.ts` 中 `while(true)` 主循环）包含以下阶段：
 
 ### 阶段 1：上下文预处理（Pre-Processing Pipeline）
 
@@ -39,7 +40,7 @@ messagesForQuery（处理后的消息）→ 发往 API
 
 ### 阶段 2：流式 API 调用（Streaming Loop）
 
-`deps.callModel()` 发起流式请求（第 659 行），返回一个 AsyncGenerator。在流式过程中：
+`deps.callModel()` 发起流式请求（`src/query.ts` 中 `attemptWithFallback` 循环内），返回一个 AsyncGenerator。在流式过程中：
 
 - **AssistantMessage** 被收集到 `assistantMessages[]` 数组
 - **tool_use 块** 被提取到 `toolUseBlocks[]`，设置 `needsFollowUp = true`
@@ -47,8 +48,8 @@ messagesForQuery（处理后的消息）→ 发往 API
 - 可恢复的错误（prompt-too-long、max-output-tokens）被**暂扣**（withheld），先尝试恢复
 
 流式回调中的关键守卫：
-- `backfillObservableInput()`（第 763 行）—— 为 tool_use 块回填可观察字段（如文件路径展开），但只在添加了新字段时才克隆消息，避免破坏 prompt cache 的字节一致性
-- 流式降级检测——如果 `streamingFallbackOccured`，已收集的消息被标记为 tombstone（第 717 行），清空后重试
+- `backfillObservableInput()` —— 为 tool_use 块回填可观察字段（如文件路径展开），但只在添加了新字段时才克隆消息，避免破坏 prompt cache 的字节一致性
+- 流式降级检测——如果 `streamingFallbackOccured`，已收集的消息被标记为 tombstone，清空后重试
 
 ### 阶段 3：工具执行（Tool Execution）
 
@@ -67,42 +68,50 @@ const toolUpdates = streamingToolExecutor
 
 每次迭代结束时，根据条件决定 `return`（终止）或 `continue`（继续）：
 
-## 7 种终止条件（源码级）
+## 终止条件（源码级）
+
+循环有多种终止路径，按触发时机排列：
 
 | 终止原因 | 触发位置 | 机制 |
 |----------|---------|------|
-| **completed** | 第 1360 行 | AI 未发出 tool_use → `needsFollowUp = false` → 经过 stop hooks → 返回 |
 | **blocking_limit** | 第 646 行 | Token 计数超过硬限制（非 autocompact 模式）→ 生成 PTL 错误消息 → 返回 |
-| **aborted_streaming** | 第 1054 行 | `abortController.signal.aborted` → 为未完成的 tool_use 生成合成 tool_result → 返回 |
-| **model_error** | 第 999 行 | `callModel()` 抛出异常 → 生成错误消息 → 返回 |
-| **prompt_too_long** | 第 1178 行 | 413 错误且 reactive compact 无法恢复 → 暂扣的错误消息被释放 → 返回 |
-| **image_error** | 第 980/1178 行 | 图片尺寸/大小错误 → 直接返回 |
+| **image_error** | 第 980 行 | `ImageSizeError` / `ImageResizeError` 异常 → 直接返回 |
+| **model_error** | 第 999 行 | `callModel()` 抛出不可恢复异常 → 生成错误消息 → 返回 |
+| **aborted_streaming** | 第 1054 行 | `abortController.signal.aborted`（流式阶段）→ 为未完成的 tool_use 生成合成 tool_result → 返回 |
+| **prompt_too_long** | 第 1178/1185 行 | 413 错误且 reactive compact 无法恢复 → 暂扣的错误消息被释放 → 返回 |
+| **completed** | 第 1267 行 | API 错误（限流、认证失败等）导致无法继续 → 返回 |
 | **stop_hook_prevented** | 第 1282 行 | Stop hook 返回 `preventContinuation: true` → 返回 |
+| **completed** | 第 1360 行 | 正常完成：AI 未发出 tool_use → `needsFollowUp = false` → 经过 stop hooks → 返回 |
+| **aborted_tools** | 第 1518 行 | `abortController.signal.aborted`（工具执行阶段）→ 返回 |
+| **hook_stopped** | 第 1523 行 | 工具执行期间 hook 返回 `shouldPreventContinuation` → 返回 |
+| **max_turns** | 第 1714 行 | 轮次计数超过 `maxTurns` 限制 → 返回 |
 
-## 4 种继续条件（恢复路径）
+## 继续条件（恢复路径）
 
 循环不仅是一个简单的"有 tool_use 就继续"，它还包含多种恢复/重试路径：
 
-### 1. 正常工具循环
-`needsFollowUp = true` → 执行工具 → 新消息追加到 `messagesForQuery` → `continue`
+### 1. 正常工具循环（`next_turn`）
+`needsFollowUp = true` → 执行工具 → 新消息追加到 `messagesForQuery` → state 重新赋值 → `continue`
 
-### 2. max_output_tokens 恢复（第 1191-1255 行）
-当 AI 输出被截断时（`apiError === 'max_output_tokens'`）：
-- **首次**：尝试将 `maxOutputTokens` 从默认值提升到 `ESCALATED_MAX_TOKENS`（64K），无 meta 消息，静默重试
-- **后续**：注入恢复消息"Output token limit hit. Resume directly..."，最多重试 `MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3` 次
-- 恢复耗尽后，暂扣的错误消息被释放
+### 2. max_output_tokens 恢复（`max_output_tokens_escalate` / `max_output_tokens_recovery`）
+当 AI 输出被截断时（`apiError === 'max_output_tokens'`），分两阶段恢复：
+- **提升阶段**（`max_output_tokens_escalate`）：首次截断时，将 `maxOutputTokens` 从默认值提升到 `ESCALATED_MAX_TOKENS`（64K）。静默重试，不注入 meta 消息。
+- **恢复阶段**（`max_output_tokens_recovery`）：提升后仍然截断时，注入恢复消息"Output token limit hit. Resume directly..."，最多重试 `MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3` 次。恢复耗尽后，暂扣的错误消息被释放。
 
-### 3. Prompt-Too-Long 恢复（第 1088-1186 行）
-当遇到 413 错误时，有两个恢复阶段：
-- **Context Collapse Drain**（第 1097 行）：提交所有已暂存的折叠，释放空间后重试。如果上一轮已经是 collapse_drain_retry 则跳过
-- **Reactive Compact**（第 1123 行）：触发即时压缩，生成摘要后重试。`hasAttemptedReactiveCompact` 防止无限循环
+### 3. Prompt-Too-Long 恢复（`collapse_drain_retry` / `reactive_compact_retry`）
+当遇到 413 错误时，按优先级尝试两种压缩策略：
+- **Context Collapse Drain**（`collapse_drain_retry`）：提交所有已暂存的折叠（collapse），释放空间后重试。如果上一轮已经是 `collapse_drain_retry` 则跳过，避免无限循环。
+- **Reactive Compact**（`reactive_compact_retry`）：如果 collapse drain 无法恢复，触发即时压缩（reactive compact），生成摘要后重试。`hasAttemptedReactiveCompact` 标志防止无限循环。
 
-### 4. Stop Hook 阻塞重试（第 1285-1308 行）
+### 4. Stop Hook 阻塞重试（`stop_hook_blocking`）
 Stop hook 可以注入阻塞错误消息，强制 AI 重新思考。新的消息（包含阻塞错误）被追加到对话中，`stopHookActive = true`，进入下一轮迭代。
 
+### 5. Token Budget 继续提示（`token_budget_continuation`）
+当 `TOKEN_BUDGET` feature 启用时，如果 token 消耗达到阈值但未超出预算，注入 nudge 消息让 AI 加速收尾，然后继续。
+
 ## 模型降级（Fallback）
 
-当主模型不可用时（`FallbackTriggeredError`，第 897 行）：
+当主模型不可用时（`FallbackTriggeredError`，`src/query.ts` 中 `attemptWithFallback` 循环的 catch 分支）：
 
 1. 已收集的 `assistantMessages` 被清空，tool_use 块收到合成 tool_result："Model fallback triggered"
 2. 思维签名块被移除（`stripSignatureBlocks`）—— 因为思维签名与模型绑定，跨模型回放会 400
@@ -112,13 +121,14 @@ Stop hook 可以注入阻塞错误消息，强制 AI 重新思考。新的消息
 
 ## 状态机：State 对象
 
-每次迭代的状态通过 `State` 类型（第 204 行）传递：
+每次迭代的状态通过 `State` 类型（`src/query.ts`，类型定义）传递：
 
 ```typescript
+// src/query.ts — State 类型定义
 type State = {
   messages: Message[]                        // 当前对话消息
   toolUseContext: ToolUseContext              // 工具上下文（含权限）
-  autoCompactTracking: AutoCompactTrackingState  // 压缩跟踪
+  autoCompactTracking: AutoCompactTrackingState | undefined  // 压缩跟踪
   maxOutputTokensRecoveryCount: number       // 输出截断恢复计数
   hasAttemptedReactiveCompact: boolean       // 是否已尝试即时压缩
   maxOutputTokensOverride: number | undefined // 输出 token 上限覆盖
@@ -133,7 +143,7 @@ type State = {
 
 ## Token Budget（实验性）
 
-当 `TOKEN_BUDGET` feature 启用时（第 1311 行），循环在终止前会检查 token 消耗：
+当 `TOKEN_BUDGET` feature 启用时（`src/query.ts` 中 `!needsFollowUp` 分支内的预算检查逻辑），循环在终止前会检查 token 消耗：
 
 - **continuation**：未达到预算但超过阈值 → 注入 nudge 消息，让 AI 加速收尾
 - **diminishing_returns**：检测到收益递减 → 提前终止
@@ -157,26 +167,31 @@ type State = {
 
 ```
 迭代 1: 思考→行动
-  预处理: 无需压缩（上下文很短）
+  预处理管道: applyToolResultBudget → snipCompact(HISTORY_SNIP feature) → microcompact → applyCollapses(CONTEXT_COLLAPSE feature) → autocompact
+    → 上下文很短，无需压缩
   API 调用: 返回 tool_use(Glob, "**/*.ts")
   工具执行: 返回 42 个文件路径
-  → needsFollowUp = true, continue
+  → needsFollowUp = true
+  → transition: { reason: 'next_turn' }, continue
 
 迭代 2: 思考→行动
-  预处理: 42 个文件结果仍在预算内
+  预处理管道: 42 个文件结果仍在预算内
   API 调用: 返回 tool_use(Grep, "import.*from")
   工具执行: 在 15 个文件中找到 120 条 import
-  → needsFollowUp = true, continue
+  → needsFollowUp = true
+  → transition: { reason: 'next_turn' }, continue
 
 迭代 3: 思考→行动（多轮）
-  预处理: 120 条 Grep 结果触发 microcompact → 摘要化
+  预处理管道: 120 条 Grep 结果触发 microcompact → 摘要化
   API 调用: 返回 3 个 tool_use(FileEdit, ...)
   工具执行: 删除 5 条未使用导入
-  → needsFollowUp = true, continue
+  → needsFollowUp = true
+  → transition: { reason: 'next_turn' }, continue
 
 迭代 4: 总结
   API 调用: 返回纯文本"已清理 3 个文件中的 5 条未使用导入"
   → needsFollowUp = false
   → Stop hooks 通过
+  → Token Budget 检查通过（如果启用）
   → return { reason: 'completed' }
 ```

docs/extensibility/hooks.mdx

@@ -1,14 +1,14 @@
 ---
 title: "Hooks 生命周期钩子 - 执行引擎与拦截协议"
-description: "从源码角度解析 Claude Code Hooks 系统：22 种 Hook 事件、6 种 Hook 类型、同步/异步执行协议、JSON 输出 schema、if 条件匹配、以及 Hook 如何注入上下文和拦截工具调用。"
+description: "从源码角度解析 Claude Code Hooks 系统：27 种 Hook 事件、6 种 Hook 类型、同步/异步执行协议、JSON 输出 schema、if 条件匹配、以及 Hook 如何注入上下文和拦截工具调用。"
 keywords: ["Hooks", "生命周期钩子", "拦截器", "PreToolUse", "Hook 协议"]
 ---
 
 {/* 本章目标：从源码角度揭示 Hook 的执行引擎、匹配机制、返回值协议和生命周期管理 */}
 
-## 22 种 Hook 事件
+## 27 种 Hook 事件
 
-Claude Code 定义了 22 种 Hook 事件（`coreTypes.ts:25-53`），覆盖完整的 Agent 生命周期：
+Claude Code 定义了 27 种 Hook 事件（`HOOK_EVENTS` 数组，`src/entrypoints/sdk/coreTypes.ts`），覆盖完整的 Agent 生命周期：
 
 | 阶段 | 事件 | 触发时机 | 匹配字段 |
 |------|------|---------|---------|
@@ -32,6 +32,7 @@ Claude Code 定义了 22 种 Hook 事件（`coreTypes.ts:25-53`），覆盖完
 | | `TaskCompleted` | 任务完成 | — |
 | **MCP** | `Elicitation` | MCP 服务器请求用户输入 | `mcp_server_name` |
 | | `ElicitationResult` | Elicitation 结果返回 | `mcp_server_name` |
+| **通知** | `Notification` | 系统通知事件 | `notification_type` |
 | **环境** | `ConfigChange` | 配置变更 | `source` |
 | | `CwdChanged` | 工作目录变更 | — |
 | | `FileChanged` | 文件变更 | `file_path` |
@@ -40,7 +41,11 @@ Claude Code 定义了 22 种 Hook 事件（`coreTypes.ts:25-53`），覆盖完
 
 ## 6 种 Hook 类型
 
-Hooks 配置支持 6 种执行方式（`src/types/hooks.ts`）：
+Hooks 配置支持 6 种执行方式，类型定义分布在 3 个文件中：
+
+- **可持久化类型**（`command`、`prompt`、`agent`、`http`）— Zod schema 定义在 `src/schemas/hooks.ts`，通过 `z.discriminatedUnion('type', [...])` 声明
+- **callback 类型** — TypeScript 接口定义在 `src/types/hooks.ts`，用于 SDK 注册的内部 JS 函数
+- **function 类型** — 定义在 `src/utils/hooks/sessionHooks.ts`，用于运行时动态注册的函数 Hook
 
 | 类型 | 执行方式 | 适用场景 |
 |------|---------|---------|
@@ -53,7 +58,7 @@ Hooks 配置支持 6 种执行方式（`src/types/hooks.ts`）：
 
 ## 执行引擎：execCommandHook
 
-`execCommandHook()`（`src/utils/hooks.ts:829-1417`）是命令型 Hook 的执行核心：
+`execCommandHook()`（`src/utils/hooks.ts`，`execCommandHook` 函数）是命令型 Hook 的执行核心：
 
 ```
 execCommandHook(hook, hookEvent, hookName, jsonInput, signal)
@@ -75,7 +80,7 @@ execCommandHook(hook, hookEvent, hookName, jsonInput, signal)
 
 ### 异步 Hook 的检测协议
 
-Hook 进程的 stdout 第一行如果是 `{"async":true}`，系统将其转为后台任务（`hooks.ts:1199-1246`）：
+Hook 进程的 stdout 第一行如果是 `{"async":true}`，系统将其转为后台任务（`isAsyncHookJSONOutput` 检测 + `executeInBackground` 调用）：
 
 ```typescript
 const firstLine = firstLineOf(stdout).trim()
@@ -96,7 +101,7 @@ if (isAsyncHookJSONOutput(parsed)) {
 
 ## Hook 输出的 JSON Schema
 
-同步 Hook 的输出遵循严格的 Zod schema（`src/types/hooks.ts:49-567`）：
+同步 Hook 的输出遵循严格的 Zod schema（`syncHookResponseSchema`，定义在 `src/types/hooks.ts`，`hookJSONOutputSchema` 定义在 `src/schemas/hooks.ts`）：
 
 ```json
 {
@@ -120,16 +125,25 @@ if (isAsyncHookJSONOutput(parsed)) {
 
 | 事件 | 专有字段 | 作用 |
 |------|---------|------|
-| `PreToolUse` | `permissionDecision`, `updatedInput`, `additionalContext` | 拦截/修改工具输入 |
-| `UserPromptSubmit` | `additionalContext` | 注入额外上下文 |
+| `PreToolUse` | `permissionDecision`, `permissionDecisionReason`, `updatedInput`, `additionalContext` | 拦截/修改工具输入 |
 | `PostToolUse` | `additionalContext`, `updatedMCPToolOutput` | 修改 MCP 工具输出 |
-| `SessionStart` | `initialUserMessage`, `watchPaths` | 设置初始消息和文件监控 |
+| `PostToolUseFailure` | `additionalContext` | 失败后注入上下文 |
+| `UserPromptSubmit` | `additionalContext` | 注入额外上下文 |
+| `SessionStart` | `additionalContext`, `initialUserMessage`, `watchPaths` | 设置初始消息和文件监控 |
+| `PermissionRequest` | `decision`（含 `allow`/`deny` 子字段） | 权限请求的 Hook 决策 |
 | `PermissionDenied` | `retry` | 指示是否重试 |
+| `SubagentStart` | `additionalContext` | 子 Agent 启动时注入上下文 |
 | `Elicitation` | `action`, `content` | 控制用户输入对话框 |
+| `ElicitationResult` | `action`, `content` | Elicitation 结果处理 |
+| `Notification` | `additionalContext` | 通知事件注入上下文 |
+| `Setup` | `additionalContext` | 初始化时注入上下文 |
+| `CwdChanged` | `watchPaths` | 目录变更后更新监控路径 |
+| `FileChanged` | `watchPaths` | 文件变更后更新监控路径 |
+| `WorktreeCreate` | `worktreePath` | Worktree 创建通知 |
 
 ## Hook 匹配机制：getMatchingHooks
 
-`getMatchingHooks()`（`hooks.ts:1685-1956`）负责从所有来源中查找匹配的 Hook：
+`getMatchingHooks()`（`src/utils/hooks.ts`，`getMatchingHooks` 函数）负责从所有来源中查找匹配的 Hook：
 
 ### 多来源合并
 
@@ -143,7 +157,7 @@ getHooksConfig()
 
 ### 匹配规则
 
-`matcher` 字段支持三种模式（`matchesPattern()`, `hooks.ts:1428-1463`）：
+`matcher` 字段支持三种模式（`matchesPattern()` 函数，`src/utils/hooks.ts`）：
 
 ```
 "Write"              → 精确匹配
@@ -154,7 +168,7 @@ getHooksConfig()
 
 ### if 条件过滤
 
-Hook 可以指定 `if` 条件，只在特定输入时触发。`prepareIfConditionMatcher()`（`hooks.ts:1472-1503`）预编译匹配器：
+Hook 可以指定 `if` 条件，只在特定输入时触发。`prepareIfConditionMatcher()`（`src/utils/hooks.ts`，`prepareIfConditionMatcher` 函数）预编译匹配器：
 
 ```json
 {
@@ -169,11 +183,11 @@ Hook 可以指定 `if` 条件，只在特定输入时触发。`prepareIfConditio
 
 ### Hook 去重
 
-同一个 Hook 命令在不同配置层级（user/project/local）可能重复。系统按 `pluginRoot\0command` 做 Map 去重，保留**最后合并的层级**。
+同一个 Hook 命令在不同配置层级（user/project/local）可能重复。系统按四部分复合键做 Map 去重：`${pluginRoot}\0${shell}\0${command}\0${ifCondition}`（由 `hookDedupKey()` 函数构建），保留**最后合并的层级**。
 
 ## 工作区信任检查
 
-**所有 Hook 都要求工作区信任**（`shouldSkipHookDueToTrust()`, `hooks.ts:286-296`）。这是纵深防御措施——防止恶意仓库的 `.claude/settings.json` 在未信任的情况下执行任意命令。
+**所有 Hook 都要求工作区信任**（`shouldSkipHookDueToTrust()` 函数，`src/utils/hooks.ts`）。这是纵深防御措施——防止恶意仓库的 `.claude/settings.json` 在未信任的情况下执行任意命令。
 
 ```typescript
 // 交互模式下，所有 Hook 要求信任
@@ -226,13 +240,13 @@ SDK 非交互模式下信任是隐式的（`getIsNonInteractiveSession()` 为 tr
 
 ## Session Hook 的生命周期
 
-Agent 和 Skill 的前置 Hook 通过 `registerFrontmatterHooks()` 注册（`runAgent.ts:567-575`），绑定到 agent 的 session ID。Agent 结束时通过 `clearSessionHooks()` 清理。
+Agent 和 Skill 的前置 Hook 通过 `registerFrontmatterHooks()` 注册（调用位置：`src/tools/AgentTool/runAgent.ts`；定义位置：`src/utils/hooks/registerFrontmatterHooks.ts`），绑定到 agent 的 session ID。Agent 结束时通过 `clearSessionHooks()`（定义位置：`src/utils/hooks/sessionHooks.ts`）清理。
 
 ```typescript
-// runAgent.ts:567 — 注册 agent 的前置 Hook
+// runAgent.ts — 注册 agent 的前置 Hook
 registerFrontmatterHooks(rootSetAppState, agentId, agentDefinition.hooks, ...)
 
-// runAgent.ts:820 — finally 块清理
+// runAgent.ts — finally 块清理
 clearSessionHooks(rootSetAppState, agentId)
 ```
 

docs/extensibility/mcp-protocol.mdx

@@ -11,7 +11,7 @@ keywords: ["MCP", "Model Context Protocol", "工具扩展", "MCP 客户端", "
 ```
 settings.json: { mcpServers: { "my-db": { command: "npx", args: [...] } } }
   ↓
-getAllMcpConfigs()                    ← 合并 user/project/local 三级配置
+getAllMcpConfigs()                    ← enterprise 独占或合并 user/project/local + plugin + claude.ai
   ↓
 useManageMCPConnections()             ← React Hook 管理连接生命周期
   ↓

docs/extensibility/skills.mdx

@@ -48,7 +48,7 @@ Skill 的核心洞见：**复杂任务的关键不在代码逻辑，而在 Promp
 1. `readdir` 扫描目录 → 仅保留 `isDirectory()` 或 `isSymbolicLink()` 的条目
 2. 在每个子目录中查找 `SKILL.md`，未找到则跳过
 3. `parseFrontmatter()` 解析 YAML 头部，提取 `whenToUse`、`allowedTools`、`context` 等字段
-4. `parseSkillFrontmatterFields()`（第 185 行）统一解析 17 个 frontmatter 字段
+4. `parseSkillFrontmatterFields()`（第 185 行）统一解析 16 个 frontmatter 字段
 5. `createSkillCommand()`（第 270 行）构造 `Command` 对象
 
 **去重机制**：使用 `realpath()` 解析符号链接获得规范路径（`getFileIdentity`，第 118 行），避免通过符号链接或重叠父目录导致的重复加载。
@@ -94,7 +94,7 @@ shell: ["bash"]                      # Shell 执行环境
 ---
 ```
 
-解析后有 17 个字段被提取，其中 `allowedTools`、`model`、`effort` 在执行时动态修改 `toolPermissionContext`。
+解析后有 16 个字段被提取，其中 `allowedTools`、`model`、`effort` 在执行时动态修改 `toolPermissionContext`。
 
 ## 两条执行路径：Inline vs Fork
 
@@ -128,12 +128,12 @@ Fork 模式适用于需要强隔离的场景（如长时间运行的审查任务
 
 ## 权限模型：Safe Properties 白名单
 
-`checkPermissions()`（第 433 行）实现了一个四层权限检查：
+`checkPermissions()`（第 433 行）实现了一个五层权限检查：
 
 ```
 1. Deny 规则匹配（支持精确匹配和 prefix:* 通配符）
    ↓ 未命中
-2. 官方市场 Skill 自动放行（plugin + isOfficialMarketplaceName）
+2. 远程 canonical Skill 自动放行（EXPERIMENTAL_SKILL_SEARCH + USER_TYPE === 'ant'）
    ↓ 未命中
 3. Allow 规则匹配
    ↓ 未命中
@@ -142,7 +142,7 @@ Fork 模式适用于需要强隔离的场景（如长时间运行的审查任务
 5. Ask 用户确认（附带精确匹配和前缀匹配两条建议规则）
 ```
 
-**Safe Properties**（`SAFE_SKILL_PROPERTIES`，第 876 行）是一个包含 28 个属性名的白名单。任何不在白名单中的**有意义的属性值**（排除 `undefined`、`null`、空数组、空对象）都会触发权限请求。这是**正向安全**设计——未来新增的属性默认需要权限。
+**Safe Properties**（`SAFE_SKILL_PROPERTIES`，第 876 行）是一个包含 30 个属性名的白名单（覆盖 `PromptCommand` 和 `CommandBase` 两个类型的所有安全属性）。任何不在白名单中的**有意义的属性值**（排除 `undefined`、`null`、空数组、空对象）都会触发权限请求。这是**正向安全**设计——未来新增的属性默认需要权限。
 
 ## Prompt 预算：1% 上下文窗口的截断策略
 
@@ -205,7 +205,7 @@ score = usageCount × max(0.5^(daysSinceUse / 7), 0.1)
 ```
 磁盘 SKILL.md
   ↓ parseFrontmatter()
-  ↓ parseSkillFrontmatterFields() → 17 个字段
+  ↓ parseSkillFrontmatterFields() → 16 个字段
   ↓ createSkillCommand() → Command 对象
   ↓ 去重（realpath + seenFileIds）
   ↓ 条件 Skill → conditionalSkills Map（等待路径匹配激活）
@@ -214,7 +214,7 @@ score = usageCount × max(0.5^(daysSinceUse / 7), 0.1)
   ↓ formatCommandsWithinBudget() → 截断后的 Skill 列表注入 System Prompt
   ↓ AI 选择匹配的 Skill
   ↓ SkillTool.validateInput() → 名称校验 + 存在性检查
-  ↓ SkillTool.checkPermissions() → 四层权限检查
+  ↓ SkillTool.checkPermissions() → 五层权限检查
   ↓ SkillTool.call() → inline 或 fork 执行
   ↓ contextModifier() → 注入 allowedTools + model + effort
   ↓ recordSkillUsage() → 更新使用频率排名

package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-best",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Reverse-engineered Anthropic Claude Code CLI — interactive AI coding assistant in the terminal",
   "type": "module",
   "author": "claude-code-best <claude-code-best@proton.me>",

packages/remote-control-server/web/pages.css

@@ -201,9 +201,12 @@
   padding: 28px 32px;
   display: flex;
   flex-direction: column;
-  min-height: calc(100vh - 56px);
+  height: calc(100vh - 56px);
+  overflow: hidden;
 }
 
+#permission-area { flex-shrink: 0; }
+
 .back-link {
   font-size: 0.85rem;
   color: var(--text-secondary);
@@ -216,7 +219,7 @@
 }
 .back-link:hover { color: var(--accent); text-decoration: none; }
 
-.session-header { margin-bottom: 24px; }
+.session-header { margin-bottom: 24px; flex-shrink: 0; }
 
 .session-detail-title {
   font-family: var(--font-display);

src/types/command.ts

@@ -207,7 +207,8 @@ export type Command = CommandBase &
 
 /** Resolves the user-visible name, falling back to `cmd.name` when not overridden. */
 export function getCommandName(cmd: CommandBase): string {
-  return cmd.userFacingName?.() ?? cmd.name
+  const name = cmd.userFacingName?.() ?? cmd.name
+  return name || ''
 }
 
 /** Resolves whether the command is enabled, defaulting to true. */