@steerable/agent-shell 0.6.74 → 0.7.2

package/dist/sidecar/approval-label.js

@@ -0,0 +1,102 @@
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { canonicalFencePath, canonicalPathInside } from '../fence-path.js';
+const COMMAND_TOOLS = new Set(['local_exec_shell', 'local_run_snippet']);
+// Only the shell starts an explicit cwd outside the writable roots. A snippet
+// is rejected before it runs, so its card must not say the command still runs.
+const OUTSIDE_CWD_TOOLS = new Set(['local_exec_shell']);
+const BUILTIN_CATEGORY_LABEL = {
+    network_egress: 'Internet access',
+    sandbox_escalation: 'Sandbox',
+};
+/**
+ * Display name for an approval category.
+ * Pack declarations win. Built-in categories and shell tools use the shell dictionary.
+ *
+ * @param input Locale, category, and the tool's declared labels.
+ * @returns A label for the card, or undefined when the category is just the tool name.
+ */
+export function resolveApprovalCategoryLabel(input) {
+    const declared = declaredLabel(input.declaredLabel, input.locale);
+    if (declared)
+        return declared;
+    const builtin = BUILTIN_CATEGORY_LABEL[input.category];
+    if (builtin)
+        return input.translate(builtin);
+    if (COMMAND_TOOLS.has(input.toolName) || COMMAND_TOOLS.has(input.category))
+        return input.translate('Command');
+    return undefined;
+}
+/** English source string for the approval card. The web view translates it. */
+export function hostApprovalCategoryLabel(input) {
+    return resolveApprovalCategoryLabel({
+        locale: 'en',
+        category: input.category,
+        toolName: input.toolName,
+        ...(input.declaredLabel ? { declaredLabel: input.declaredLabel } : {}),
+        translate: (message) => message,
+    });
+}
+/**
+ * Which approval sentence to show when `local_exec_shell` names a cwd
+ * outside the writable root. A bound project uses its folder and source
+ * folders. A chat without a project uses the conversation workspace.
+ *
+ * @param input Tool name, cwd, and the chat's project or workspace root.
+ * @returns `false` when the card should not mention an outside directory.
+ */
+export function approvalCwdFence(input) {
+    const bound = Boolean(input.projectRoot);
+    const outside = shellCwdOutsideProject({
+        toolName: input.toolName,
+        cwd: input.cwd,
+        projectRoot: input.projectRoot ?? input.workspaceRoot,
+        sourceFolders: bound ? input.sourceFolders : [],
+        ...(input.home ? { home: input.home } : {}),
+    });
+    if (!outside)
+        return false;
+    return bound ? 'project' : 'workspace';
+}
+/**
+ * True when `local_exec_shell` names a cwd outside the given root and its source folders.
+ *
+ * The root is the project folder, or the conversation workspace when the chat
+ * has no project. `home` defaults to the process home directory, the same
+ * directory the shell fence uses when it expands `~`.
+ *
+ * @param input Tool name, cwd argument, and the chat's writable folders.
+ * @returns Whether that cwd is outside those folders.
+ */
+export function shellCwdOutsideProject(input) {
+    if (!OUTSIDE_CWD_TOOLS.has(input.toolName))
+        return false;
+    if (!input.projectRoot || typeof input.cwd !== 'string' || !input.cwd.trim())
+        return false;
+    const target = resolveCwd(input.cwd.trim(), input.projectRoot, input.home ?? homedir());
+    const roots = [input.projectRoot, ...input.sourceFolders];
+    return !roots.some((root) => canonicalPathInside(root, target));
+}
+function declaredLabel(label, locale) {
+    if (!label)
+        return undefined;
+    const exact = label[locale];
+    if (exact)
+        return exact;
+    const normalized = locale.trim().toLowerCase().replace(/_/g, '-');
+    if (normalized === 'zh' || normalized.startsWith('zh-')) {
+        return label['zh-CN'] || label.zh || label['zh-Hans'];
+    }
+    if (normalized === 'en' || normalized.startsWith('en-'))
+        return label.en;
+    return label.en;
+}
+function resolveCwd(cwd, projectRoot, home) {
+    // Same `~` rule as ToolRouter.applyProjectCwdSandbox: slice(1) keeps the
+    // separator, and path.join folds it into the home directory. The fence
+    // comparison uses the real path, so `/tmp` and `/private/tmp` match.
+    const expanded = cwd.startsWith('~') ? path.join(home, cwd.slice(1)) : cwd;
+    const root = canonicalFencePath(path.resolve(projectRoot));
+    const resolved = path.isAbsolute(expanded) ? path.resolve(expanded) : path.resolve(root, expanded);
+    return canonicalFencePath(resolved);
+}

package/dist/sidecar/reverse-approval.d.ts

@@ -31,6 +31,20 @@ export interface ApprovalPromptRequest {
     round: number;
     /** Chat that asked. The renderer only shows the card in that composer. */
     chatId?: string;
+    /** Localized category name. Absent when the category is the tool name. */
+    categoryLabel?: string;
+    /** Shell cwd is outside the chat project's writable folders. */
+    outsideWorkspace?: boolean;
+    /**
+     * `workspace` when the chat has no project and the cwd is outside the
+     * conversation workspace. Absent means the project sentence.
+     */
+    outsideWorkspaceKind?: 'workspace';
+    /**
+     * Live command sandbox. `false` means the card must not say writes are
+     * blocked. Absent keeps that sentence for an older sidecar.
+     */
+    sandboxEnforced?: boolean;
 }
 export interface ApprovalBridgeDeps {
     /**
@@ -42,6 +56,18 @@ export interface ApprovalBridgeDeps {
     /** True when at least one renderer window can receive the prompt. */
     hasWindow: () => boolean;
     onLog?: (line: string) => void;
+    /** Localized category name from the tool declaration or the shell dictionary. */
+    categoryLabel?: (toolName: string, category: string) => string | undefined;
+    /**
+     * Whether a shell cwd sits outside the writable root.
+     * `true` and `'project'` use the project sentence. `'workspace'` uses the
+     * conversation-workspace sentence. `false` adds no outside-cwd sentence.
+     */
+    outsideWorkspace?: (input: {
+        toolName: string;
+        arguments: Record<string, unknown>;
+        chatId?: string;
+    }) => boolean | 'project' | 'workspace' | Promise<boolean | 'project' | 'workspace'>;
 }
 export interface ApprovalBridge {
     /** Reverse-channel handler for the sidecar's `approval.request`. */

package/dist/sidecar/reverse-approval.js

@@ -44,16 +44,27 @@ export function createApprovalBridge(deps) {
             }
             const requestId = randomUUID();
             const chatId = typeof p.chatId === 'string' && p.chatId ? p.chatId : undefined;
+            const args = p.arguments && typeof p.arguments === 'object'
+                ? p.arguments
+                : {};
+            const category = typeof p.category === 'string' ? p.category : toolName;
+            const categoryLabel = deps.categoryLabel?.(toolName, category);
+            const fence = deps.outsideWorkspace
+                ? await deps.outsideWorkspace({ toolName, arguments: args, ...(chatId ? { chatId } : {}) })
+                : false;
+            const outsideWorkspace = fence === true || fence === 'project' || fence === 'workspace';
             const prompt = {
                 requestId,
                 toolName,
-                arguments: p.arguments && typeof p.arguments === 'object'
-                    ? p.arguments
-                    : {},
+                arguments: args,
                 mode: typeof p.mode === 'string' ? p.mode : 'other',
-                category: typeof p.category === 'string' ? p.category : toolName,
+                category,
                 round: typeof p.round === 'number' ? p.round : 0,
                 ...(chatId ? { chatId } : {}),
+                ...(categoryLabel ? { categoryLabel } : {}),
+                ...(outsideWorkspace ? { outsideWorkspace: true } : {}),
+                ...(fence === 'workspace' ? { outsideWorkspaceKind: 'workspace' } : {}),
+                ...(typeof p.sandboxEnforced === 'boolean' ? { sandboxEnforced: p.sandboxEnforced } : {}),
             };
             deps.onLog?.(`approval: prompting for ${toolName} (${prompt.mode}/${prompt.category})`);
             return await new Promise((resolve) => {

package/dist/sidecar/types.d.ts

@@ -470,6 +470,13 @@ export interface SidecarChatStreamRequest {
          * host prompt. Independent of whether the OS exec sandbox is on.
          */
         writableRoots?: string[];
+        /**
+         * Directory relative tool paths are joined to before the inside-root
+         * check. This is the project home, or the conversation workspace when
+         * the chat has no project. Absent, a relative path is inside unless it
+         * starts with `..`.
+         */
+        pathBase?: string;
     };
 }
 /**
@@ -524,6 +531,13 @@ export interface SidecarStreamChunk {
             backend?: string;
             enforcement: string;
         };
+        /** Session-allow reuse. `cached` means this call did not show a card. */
+        approval?: {
+            kind?: string;
+            category?: string;
+            cached?: boolean;
+            waitMs?: number;
+        };
     };
     /** CoreLoop notices: soft_timeout / budget_exhausted / round_end / hook_action. */
     notice?: {

package/dist/storage/index.d.ts

@@ -19,6 +19,13 @@ export interface ChatSessionRecord {
     isPinned: boolean;
     systemPrompt: string | null;
     pinnedRefs: unknown[] | null;
+    /**
+     * 标题从哪来。`user` 表示用户改过名，自动标题不再覆盖（即使用户把标题改回「新对话」）。
+     * `auto` 表示上次由标题生成写入。缺省是旧库，仍按标题文本是否还是「新对话」判断。
+     */
+    titleSource?: 'user' | 'auto' | null;
+    /** 分叉来源会话 id。原会话已删除时仍保留 id，读取接口再决定是否展示。 */
+    forkedFrom?: string | null;
 }
 export interface ChatMessageRecord {
     id: string;
@@ -183,7 +190,7 @@ export declare class SqliteScopedStore implements ScopedStore {
     /** 删除项目时调用：把该项目下所有会话降级为无项目对话（不删会话）。 */
     clearProjectAssignment(projectId: string): Promise<number>;
     getChat(chatId: string): Promise<ChatSessionRecord | null>;
-    updateChat(chatId: string, updates: Partial<Pick<ChatSessionRecord, 'title' | 'systemPrompt' | 'pinnedRefs' | 'isPinned' | 'projectId'>>): Promise<ChatSessionRecord | null>;
+    updateChat(chatId: string, updates: Partial<Pick<ChatSessionRecord, 'title' | 'systemPrompt' | 'pinnedRefs' | 'isPinned' | 'projectId' | 'titleSource' | 'forkedFrom'>>): Promise<ChatSessionRecord | null>;
     deleteChat(chatId: string): Promise<boolean>;
     chatHasMessages(chatId: string): Promise<boolean>;
     /**

package/dist/storage/index.js

@@ -322,6 +322,9 @@ export class SqliteScopedStore {
         // 项目记录本身存在 json-store（agent-projects.json），这里只存外键；
         // 删项目时由路由层把本列置 NULL（会话降级为无项目对话）。
         this.ensureColumn('chat_sessions', 'project_id', 'TEXT');
+        // 用户改名后自动标题不再覆盖。NULL 保持旧规则：标题不是「新对话」就跳过。
+        this.ensureColumn('chat_sessions', 'title_source', 'TEXT');
+        this.ensureColumn('chat_sessions', 'forked_from', 'TEXT');
         // 任务编排（增量迁移）：depends_on 存 JSON string[]——本任务等待的
         // 依赖 taskId 列表；NULL = 无依赖。依赖必须指向建任务时已存在的
         // 任务，所以依赖图天然无环。
@@ -725,9 +728,9 @@ export class SqliteScopedStore {
         };
         this.db.prepare(`
       UPDATE chat_sessions
-      SET title = ?, system_prompt = ?, pinned_refs = ?, is_pinned = ?, project_id = ?, updated_at = ?
+      SET title = ?, system_prompt = ?, pinned_refs = ?, is_pinned = ?, project_id = ?, title_source = ?, forked_from = ?, updated_at = ?
       WHERE tenant_id = ? AND user_id = ? AND id = ?
-    `).run(next.title, next.systemPrompt, JSON.stringify(next.pinnedRefs ?? null), next.isPinned ? 1 : 0, next.projectId ?? null, next.updatedAt, this.scope.tenantId, this.scope.userId, chatId);
+    `).run(next.title, next.systemPrompt, JSON.stringify(next.pinnedRefs ?? null), next.isPinned ? 1 : 0, next.projectId ?? null, next.titleSource ?? null, next.forkedFrom ?? null, next.updatedAt, this.scope.tenantId, this.scope.userId, chatId);
         emitChatActivity({ chatId, updatedAt: next.updatedAt });
         return await this.getChat(chatId);
     }
@@ -1363,6 +1366,8 @@ export class SqliteScopedStore {
             isPinned: Number(row.is_pinned ?? 0) === 1,
             systemPrompt: row.system_prompt ? String(row.system_prompt) : null,
             pinnedRefs: row.pinned_refs ? this.safeJson(row.pinned_refs) : null,
+            titleSource: row.title_source === 'user' || row.title_source === 'auto' ? row.title_source : null,
+            forkedFrom: row.forked_from ? String(row.forked_from) : null,
         };
     }
     mapChatMessage(row) {

package/dist/storage/process-locks.d.ts

@@ -2,6 +2,12 @@ import { type HeldWriteLease } from './write-lease.js';
 export declare const HOST_SCHEMA_VERSION = 1;
 /** How long a starting host waits for another host to finish migrating. */
 export declare const OPEN_LOCK_WAIT_MS = 15000;
+/**
+ * How long a new process waits while probing the old exclusive database lock.
+ * A current process releases that lock immediately. An older build holds it
+ * until it exits, so the wait still fails closed.
+ */
+export declare const LEGACY_LOCK_PROBE_MS = 2000;
 export declare class ChatBusyError extends Error {
     readonly chatId: string;
     readonly code = "chat_busy";

package/dist/storage/process-locks.js

@@ -10,6 +10,12 @@ import { acquireWriteLease, StoreAlreadyOwnedError, } from './write-lease.js';
 export const HOST_SCHEMA_VERSION = 1;
 /** How long a starting host waits for another host to finish migrating. */
 export const OPEN_LOCK_WAIT_MS = 15_000;
+/**
+ * How long a new process waits while probing the old exclusive database lock.
+ * A current process releases that lock immediately. An older build holds it
+ * until it exits, so the wait still fails closed.
+ */
+export const LEGACY_LOCK_PROBE_MS = 2_000;
 export class ChatBusyError extends Error {
     chatId;
     code = 'chat_busy';

package/dist/storage/scoped-store.d.ts

@@ -16,7 +16,7 @@ export interface ScopedStore {
     createChatWithId(chatId: string, title?: string, agentId?: string | null, projectId?: string | null): Promise<ChatSessionRecord>;
     clearProjectAssignment(projectId: string): Promise<number>;
     getChat(chatId: string): Promise<ChatSessionRecord | null>;
-    updateChat(chatId: string, updates: Partial<Pick<ChatSessionRecord, 'title' | 'systemPrompt' | 'pinnedRefs' | 'isPinned' | 'projectId'>>): Promise<ChatSessionRecord | null>;
+    updateChat(chatId: string, updates: Partial<Pick<ChatSessionRecord, 'title' | 'systemPrompt' | 'pinnedRefs' | 'isPinned' | 'projectId' | 'titleSource' | 'forkedFrom'>>): Promise<ChatSessionRecord | null>;
     deleteChat(chatId: string): Promise<boolean>;
     chatHasMessages(chatId: string): Promise<boolean>;
     deleteChatIfEmpty(chatId: string): Promise<boolean>;

package/dist/storage/sqlite-driver.js

@@ -5,7 +5,7 @@ import { getProductConfig } from '../product-config.js';
 import { getUserDataDir } from '../runtime.js';
 import { LOCAL_SCOPE } from './driver.js';
 import { SqliteScopedStore } from './index.js';
-import { HOST_SCHEMA_VERSION, OPEN_LOCK_WAIT_MS, StorageUpgradeBlockedError, openLockPath, } from './process-locks.js';
+import { HOST_SCHEMA_VERSION, LEGACY_LOCK_PROBE_MS, OPEN_LOCK_WAIT_MS, StorageUpgradeBlockedError, openLockPath, } from './process-locks.js';
 import { acquireSharedLease, acquireWriteLease, lockPathForDb, StoreAlreadyOwnedError, } from './write-lease.js';
 import { acquireWriteLeaseOrExit } from './write-lease-error.js';
 const MAIN_DB_BUSY_TIMEOUT_MS = 5_000;
@@ -101,11 +101,12 @@ export class SqliteStorageDriver {
         if (this.db)
             return;
         const dbPath = path.join(getUserDataDir(), getProductConfig().dbFileName ?? 'agent-shell.db');
-        // A previous build held this lock for the whole process. If it is still
-        // held, that process cannot share the database, so refuse to migrate
-        // or to open alongside it.
+        // A previous build held this lock for the whole process. A current
+        // process only holds it for this probe, so wait briefly for a peer
+        // probe to finish. If the lock is still held, that process cannot
+        // share the database.
         acquireWriteLeaseOrExit(() => {
-            const legacy = acquireWriteLease(lockPathForDb(dbPath));
+            const legacy = acquireWriteLease(lockPathForDb(dbPath), LEGACY_LOCK_PROBE_MS);
             legacy.release();
         });
         const gate = openLockPath(dbPath);

package/dist/tool-router.d.ts

@@ -4,7 +4,7 @@ import type { McpServerRegistry } from './mcp-server-registry.js';
 import type { ProjectRegistry } from './project-registry.js';
 import type { TaskService } from './local-backend/task-service.js';
 import type { WorktreeService } from './local-backend/worktree-service.js';
-import type { ToolContribution, ToolMode, ToolExposure } from './scenario/pack.js';
+import type { ToolApprovalSpec, ToolContribution, ToolMode, ToolExposure } from './scenario/pack.js';
 export type { ToolMode, ToolExposure } from './scenario/pack.js';
 import { type AgentToolPolicy } from './local-backend/agent-capability.js';
 import { GoalStore } from './goal-store.js';
@@ -31,7 +31,9 @@ export interface ToolCall {
  * `projectRoot` 是项目模式的硬沙箱根：非空时
  *   - 读路径必须落在根内，或落在 additionalReadRoots 内（含各自子目录）
  *   - 写路径必须落在根内，或落在 additionalWriteRoots 内（含各自子目录）
- *   - local_exec_shell 的 cwd 默认改为项目根；显式 cwd 必须落在上述可写根内
+ *   - local_exec_shell 的 cwd 默认改为项目根；显式 cwd 可以落在可写根外，
+ *     命令仍启动。命令沙箱开着时，写入由 exec 沙箱拒绝；沙箱关掉时这次写入不会被沙箱拦住。
+ *     pwsh 与 local_run_snippet 的 cwd 仍必须落在可写根内
  * 无项目对话（null/缺省）行为与之前完全一致。
  */
 export interface ToolExecContext {
@@ -67,7 +69,16 @@ export interface ToolSchema {
     mode: ToolMode;
     /** 曝光层；缺省 `direct`。MCP 动态工具默认 `deferred`。 */
     exposure?: ToolExposure;
+    /** 审批分组。缺省时 sidecar 用工具名做类别。 */
+    approval?: ToolApprovalSpec;
 }
+/** 审批类别：小写开头，最长 64，且不占用内置类别。 */
+export declare const APPROVAL_CATEGORY_PATTERN: RegExp;
+export declare const RESERVED_APPROVAL_CATEGORIES: ReadonlySet<string>;
+/**
+ * 装配期校验包工具的审批类别。非法或与内置类别同名时抛错，宿主不装上该包。
+ */
+export declare function assertToolApproval(contribution: Pick<ToolContribution, 'name' | 'approval'>): void;
 type ShellExecutor = (request: LocalExecRequest) => Promise<LocalExecResult>;
 /**
  * web_search / web_fetch 的执行缝（W5-2）：唯一实现在 sidecar 的
@@ -237,15 +248,17 @@ export declare class ToolRouter {
      */
     private autoInstallSkillOnSuccess;
     /**
-     * 项目模式硬沙箱（cwd 维度）：有可写根时，cwd 默认收到项目家目录；
-     * 模型显式给的 cwd 必须落在家目录或额外可写根（源文件夹）内，含各自子目录。
-     * 相对 cwd 按家目录解析（而不是进程 cwd）。
+     * 项目模式的 cwd 解析：有可写根时，缺省 cwd 收到项目家目录。
+     * 相对 cwd 按家目录解析（而不是进程 cwd）。`~` 与命令围栏同一规则。
      *
-     * 注意边界：shell 命令文本里内嵌的绝对路径无法可靠解析，围栏只覆盖
-     * cwd 与文件读写工具。命令实际写盘还受 exec 沙箱的 writableRoots 约束，
-     * 那些根同样包含子目录。
+     * `allowOutside` 为真时，落在可写根外的 cwd 仍原样交给执行器。只有
+     * `local_exec_shell` 走这条路。命令沙箱开着时，审批卡说明写入该目录会被拒绝；
+     * 沙箱关掉时卡片不说这句话，这次写入也不会被沙箱拦住。
+     * `pwsh` 与代码片段不走这条路，越界 cwd 继续返回路径越界。
      *
-     * local_exec_shell 与 local_run_snippet 共用本 helper。
+     * 命令文本里内嵌的绝对路径无法可靠解析。文件读写工具另有路径围栏，
+     * 不随命令沙箱开关放行。命令沙箱开着时，shell 的实际写盘还受 exec 沙箱的
+     * writableRoots 约束，那些根含其子目录。
      */
     private applyProjectCwdSandbox;
     private executeShell;

package/dist/tool-router.js

@@ -1,6 +1,6 @@
 import os from 'node:os';
 import path from 'node:path';
-import { buildProjectRootViolation, expandFencePath, isPathWithinRoot, writableFenceRoots, writableFenceViolation, } from './local-executor.js';
+import { buildProjectRootViolation, canonicalFencePath, expandFencePath, resolveFencePath, isPathWithinRoot, writableFenceRoots, writableFenceViolation, } from './local-executor.js';
 import { writeShellStdin } from './shell-session.js';
 import { mcpExecutor } from './mcp-executor.js';
 import { rankTools, resolveMaxResults, TOOL_SEARCH_DEFAULT_MAX_RESULTS, } from './tool-search-rank.js';
@@ -24,6 +24,26 @@ export const MCP_DYNAMIC_TOOL_PREFIX = 'mcp__';
  */
 /** deferred 层的发现缝：一个 direct 层搜索工具，关键词命中即调。 */
 export const TOOL_SEARCH_TOOL_NAME = 'tool_search';
+/** 审批类别：小写开头，最长 64，且不占用内置类别。 */
+export const APPROVAL_CATEGORY_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+export const RESERVED_APPROVAL_CATEGORIES = new Set([
+    'network_egress',
+    'sandbox_escalation',
+]);
+/**
+ * 装配期校验包工具的审批类别。非法或与内置类别同名时抛错，宿主不装上该包。
+ */
+export function assertToolApproval(contribution) {
+    const approval = contribution.approval;
+    if (approval == null)
+        return;
+    const category = approval.category;
+    if (typeof category !== 'string'
+        || !APPROVAL_CATEGORY_PATTERN.test(category)
+        || RESERVED_APPROVAL_CATEGORIES.has(category)) {
+        throw new Error(`[tool-router] tool ${contribution.name} has invalid approval category '${String(category)}'`);
+    }
+}
 /** 前转 RPC 超时：sidecar 侧单次请求上限默认 30s（可配到 600s），这里给足余量。 */
 export const WEB_TOOL_RPC_TIMEOUT_MS = 130_000;
 const PLUGIN_TOOL_MODES = new Set(['read', 'safe_write', 'destructive']);
@@ -70,6 +90,7 @@ export class ToolRouter {
             if (existing.has(contribution.name)) {
                 throw new Error(`[tool-router] duplicate tool name from contribution: ${contribution.name}`);
             }
+            assertToolApproval(contribution);
             this.contributedTools.set(contribution.name, contribution);
             existing.add(contribution.name);
         }
@@ -489,6 +510,7 @@ export class ToolRouter {
                 inputSchema: c.inputSchema,
                 mode: c.mode,
                 ...(c.exposure ? { exposure: c.exposure } : {}),
+                ...(c.approval ? { approval: c.approval } : {}),
             })),
         ];
     }
@@ -983,7 +1005,7 @@ export class ToolRouter {
                     timeout: typeof args.timeout === 'number' ? args.timeout : undefined,
                     pty: args.pty !== false,
                     yieldMs: typeof args.yieldMs === 'number' ? args.yieldMs : undefined,
-                }, projectRoot, context?.additionalWriteRoots ?? null);
+                }, projectRoot, context?.additionalWriteRoots ?? null, { allowOutside: true });
             case 'write_stdin':
                 return await writeShellStdin({
                     sessionId: typeof args.sessionId === 'string' ? args.sessionId : '',
@@ -1055,7 +1077,7 @@ export class ToolRouter {
                     target: String(args.target || ''),
                 });
             case 'local_run_snippet': {
-                // 与 local_exec_shell 同款项目沙箱：cwd 默认项目根，显式越界拒绝。
+                // cwd 默认项目根。代码片段不走 exec 沙箱，显式越界 cwd 直接拒绝。
                 const sandboxed = this.applyProjectCwdSandbox({ cwd: typeof args.cwd === 'string' ? args.cwd : undefined }, projectRoot, context?.additionalWriteRoots ?? null);
                 if ('error' in sandboxed)
                     return sandboxed.error;
@@ -1329,17 +1351,19 @@ export class ToolRouter {
         }
     }
     /**
-     * 项目模式硬沙箱（cwd 维度）：有可写根时，cwd 默认收到项目家目录；
-     * 模型显式给的 cwd 必须落在家目录或额外可写根（源文件夹）内，含各自子目录。
-     * 相对 cwd 按家目录解析（而不是进程 cwd）。
+     * 项目模式的 cwd 解析：有可写根时，缺省 cwd 收到项目家目录。
+     * 相对 cwd 按家目录解析（而不是进程 cwd）。`~` 与命令围栏同一规则。
      *
-     * 注意边界：shell 命令文本里内嵌的绝对路径无法可靠解析，围栏只覆盖
-     * cwd 与文件读写工具。命令实际写盘还受 exec 沙箱的 writableRoots 约束，
-     * 那些根同样包含子目录。
+     * `allowOutside` 为真时，落在可写根外的 cwd 仍原样交给执行器。只有
+     * `local_exec_shell` 走这条路。命令沙箱开着时，审批卡说明写入该目录会被拒绝；
+     * 沙箱关掉时卡片不说这句话，这次写入也不会被沙箱拦住。
+     * `pwsh` 与代码片段不走这条路，越界 cwd 继续返回路径越界。
      *
-     * local_exec_shell 与 local_run_snippet 共用本 helper。
+     * 命令文本里内嵌的绝对路径无法可靠解析。文件读写工具另有路径围栏，
+     * 不随命令沙箱开关放行。命令沙箱开着时，shell 的实际写盘还受 exec 沙箱的
+     * writableRoots 约束，那些根含其子目录。
      */
-    applyProjectCwdSandbox(request, projectRoot, additionalWriteRoots) {
+    applyProjectCwdSandbox(request, projectRoot, additionalWriteRoots, options) {
         const roots = writableFenceRoots(projectRoot, additionalWriteRoots);
         if (roots.length === 0)
             return { request };
@@ -1348,11 +1372,11 @@ export class ToolRouter {
             const expanded = request.cwd.startsWith('~')
                 ? path.join(os.homedir(), request.cwd.slice(1))
                 : request.cwd;
-            const resolvedCwd = path.isAbsolute(expanded)
+            const resolvedCwd = canonicalFencePath(path.isAbsolute(expanded)
                 ? path.resolve(expanded)
-                : path.resolve(home, expanded);
+                : path.resolve(home, expanded));
             const violation = writableFenceViolation(resolvedCwd, roots);
-            if (violation) {
+            if (violation && !options?.allowOutside) {
                 return {
                     error: {
                         success: false,
@@ -1365,8 +1389,8 @@ export class ToolRouter {
         }
         return { request: { ...request, cwd: home } };
     }
-    async executeShell(request, projectRoot, additionalWriteRoots) {
-        const sandboxed = this.applyProjectCwdSandbox(request, projectRoot, additionalWriteRoots);
+    async executeShell(request, projectRoot, additionalWriteRoots, options) {
+        const sandboxed = this.applyProjectCwdSandbox(request, projectRoot, additionalWriteRoots, options);
         if ('error' in sandboxed)
             return sandboxed.error;
         if (this.shellExecutor) {
@@ -1377,21 +1401,11 @@ export class ToolRouter {
     resolveReadablePath(inputPath, projectRoot, additionalReadRoots) {
         if (!inputPath.trim())
             return { error: 'path 不能为空' };
-        const expanded = inputPath.startsWith('~')
-            ? path.join(os.homedir(), inputPath.slice(1))
-            : inputPath;
-        const resolved = path.resolve(expanded);
+        const resolved = resolveFencePath(inputPath, projectRoot);
         if (!projectRoot)
             return { path: resolved };
-        const root = path.resolve(projectRoot.startsWith('~')
-            ? path.join(os.homedir(), projectRoot.slice(1))
-            : projectRoot);
-        const inAdditionalRoot = (additionalReadRoots ?? []).some((candidate) => {
-            const expandedCandidate = candidate.startsWith('~')
-                ? path.join(os.homedir(), candidate.slice(1))
-                : candidate;
-            return isPathWithinRoot(resolved, path.resolve(expandedCandidate));
-        });
+        const root = expandFencePath(projectRoot);
+        const inAdditionalRoot = (additionalReadRoots ?? []).some((candidate) => isPathWithinRoot(resolved, expandFencePath(candidate)));
         if (!isPathWithinRoot(resolved, root) && !inAdditionalRoot) {
             return { error: buildProjectRootViolation(resolved, root) };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-shell",
-  "version": "0.6.74",
+  "version": "0.7.2",
   "description": "Steerable framework — product-neutral Node HostRuntime and headless HTTP server shared by Tauri desktop and browser deployments; scenario packs extend it through @steerable/pack-sdk.",
   "license": "Apache-2.0",
   "homepage": "https://steerableframework.com/",
@@ -53,9 +53,9 @@
     "jpeg-js": "^0.4.4",
     "node-pty": "^1.1.0",
     "pngjs": "^7.0.0",
-    "@steerable/agent-harness": "0.6.74",
-    "@steerable/agent-protocol": "0.6.74",
-    "@steerable/pack-sdk": "0.6.74"
+    "@steerable/agent-harness": "0.7.2",
+    "@steerable/agent-protocol": "0.7.2",
+    "@steerable/pack-sdk": "0.7.2"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",