@steerable/agent-shell 0.6.50 → 0.6.52

package/dist/brand.d.ts

@@ -18,6 +18,11 @@ export interface Brand {
     agentName: string;
     /** 一句话定位（fallback prompt 用） */
     tagline: string;
+    /**
+     * 新对话落地页 / 空会话首屏副文案。省略用 shell 默认句；
+     * 空字符串表示不显示。只进渲染层，不进系统提示词。
+     */
+    homeHint?: string;
     /** 新对话 / 首页未选手动专家时绑定的内置智能体 id */
     defaultAgentId: string;
 }

package/dist/goal-store.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 会话目标。每个 chat 一份，写在用户数据目录的 goals.json。
+ *
+ * 修订号做乐观并发：update_goal 必须带上一次读到的 revision。
+ */
+export type GoalPhase = 'active' | 'paused' | 'blocked' | 'complete';
+export type GoalAction = 'edit' | 'pause' | 'resume' | 'complete' | 'blocked';
+export declare const GOAL_ACTIONS: readonly GoalAction[];
+export interface StoredGoal {
+    id: string;
+    chatId: string;
+    revision: number;
+    objective: string;
+    phase: GoalPhase;
+    blockedReason?: string;
+    updatedAt: number;
+}
+export interface GoalToolResult {
+    success: boolean;
+    goal?: StoredGoal | null;
+    error?: string;
+    needsFollowup?: boolean;
+}
+export declare class GoalStore {
+    private readonly filePath;
+    private pending;
+    constructor(filePath: string);
+    static default(): GoalStore;
+    get(chatId: string): Promise<GoalToolResult>;
+    create(chatId: string, objective: string): Promise<GoalToolResult>;
+    update(input: {
+        chatId: string;
+        id: string;
+        revision: number;
+        action: string;
+        objective?: string;
+        reason?: string;
+    }): Promise<GoalToolResult>;
+    private queue;
+    private load;
+    private read;
+    private write;
+}

package/dist/goal-store.js

@@ -0,0 +1,155 @@
+/**
+ * 会话目标。每个 chat 一份，写在用户数据目录的 goals.json。
+ *
+ * 修订号做乐观并发：update_goal 必须带上一次读到的 revision。
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { getUserDataDir } from './runtime.js';
+export const GOAL_ACTIONS = [
+    'edit',
+    'pause',
+    'resume',
+    'complete',
+    'blocked',
+];
+export class GoalStore {
+    filePath;
+    pending = Promise.resolve();
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    static default() {
+        return new GoalStore(path.join(getUserDataDir(), 'goals.json'));
+    }
+    async get(chatId) {
+        const data = await this.load();
+        return { success: true, goal: data.goals[chatId] ?? null };
+    }
+    async create(chatId, objective) {
+        const text = objective.trim();
+        if (!text)
+            return { success: false, error: 'objective 不能为空', needsFollowup: true };
+        return this.queue(async () => {
+            const data = await this.read();
+            const existing = data.goals[chatId];
+            if (existing && existing.phase !== 'complete') {
+                return {
+                    success: false,
+                    error: `本会话已有未完成目标（${existing.id}，revision ${existing.revision}）。先 update_goal 完成或改写它。`,
+                    goal: existing,
+                    needsFollowup: true,
+                };
+            }
+            const goal = {
+                id: randomUUID(),
+                chatId,
+                revision: 1,
+                objective: text,
+                phase: 'active',
+                updatedAt: Date.now(),
+            };
+            data.goals[chatId] = goal;
+            await this.write(data);
+            return { success: true, goal };
+        });
+    }
+    async update(input) {
+        if (!GOAL_ACTIONS.includes(input.action)) {
+            return {
+                success: false,
+                error: `action 必须是 ${GOAL_ACTIONS.join(' | ')}`,
+                needsFollowup: true,
+            };
+        }
+        const action = input.action;
+        return this.queue(async () => {
+            const data = await this.read();
+            const current = data.goals[input.chatId];
+            if (!current || current.id !== input.id) {
+                return { success: false, error: '目标不存在或 id 不匹配。先 get_goal。', needsFollowup: true };
+            }
+            if (current.revision !== input.revision) {
+                return {
+                    success: false,
+                    error: `revision 已变（当前 ${current.revision}）。重新 get_goal 后再更新。`,
+                    goal: current,
+                    needsFollowup: true,
+                };
+            }
+            const next = applyAction(current, action, input.objective, input.reason);
+            if ('error' in next)
+                return { success: false, error: next.error, goal: current, needsFollowup: true };
+            data.goals[input.chatId] = next;
+            await this.write(data);
+            return { success: true, goal: next };
+        });
+    }
+    queue(fn) {
+        const run = this.pending.then(fn, fn);
+        this.pending = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async load() {
+        return this.queue(() => this.read());
+    }
+    async read() {
+        try {
+            const raw = await readFile(this.filePath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== 'object' || !parsed.goals)
+                return { goals: {} };
+            return parsed;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === 'ENOENT')
+                return { goals: {} };
+            throw err;
+        }
+    }
+    async write(data) {
+        await mkdir(path.dirname(this.filePath), { recursive: true });
+        await writeFile(this.filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+    }
+}
+function applyAction(current, action, objective, reason) {
+    const next = { ...current, revision: current.revision + 1, updatedAt: Date.now() };
+    if (action === 'edit') {
+        const text = objective?.trim() ?? '';
+        if (!text)
+            return { error: 'edit 需要 objective' };
+        next.objective = text;
+        return next;
+    }
+    if (action === 'pause') {
+        if (current.phase !== 'active')
+            return { error: `只有 active 目标可以暂停（当前 ${current.phase}）` };
+        next.phase = 'paused';
+        return next;
+    }
+    if (action === 'resume') {
+        if (current.phase !== 'paused' && current.phase !== 'blocked') {
+            return { error: `只有 paused 或 blocked 目标可以恢复（当前 ${current.phase}）` };
+        }
+        next.phase = 'active';
+        delete next.blockedReason;
+        return next;
+    }
+    if (action === 'complete') {
+        if (current.phase === 'complete')
+            return { error: '目标已经完成' };
+        next.phase = 'complete';
+        return next;
+    }
+    const text = reason?.trim() ?? '';
+    if (!text)
+        return { error: 'blocked 需要 reason' };
+    if (current.phase !== 'active' && current.phase !== 'paused') {
+        return { error: `当前阶段 ${current.phase} 不能标为 blocked` };
+    }
+    next.phase = 'blocked';
+    next.blockedReason = text;
+    return next;
+}

package/dist/host/runtime.js

@@ -120,7 +120,13 @@ export async function createHostRuntime(options) {
         if (!projectId)
             return null;
         const project = projectRegistry.get(projectId);
-        return project ? { name: project.name, folderPath: project.folderPath } : null;
+        return project
+            ? {
+                name: project.name,
+                folderPath: project.folderPath,
+                sourceFolders: project.sourceFolders ?? [],
+            }
+            : null;
     };
     // 场景包装配（2.3）：产品组装根（products/<id>/active.ts）在 import 期
     // 把包装配函数注册进 pack-assembly 注册表；这里统一装配。宿主不 import
@@ -214,8 +220,8 @@ export async function createHostRuntime(options) {
                 store: defaultStore,
                 toolRouter,
                 resolveProjectRoot: async (chatId) => localBackendRouter.resolveChatWorkspaceRoot(chatId),
-                // 项目模式下文件读写被围栏在项目目录内；会话附件目录是额外放行的
-                // 只读根，保证用户上传的文件即使在项目会话里也能被 agent 读回。
+                // 读：项目家目录之外，附件目录和源文件夹（含各自子目录）也可读。
+                // 写：源文件夹及其子目录与家目录同一档；附件目录保持只读。
                 resolveAdditionalReadRoots: async (chatId) => {
                     const project = await localBackendRouter.resolveChatProject(chatId);
                     return [
@@ -223,6 +229,10 @@ export async function createHostRuntime(options) {
                         ...(project?.sourceFolders ?? []),
                     ];
                 },
+                resolveAdditionalWriteRoots: async (chatId) => {
+                    const project = await localBackendRouter.resolveChatProject(chatId);
+                    return project?.sourceFolders ?? [];
+                },
                 approvalHandler: approvalBridge.handler,
                 askUserHandler: askUserBridge.handler,
                 // P2b: resume 时 sidecar 把记录里的读证据推给 LocalExecutor 的

package/dist/host-tools-runtime.d.ts

@@ -5,6 +5,12 @@ export declare function isProductApprovalEnabled(): boolean;
 export declare function resolveTurnApproval(storePath?: string): ReturnType<typeof buildHostApproval>;
 export declare function assertHostIpcAllowed(channel: string): void;
 export declare function resolveTurnChatMode(requested: unknown): ChatModeId;
+/** 解析当前产品是否启用多智能体编排六件套（STEERABLE_ORCHESTRATION 环境变量与回合 payload 优先）。 */
+export declare function resolveTurnOrchestration(payload?: Record<string, unknown>): {
+    enabled: boolean;
+    maxDepth: number;
+    maxParallel: number;
+} | undefined;
 export declare function isProductLlmLocked(): boolean;
 /** 设置页开着走已存/出厂默认；关掉则钉死 product.json 的 llm。 */
 export declare function resolveRuntimeLlmSettings(persisted: LlmSettings | null): LlmSettings;

package/dist/host-tools-runtime.js

@@ -32,6 +32,42 @@ export function assertHostIpcAllowed(channel) {
 export function resolveTurnChatMode(requested) {
     return clampChatMode(requested, resolveChatModes(getProductConfig().chatModes));
 }
+/** 解析当前产品是否启用多智能体编排六件套（STEERABLE_ORCHESTRATION 环境变量与回合 payload 优先）。 */
+export function resolveTurnOrchestration(payload) {
+    if (process.env.STEERABLE_ORCHESTRATION === '0')
+        return undefined;
+    if (process.env.STEERABLE_ORCHESTRATION === '1') {
+        return { enabled: true, maxDepth: 1, maxParallel: 4 };
+    }
+    // 回合请求体优先（用户在前端设置中打开/关闭，随 metadata/payload 透传）
+    if (payload) {
+        if (payload.orchestration === false)
+            return undefined;
+        if (payload.orchestration === true) {
+            return { enabled: true, maxDepth: 1, maxParallel: 4 };
+        }
+        const meta = payload.metadata;
+        if (meta && typeof meta === 'object') {
+            if (meta.orchestration === false)
+                return undefined;
+            if (meta.orchestration === true) {
+                return { enabled: true, maxDepth: 1, maxParallel: 4 };
+            }
+        }
+    }
+    const config = getProductConfig().orchestration;
+    if (config === true) {
+        return { enabled: true, maxDepth: 1, maxParallel: 4 };
+    }
+    if (typeof config === 'object' && config !== null && config.enabled !== false) {
+        return {
+            enabled: true,
+            maxDepth: typeof config.maxDepth === 'number' ? config.maxDepth : 1,
+            maxParallel: typeof config.maxParallel === 'number' ? config.maxParallel : 4,
+        };
+    }
+    return undefined;
+}
 export function isProductLlmLocked() {
     return !resolveSettingsChrome(getProductConfig().settings).llm;
 }

package/dist/host-tools.d.ts

@@ -34,7 +34,7 @@ export type ResolvedSettingsChrome = Record<SettingsItemId, boolean>;
  */
 export declare function resolveSettingsChrome(value?: unknown, tools?: ResolvedHostTools): ResolvedSettingsChrome;
 export declare function hasGeneralSettingsChrome(chrome?: ResolvedSettingsChrome): boolean;
-export declare const LOCAL_FS_TOOL_NAMES: readonly ["local_exec_shell", "local_read_file", "view_image", "local_write_file", "local_edit_file", "present_files", "local_open_path", "local_run_snippet", "local_list_scripts", "local_run_script"];
+export declare const LOCAL_FS_TOOL_NAMES: readonly ["local_exec_shell", "local_read_file", "view_image", "local_write_file", "local_edit_file", "present_files", "local_open_path", "local_run_snippet", "local_list_scripts", "local_run_script", "grep", "glob", "pwsh"];
 export declare function resolveHostToolSurface(value: boolean | {
     capability?: boolean;
     chrome?: boolean;

package/dist/host-tools.js

@@ -84,6 +84,9 @@ export const LOCAL_FS_TOOL_NAMES = [
     'local_run_snippet',
     'local_list_scripts',
     'local_run_script',
+    'grep',
+    'glob',
+    'pwsh',
 ];
 const FAMILY_TOOL_PREFIX = {
     terminal: [],
@@ -97,6 +100,9 @@ const FAMILY_TOOL_PREFIX = {
         'worktree_create',
         'worktree_list',
         'worktree_remove',
+        'job_list',
+        'job_output',
+        'job_kill',
     ],
     mcp: ['mcp_list_tools', 'mcp_tool_exec'],
     web: ['web_search', 'web_fetch'],

package/dist/local-backend/router.js

@@ -10,6 +10,7 @@ import { buildWorldState, getActiveCoreLoopStreamId, streamCoreLoopTurn, } from
 import { driveWithAutoContinue, resolveAutoContinueMax, } from './auto-continue-helper.js';
 import { buildAmbientDelegateRoster, buildDelegateDispatchInstruction, buildDelegateRosterHint, buildMentionDelegateRoster, BUILTIN_SUBAGENT_PROFILES, mergeTurnSubagentParam, } from './subagent-profiles.js';
 import { resolveMentionedAgentIds } from './mention-targets.js';
+import { presentToolCall } from '../tool-presentation.js';
 import { readSidecarHistoryEntries, timelineFromHistoryEntries, } from './task-process.js';
 import { appendTimelineDelta, freezeTimelineReasoning, sealLastTimelineBlock, syncTimelineTools, } from './turn-timeline.js';
 import { turnDurationMs } from './turn-duration.js';
@@ -23,7 +24,7 @@ import { setDefaultExecTimeoutMs } from '../local-executor.js';
 import { allowEgressForBaseUrl, getActiveEgressBroker, getEgressPosture } from '../sidecar/egress-proxy.js';
 import { buildExecSandbox, parseExecPolicy } from '../sidecar/exec-sandbox.js';
 import { clampExecPolicy } from '../host-tools.js';
-import { getResolvedHostTools, isProductLlmLocked, resolveRuntimeLlmSettings, resolveTurnApproval, resolveTurnChatMode, } from '../host-tools-runtime.js';
+import { getResolvedHostTools, isProductLlmLocked, resolveRuntimeLlmSettings, resolveTurnApproval, resolveTurnChatMode, resolveTurnOrchestration, } from '../host-tools-runtime.js';
 import { SidecarSupervisor } from '../sidecar/index.js';
 import { diagnoseLlmConnection } from './llm-diagnose.js';
 import { brandSkillVars, buildSystemPrompt, buildForcedSkillMessage, conditionsFromTools, } from './prompt-builder.js';
@@ -2448,17 +2449,17 @@ export class LocalBackendRouter {
             ? chatProject.folderPath
             : await this.resolveChatWorkspaceRoot(chatId);
         if (chatProject) {
+            const sourceFolderLine = chatProject.sourceFolders.length > 0
+                ? `源文件夹及其子目录也可读写：${chatProject.sourceFolders.join('、')}。`
+                : '如确需读写家目录外的目录，可请用户把该目录附加为源文件夹。';
             systemPrompt +=
                 `\n\n【项目模式】当前对话绑定项目「${chatProject.name}」，家目录：${chatProject.folderPath}\n` +
-                    `你的文件写入（local_write_file）和命令执行（local_exec_shell）都被限制在该家目录内：` +
-                    `写入路径越界会被拒绝；命令默认在家目录下运行，显式指定的 cwd 越界也会被拒绝。` +
-                    (chatProject.sourceFolders.length > 0
-                        ? `另有源文件夹（只读）：${chatProject.sourceFolders.join('、')}。`
-                        : '') +
-                    `请一律使用项目目录内的路径（相对路径按家目录解析）。` +
-                    `如确需读取项目外的文件，可请用户在项目里附加为源文件夹。\n` +
-                    `例外：本会话的用户上传附件目录 ${chatAttachmentsDirPath(chatId)} 也在项目家目录外，` +
-                    `但它已作为**只读放行根**开放给 local_read_file（用绝对路径可直接读取，不会被项目围栏拒绝）。` +
+                    `文件写入（local_write_file / local_edit_file）和命令写入可以落在家目录及其全部子目录内。` +
+                    `${sourceFolderLine}` +
+                    `这些范围之外的写入会被拒绝。命令未指定 cwd 时在家目录运行；显式 cwd 必须落在上述可写目录（含子目录）内。` +
+                    `相对路径按家目录解析。\n` +
+                    `例外：本会话的用户上传附件目录 ${chatAttachmentsDirPath(chatId)} 只读，不在可写范围内，` +
+                    `但 local_read_file 可以用绝对路径读取。` +
                     /* shell-neutral:allow generic document extensions, not product identity */ `用户附到本条消息的文件都放在那里；需要转换（docx / pdf / xlsx / pptx 等）时，` +
                     `把该绝对路径交给 local_exec_shell 的转换脚本处理即可，**不要**因为它在项目家目录外就拒绝读取或要求用户重新拷贝。`;
             // W6-5 + W6-7a：项目级规则文件（AGENTS.md / CLAUDE.md）是不可信输入，
@@ -2481,7 +2482,7 @@ export class LocalBackendRouter {
         else {
             systemPrompt +=
                 `\n\n【对话工作区】当前对话没有绑定项目。工作区：${workspaceRoot}\n` +
-                    `你的文件写入（local_write_file）和命令执行（local_exec_shell）都被限制在该目录内：` +
+                    `你的文件写入（local_write_file）和命令执行（local_exec_shell）都被限制在该目录及其子目录内：` +
                     `写入路径越界会被拒绝；命令默认在工作区下运行，显式指定的 cwd 越界也会被拒绝。` +
                     `请一律使用工作区内的路径（相对路径按工作区解析）。` +
                     `用户若要把对话绑到已有项目，可在输入框上方选择项目。`;
@@ -2940,7 +2941,7 @@ export class LocalBackendRouter {
         // spec (default.harness.yaml) is the single source of truth for
         // maxRounds / maxToolErrors, and an explicit request param overrides it.
         // W4-2: per-exec sandbox for shell tool calls, default-on. Writable
-        // roots = 项目家目录，或无项目时 Documents/<应用>/conversations/<chatId>。
+        // roots = 项目家目录（或无项目时的对话工作区）+ 源文件夹。每个根含其子目录。
         // `execPolicy: 'full'`（输入框「完整权限」）关闭这一层，让 mkdir
         // Downloads 这类工作区外写入不再被 Seatbelt 拦成 Operation not permitted。
         const chatProject = await this.resolveChatProject(chatId);
@@ -2952,6 +2953,7 @@ export class LocalBackendRouter {
             // 工作区）。
             ...collectPackExecWritableRoots(chatId),
             workspaceRoot,
+            ...(chatProject?.sourceFolders ?? []),
         ], { policy: clampExecPolicy(parseExecPolicy(payload.execPolicy), getResolvedHostTools()) });
         // W4-1: approval algebra, host mode — every tool call is gated by the
         // Electron approval UI over the reverse channel. The durable scope
@@ -2989,6 +2991,7 @@ export class LocalBackendRouter {
         const turnFileRoots = [
             ...collectPackExecWritableRoots(chatId),
             workspaceRoot,
+            ...(chatProject?.sourceFolders ?? []),
         ];
         try {
             const coreLoopOptions = {
@@ -3077,7 +3080,7 @@ export class LocalBackendRouter {
                     ...(toolPolicy.mode === 'all' ? {} : { toolPolicy }),
                 },
                 execSandbox,
-                approval,
+                approval: approval ? { ...approval, writableRoots: turnFileRoots } : undefined,
                 // delegate-on-pool 统一:模型的多代理面收敛为单工具
                 // delegate_subagent(默认开)。内置画像集(explore/research/coder)
                 // 带工具域/轮次/并发/系统提示,模型按画像 description 选委派
@@ -3085,10 +3088,10 @@ export class LocalBackendRouter {
                 // 子运行执行,生命周期经 onChildEvent → SSE 进 UI 编排卡片。
                 subagent,
                 // 六件套(agent_spawn/send/wait/close/list/interrupt)收缩为
-                // opt-in 高级模式:STEERABLE_ORCHESTRATION=1 开启;开启后与
-                // delegate 共享同一 AgentPool(同一 maxParallel 预算)。
-                ...(process.env.STEERABLE_ORCHESTRATION === '1'
-                    ? { orchestration: { enabled: true, maxDepth: 1, maxParallel: 4 } }
+                // opt-in 高级模式:STEERABLE_ORCHESTRATION 环境变量、回合 payload 或 product.json.orchestration 开启;
+                // 开启后与 delegate 共享同一 AgentPool(同一 maxParallel 预算)。
+                ...(resolveTurnOrchestration(payload)
+                    ? { orchestration: resolveTurnOrchestration(payload) }
                     : {}),
                 signal,
                 onText: (delta) => {
@@ -3110,6 +3113,7 @@ export class LocalBackendRouter {
                         tool: call.tool,
                         mode: chatMode,
                         arguments: call.arguments,
+                        view: presentToolCall(call.tool, call.arguments),
                         threw: false,
                     });
                     syncTimelineTools(timeline, executedActions);
@@ -3124,6 +3128,7 @@ export class LocalBackendRouter {
                         tool: action.tool,
                         mode: chatMode,
                         arguments: action.arguments,
+                        view: presentToolCall(action.tool, action.arguments, action.result),
                         result: action.result,
                         success: action.success,
                         error: action.error,

package/dist/local-backend/subagent-profiles.js

@@ -20,8 +20,12 @@ import { loadSkills } from './skill-loader.js';
 /** 只读工具域：探索与调研画像共享的「摸不到写操作」基线。 */
 const READ_ONLY_TOOLS = [
     'local_read_file',
+    'view_image',
     'local_list_scripts',
     'local_open_path',
+    'grep',
+    'glob',
+    'get_goal',
     'web_search',
     'web_fetch',
     'mcp_list_tools',

package/dist/local-backend/task-service.d.ts

@@ -54,6 +54,7 @@ export interface TaskServiceDeps {
     resolveChatProject: (chatId: string) => Promise<{
         name: string;
         folderPath: string;
+        sourceFolders?: string[];
     } | null>;
     /**
      * 无项目对话的可写根（Documents/<应用>/conversations/<chatId>）。
@@ -120,6 +121,11 @@ export declare class TaskService {
     private executeTask;
     /** task_status 工具：单任务或本 chat 全部任务的快照。 */
     status(chatId: string, taskId?: string): Promise<Record<string, unknown>>;
+    /**
+     * job_kill：结束 running 或 blocked 任务。running 先打标记再取消流，
+     * 终态回写看到标记后保持 failed，避免流的正常完成把杀死盖掉。
+     */
+    kill(chatId: string, taskId: string, reason?: string): Promise<Record<string, unknown>>;
     /** task_result 工具：取终态任务的完整结果。 */
     result(chatId: string, taskId: string): Promise<Record<string, unknown>>;
     /** 喂给模型的任务视图（完整字段，answer 截断防爆上下文）。 */

package/dist/local-backend/task-service.js

@@ -32,6 +32,7 @@ import { buildExecSandbox } from '../sidecar/exec-sandbox.js';
 import { resolveTurnApproval } from '../host-tools-runtime.js';
 import { readSidecarHistoryEntries, timelineFromHistoryEntries, } from './task-process.js';
 import { appendTimelineDelta, syncTimelineTools, } from './turn-timeline.js';
+import { presentToolCall } from '../tool-presentation.js';
 /** 任务回合的系统提示词：自包含、汇报结果、不假装执行。 */
 function buildTaskSystemPrompt(input) {
     const lines = [
@@ -278,7 +279,11 @@ export class TaskService {
             (this.deps.resolveChatWorkspaceRoot
                 ? await this.deps.resolveChatWorkspaceRoot(chatId)
                 : null);
-        const execSandbox = buildExecSandbox(fenceRoot ? [fenceRoot] : []);
+        const writableRoots = [
+            ...(fenceRoot ? [fenceRoot] : []),
+            ...(project?.sourceFolders ?? []),
+        ];
+        const execSandbox = buildExecSandbox(writableRoots);
         const approval = resolveTurnApproval();
         // depth-1：任务回合没有 task_run（不能再派生任务），其余工具面与
         // 普通回合一致；task_status / task_result 保留（任务可以自查/互查）。
@@ -332,7 +337,7 @@ export class TaskService {
                     },
                 }),
                 execSandbox,
-                approval,
+                approval: approval ? { ...approval, writableRoots } : undefined,
                 // 与主对话同一套内置画像（explore/research/coder）——任务回合的
                 // 子代理编排语义不分叉。
                 subagent: builtinSubagentParam(),
@@ -341,6 +346,8 @@ export class TaskService {
                 askUser: false,
                 onStreamId: (streamId) => {
                     entry.streamId = streamId;
+                    if (entry.killed)
+                        void supervisor.cancelChat(streamId);
                 },
                 onText: (delta) => {
                     answer += delta;
@@ -356,6 +363,7 @@ export class TaskService {
                         id: call.id,
                         tool: call.tool,
                         arguments: call.arguments,
+                        view: presentToolCall(call.tool, call.arguments),
                         threw: false,
                     });
                     syncTimelineTools(entry.timeline, entry.actions);
@@ -369,6 +377,7 @@ export class TaskService {
                         id: action.id,
                         tool: action.tool,
                         arguments: action.arguments,
+                        view: presentToolCall(action.tool, action.arguments, action.result),
                         result: action.result,
                         success: action.success,
                         error: action.error,
@@ -398,6 +407,10 @@ export class TaskService {
                 traceId = failureTraceId;
             }
         }
+        if (entry.killed) {
+            status = 'failed';
+            error = entry.killReason || 'killed by job_kill';
+        }
         await this.store.updateTask(taskId, {
             status,
             answer: answer.trim() || null,
@@ -430,6 +443,38 @@ export class TaskService {
             tasks: tasks.map((t) => this.toModelView(t)),
         };
     }
+    /**
+     * job_kill：结束 running 或 blocked 任务。running 先打标记再取消流，
+     * 终态回写看到标记后保持 failed，避免流的正常完成把杀死盖掉。
+     */
+    async kill(chatId, taskId, reason) {
+        const task = await this.store.getTask(taskId);
+        if (!task || task.chatId !== chatId) {
+            return { success: false, error: `任务不存在：${taskId}` };
+        }
+        if (task.status === 'completed' || task.status === 'failed') {
+            return { success: false, error: `任务已终态（${task.status}），不能再结束。` };
+        }
+        const note = reason?.trim() || 'killed by job_kill';
+        const entry = this.running.get(taskId);
+        if (entry) {
+            entry.killed = true;
+            entry.killReason = note;
+        }
+        if (!entry || task.status === 'blocked') {
+            await this.store.updateTask(taskId, { status: 'failed', error: note });
+            this.deps.broadcast?.('task-updated', { chatId, taskId });
+            if (task.status === 'blocked')
+                await this.maybeUnblock(chatId);
+            return { success: true, job_id: taskId, status: 'failed', killed: true };
+        }
+        const getSupervisor = this.deps.getSupervisor ?? getSidecarSupervisor;
+        const supervisor = getSupervisor();
+        if (entry.streamId && supervisor) {
+            await supervisor.cancelChat(entry.streamId);
+        }
+        return { success: true, job_id: taskId, status: 'failed', killed: true };
+    }
     /** task_result 工具：取终态任务的完整结果。 */
     async result(chatId, taskId) {
         const task = await this.store.getTask(taskId);

package/dist/local-executor.d.ts

@@ -159,8 +159,20 @@ export declare function isGuiLaunchCommand(command: string): boolean;
  * 字符串/相对路径判断，不碰 fs，方便 ToolRouter 与 LocalExecutor 共用。
  */
 export declare function isPathWithinRoot(resolvedPath: string, resolvedRoot: string): boolean;
+/** `~` 展开后 resolve。围栏比较前路径与根都要过这一步。 */
+export declare function expandFencePath(inputPath: string): string;
+/**
+ * 可写根：项目家目录（或对话工作区）加上额外可写根（源文件夹）。
+ * 每个根都包含它自己和全部子目录。空列表表示不设围栏。
+ */
+export declare function writableFenceRoots(projectRoot?: string | null, additionalWriteRoots?: string[] | null): string[];
 /** 越界错误消息（给模型看，引导它把操作收回项目目录内）。 */
 export declare function buildProjectRootViolation(resolvedPath: string, resolvedRoot: string): string;
+/**
+ * 路径不在任一可写根（含其子目录）内时返回给模型的错误；在围栏内或未设围栏时返回 null。
+ * `resolvedPath` 与 `roots` 都应已 resolve。
+ */
+export declare function writableFenceViolation(resolvedPath: string, roots: string[]): string | null;
 export interface CommandSafetyConfigPayload {
     disabledPatternIds: string[];
     customPatterns: Array<{
@@ -216,13 +228,13 @@ export declare class LocalExecutor {
     };
     executeShell(request: LocalExecRequest): Promise<LocalExecResult>;
     readLocalFile(request: LocalFileReadRequest, projectRoot?: string | null, additionalReadRoots?: string[] | null): Promise<LocalFileReadResult>;
-    writeLocalFile(request: LocalFileWriteRequest, projectRoot?: string | null): Promise<LocalFileWriteResult>;
+    writeLocalFile(request: LocalFileWriteRequest, projectRoot?: string | null, additionalWriteRoots?: string[] | null): Promise<LocalFileWriteResult>;
     /**
      * local_edit_file 的实现（W6-1）：结构化批量编辑。先按 expectedVersion 做
      * read-before-write 冲突检测，再在原文上做三级模糊定位 + 逆序替换，最后
      * 原子落盘。返回新版本令牌与统一 diff。
      */
-    editLocalFile(request: LocalFileEditRequest, projectRoot?: string | null): Promise<LocalFileEditResult>;
+    editLocalFile(request: LocalFileEditRequest, projectRoot?: string | null, additionalWriteRoots?: string[] | null): Promise<LocalFileEditResult>;
     /**
      * read-before-write 冲突检测：当前内容版本与调用方期望不一致时返回错误
      * 消息（引导重新读取），一致返回 null。文件不存在且期望存在也算冲突，