c0de-agent 1.12.0 → 1.13.0

package/dist/core/config.d.ts

@@ -1,10 +1,43 @@
 import type { AgentsConfig, CompactionConfig, Config, MCPServerConfig, PermissionConfig, SecurityConfig, ToolMetricsConfig, UpdateConfig, WebSearchConfig } from '../shared/types/config.js';
+/**
+ * 全局配置根目录：默认 `~/.c0de`；C0DE_CONFIG_DIR 环境变量可整体重定向
+ * （相对路径按进程 cwd 解析），全局工作流/插件同样落于此根下。
+ * 与 C0DE_DB_DIR 同口径——开发隔离场景把全局配置从安装版默认位置切到独立目录。
+ */
+declare function resolveGlobalConfigDir(): string;
 declare const DEFAULT_CONFIG: Config;
 declare function mergeConfig(...configs: (Partial<Config> | undefined)[]): Config;
+/**
+ * usage 下「全局口径」预算键——仅 global 作用域生效。项目作用域写入这些键
+ * 会被忽略（作用域收敛）：此前「项目配置里设全局预算无意义但会生效」既造成
+ * 双预算语义混乱，又会随 git clone 传播、未被信任门禁拦截。收敛后项目作用域
+ * 的这两键不再进入任何合并视图，也不随 clone 影响本机护栏。
+ */
+declare const GLOBAL_ONLY_USAGE_KEYS: readonly ["globalMonthlyBudgetUsd", "globalMonthlyTokenBudget"];
+/** 从项目作用域原始配置中剥离「服务端/全局」键（security 顶层键 + usage 全局口径预算键）。
+ *  浅拷贝，不改入参；无剥离键时原样返回（保持身份，调用方可安全比较）。 */
+declare function stripProjectServerKeys(project: Partial<Config> | undefined): Partial<Config> | undefined;
+/**
+ * 返回项目作用域**原始文件**中出现的全局口径预算键名（strip 前的原始内容）。
+ * 供设置页告警展示：这些键来自旧版本或手动编辑，加载时已被剥离、不再生效。
+ */
+declare function projectGlobalOnlyUsageKeys(projectDir?: string): string[];
+/**
+ * 返回项目作用域**原始文件**中出现的 security 子键名（strip 前的原始内容）。
+ * 供设置页告警展示：security 是服务端全局参数，随项目配置出现时已被剥离、不再生效。
+ */
+declare function projectSecurityKeys(projectDir?: string): string[];
+/**
+ * 读取项目作用域原始文件内容（不剥离 security/全局键）。
+ * 供「文件原文」敏感的检查使用——被剥离的键仍可能携带明文密钥（如 security.token），
+ * 配置落在 git 仓库内同样要防误提交，不能因键不生效而漏掉警告。
+ */
+declare function loadProjectRawScope(projectDir?: string): Partial<Config> | undefined;
 /**
  * 读取 global/project 两个作用域的**原始文件内容**（不经 DEFAULT 合并）。
  * 供配置持久化使用：写回某个作用域时只落该作用域应有的键，
  * 避免把合并结果（含默认值与另一作用域的配置）整体序列化进文件。
+ * 项目作用域经 stripProjectServerKeys 收敛——security 与全局口径预算键只会从 global 读。
  */
 declare function loadConfigScopes(projectDir?: string): {
     global: Partial<Config> | undefined;
@@ -31,6 +64,15 @@ declare function mergeRaw(...cfgs: (Record<string, unknown> | undefined)[]): Rec
  *  - 写入后 chmod 600：配置文件可能含 token/加密密钥，默认 0644 同机可读。 */
 declare function saveConfigScoped(scope: 'global' | 'project', projectDir: string | undefined, data: Record<string, unknown>): Promise<void>;
 declare function loadConfig(projectDir?: string): Promise<Config>;
+/**
+ * P0-1：配置迁移告警（返回值，供 Web 设置页 warnings 展示；CLI 侧 console.warn
+ * 复用）。检测语义翻转/易混淆键：
+ *  - tools.enabled: [] —— 旧版含义「启用全部」已改为「禁用全部」（fail-closed），
+ *    老用户升级后会静默失去全部工具，必须在 Web 界面可见（不只落在 stderr）。
+ *  - slashCommands.enabled: [] —— 旧版含义「全部启用」已同步改为「禁用全部」
+ *    （与 tools.enabled 语义统一），升级后斜杠命令将全部失效，须显式引导。
+ */
+export declare function collectConfigMigrationWarnings(scope: 'global' | 'project', data: Record<string, unknown> | undefined): string[];
 /** Config 全部顶层键（DEFAULT_CONFIG + 可选键）。未知顶层键校验与告警共用。 */
 declare const KNOWN_CONFIG_KEYS: Set<string>;
 /** 收集对象中不属于 Config 顶层键的未知键。 */
@@ -38,4 +80,4 @@ declare function collectUnknownConfigKeys(data: Record<string, unknown> | undefi
 /** 加载配置时对未知顶层键告警（拼写错误/旧版键静默失效的唯一提示）。 */
 declare function warnUnknownConfigKeys(scope: 'global' | 'project', data: Record<string, unknown> | undefined): void;
 export type { AgentsConfig, CompactionConfig, Config, MCPServerConfig, PermissionConfig, SecurityConfig, ToolMetricsConfig, UpdateConfig, WebSearchConfig, };
-export { applyScopedPatch, collectUnknownConfigKeys, DEFAULT_CONFIG, KNOWN_CONFIG_KEYS, loadConfig, loadConfigScopes, mergeConfig, mergeRaw, saveConfigScoped, warnUnknownConfigKeys, };
+export { applyScopedPatch, collectUnknownConfigKeys, DEFAULT_CONFIG, GLOBAL_ONLY_USAGE_KEYS, KNOWN_CONFIG_KEYS, loadConfig, loadConfigScopes, loadProjectRawScope, mergeConfig, mergeRaw, projectGlobalOnlyUsageKeys, projectSecurityKeys, resolveGlobalConfigDir, saveConfigScoped, stripProjectServerKeys, warnUnknownConfigKeys, };

package/dist/core/config.js

@@ -1,9 +1,20 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { isAbsolute, join, resolve } from 'node:path';
 import { encryptSecret, isEncryptedSecret } from './secret.js';
 const GLOBAL_CONFIG_DIR = '.c0de';
 const CONFIG_FILENAME = 'config.json';
+/**
+ * 全局配置根目录：默认 `~/.c0de`；C0DE_CONFIG_DIR 环境变量可整体重定向
+ * （相对路径按进程 cwd 解析），全局工作流/插件同样落于此根下。
+ * 与 C0DE_DB_DIR 同口径——开发隔离场景把全局配置从安装版默认位置切到独立目录。
+ */
+function resolveGlobalConfigDir() {
+    const envDir = process.env.C0DE_CONFIG_DIR?.trim();
+    if (envDir)
+        return isAbsolute(envDir) ? envDir : resolve(envDir);
+    return join(homedir(), GLOBAL_CONFIG_DIR);
+}
 const DEFAULT_CONFIG = {
     providers: [],
     defaultProvider: 'openai',
@@ -17,9 +28,10 @@ const DEFAULT_CONFIG = {
         keepRecentTokens: 4000,
         midTurnEnabled: false,
     },
-    // enabled 为空 = 启用全部注册工具（registry 层过滤 disabled）。
-    // 非空 = 默认工具集。CLI print 与 Web chat 统一经 resolveEnabledToolNames 解析。
-    tools: { enabled: [], disabled: [] },
+    // enabled 语义（P1-1 修复「空=全部」安全陷阱）：
+    //   ['*']（通配）= 启用全部注册工具（默认）；[] = 无工具（fail-closed）；
+    //   非空名单 = 默认工具集。CLI print 与 Web chat 统一经 resolveEnabledToolNames 解析。
+    tools: { enabled: ['*'], disabled: [] },
     plugins: { enabled: [] },
     mcpServers: [],
     slashCommands: {
@@ -28,8 +40,15 @@ const DEFAULT_CONFIG = {
     toolMetrics: { enabled: true, threshold: 0.8, minSamples: 5 },
     security: { authEnabled: true, allowedOrigins: [] },
     websearch: { provider: 'auto' },
-    agents: { dir: '.c0de/agents', subagentConcurrency: 3 },
-    permission: { defaultMode: 'default' },
+    agents: { subagentConcurrency: 3 },
+    permission: { defaultMode: 'default', timeoutAction: 'pause' },
+    usage: {
+        monthlyBudgetUsd: 0,
+        globalMonthlyBudgetUsd: 0,
+        monthlyTokenBudget: 0,
+        globalMonthlyTokenBudget: 0,
+        budgetAction: 'warn',
+    },
     update: { enabled: true, intervalMs: 60 * 60 * 1000, initialDelayMs: 10_000 },
     theme: 'system',
 };
@@ -70,15 +89,95 @@ function readJsonIfExists(path) {
         return undefined;
     }
 }
+/**
+ * usage 下「全局口径」预算键——仅 global 作用域生效。项目作用域写入这些键
+ * 会被忽略（作用域收敛）：此前「项目配置里设全局预算无意义但会生效」既造成
+ * 双预算语义混乱，又会随 git clone 传播、未被信任门禁拦截。收敛后项目作用域
+ * 的这两键不再进入任何合并视图，也不随 clone 影响本机护栏。
+ */
+const GLOBAL_ONLY_USAGE_KEYS = ['globalMonthlyBudgetUsd', 'globalMonthlyTokenBudget'];
+/**
+ * 项目作用域中「服务端/全局生效、随 git clone 传播有安全风险」的顶层键：整体剥离。
+ * `security` 是服务级信任边界（鉴权开关 / token / CORS origin / 首设备窗口）——单进程
+ * 多项目架构下不存在「按项目」的安全参数。此前项目配置可静默改写服务端安全参数
+ * （如 authEnabled:false、security.token 静态弱 token、allowedOrigins 放宽），且这些键
+ * 不在信任门禁的风险 kind（trust.ts summarizeProjectRisk）内，克隆仓库即可无确认生效。
+ * 收敛为 global-only：security 仅从全局作用域读取。
+ */
+const PROJECT_SERVER_ONLY_KEYS = ['security'];
+/** 从项目作用域原始配置中剥离「服务端/全局」键（security 顶层键 + usage 全局口径预算键）。
+ *  浅拷贝，不改入参；无剥离键时原样返回（保持身份，调用方可安全比较）。 */
+function stripProjectServerKeys(project) {
+    if (!project)
+        return project;
+    let stripped = false;
+    const next = { ...project };
+    // 顶层「服务端/全局」键整体移除（见 PROJECT_SERVER_ONLY_KEYS）。
+    for (const k of PROJECT_SERVER_ONLY_KEYS) {
+        if (k in next) {
+            delete next[k];
+            stripped = true;
+        }
+    }
+    // usage 下全局口径预算键移除（仅 global 作用域生效）。
+    const usage = project.usage;
+    if (typeof usage === 'object' && usage !== null && !Array.isArray(usage)) {
+        const u = { ...usage };
+        for (const k of GLOBAL_ONLY_USAGE_KEYS) {
+            if (k in u) {
+                delete u[k];
+                stripped = true;
+            }
+        }
+        next.usage = u;
+    }
+    if (!stripped)
+        return project;
+    return next;
+}
+/**
+ * 返回项目作用域**原始文件**中出现的全局口径预算键名（strip 前的原始内容）。
+ * 供设置页告警展示：这些键来自旧版本或手动编辑，加载时已被剥离、不再生效。
+ */
+function projectGlobalOnlyUsageKeys(projectDir) {
+    const raw = readJsonIfExists(join(projectDir ?? process.cwd(), '.c0de', CONFIG_FILENAME));
+    const usage = raw?.usage;
+    if (typeof usage !== 'object' || usage === null || Array.isArray(usage))
+        return [];
+    return GLOBAL_ONLY_USAGE_KEYS.filter((k) => k in usage);
+}
+/**
+ * 返回项目作用域**原始文件**中出现的 security 子键名（strip 前的原始内容）。
+ * 供设置页告警展示：security 是服务端全局参数，随项目配置出现时已被剥离、不再生效。
+ */
+function projectSecurityKeys(projectDir) {
+    const raw = readJsonIfExists(join(projectDir ?? process.cwd(), '.c0de', CONFIG_FILENAME));
+    const sec = raw?.security;
+    if (typeof sec !== 'object' || sec === null || Array.isArray(sec))
+        return [];
+    return Object.keys(sec);
+}
+/**
+ * 读取项目作用域原始文件内容（不剥离 security/全局键）。
+ * 供「文件原文」敏感的检查使用——被剥离的键仍可能携带明文密钥（如 security.token），
+ * 配置落在 git 仓库内同样要防误提交，不能因键不生效而漏掉警告。
+ */
+function loadProjectRawScope(projectDir) {
+    return readJsonIfExists(join(projectDir ?? process.cwd(), '.c0de', CONFIG_FILENAME));
+}
 /**
  * 读取 global/project 两个作用域的**原始文件内容**（不经 DEFAULT 合并）。
  * 供配置持久化使用：写回某个作用域时只落该作用域应有的键，
  * 避免把合并结果（含默认值与另一作用域的配置）整体序列化进文件。
+ * 项目作用域经 stripProjectServerKeys 收敛——security 与全局口径预算键只会从 global 读。
  */
 function loadConfigScopes(projectDir) {
-    const globalPath = join(homedir(), GLOBAL_CONFIG_DIR, CONFIG_FILENAME);
+    const globalPath = join(resolveGlobalConfigDir(), CONFIG_FILENAME);
     const projectPath = join(projectDir ?? process.cwd(), '.c0de', CONFIG_FILENAME);
-    return { global: readJsonIfExists(globalPath), project: readJsonIfExists(projectPath) };
+    return {
+        global: readJsonIfExists(globalPath),
+        project: stripProjectServerKeys(readJsonIfExists(projectPath)),
+    };
 }
 /**
  * 把 patch 应用到某个作用域的原始配置（scoped patch，null=删除）：
@@ -145,9 +244,7 @@ function mergeRaw(...cfgs) {
  *    CLI config set 与 /config 斜杠命令共用此路径，保证「apiKey 不明文落盘」全链路成立。
  *  - 写入后 chmod 600：配置文件可能含 token/加密密钥，默认 0644 同机可读。 */
 async function saveConfigScoped(scope, projectDir, data) {
-    const dir = scope === 'global'
-        ? join(homedir(), GLOBAL_CONFIG_DIR)
-        : join(projectDir ?? process.cwd(), '.c0de');
+    const dir = scope === 'global' ? resolveGlobalConfigDir() : join(projectDir ?? process.cwd(), '.c0de');
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
     const path = join(dir, CONFIG_FILENAME);
@@ -194,14 +291,66 @@ function redactSensitiveOnSave(data) {
     return out;
 }
 async function loadConfig(projectDir) {
-    const globalPath = join(homedir(), GLOBAL_CONFIG_DIR, CONFIG_FILENAME);
+    const globalPath = join(resolveGlobalConfigDir(), CONFIG_FILENAME);
     const projectPath = join(projectDir ?? process.cwd(), '.c0de', CONFIG_FILENAME);
     const global = readJsonIfExists(globalPath);
-    const project = readJsonIfExists(projectPath);
+    // 与 loadConfigScopes 同口径剥离：security 与 usage 全局口径预算键不进合并视图
+    // （此前 loadConfig 不剥离，服务启动目录项目的 security/全局预算键会静默生效——
+    //  安全键可被克隆仓库无确认改写，全局预算可被项目作用域注入）。
+    const projectRaw = readJsonIfExists(projectPath);
+    const project = stripProjectServerKeys(projectRaw);
+    // 项目配置遗留 security 键（旧版本/手动编辑/克隆仓库自带）→ CLI 侧明示已忽略，
+    // 与 Web 设置页 securityWarnings 同口径（stderr 可见，不必等到打开设置页）。
+    const rawSecurity = projectRaw?.security;
+    if (typeof rawSecurity === 'object' && rawSecurity !== null && !Array.isArray(rawSecurity)) {
+        const keys = Object.keys(rawSecurity);
+        if (keys.length > 0) {
+            console.warn(`[config] 项目配置含 security 键（${keys.join('、')}，服务端全局参数），已忽略——` +
+                `请在全局配置（${join(resolveGlobalConfigDir(), CONFIG_FILENAME)}）或 c0de config set --global 设置。`);
+        }
+    }
     warnUnknownConfigKeys('global', global);
     warnUnknownConfigKeys('project', project);
+    for (const [scope, data] of [
+        ['global', global],
+        ['project', project],
+    ]) {
+        for (const w of collectConfigMigrationWarnings(scope, data))
+            console.warn(`[config] ${w}`);
+    }
     return mergeConfig(global, project);
 }
+/**
+ * P0-1：配置迁移告警（返回值，供 Web 设置页 warnings 展示；CLI 侧 console.warn
+ * 复用）。检测语义翻转/易混淆键：
+ *  - tools.enabled: [] —— 旧版含义「启用全部」已改为「禁用全部」（fail-closed），
+ *    老用户升级后会静默失去全部工具，必须在 Web 界面可见（不只落在 stderr）。
+ *  - slashCommands.enabled: [] —— 旧版含义「全部启用」已同步改为「禁用全部」
+ *    （与 tools.enabled 语义统一），升级后斜杠命令将全部失效，须显式引导。
+ */
+export function collectConfigMigrationWarnings(scope, data) {
+    if (!data)
+        return [];
+    const scopeLabel = scope === 'global' ? '全局' : '项目';
+    const out = [];
+    const tools = data.tools;
+    if (typeof tools === 'object' && tools !== null && !Array.isArray(tools)) {
+        const enabled = tools.enabled;
+        if (Array.isArray(enabled) && enabled.length === 0) {
+            out.push(`${scopeLabel}配置的 tools.enabled 为空数组：旧版含义「启用全部」已改为「禁用全部」——` +
+                `如需启用全部，请改为 ["*"]，或删除该键恢复默认值。`);
+        }
+    }
+    const slash = data.slashCommands;
+    if (typeof slash === 'object' && slash !== null && !Array.isArray(slash)) {
+        const enabled = slash.enabled;
+        if (Array.isArray(enabled) && enabled.length === 0) {
+            out.push(`${scopeLabel}配置的 slashCommands.enabled 为空数组：旧版含义「全部启用」已改为「禁用全部」` +
+                `（与 tools.enabled 语义统一）——如需启用全部，请改为 ["*"]，或删除该键恢复默认值。`);
+        }
+    }
+    return out;
+}
 /** Config 全部顶层键（DEFAULT_CONFIG + 可选键）。未知顶层键校验与告警共用。 */
 const KNOWN_CONFIG_KEYS = new Set([
     ...Object.keys(DEFAULT_CONFIG),
@@ -222,4 +371,4 @@ function warnUnknownConfigKeys(scope, data) {
     console.warn(`[config] ${scope} 配置包含未知键：${unknown.join(', ')}。` +
         `这些键不会生效——请检查拼写，或移除过时配置。有效顶层键：${[...KNOWN_CONFIG_KEYS].join(', ')}`);
 }
-export { applyScopedPatch, collectUnknownConfigKeys, DEFAULT_CONFIG, KNOWN_CONFIG_KEYS, loadConfig, loadConfigScopes, mergeConfig, mergeRaw, saveConfigScoped, warnUnknownConfigKeys, };
+export { applyScopedPatch, collectUnknownConfigKeys, DEFAULT_CONFIG, GLOBAL_ONLY_USAGE_KEYS, KNOWN_CONFIG_KEYS, loadConfig, loadConfigScopes, loadProjectRawScope, mergeConfig, mergeRaw, projectGlobalOnlyUsageKeys, projectSecurityKeys, resolveGlobalConfigDir, saveConfigScoped, stripProjectServerKeys, warnUnknownConfigKeys, };

package/dist/core/loop/segment.d.ts

@@ -5,4 +5,6 @@ import type { StreamCollectResult } from './stream-collect.js';
 /** 段管理：判断段边界（pending trigger / model / systemPrompt / tools 变化），
  *  构造本轮 LLMCall 并 push 到当前段，持久化 segments。直接修改 state.segments（引用语义）。
  *  trigger 判定用于新段元数据；needSegment 决定是否真正开新段（否则复用 activeSeg）。 */
-export declare function manageSegment(state: AgentState, deps: LoopDeps, systemPrompt: string, tools: ChatTool[], requestStartTime: number, totalLatency: number, collectedUsage: StreamCollectResult['usage'], collectedText: string[], collectedThinking: string[], truncated: FinishReason | null, firstTokenTime: number | null, contextWindow: number | undefined, computedCost: number): Promise<void>;
+export declare function manageSegment(state: AgentState, deps: LoopDeps, systemPrompt: string, tools: ChatTool[], requestStartTime: number, totalLatency: number, collectedUsage: StreamCollectResult['usage'], collectedText: string[], collectedThinking: string[], truncated: FinishReason | null, firstTokenTime: number | null, contextWindow: number | undefined, 
+/** null = 价格未知（loop 层已判定），按 $0 计入并由聚合层计数提示。 */
+computedCost: number | null): Promise<void>;

package/dist/core/loop/segment.js

@@ -1,9 +1,12 @@
+import { usageEvents } from '../../db/schema.js';
 import { saveLLMSegments, segmentFingerprint } from '../../session/session.js';
 import { generateId } from '../../shared/index.js';
 /** 段管理：判断段边界（pending trigger / model / systemPrompt / tools 变化），
  *  构造本轮 LLMCall 并 push 到当前段，持久化 segments。直接修改 state.segments（引用语义）。
  *  trigger 判定用于新段元数据；needSegment 决定是否真正开新段（否则复用 activeSeg）。 */
-export async function manageSegment(state, deps, systemPrompt, tools, requestStartTime, totalLatency, collectedUsage, collectedText, collectedThinking, truncated, firstTokenTime, contextWindow, computedCost) {
+export async function manageSegment(state, deps, systemPrompt, tools, requestStartTime, totalLatency, collectedUsage, collectedText, collectedThinking, truncated, firstTokenTime, contextWindow, 
+/** null = 价格未知（loop 层已判定），按 $0 计入并由聚合层计数提示。 */
+computedCost) {
     // —— 段管理：判断是否开新段 ——
     const fp = segmentFingerprint(systemPrompt, tools);
     const activeSeg = state.segments[state.segments.length - 1];
@@ -69,4 +72,24 @@ export async function manageSegment(state, deps, systemPrompt, tools, requestSta
     };
     currentSeg.calls.push(call);
     await saveLLMSegments(deps.db, state.session.id, state.segments);
+    // P2 成本账本：每个 LLM 调用同时落独立 usage_events 表（与 session 生命周期解耦——
+    // 会话物理清除后花费记录仍在，账本不随回收站到期/彻底删除而消失）。
+    await deps.db.db
+        .insert(usageEvents)
+        .values({
+        callId: call.id,
+        sessionId: state.session.id,
+        projectId: state.session.projectId ?? null,
+        provider: state.config.provider,
+        model: state.config.model,
+        inputTokens: call.usage.input,
+        outputTokens: call.usage.output,
+        cacheRead: call.usage.cacheRead ?? 0,
+        cost: computedCost,
+        timestamp: call.timestamp,
+    })
+        .catch((err) => {
+        // 账本写入失败不致命（会话元数据仍含 segments 备份）；告警便于排查。
+        console.warn(`[loop] usage_events 写入失败（成本账本将缺失本次调用）：${err instanceof Error ? err.message : String(err)}`);
+    });
 }

package/dist/core/loop/subagent.js

@@ -57,41 +57,74 @@ export async function runSubAgent(deps, parent, request) {
         }
     }
     const childCwd = worktreePath ?? deps.cwd;
-    // 实际运行子 agent 的内部函数（sync 与 background 共用）
+    // 4. 构建子 agent 配置：工具集隔离 + 模型覆盖 + 递归限制 + yield
+    const parentDepth = deps._subagentDepth ?? 0;
+    const childDepth = parentDepth + 1;
+    // P1/P2-5：子 agent 工具集无条件取交集（def.tools ∩ 父工具集）——父工具集
+    // 已统一为 resolveEnabledToolNames 的配置解析结果（chat 主 run、CLI print、
+    // 工作流 runner 三处同口径），config.tools.enabled 的 fail-closed 语义对一切
+    // 派生路径成立：全禁时交集为空，子 agent 仅持 yield，写/执行能力不再被
+    // def 固定名单绕过。此前 length>0 例外为工作流 runner 恒 tools=[] 而设，
+    // 子 agent 因而拿到全套固定名单——现 runner 传解析结果，例外不再需要。
+    const declaredTools = def.tools
+        ? def.tools.filter((t) => parent.config.tools.includes(t))
+        : parent.config.tools;
+    const maxRec = def.maxRecursion ?? 0;
+    const baseTools = childDepth > maxRec ? declaredTools.filter((t) => t !== 'task') : declaredTools;
+    const childTools = Array.from(new Set([...baseTools, 'yield']));
+    const childConfig = {
+        ...parent.config,
+        systemPrompt: def.systemPrompt,
+        // 子 agent 走整段 systemPrompt 替换，清除父的 role override 避免干扰
+        agentRolePrompt: undefined,
+        tools: childTools,
+        ...(def.model ? { model: def.model } : {}),
+        ...(request.model ? { model: request.model } : {}),
+    };
+    // 子 agent 的 deps：覆盖 cwd（worktree）+ 注入 yield 收集器 + 递归深度
+    const childDeps = {
+        ...deps,
+        cwd: childCwd,
+        _subagentYieldCollector: (data) => {
+            yielded.push(data);
+        },
+        _subagentDepth: childDepth,
+    };
+    const childState = await createAgent(childSession, childConfig, childDeps);
+    // 继承父 agent 的「预算已确认超支」标记：父 run 已因预算暂停、用户点「恢复」
+    // 继续后，子 agent 不应再因同一预算超支提前中止（用户已知情继续）；父未超支
+    // 时标记为 undefined，子 agent 自跑其 loop 仍会按轮次独立检查预算。
+    childState.budgetPauseTriggered = parent.budgetPauseTriggered;
+    // abort 链接：父 abort 则子 abort
+    if (parent.abortController.signal.aborted) {
+        childState.abortController.abort();
+    }
+    else {
+        parent.abortController.signal.addEventListener('abort', () => childState.abortController.abort(), { once: true });
+    }
+    // P1：把子 run（同步 + 后台）注册进宿主 run 跟踪器（Web=agentManager）。
+    // 此前子 run 完全游离：暂停（权限超时/用户/预算）、热更新 pauseAll、
+    // 删除父会话的中止级联、更新影响面列表全部绕过后台子 agent。
+    // 注册必须先于 dispatch：background 路径「返回 running」时子 run 已可被控制。
+    const unregisterChild = deps.registerChildRun?.({
+        sessionId: childSession.id,
+        parentSessionId: parent.session.id,
+        ...(request.background ? { jobId: childSession.id } : {}),
+        state: childState,
+        deps: childDeps,
+    });
+    // 实际运行子 agent 的内部函数（sync 与 background 共用）。
+    // 无论正常完成/出错/被中止，finally 中注销宿主注册，避免 run 槽位泄漏。
     const runBody = async () => {
-        // 4. 构建子 agent 配置：工具集隔离 + 模型覆盖 + 递归限制 + yield
-        const parentDepth = deps._subagentDepth ?? 0;
-        const childDepth = parentDepth + 1;
-        const declaredTools = def.tools ?? parent.config.tools;
-        const maxRec = def.maxRecursion ?? 0;
-        const baseTools = childDepth > maxRec ? declaredTools.filter((t) => t !== 'task') : declaredTools;
-        const childTools = Array.from(new Set([...baseTools, 'yield']));
-        const childConfig = {
-            ...parent.config,
-            systemPrompt: def.systemPrompt,
-            // 子 agent 走整段 systemPrompt 替换，清除父的 role override 避免干扰
-            agentRolePrompt: undefined,
-            tools: childTools,
-            ...(def.model ? { model: def.model } : {}),
-            ...(request.model ? { model: request.model } : {}),
-        };
-        // 子 agent 的 deps：覆盖 cwd（worktree）+ 注入 yield 收集器 + 递归深度
-        const childDeps = {
-            ...deps,
-            cwd: childCwd,
-            _subagentYieldCollector: (data) => {
-                yielded.push(data);
-            },
-            _subagentDepth: childDepth,
-        };
-        const childState = await createAgent(childSession, childConfig, childDeps);
-        // abort 链接：父 abort 则子 abort
-        if (parent.abortController.signal.aborted) {
-            childState.abortController.abort();
+        try {
+            return await runChildBody(childState, childDeps, childSession, title, baseline, worktreePath);
         }
-        else {
-            parent.abortController.signal.addEventListener('abort', () => childState.abortController.abort(), { once: true });
+        finally {
+            unregisterChild?.();
         }
+    };
+    // 子 agent loop 执行体：运行 loop → worktree delta 回传 → 发射结束事件。
+    const runChildBody = async (childState, childDeps, childSession, title, baseline, worktreePath) => {
         // 运行子 agent loop
         const childPrompt = request.context
             ? `CONTEXT\n${request.context}\n\nASSIGNMENT\n${request.prompt}`

package/dist/core/loop.d.ts

@@ -12,6 +12,13 @@ type LoopDeps = AgentDependencies & {
     readonly _subagentEventSink?: (event: AgentEvent) => void;
     /** 当前递归深度（0=顶层主 agent）。用于 maxRecursion 控制（spec §4.5 step 4）。 */
     readonly _subagentDepth?: number;
+    /** P3 成本护栏：Web 会话「启用预算检查」的门禁。具体 pause/abort 由
+     *  budgetOverageParts 按超支轴配置动作判定（abort > pause），此处仅表启用。
+     *  由 chat 路由按 usage 任一轴动作为 'pause'/'abort' 注入。 */
+    readonly budgetPause?: boolean;
+    /** 预算护栏的 CLI 变体：无恢复 UI，超支时**中止 run**并产出 error（而非暂停挂起）。
+     *  由 CLI deps 组装（buildAgentDeps）按 usage 动作注入，替代 budgetPause（恒 abort）。 */
+    readonly budgetAbort?: boolean;
 };
 export type { LoopDeps };
 export declare function agentLoop(state: AgentState, deps: LoopDeps): AsyncGenerator<AgentEvent>;

package/dist/core/loop.js

@@ -3,8 +3,9 @@ import { resolveRoute } from '../llm/registry.js';
 import { detectProjectInfo } from '../project/detect.js';
 import { entriesToChatMessages, getSessionContext } from '../session/context.js';
 import { getMessages } from '../session/message.js';
-import { updateSessionLastRun } from '../session/session.js';
+import { markBudgetPause, updateSessionLastRun } from '../session/session.js';
 import { estimateTokens } from '../session/token.js';
+import { budgetOverageParts } from '../session/usage.js';
 import { calibrateEstimate, createTokenBudget, estimateBudget } from './context.js';
 import { runCompactionIfNeeded } from './loop/compaction.js';
 import { persistAssistantAndTools } from './loop/persist.js';
@@ -22,6 +23,8 @@ const FALLBACK_CONTEXT_WINDOW = 32_000;
 /** 每个 agent 已解析的有效 contextWindow 缓存（真实值或保守估计）。
  *  避免每轮重复解析/告警，并防止估计值随每轮 input token 抖动导致预算基准漂移。 */
 const effectiveContextWindowCache = new WeakMap();
+/** 已记录「金额口径低估」告警的 agent（每 run 至多记一次，防逐轮刷屏）。 */
+const budgetWarnedStates = new WeakSet();
 /**
  * 解析本轮有效 contextWindow，确保 shouldCompact 始终有合理基准：
  *  - provider 已声明（capabilities.contextWindow 为正数）→ 原样采用，不改变正常配置行为。
@@ -85,6 +88,82 @@ export async function* agentLoop(state, deps) {
             if (state.status._tag === 'paused')
                 return; // 等待期间被 abort 等终结
         }
+        // 预算护栏：金额 + token 双口径（token 兜底价格未知的自建网关/未登记模型），
+        // 每轮 LLM 请求前检查。每 run 至多触发一次（budgetPauseTriggered），恢复后
+        // 用户已知情继续。deps.budgetPause 由 Web 路由按配置注入；deps.budgetAbort
+        // 由 CLI 组装注入（无恢复 UI，超支中止而非暂停挂起）。
+        // 顶层 agent：超支 → 暂停（Web，可恢复）/ 中止（CLI，产出 error）。
+        // 子 agent：无恢复 UI，超支 → 提前中止自身（把超支作为错误回报父 agent，父
+        //   run 下一轮检查将暂停）——收紧子 agent 单轮内 fan-out 的超支粒度。
+        if ((deps.budgetPause === true || deps.budgetAbort === true) && !state.budgetPauseTriggered) {
+            try {
+                const { parts, action, warnings } = await budgetOverageParts(deps.db, deps.config.usage, state.session.projectId);
+                if (parts.length > 0) {
+                    state.budgetPauseTriggered = true;
+                    const reason = `月度预算超支（${parts.join('；')}）${warnings.length > 0 ? `；注意：${warnings.join('；')}` : ''}`;
+                    if (deps._subagentDepth === undefined) {
+                        // CLI（budgetAbort）恒中止；Web 按超支轴配置动作判定（abort > pause）。
+                        if (deps.budgetAbort === true || action === 'abort') {
+                            state.status = {
+                                _tag: 'stopped',
+                                reason: 'error',
+                                error: { _tag: 'unexpected', message: reason },
+                            };
+                            yield { _tag: 'error', error: { _tag: 'unexpected', message: reason } };
+                            return;
+                        }
+                        state.status = { _tag: 'paused', pauseReason: reason };
+                        yield { _tag: 'status_change', status: state.status };
+                        await updateSessionLastRun(deps.db, state.session.id, {
+                            status: 'paused',
+                            agentName: state.config.agentName,
+                            provider: state.config.provider,
+                            model: state.config.model,
+                            startedAt: state.lastRunStartedAt ?? Date.now(),
+                        }).catch(() => { });
+                        // P2-3：暂停原因落盘——热更新/重启后 run 重建，消费此标记还原
+                        // budgetPauseTriggered，避免同一超支原因二次暂停打断用户。
+                        await markBudgetPause(deps.db, state.session.id, reason).catch(() => { });
+                        await waitForResume(state);
+                        if (state.status._tag === 'paused')
+                            return;
+                    }
+                    else {
+                        state.status = {
+                            _tag: 'stopped',
+                            reason: 'error',
+                            error: { _tag: 'unexpected', message: reason },
+                        };
+                        yield { _tag: 'error', error: { _tag: 'unexpected', message: reason } };
+                        return;
+                    }
+                }
+                else if (warnings.length > 0 && !budgetWarnedStates.has(state)) {
+                    // P2-2：未超支但金额口径不可靠（价格未知调用无 token 兜底）——每 run
+                    // 记日志一次，不阻断。用户主动看日志即可发现「预算未真正兜底」。
+                    budgetWarnedStates.add(state);
+                    console.warn(`[usage] 预算金额口径低估告警：${warnings.join('；')}`);
+                }
+            }
+            catch (err) {
+                // 账本查询失败：记录告警。'warn'/'pause' 路径 fail-open（可用性优先）；
+                // 'abort' 路径（用户显式要求硬封顶）保守 fail-closed——账本不可用即无法
+                // 保证「绝不超限」，宁可本轮中止并明示，而非静默放行继续烧钱。
+                console.error('[usage] 预算护栏账本查询失败：', err);
+                const abortSeverity = deps.config.usage.budgetAction === 'abort' ||
+                    deps.config.usage.tokenBudgetAction === 'abort';
+                if (abortSeverity) {
+                    const reason = '月度预算账本查询失败且预算动作为 abort（硬封顶）：无法确认是否超支，出于安全中止本轮';
+                    state.status = {
+                        _tag: 'stopped',
+                        reason: 'error',
+                        error: { _tag: 'unexpected', message: reason },
+                    };
+                    yield { _tag: 'error', error: { _tag: 'unexpected', message: reason } };
+                    return;
+                }
+            }
+        }
         state.status = { _tag: 'running', turnCount: turn };
         const steering = drainSteering(state);
         const { entries, snapshots } = await getSessionContext(deps.db, state.session.id, deps.cwd);
@@ -198,18 +277,23 @@ export async function* agentLoop(state, deps) {
         }
         const totalLatency = Date.now() - requestStartTime;
         let contextWindow;
-        let computedCost = 0;
+        // H2：价格未知时 cost=null（聚合按 $0 计 + 显式计数），不再静默记 0。
+        // 未知判定：provider 未注册/解析失败，或模型价目全为 0（未声明价格的
+        // 自建网关模型回退到 DEFAULT_MODEL_CAPABILITIES 的 0 价）。
+        let computedCost = null;
         try {
             const { capabilities } = resolveRoute(deps.llmRegistry, state.config.provider, state.config.model);
             contextWindow = capabilities.contextWindow;
             const inputTokens = collected.usage?.inputTokens ?? 0;
             const outputTokens = collected.usage?.outputTokens ?? 0;
-            computedCost =
-                (inputTokens / 1000) * capabilities.costPer1kInput +
-                    (outputTokens / 1000) * capabilities.costPer1kOutput;
+            if (capabilities.costPer1kInput > 0 || capabilities.costPer1kOutput > 0) {
+                computedCost =
+                    (inputTokens / 1000) * capabilities.costPer1kInput +
+                        (outputTokens / 1000) * capabilities.costPer1kOutput;
+            }
         }
         catch {
-            // provider 未注册或模型未知：保留 contextWindow=undefined、cost=0
+            // provider 未注册：保留 contextWindow=undefined、cost=null
         }
         // —— contextWindow 兜底 + token 预算同步 ——
         // provider 未声明 contextWindow 时回填保守估计（见 resolveEffectiveContextWindow），

package/dist/core/slash.d.ts

@@ -10,6 +10,16 @@ type SlashRegistry = {
     register: (cmd: SlashCommand) => void;
 };
 declare function createSlashRegistry(): SlashRegistry;
+/**
+ * P0-2：统一斜杠命令启用判定（Web chat / CLI chat / 命令列表 / /help 共用）。
+ * 语义（fail-closed，与 tools.enabled 对齐）：
+ *  - enabled 含 '*'（通配）→ 全部启用。
+ *  - enabled 为显式名单 → 仅名单内启用（名称兼容带/不带前缀斜杠）。
+ *  - enabled 为空数组/缺失 → 全部禁用（旧版含义「空=全部启用」，升级告警见
+ *    collectConfigMigrationWarnings——两处同形键不再语义相反）。
+ * `enabled` 已含 '/' 前缀或裸名均可。
+ */
+export declare function isSlashCommandEnabled(enabled: string[] | undefined, name: string): boolean;
 declare const builtinCommands: SlashCommand[];
 export type { SlashRegistry };
 export { builtinCommands, createSlashRegistry, parseSlashInput };