@armadra/agent 0.3.0 → 0.5.0

package/dist/codemode/host-side.d.ts

@@ -12,7 +12,13 @@
  *   （完整门禁）；名字是 `codemode` 直接拒绝。脚本结束时 abort 仍在跑的调用。
  * - 超时：父进程计时，到点杀子进程树（POSIX 进程组 / Windows taskkill）；外层 abort：先发
  *   `abort`，宽限后杀树。
+ * - OS 沙箱（docs/sandbox.md）：有可用的 sandbox-exec / bwrap / unshare 时，整条命令行经它启动，拒绝
+ *   网络与一切写入（`CODEMODE_OS_POLICY`；子进程本来就没有写权限）。Node 22 / 24 的 strict 依赖这一层
+ *   （`requireOsSandbox`），包装不了就报错，不裸跑；Node ≥ 25 是叠加的纵深防御。
  */
+import { type OsSandboxStatus } from "../sandbox/detect.js";
+import type { OsSandboxPolicy } from "../sandbox/profile.js";
+import { type WrappedCommand } from "../sandbox/wrap.js";
 import { type SandboxCapability } from "./capability.js";
 import { type ScriptOptions, type StoreSnapshot, type ToolDecl } from "./protocol.js";
 /** 父进程累积的输出上限（字符）；超出后丢弃中段（给模型的再按 max_output_tokens 截）。 */
@@ -23,6 +29,10 @@ export declare const ABORT_GRACE_MS = 500;
 export declare function resolveSandboxEntry(moduleUrl?: string): string | undefined;
 /** 子进程参数（不含可执行文件）。 */
 export declare function sandboxArgs(entry: string, capability?: Pick<SandboxCapability, "permissionFlag">): string[];
+/** codemode 子进程的 OS 沙箱策略：拒绝网络，任何位置都不可写。 */
+export declare const CODEMODE_OS_POLICY: OsSandboxPolicy;
+/** 完整命令行：`<node> <sandboxArgs>`，有 OS 沙箱时再经它包装。 */
+export declare function sandboxCommand(nodePath: string, args: readonly string[], os: Pick<OsSandboxStatus, "kind" | "path">): WrappedCommand;
 /** 子进程环境：空；Electron 下以 Node 方式运行同一可执行文件；Windows 保留 SystemRoot。 */
 export declare function sandboxEnv(versions?: NodeJS.ProcessVersions, platform?: NodeJS.Platform, parentEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export interface SandboxRunRequest {
@@ -39,6 +49,10 @@ export interface SandboxRunRequest {
     /** 缺省 process.execPath。 */
     nodePath?: string;
     capability?: Pick<SandboxCapability, "permissionFlag">;
+    /** 缺省 osSandboxStatus()（进程内缓存的探测结果）。 */
+    os?: Pick<OsSandboxStatus, "kind" | "path">;
+    /** true：必须经 OS 沙箱启动（Node 22 / 24 的 strict 依赖它），包装不了直接失败。 */
+    requireOsSandbox?: boolean;
 }
 export interface SandboxRunResult {
     ok: boolean;

package/dist/codemode/host-side.js

@@ -12,11 +12,16 @@
  *   （完整门禁）；名字是 `codemode` 直接拒绝。脚本结束时 abort 仍在跑的调用。
  * - 超时：父进程计时，到点杀子进程树（POSIX 进程组 / Windows taskkill）；外层 abort：先发
  *   `abort`，宽限后杀树。
+ * - OS 沙箱（docs/sandbox.md）：有可用的 sandbox-exec / bwrap / unshare 时，整条命令行经它启动，拒绝
+ *   网络与一切写入（`CODEMODE_OS_POLICY`；子进程本来就没有写权限）。Node 22 / 24 的 strict 依赖这一层
+ *   （`requireOsSandbox`），包装不了就报错，不裸跑；Node ≥ 25 是叠加的纵深防御。
  */
 import { spawn } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { osSandboxStatus } from "../sandbox/detect.js";
+import { wrapCommand } from "../sandbox/wrap.js";
 import { killProcessTree, trackProcessGroup, untrackProcessGroup } from "../tools/process-tree.js";
 import { detectSandboxCapability } from "./capability.js";
 import { LineSplitter, SANDBOX_MAIN_FLAG, decodeChildLine, encodeLine, } from "./protocol.js";
@@ -49,6 +54,15 @@ export function sandboxArgs(entry, capability = detectSandboxCapability()) {
         SANDBOX_MAIN_FLAG,
     ];
 }
+/** codemode 子进程的 OS 沙箱策略：拒绝网络，任何位置都不可写。 */
+export const CODEMODE_OS_POLICY = Object.freeze({
+    network: "deny",
+    writable: Object.freeze([]),
+});
+/** 完整命令行：`<node> <sandboxArgs>`，有 OS 沙箱时再经它包装。 */
+export function sandboxCommand(nodePath, args, os) {
+    return wrapCommand(os, nodePath, args, CODEMODE_OS_POLICY);
+}
 /** 子进程环境：空；Electron 下以 Node 方式运行同一可执行文件；Windows 保留 SystemRoot。 */
 export function sandboxEnv(versions = process.versions, platform = process.platform, parentEnv = process.env) {
     const env = {};
@@ -82,8 +96,17 @@ export async function runSandbox(request) {
     if (request.signal.aborted) {
         return { ...base, ok: false, error: "Script aborted", aborted: true, elapsedMs: 0 };
     }
+    const command = sandboxCommand(request.nodePath ?? process.execPath, sandboxArgs(entry, request.capability), request.os ?? osSandboxStatus());
+    if (request.requireOsSandbox === true && !command.networkDenied) {
+        return {
+            ...base,
+            ok: false,
+            error: "codemode sandbox requires an OS sandbox to isolate network, but none is available",
+            elapsedMs: 0,
+        };
+    }
     const isWindows = process.platform === "win32";
-    const child = spawn(request.nodePath ?? process.execPath, sandboxArgs(entry, request.capability), {
+    const child = spawn(command.command, command.args, {
         env: sandboxEnv(),
         stdio: ["pipe", "pipe", "pipe"],
         detached: !isWindows,

package/dist/codemode/modes.d.ts

@@ -4,20 +4,13 @@
  * | 模式   | 模型看到的工具                                                             |
  * | ------ | -------------------------------------------------------------------------- |
  * | `off`  | 不注册 codemode（工厂返回 undefined）                                       |
- * | `on`   | 预设的工具 + codemode；其它工具描述末尾加一行「也可在 codemode 脚本里调用」 |
+ * | `on`   | 预设的工具 + codemode；codemode 描述一行列出可在脚本里调用的直接工具       |
  * | `only` | 只有 codemode（宿主 / SDK 工具也不直接暴露）；其它工具的声明列在它的描述里 |
  *
- * 活动集由 B6 的 `resolvePreset` 决定（`only` → `["codemode"]`）；这里补两件事：`on` 模式下的描述
- * 追加（在注册前包一层，描述在会话开始时就确定、字节稳定）与 `only` 模式的独占活动集
- * （`PresetToolRegistry.setPresetTools(names, { exclusive: true })`）。
+ * 活动集由 B6 的 `resolvePreset` 决定（`only` → `["codemode"]`）；这里落 `only` 模式的独占活动集
+ * （`PresetToolRegistry.setPresetTools(names, { exclusive: true })`）。`on` 模式不再给其它工具的描述
+ * 追加提示：直接工具的描述与 off 模式逐字节相同，codemode 描述里一行列出它们（codemode/tool.ts）。
  */
-import type { CodemodeMode } from "../config/types.js";
 import { type PresetResolution, type PresetToolRegistry } from "../tools/presets.js";
-import type { ToolDefinition } from "../tools/types.js";
-export declare function codemodeHint(name: string): string;
-/** 复制工具（保留 getter 与方法），描述末尾追加一行 codemode 提示。 */
-export declare function withCodemodeHint<I>(tool: ToolDefinition<I>): ToolDefinition<I>;
-/** 注册前的包装：`on` 模式给 codemode 以外的工具加提示，其它模式原样返回。 */
-export declare function decorateForMode(mode: CodemodeMode): <I>(tool: ToolDefinition<I>) => ToolDefinition<I>;
 /** 把预设结果落到注册表：`only` 时活动集独占（宿主 / SDK 工具也只能在脚本里调用）。 */
 export declare function applyCodemodeMode(registry: PresetToolRegistry, resolution: Pick<PresetResolution, "builtin" | "codemode">): void;

package/dist/codemode/modes.js

@@ -4,36 +4,14 @@
  * | 模式   | 模型看到的工具                                                             |
  * | ------ | -------------------------------------------------------------------------- |
  * | `off`  | 不注册 codemode（工厂返回 undefined）                                       |
- * | `on`   | 预设的工具 + codemode；其它工具描述末尾加一行「也可在 codemode 脚本里调用」 |
+ * | `on`   | 预设的工具 + codemode；codemode 描述一行列出可在脚本里调用的直接工具       |
  * | `only` | 只有 codemode（宿主 / SDK 工具也不直接暴露）；其它工具的声明列在它的描述里 |
  *
- * 活动集由 B6 的 `resolvePreset` 决定（`only` → `["codemode"]`）；这里补两件事：`on` 模式下的描述
- * 追加（在注册前包一层，描述在会话开始时就确定、字节稳定）与 `only` 模式的独占活动集
- * （`PresetToolRegistry.setPresetTools(names, { exclusive: true })`）。
+ * 活动集由 B6 的 `resolvePreset` 决定（`only` → `["codemode"]`）；这里落 `only` 模式的独占活动集
+ * （`PresetToolRegistry.setPresetTools(names, { exclusive: true })`）。`on` 模式不再给其它工具的描述
+ * 追加提示：直接工具的描述与 off 模式逐字节相同，codemode 描述里一行列出它们（codemode/tool.ts）。
  */
-import { CODEMODE_TOOL } from "../tools/presets.js";
-export function codemodeHint(name) {
-    return `Also callable inside codemode scripts as tools.${name}(args).`;
-}
-/** 复制工具（保留 getter 与方法），描述末尾追加一行 codemode 提示。 */
-export function withCodemodeHint(tool) {
-    const copy = Object.create(Object.getPrototypeOf(tool), {
-        ...Object.getOwnPropertyDescriptors(tool),
-    });
-    Object.defineProperty(copy, "description", {
-        value: `${tool.description}\n${codemodeHint(tool.name)}`,
-        enumerable: true,
-        writable: false,
-        configurable: true,
-    });
-    return copy;
-}
-/** 注册前的包装：`on` 模式给 codemode 以外的工具加提示，其它模式原样返回。 */
-export function decorateForMode(mode) {
-    if (mode !== "on")
-        return (tool) => tool;
-    return (tool) => (tool.name === CODEMODE_TOOL ? tool : withCodemodeHint(tool));
-}
+import {} from "../tools/presets.js";
 /** 把预设结果落到注册表：`only` 时活动集独占（宿主 / SDK 工具也只能在脚本里调用）。 */
 export function applyCodemodeMode(registry, resolution) {
     registry.setPresetTools(resolution.builtin, { exclusive: resolution.codemode === "only" });

package/dist/codemode/tool.d.ts

@@ -12,7 +12,11 @@
  * - store 只在脚本成功时提交（store.ts）；
  * - 描述（含工具声明）在第一次读取时确定并冻结：同一会话内字节稳定（设计 §9.1），之后注册的宿主
  *   工具仍可在脚本里调用（`ALL_TOOLS` / `describeTool` 是执行时的清单）。
+ * - 描述分两种（`buildCodemodeDescription` 的 `layout`）：`only` 模式按预算内联全部工具声明；`on`
+ *   模式不重复已直接暴露给模型的工具（它们的 schema 已在工具表里），只用一行列出名字，「仅脚本可
+ *   调用」的工具也只列名字（`describeTool(name)` 取签名），把 on 模式的前缀增量压在约 400 token。
  */
+import type { AmaConfig } from "../config/types.js";
 import type { ToolDefinition, ToolResult } from "../tools/types.js";
 import { type SandboxCapability } from "./capability.js";
 import { type DeclarableTool } from "./declarations.js";
@@ -25,6 +29,8 @@ export interface CallableTool {
     tool: DeclarableTool;
     /** 内置工具（非 bash）解析为文本；宿主 / SDK 工具可能返回结构化值。 */
     textResult: boolean;
+    /** 模型也能直接调用（在活动集里）；`on` 模式的描述只列名字。 */
+    direct?: boolean;
 }
 export interface CodemodeToolOptions {
     /** 脚本里可调用的工具（不含 codemode 本身）；描述冻结时与每次执行时各调用一次。 */
@@ -37,6 +43,8 @@ export interface CodemodeToolOptions {
     maxResultChars?: number;
     /** `only` 模式：其它工具不直接暴露，系统提示的工具行与规则写明只能在脚本里调用。 */
     exclusive?: boolean;
+    /** 描述的写法：缺省 `only`（按预算内联声明）；`on` 只列名字（见 `buildCodemodeDescription`）。 */
+    layout?: DescriptionLayout;
     /** 子进程入口（测试 / 嵌入方覆盖）。 */
     entry?: string;
     nodePath?: string;
@@ -68,7 +76,8 @@ export declare const CODEMODE_EXAMPLE: readonly string[];
  * （实测模型常见的两种错误）。其它错误原样返回。
  */
 export declare function scriptErrorHint(error: string, toolNames: readonly string[]): string;
-export declare function buildCodemodeDescription(tools: readonly CallableTool[], inlineBudget: number, capability: SandboxCapability): string;
+export type DescriptionLayout = "only" | "on";
+export declare function buildCodemodeDescription(tools: readonly CallableTool[], inlineBudget: number, capability: SandboxCapability, layout?: DescriptionLayout): string;
 /** 结果文本：状态行 + 输出（超限保留首尾）+ 失败原因。 */
 export declare function formatCodemodeResult(run: Pick<SandboxRunResult, "ok" | "error" | "outputs" | "elapsedMs" | "droppedChars">, limitChars: number, saveFull: (text: string) => string | undefined): {
     text: string;
@@ -79,27 +88,22 @@ export declare const CODEMODE_ONLY_GUIDELINE = "read, edit, write, bash and the
 export declare function createCodemodeTool(options: CodemodeToolOptions): ToolDefinition<CodemodeInput>;
 /** 组装根用：从 ToolFactoryContext 的形状取所需（避免 codemode → cli 的依赖）。 */
 export interface CodemodeFactoryContext {
-    config: {
-        codemode?: {
-            mode?: "off" | "on" | "only";
-            inlineBudget?: number;
-            requireStrict?: boolean;
-        };
-        tools?: {
-            preset?: string;
-            maxToolResultChars?: number;
-        };
-    };
+    config: Pick<AmaConfig, "tools" | "codemode" | "sandbox">;
     registry: {
         list(): readonly string[];
         get(name: string): ToolDefinition | undefined;
     } & {
         sourceOf?(name: string): string | undefined;
+        /** 活动集（coordinator 预设下脚本只能调这些）。 */
+        active?(): readonly {
+            name: string;
+        }[];
     };
     warn(message: string): void;
 }
 /**
- * codemode 工具工厂：`codemode.mode` 生效值为 off → 不注册；`requireStrict` 而运行时不隔离网络
- * → 不注册并 warning（预设随之回退到 default）。
+ * codemode 工具工厂：生效模式（显式 `codemode.mode`，否则跟随预设，见 tools/presets.ts）为 off →
+ * 不注册；`requireStrict` 而运行时不隔离网络 → 不注册并 warning（预设随之回退到 default）。
+ * `coordinator` 预设下脚本可调用的工具限于活动集（不含 codemode 本身）。
  */
 export declare function codemodeToolFactory(overrides?: Partial<Pick<CodemodeToolOptions, "capability" | "entry" | "nodePath">>): (ctx: CodemodeFactoryContext) => ToolDefinition | undefined;

package/dist/codemode/tool.js

@@ -12,14 +12,17 @@
  * - store 只在脚本成功时提交（store.ts）；
  * - 描述（含工具声明）在第一次读取时确定并冻结：同一会话内字节稳定（设计 §9.1），之后注册的宿主
  *   工具仍可在脚本里调用（`ALL_TOOLS` / `describeTool` 是执行时的清单）。
+ * - 描述分两种（`buildCodemodeDescription` 的 `layout`）：`only` 模式按预算内联全部工具声明；`on`
+ *   模式不重复已直接暴露给模型的工具（它们的 schema 已在工具表里），只用一行列出名字，「仅脚本可
+ *   调用」的工具也只列名字（`describeTool(name)` 取签名），把 on 模式的前缀增量压在约 400 token。
  */
 import { mkdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { codemodeAvailability, detectSandboxCapability, } from "./capability.js";
-import { DEFAULT_INLINE_BUDGET, buildDeclarationBlock, toolDeclaration, } from "./declarations.js";
+import { codemodeCallableFilter, resolveCodemodeMode } from "../tools/presets.js";
+import { codemodeAvailability, detectSandboxCapability, sandboxCapabilityFor, strictNeedsOsSandbox, } from "./capability.js";
+import { BASH_RESULT_DECLARATION, DEFAULT_INLINE_BUDGET, buildDeclarationBlock, toolDeclaration, } from "./declarations.js";
 import { runSandbox } from "./host-side.js";
-import { codemodeHint } from "./modes.js";
 import { parseOptionsLine } from "./protocol.js";
 import { commitStore, readStore } from "./store.js";
 export const CODEMODE_TOOL_NAME = "codemode";
@@ -54,13 +57,6 @@ export function toScriptValue(name, result) {
         throw new Error(textOf(result.content) || `Tool ${name} failed`);
     return result.structured !== undefined ? result.structured : textOf(result.content);
 }
-/** on 模式下其它工具描述末尾的提示不进声明。 */
-function declarable(tool) {
-    const suffix = `\n${codemodeHint(tool.name)}`;
-    if (!tool.description.endsWith(suffix))
-        return tool;
-    return { ...tool, description: tool.description.slice(0, -suffix.length) };
-}
 /** 描述里的示例脚本（6 行）：并发两个 read、过滤、return。 */
 export const CODEMODE_EXAMPLE = [
     "const [a, b] = await Promise.all([",
@@ -86,7 +82,39 @@ export function scriptErrorHint(error, toolNames) {
     }
     return error;
 }
-export function buildCodemodeDescription(tools, inlineBudget, capability) {
+/**
+ * `on` 模式的描述：规则压成三行 + 示例；已直接暴露的工具只列名字（参数同直接调用），仅脚本可调用的
+ * 工具也只列名字。不内联任何声明，字节只依赖工具名与沙箱能力。
+ */
+function buildOnDescription(tools, capability) {
+    const names = (list) => list
+        .map(({ tool }) => tool.name)
+        .sort()
+        .join(", ");
+    const direct = tools.filter((t) => t.direct === true);
+    const scriptOnly = tools.filter((t) => t.direct !== true);
+    const lines = [
+        "Run a JavaScript script that calls tools; only its output comes back to you. Use it to batch many tool calls (Promise.all), filter or summarize large results, or loop, in one step.",
+        "Input: raw JavaScript (not JSON, no code fence), the body of an async function (top-level await and return work). Only tools.<name>(args) exists: no require, import, process, fetch or timers.",
+        "Example:",
+        ...CODEMODE_EXAMPLE,
+        "tools.<name>(args) returns a Promise that rejects when the call fails or is denied (Promise.allSettled keeps the rest); text(v) / console.log(...) append output; return v is text(v); store(key, v) / load(key) keep small JSON values across scripts; describeTool(name) returns a signature. At most 8 calls run at once, each through the normal permissions.",
+    ];
+    if (!capability.strict)
+        lines.push(`Sandbox: ${capability.reason}.`);
+    if (direct.length > 0) {
+        const bash = direct.some(({ tool }) => tool.name === "bash");
+        lines.push(`Your direct tools are callable here too, same arguments: ${names(direct)}${bash ? " (tools.bash resolves to BashResult; the others to text)" : ""}.`);
+        if (bash)
+            lines.push(BASH_RESULT_DECLARATION);
+    }
+    if (scriptOnly.length > 0)
+        lines.push(`Callable only from scripts: ${names(scriptOnly)}.`);
+    return lines.join("\n");
+}
+export function buildCodemodeDescription(tools, inlineBudget, capability, layout = "only") {
+    if (layout === "on")
+        return buildOnDescription(tools, capability);
     const lines = [
         "Run a JavaScript script that calls tools; only the script's output comes back to you. Use it to batch many tool calls (Promise.all), filter or summarize large results, or loop, in one step.",
         "Only tools.<name>(args) is available. There is no require, import, process, fetch or timers; do not call tools directly as functions.",
@@ -98,7 +126,7 @@ export function buildCodemodeDescription(tools, inlineBudget, capability) {
     if (!capability.strict) {
         lines.push(`Sandbox: ${capability.reason}.`);
     }
-    const block = buildDeclarationBlock(tools.map(({ tool, textResult }) => ({ tool: declarable(tool), textResult })), inlineBudget);
+    const block = buildDeclarationBlock(tools.map(({ tool, textResult }) => ({ tool, textResult })), inlineBudget);
     if (block.text !== "")
         lines.push(block.text);
     return lines.join("\n");
@@ -151,7 +179,7 @@ export function createCodemodeTool(options) {
         name: CODEMODE_TOOL_NAME,
         label: "Codemode",
         get description() {
-            frozenDescription ??= buildCodemodeDescription(options.listTools(), inlineBudget, capability);
+            frozenDescription ??= buildCodemodeDescription(options.listTools(), inlineBudget, capability, options.layout);
             return frozenDescription;
         },
         parameters: {
@@ -161,8 +189,8 @@ export function createCodemodeTool(options) {
             },
             required: ["script"],
         },
-        // 网络隔离（Node ≥ 25）时脚本只能经 tools.* 做事，每次内层调用各自过权限：codemode 本身按 read
-        // 类（default 模式免审批）；不隔离网络时脚本逃出 vm 就能联网，仍按 execute。
+        // 网络隔离（Node ≥ 25，或 OS 沙箱）时脚本只能经 tools.* 做事，每次内层调用各自过权限：codemode
+        // 本身按 read 类（default 模式免审批）；不隔离网络时脚本逃出 vm 就能联网，仍按 execute。
         permission: capability.strict ? "read" : "execute",
         executionMode: "sequential",
         promptSnippet: options.exclusive === true
@@ -179,8 +207,10 @@ export function createCodemodeTool(options) {
             }
             const tools = options.listTools().map(({ tool: t, textResult }) => ({
                 name: t.name,
-                declaration: toolDeclaration(declarable(t), textResult ? {} : { textResult: false }),
+                declaration: toolDeclaration(t, textResult ? {} : { textResult: false }),
             }));
+            // 只有清单里的工具可调（coordinator 预设的清单只含活动集）；脚本拼出别的名字也不放行。
+            const callable = new Set(tools.map((t) => t.name));
             let tail = "";
             const run = await runSandbox({
                 script: input.script,
@@ -188,9 +218,15 @@ export function createCodemodeTool(options) {
                 tools,
                 store: readStore(ctx.session),
                 signal: ctx.signal,
+                os: capability.os,
+                requireOsSandbox: strictNeedsOsSandbox(capability),
                 ...(options.entry !== undefined ? { entry: options.entry } : {}),
                 ...(options.nodePath !== undefined ? { nodePath: options.nodePath } : {}),
-                callTool: async (name, args, signal) => toScriptValue(name, await ctx.tools.executeTool(name, args, { signal })),
+                callTool: async (name, args, signal) => {
+                    if (!callable.has(name))
+                        throw new Error(`Tool ${name} is not available in codemode`);
+                    return toScriptValue(name, await ctx.tools.executeTool(name, args, { signal }));
+                },
                 onOutput: (text) => {
                     tail = `${tail}${tail === "" ? "" : "\n"}${text}`.slice(-TAIL_CHARS);
                     ctx.onUpdate(tail);
@@ -240,33 +276,42 @@ export function createCodemodeTool(options) {
     return tool;
 }
 /**
- * codemode 工具工厂：`codemode.mode` 生效值为 off → 不注册；`requireStrict` 而运行时不隔离网络
- * → 不注册并 warning（预设随之回退到 default）。
+ * codemode 工具工厂：生效模式（显式 `codemode.mode`，否则跟随预设，见 tools/presets.ts）为 off →
+ * 不注册；`requireStrict` 而运行时不隔离网络 → 不注册并 warning（预设随之回退到 default）。
+ * `coordinator` 预设下脚本可调用的工具限于活动集（不含 codemode 本身）。
  */
 export function codemodeToolFactory(overrides = {}) {
     return (ctx) => {
-        const explicit = ctx.config.codemode?.mode;
-        const mode = explicit ?? (ctx.config.tools?.preset === "codemode" ? "only" : "off");
+        const capability = overrides.capability ?? sandboxCapabilityFor(ctx.config);
+        const mode = resolveCodemodeMode(ctx.config, capability.strict).mode;
         if (mode === "off")
             return undefined;
-        const availability = codemodeAvailability(ctx.config.codemode?.requireStrict, overrides.capability ?? detectSandboxCapability());
+        const availability = codemodeAvailability(ctx.config.codemode?.requireStrict, capability);
         if (!availability.available) {
             ctx.warn(availability.warning);
             return undefined;
         }
         const registry = ctx.registry;
+        const onlyActive = codemodeCallableFilter(ctx.config) === "active";
+        const allowed = (name) => !onlyActive || (registry.active?.() ?? []).some((tool) => tool.name === name);
+        const direct = () => new Set(mode === "on" ? (registry.active?.() ?? []).map((tool) => tool.name) : []);
         const options = {
             capability: availability.capability,
             exclusive: mode === "only",
-            listTools: () => registry
-                .list()
-                .filter((name) => name !== CODEMODE_TOOL_NAME)
-                .map((name) => registry.get(name))
-                .filter((t) => t !== undefined)
-                .map((t) => ({
-                tool: t,
-                textResult: (registry.sourceOf?.(t.name) ?? "builtin") === "builtin",
-            })),
+            layout: mode === "on" ? "on" : "only",
+            listTools: () => {
+                const active = direct();
+                return registry
+                    .list()
+                    .filter((name) => name !== CODEMODE_TOOL_NAME && allowed(name))
+                    .map((name) => registry.get(name))
+                    .filter((t) => t !== undefined)
+                    .map((t) => ({
+                    tool: t,
+                    textResult: (registry.sourceOf?.(t.name) ?? "builtin") === "builtin",
+                    ...(active.has(t.name) ? { direct: true } : {}),
+                }));
+            },
         };
         const budget = ctx.config.codemode?.inlineBudget;
         if (budget !== undefined)

package/dist/compaction/breaker.d.ts

@@ -1,31 +1,47 @@
 /**
- * 压缩熔断（设计 §9「熔断」）。[B2]
+ * 压缩熔断（设计 §9「熔断」，wave5 §8.2 C5）。[B2][W5-H1]
  *
  * - 无 `contextWindow` 或配置关闭 → 自动压缩关闭（手动 /compact 仍可用）。
- * - 同一 run 内档二（摘要）≤ 1 次（`startRun()` 重置计数）。
- * - 连续两次摘要失败 → 跳闸，关闭自动压缩直到 `reset()`（例如用户手动压缩成功）。
+ * - 不再限制「每 run 档二 ≤ 1 次」（单提示长任务需要多次摘要）；改为两种跳闸：
+ *   - 连续 3 次摘要失败；
+ *   - 快速回填：连续 3 次摘要都在上一次摘要后不到 3 回合就又需要摘要（压缩不动、越压越满）。
+ *   跳闸后关闭自动压缩直到 `reset()`（例如用户手动压缩成功）。
+ * - 固定前缀（system + 工具表）已超过预算：摘要无济于事，直接告警、不再尝试（`prefix_overflow`，
+ *   由调用方每次检查时更新）。
+ * - 「nothing to compact」不计失败（调用方不调 `recordSummary`）。
  * - 溢出恢复：压缩后估算仍 > 0.8 × window → 不重试。
  */
-export declare const MAX_SUMMARIES_PER_RUN = 1;
-export declare const MAX_CONSECUTIVE_FAILURES = 2;
+export declare const MAX_CONSECUTIVE_FAILURES = 3;
+/** 上一次摘要后不到这么多回合又需要摘要，记一次快速回填。 */
+export declare const RAPID_REFILL_TURNS = 3;
+export declare const MAX_RAPID_REFILLS = 3;
 export declare const RETRY_AFTER_COMPACTION_RATIO = 0.8;
-export type BreakerBlockReason = "disabled" | "no_window" | "tripped" | "run_limit";
+export type BreakerBlockReason = "disabled" | "no_window" | "tripped" | "rapid_refill" | "prefix_overflow";
 export declare class CompactionBreaker {
-    private summariesThisRun;
     private consecutiveFailures;
+    private rapidRefills;
+    private turn;
+    private lastSummaryTurn;
+    private prefixOverflow;
     private enabled;
     private contextWindow;
     constructor(enabled: boolean, contextWindow: number | undefined);
     configure(enabled: boolean, contextWindow: number | undefined): void;
+    /** 连续失败或快速回填跳闸（溢出恢复也不再尝试）。 */
     get tripped(): boolean;
-    /** 自动压缩整体是否开启（不看本 run 计数）。 */
+    /** 自动压缩整体是否开启。 */
     get autoEnabled(): boolean;
+    /** 新 run 开始（会话在 agent_start 时调用）；不再重置任何计数，保留以兼容调用点。 */
     startRun(): void;
+    /** 每次请求前的阈值检查调用一次：回合计数（快速回填按它判断）。 */
+    tick(): void;
+    /** 固定前缀是否已超预算（调用方每次准备摘要前更新）。 */
+    setPrefixOverflow(overflow: boolean): void;
     /** 自动档二能否执行；不能则给出原因。 */
     blockReason(): BreakerBlockReason | undefined;
     canSummarize(): boolean;
     recordSummary(success: boolean): void;
-    /** 手动压缩成功等场景：清零失败计数。 */
+    /** 手动压缩成功等场景：清零全部计数。 */
     reset(): void;
     /** 溢出恢复后是否值得重试。 */
     shouldRetryAfterCompaction(tokensAfter: number): boolean;

package/dist/compaction/breaker.js

@@ -1,17 +1,27 @@
 /**
- * 压缩熔断（设计 §9「熔断」）。[B2]
+ * 压缩熔断（设计 §9「熔断」，wave5 §8.2 C5）。[B2][W5-H1]
  *
  * - 无 `contextWindow` 或配置关闭 → 自动压缩关闭（手动 /compact 仍可用）。
- * - 同一 run 内档二（摘要）≤ 1 次（`startRun()` 重置计数）。
- * - 连续两次摘要失败 → 跳闸，关闭自动压缩直到 `reset()`（例如用户手动压缩成功）。
+ * - 不再限制「每 run 档二 ≤ 1 次」（单提示长任务需要多次摘要）；改为两种跳闸：
+ *   - 连续 3 次摘要失败；
+ *   - 快速回填：连续 3 次摘要都在上一次摘要后不到 3 回合就又需要摘要（压缩不动、越压越满）。
+ *   跳闸后关闭自动压缩直到 `reset()`（例如用户手动压缩成功）。
+ * - 固定前缀（system + 工具表）已超过预算：摘要无济于事，直接告警、不再尝试（`prefix_overflow`，
+ *   由调用方每次检查时更新）。
+ * - 「nothing to compact」不计失败（调用方不调 `recordSummary`）。
  * - 溢出恢复：压缩后估算仍 > 0.8 × window → 不重试。
  */
-export const MAX_SUMMARIES_PER_RUN = 1;
-export const MAX_CONSECUTIVE_FAILURES = 2;
+export const MAX_CONSECUTIVE_FAILURES = 3;
+/** 上一次摘要后不到这么多回合又需要摘要，记一次快速回填。 */
+export const RAPID_REFILL_TURNS = 3;
+export const MAX_RAPID_REFILLS = 3;
 export const RETRY_AFTER_COMPACTION_RATIO = 0.8;
 export class CompactionBreaker {
-    summariesThisRun = 0;
     consecutiveFailures = 0;
+    rapidRefills = 0;
+    turn = 0;
+    lastSummaryTurn;
+    prefixOverflow = false;
     enabled;
     contextWindow;
     constructor(enabled, contextWindow) {
@@ -22,15 +32,23 @@ export class CompactionBreaker {
         this.enabled = enabled;
         this.contextWindow = contextWindow;
     }
+    /** 连续失败或快速回填跳闸（溢出恢复也不再尝试）。 */
     get tripped() {
-        return this.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES;
+        return (this.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES || this.rapidRefills >= MAX_RAPID_REFILLS);
     }
-    /** 自动压缩整体是否开启（不看本 run 计数）。 */
+    /** 自动压缩整体是否开启。 */
     get autoEnabled() {
         return this.enabled && this.contextWindow !== undefined && !this.tripped;
     }
-    startRun() {
-        this.summariesThisRun = 0;
+    /** 新 run 开始（会话在 agent_start 时调用）；不再重置任何计数，保留以兼容调用点。 */
+    startRun() { }
+    /** 每次请求前的阈值检查调用一次：回合计数（快速回填按它判断）。 */
+    tick() {
+        this.turn++;
+    }
+    /** 固定前缀是否已超预算（调用方每次准备摘要前更新）。 */
+    setPrefixOverflow(overflow) {
+        this.prefixOverflow = overflow;
     }
     /** 自动档二能否执行；不能则给出原因。 */
     blockReason() {
@@ -38,23 +56,35 @@ export class CompactionBreaker {
             return "disabled";
         if (this.contextWindow === undefined)
             return "no_window";
-        if (this.tripped)
+        if (this.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES)
             return "tripped";
-        if (this.summariesThisRun >= MAX_SUMMARIES_PER_RUN)
-            return "run_limit";
+        if (this.rapidRefills >= MAX_RAPID_REFILLS)
+            return "rapid_refill";
+        if (this.prefixOverflow)
+            return "prefix_overflow";
         return undefined;
     }
     canSummarize() {
         return this.blockReason() === undefined;
     }
     recordSummary(success) {
-        this.summariesThisRun++;
-        this.consecutiveFailures = success ? 0 : this.consecutiveFailures + 1;
+        if (!success) {
+            this.consecutiveFailures++;
+            return;
+        }
+        this.consecutiveFailures = 0;
+        const last = this.lastSummaryTurn;
+        if (last !== undefined && this.turn - last < RAPID_REFILL_TURNS)
+            this.rapidRefills++;
+        else
+            this.rapidRefills = 0;
+        this.lastSummaryTurn = this.turn;
     }
-    /** 手动压缩成功等场景：清零失败计数。 */
+    /** 手动压缩成功等场景：清零全部计数。 */
     reset() {
         this.consecutiveFailures = 0;
-        this.summariesThisRun = 0;
+        this.rapidRefills = 0;
+        this.lastSummaryTurn = undefined;
     }
     /** 溢出恢复后是否值得重试。 */
     shouldRetryAfterCompaction(tokensAfter) {

package/dist/compaction/estimate.d.ts

@@ -2,15 +2,23 @@
  * 上下文 token 估算（设计 §9「估算」）。[B2]
  *
  * `contextTokens` = 最后一条非 error / aborted 助手消息的 `totalTokens`（缺则
- * `input + output + cacheRead + cacheWrite`，**含 output**）+ 其后消息的估算（字符 / 4，图片 1 600）。
+ * `input + output + cacheRead + cacheWrite`，**含 output**）+ 其后消息的估算（图片 1 600）。
  * 若该 usage 之后活动分支上出现过 `context_edit` 或 `compaction`，usage 不再可信，按投影全量重估。
+ *
+ * [W5-H1] 文本估算按脚本区分（wave5 D28 / C10）：CJK 统一表意文字（含扩展区与兼容区）、假名、
+ * 谚文、CJK 符号与全角形式每字 1 token，其余字符合计 / 4 向上取整。「字符 / 4」对中文低估 3–4 倍，
+ * 中文会话会晚触发直至溢出；所有阈值（档一、档二、保留区）都用这个口径。
  */
-import type { Usage } from "../ai/types.js";
+import type { ContentBlock, Usage } from "../ai/types.js";
 import type { ContextItem } from "../session/projection.js";
 import type { AgentMessage, SessionEntry } from "../session/types.js";
 export declare const IMAGE_TOKENS = 1600;
+/** 文本的 token 估算：CJK / 假名 / 谚文每字 1，其余字符 / 4（向上取整）。 */
+export declare function estimateTextTokens(text: string): number;
 export declare function calculateContextTokens(usage: Usage): number;
-/** 单条消息的估算（字符 / 4 向上取整，图片每张 1 600）。 */
+/** 内容的估算（文本按脚本，图片每张 1 600）。 */
+export declare function estimateContentTokens(content: string | readonly ContentBlock[]): number;
+/** 单条消息的估算（文本按脚本区分，图片每张 1 600）。 */
 export declare function estimateMessageTokens(message: AgentMessage): number;
 export declare function estimateMessagesTokens(messages: readonly AgentMessage[]): number;
 export interface ContextEstimate {