@steerable/agent-shell 0.6.74 → 0.7.1

package/dist/local-executor.js

@@ -6,6 +6,7 @@ import { createHash } from 'crypto';
 import { spawn, execSync } from 'child_process';
 import { log } from './log.js';
 import { constants as fsConstants } from 'fs';
+import { expandFencePath, resolveFencePath } from './fence-path.js';
 import { adaptCommandForPowerShell } from './shell-adapt.js';
 import { evaluateExecPolicy, planSshArgv, } from './shell-exec.js';
 import { nodeShellBackend } from './shell-process.js';
@@ -181,15 +182,11 @@ export function isGuiLaunchCommand(command) {
  */
 export function isPathWithinRoot(resolvedPath, resolvedRoot) {
     const rel = path.relative(resolvedRoot, resolvedPath);
-    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
-}
-/** `~` 展开后 resolve。围栏比较前路径与根都要过这一步。 */
-export function expandFencePath(inputPath) {
-    const expanded = inputPath.startsWith('~')
-        ? path.join(os.homedir(), inputPath.slice(1))
-        : inputPath;
-    return path.resolve(expanded);
+    return rel === '' || (rel !== '..' &&
+        !rel.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(rel));
 }
+export { canonicalFencePath, expandFencePath, resolveFencePath } from './fence-path.js';
 /**
  * 可写根：项目家目录（或对话工作区）加上额外可写根（源文件夹）。
  * 每个根都包含它自己和全部子目录。空列表表示不设围栏。
@@ -639,7 +636,7 @@ export class LocalExecutor {
     }
     async readLocalFile(request, projectRoot, additionalReadRoots) {
         try {
-            const filePath = this.resolvePath(request.path);
+            const filePath = this.resolvePath(request.path, projectRoot);
             if (projectRoot) {
                 const root = this.resolvePath(projectRoot);
                 const inAdditionalRoot = (additionalReadRoots ?? []).some((r) => isPathWithinRoot(filePath, this.resolvePath(r)));
@@ -674,7 +671,7 @@ export class LocalExecutor {
         }
     }
     async writeLocalFile(request, projectRoot, additionalWriteRoots) {
-        const filePath = this.resolvePath(request.path);
+        const filePath = this.resolvePath(request.path, projectRoot);
         const violation = writableFenceViolation(filePath, writableFenceRoots(projectRoot, additionalWriteRoots));
         if (violation)
             return { success: false, error: violation };
@@ -735,7 +732,7 @@ export class LocalExecutor {
      * 原子落盘。返回新版本令牌与统一 diff。
      */
     async editLocalFile(request, projectRoot, additionalWriteRoots) {
-        const filePath = this.resolvePath(request.path);
+        const filePath = this.resolvePath(request.path, projectRoot);
         const violation = writableFenceViolation(filePath, writableFenceRoots(projectRoot, additionalWriteRoots));
         if (violation)
             return { success: false, error: violation };
@@ -1096,8 +1093,8 @@ export class LocalExecutor {
             return new RegExp(d.pattern, flags);
         });
     }
-    resolvePath(inputPath) {
-        return expandFencePath(inputPath);
+    resolvePath(inputPath, baseDir) {
+        return resolveFencePath(inputPath, baseDir);
     }
     resolveCwd(cwd, shellType) {
         const resolved = this.resolvePath(cwd || os.homedir());

package/dist/product-config.d.ts

@@ -43,7 +43,8 @@ export interface ProductConfig {
     }>;
     /**
      * 命令安全询问：host = 弹宿主审批；off = 本轮不挂审批。缺省 host。
-     * STEERABLE_APPROVAL=0 仍是调试逃生口。
+     * STEERABLE_APPROVAL=0 关掉本轮审批层，破坏性工具由工具路由拒绝。
+     * 需要放行时用命令行 `--approve allow-all`，不要依赖这个环境变量。
      */
     approval?: 'host' | 'off';
     /**
@@ -126,6 +127,11 @@ export interface ProductConfig {
         locales: string[];
         defaultLocale: string;
     };
+    /**
+     * 无项目会话分叉时，工作区复制的字节上限。缺省 500 MiB。
+     * 超过则接口返回 413，不创建新会话。
+     */
+    forkWorkspaceMaxBytes?: number;
 }
 /** shell 内置智能体：只有产品显式 `true` 才开。 */
 export declare function isShellBuiltinAgentEnabled(id: 'local-assistant' | 'all-round-assistant', config?: ProductConfig): boolean;

package/dist/project-registry.d.ts

@@ -30,6 +30,11 @@ export interface ProjectRecord {
      * 旧记录没有此字段，读取时按 `false` 处理（见 {@link ProjectRegistry.isTrusted}）。
      */
     trusted?: boolean;
+    /**
+     * 命令行创建的项目。桌面创建的记录不写该字段。
+     * 旧记录没有此字段，读取时忽略。
+     */
+    origin?: 'cli';
     /**
      * 侧边栏显示顺序，越小越靠前。旧记录没有此字段时按 createdAt 升序。
      * 用户拖拽排序后每个项目都会写上序号；之后新建的项目没有序号，排在已编号项目之后。
@@ -42,11 +47,17 @@ export interface CreateProjectInput {
     name: string;
     folderPath: string;
     sourceFolders?: string[];
+    origin?: 'cli';
 }
 /** 最小 KV 存储接口，避免本模块直接依赖具体存储实现。 */
 export interface ProjectKvStore {
     get(key: 'projects'): ProjectRecord[] | undefined;
     set(key: 'projects', value: ProjectRecord[]): void;
+    /**
+     * Read-modify-write under the projects file lock. Absent in memory stores;
+     * the registry then updates in this process only.
+     */
+    mutate?(key: 'projects', update: (current: ProjectRecord[]) => ProjectRecord[]): ProjectRecord[];
 }
 export declare class ProjectRegistry {
     private readonly store;
@@ -54,6 +65,27 @@ export declare class ProjectRegistry {
     list(): ProjectRecord[];
     get(idOrName: string): ProjectRecord | null;
     create(input: CreateProjectInput): ProjectRecord;
+    /**
+     * 同名时在名称后加 `-2`、`-3`，与家目录重名的处理一致。
+     */
+    createUnique(input: CreateProjectInput): ProjectRecord;
+    /**
+     * 按真实路径查找。目录已被删除时 `realpath` 失败，改用记录里的原始路径。
+     * Windows 上只忽略大小写。
+     */
+    findByFolder(realDir: string, realpath?: (target: string) => string, platform?: NodeJS.Platform): ProjectRecord | null;
+    /**
+     * 在同一次读改写里查找或创建。`D` 等于已有项目，或落在某个项目目录之内时复用
+     * （取路径最长的那个）；否则以目录名创建，重名加后缀。
+     */
+    resolveByFolder(folderPath: string, options?: {
+        origin?: 'cli';
+        realpath?: (target: string) => string;
+        platform?: NodeJS.Platform;
+    }): {
+        project: ProjectRecord;
+        created: boolean;
+    };
     update(id: string, updates: Partial<CreateProjectInput>): ProjectRecord;
     delete(id: string): boolean;
     /**
@@ -69,4 +101,5 @@ export declare class ProjectRegistry {
     isTrusted(id: string): boolean;
     /** W6-5: grant or revoke trust. Returns the updated record. */
     setTrusted(id: string, trusted: boolean): ProjectRecord;
+    private rewrite;
 }

package/dist/project-registry.js

@@ -12,6 +12,8 @@
  * mcp-server-registry.ts 同一模式）。
  */
 import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
 const STORE_KEY = 'projects';
 export class ProjectRegistry {
     store;
@@ -34,85 +36,141 @@ export class ProjectRegistry {
             throw new Error('项目名称不能为空');
         if (!folderPath)
             throw new Error('项目文件夹不能为空');
-        if (this.get(name))
-            throw new Error(`已存在同名项目「${name}」`);
-        const sourceFolders = normalizeSourceFolders(input.sourceFolders, folderPath);
-        const now = new Date().toISOString();
-        const entry = {
-            id: randomUUID(),
-            name,
-            folderPath,
-            ...(sourceFolders.length > 0 ? { sourceFolders } : {}),
-            createdAt: now,
-            updatedAt: now,
-        };
-        this.store.set(STORE_KEY, [...this.list(), entry]);
-        return entry;
+        let created = null;
+        this.rewrite((projects) => {
+            if (projects.some((project) => project.name.toLowerCase() === name.toLowerCase())) {
+                throw new Error(`已存在同名项目「${name}」`);
+            }
+            created = buildProject(name, folderPath, input);
+            return [...projects, created];
+        });
+        return created;
     }
-    update(id, updates) {
-        const projects = this.list();
-        const idx = projects.findIndex((p) => p.id === id);
-        if (idx === -1)
-            throw new Error('项目不存在');
-        const current = projects[idx];
-        const nextName = updates.name !== undefined ? updates.name.trim() : current.name;
-        if (!nextName)
+    /**
+     * 同名时在名称后加 `-2`、`-3`，与家目录重名的处理一致。
+     */
+    createUnique(input) {
+        const base = input.name.trim();
+        const folderPath = input.folderPath.trim();
+        if (!base)
             throw new Error('项目名称不能为空');
-        const nameClash = projects.some((p) => p.id !== id && p.name.toLowerCase() === nextName.toLowerCase());
-        if (nameClash)
-            throw new Error(`已存在同名项目「${nextName}」`);
-        const nextFolder = updates.folderPath !== undefined
-            ? updates.folderPath.trim()
-            : current.folderPath;
-        if (!nextFolder)
+        if (!folderPath)
             throw new Error('项目文件夹不能为空');
-        const sourceFolders = updates.sourceFolders !== undefined
-            ? normalizeSourceFolders(updates.sourceFolders, nextFolder)
-            : normalizeSourceFolders(current.sourceFolders, nextFolder);
-        const next = {
-            ...current,
-            name: nextName,
-            folderPath: nextFolder,
-            sourceFolders: sourceFolders.length > 0 ? sourceFolders : undefined,
-            updatedAt: new Date().toISOString(),
-        };
-        projects[idx] = next;
-        this.store.set(STORE_KEY, projects);
-        return next;
+        let created = null;
+        this.rewrite((projects) => {
+            const name = uniqueProjectName(projects, base);
+            created = buildProject(name, folderPath, input);
+            return [...projects, created];
+        });
+        return created;
+    }
+    /**
+     * 按真实路径查找。目录已被删除时 `realpath` 失败，改用记录里的原始路径。
+     * Windows 上只忽略大小写。
+     */
+    findByFolder(realDir, realpath = fs.realpathSync, platform = process.platform) {
+        const target = canonicalFolder(realDir, realpath, platform);
+        if (!target)
+            return null;
+        return locateProject(this.list(), target, realpath, platform);
+    }
+    /**
+     * 在同一次读改写里查找或创建。`D` 等于已有项目，或落在某个项目目录之内时复用
+     * （取路径最长的那个）；否则以目录名创建，重名加后缀。
+     */
+    resolveByFolder(folderPath, options) {
+        const realpath = options?.realpath ?? fs.realpathSync;
+        const platform = options?.platform ?? process.platform;
+        const target = canonicalFolder(folderPath, realpath, platform);
+        if (!target)
+            throw new Error('项目文件夹不能为空');
+        let created = false;
+        let chosen = null;
+        this.rewrite((projects) => {
+            const existing = locateProject(projects, target, realpath, platform);
+            if (existing) {
+                chosen = existing;
+                return projects;
+            }
+            const name = uniqueProjectName(projects, pathFor(platform).basename(target) || 'project');
+            chosen = buildProject(name, target, { name, folderPath: target, origin: options?.origin });
+            created = true;
+            return [...projects, chosen];
+        });
+        return { project: chosen, created };
+    }
+    update(id, updates) {
+        let updated = null;
+        this.rewrite((projects) => {
+            const idx = projects.findIndex((p) => p.id === id);
+            if (idx === -1)
+                throw new Error('项目不存在');
+            const current = projects[idx];
+            const nextName = updates.name !== undefined ? updates.name.trim() : current.name;
+            if (!nextName)
+                throw new Error('项目名称不能为空');
+            const nameClash = projects.some((p) => p.id !== id && p.name.toLowerCase() === nextName.toLowerCase());
+            if (nameClash)
+                throw new Error(`已存在同名项目「${nextName}」`);
+            const nextFolder = updates.folderPath !== undefined
+                ? updates.folderPath.trim()
+                : current.folderPath;
+            if (!nextFolder)
+                throw new Error('项目文件夹不能为空');
+            const sourceFolders = updates.sourceFolders !== undefined
+                ? normalizeSourceFolders(updates.sourceFolders, nextFolder)
+                : normalizeSourceFolders(current.sourceFolders, nextFolder);
+            const next = {
+                ...current,
+                name: nextName,
+                folderPath: nextFolder,
+                sourceFolders: sourceFolders.length > 0 ? sourceFolders : undefined,
+                updatedAt: new Date().toISOString(),
+            };
+            updated = next;
+            const copy = projects.slice();
+            copy[idx] = next;
+            return copy;
+        });
+        return updated;
     }
     delete(id) {
-        const projects = this.list();
-        const next = projects.filter((p) => p.id !== id);
-        if (next.length === projects.length)
-            return false;
-        this.store.set(STORE_KEY, next);
-        return true;
+        let removed = false;
+        this.rewrite((projects) => {
+            const next = projects.filter((p) => p.id !== id);
+            removed = next.length !== projects.length;
+            return removed ? next : projects;
+        });
+        return removed;
     }
     /**
      * 按 orderedIds 重排侧边栏。未出现的 id 忽略；名单里没提到的项目
      * 保持相对顺序接在后面。写入连续的 sortOrder，list() 随后按该序号返回。
      */
     reorder(orderedIds) {
-        const current = this.list();
-        const byId = new Map(current.map((project) => [project.id, project]));
-        const next = [];
-        const seen = new Set();
-        for (const id of orderedIds) {
-            const project = byId.get(id);
-            if (!project || seen.has(id))
-                continue;
-            seen.add(id);
-            next.push(project);
-        }
-        for (const project of current) {
-            if (!seen.has(project.id))
+        let stamped = [];
+        this.rewrite((projects) => {
+            const current = [...projects].sort(compareProjects);
+            const byId = new Map(current.map((project) => [project.id, project]));
+            const next = [];
+            const seen = new Set();
+            for (const id of orderedIds) {
+                const project = byId.get(id);
+                if (!project || seen.has(id))
+                    continue;
+                seen.add(id);
                 next.push(project);
-        }
-        const stamped = next.map((project, index) => ({
-            ...project,
-            sortOrder: index,
-        }));
-        this.store.set(STORE_KEY, stamped);
+            }
+            for (const project of current) {
+                if (!seen.has(project.id))
+                    next.push(project);
+            }
+            stamped = next.map((project, index) => ({
+                ...project,
+                sortOrder: index,
+            }));
+            return stamped;
+        });
         return stamped;
     }
     /**
@@ -125,17 +183,28 @@ export class ProjectRegistry {
     }
     /** W6-5: grant or revoke trust. Returns the updated record. */
     setTrusted(id, trusted) {
-        const projects = this.list();
-        const idx = projects.findIndex((p) => p.id === id);
-        if (idx === -1)
-            throw new Error('项目不存在');
-        const next = {
-            ...projects[idx],
-            trusted,
-            updatedAt: new Date().toISOString(),
-        };
-        projects[idx] = next;
-        this.store.set(STORE_KEY, projects);
+        let updated = null;
+        this.rewrite((projects) => {
+            const idx = projects.findIndex((p) => p.id === id);
+            if (idx === -1)
+                throw new Error('项目不存在');
+            const next = {
+                ...projects[idx],
+                trusted,
+                updatedAt: new Date().toISOString(),
+            };
+            updated = next;
+            const copy = projects.slice();
+            copy[idx] = next;
+            return copy;
+        });
+        return updated;
+    }
+    rewrite(update) {
+        if (this.store.mutate)
+            return this.store.mutate(STORE_KEY, update);
+        const next = update([...(this.store.get(STORE_KEY) ?? [])]);
+        this.store.set(STORE_KEY, next);
         return next;
     }
 }
@@ -167,3 +236,62 @@ function normalizeSourceFolders(folders, homePath) {
     }
     return out;
 }
+function buildProject(name, folderPath, input) {
+    const sourceFolders = normalizeSourceFolders(input.sourceFolders, folderPath);
+    const now = new Date().toISOString();
+    return {
+        id: randomUUID(),
+        name,
+        folderPath,
+        ...(sourceFolders.length > 0 ? { sourceFolders } : {}),
+        ...(input.origin === 'cli' ? { origin: 'cli' } : {}),
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+function uniqueProjectName(projects, base) {
+    const taken = new Set(projects.map((project) => project.name.toLowerCase()));
+    if (!taken.has(base.toLowerCase()))
+        return base;
+    for (let index = 2; index < 1000; index += 1) {
+        const candidate = `${base}-${index}`;
+        if (!taken.has(candidate.toLowerCase()))
+            return candidate;
+    }
+    throw new Error('无法分配项目名称：重名过多');
+}
+function pathFor(platform) {
+    return platform === 'win32' ? path.win32 : path.posix;
+}
+function canonicalFolder(folderPath, realpath, platform) {
+    const absolute = pathFor(platform).resolve(folderPath.trim());
+    if (!absolute)
+        return '';
+    try {
+        return realpath(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+function locateProject(projects, target, realpath, platform) {
+    const platformPath = pathFor(platform);
+    const keyed = projects.map((project) => ({
+        project,
+        key: canonicalFolder(project.folderPath, realpath, platform),
+    }));
+    const exact = keyed.find((item) => platformPath.relative(item.key, target) === '');
+    if (exact)
+        return exact.project;
+    const parents = keyed
+        .filter((item) => isInsideFolder(item.key, target, platformPath))
+        .sort((left, right) => right.key.length - left.key.length);
+    return parents[0]?.project ?? null;
+}
+function isInsideFolder(parent, child, platformPath) {
+    const relative = platformPath.relative(parent, child);
+    return relative !== ''
+        && relative !== '..'
+        && !relative.startsWith(`..${platformPath.sep}`)
+        && !platformPath.isAbsolute(relative);
+}

package/dist/project-rules.d.ts

@@ -12,4 +12,6 @@ export interface ProjectRules {
  * 向上遍历在「用户 home 目录」处封顶（若项目不在 home 下则按 MAX_LEVELS
  * 封顶）——不扫 `/`、`/etc` 这类与项目无关的祖先目录。
  */
+/** Rule-file paths only. Does not read file bodies. */
+export declare function listProjectRuleFiles(folderPath: string): string[];
 export declare function loadProjectRuleFiles(folderPath: string): ProjectRules;

package/dist/project-rules.js

@@ -7,8 +7,9 @@
  * WorldState 的一节），我们此前完全没有。
  *
  * 安全前提（W6-5）：这些文件是「项目作者写给 agent 的指令」，属于不可信输入。
- * 本模块只做发现并返回内容；**是否注入由调用方按项目信任状态决定**——未信任
- * 的项目一律不调用本模块。遍历与注入都有硬上限，单个文件与总量都截断。
+ * 本模块只做发现并返回内容。未信任的项目只调用 `listProjectRuleFiles`
+ * （stat，不读正文）；`loadProjectRuleFiles` 读取正文，仅在已信任时调用。
+ * 遍历与注入都有硬上限，单个文件与总量都截断。
  *
  * 「热重载」按回合粒度天然成立：每个回合重新读取磁盘，规则文件保存即生效，
  * 不需要文件 watcher。
@@ -33,13 +34,13 @@ const EMPTY = { files: [], content: '', truncated: false };
  * 向上遍历在「用户 home 目录」处封顶（若项目不在 home 下则按 MAX_LEVELS
  * 封顶）——不扫 `/`、`/etc` 这类与项目无关的祖先目录。
  */
-export function loadProjectRuleFiles(folderPath) {
+/** Rule-file paths only. Does not read file bodies. */
+export function listProjectRuleFiles(folderPath) {
     if (!folderPath || !folderPath.trim())
-        return EMPTY;
+        return [];
     const start = path.resolve(folderPath);
     if (!fs.existsSync(start))
-        return EMPTY;
-    // 构造 根→…→起始目录 的目录链（根在前，越往后越贴近项目）。
+        return [];
     const home = os.homedir();
     const chain = [];
     let dir = start;
@@ -48,23 +49,22 @@ export function loadProjectRuleFiles(folderPath) {
         seen.add(dir);
         chain.unshift(dir);
         if (dir === home)
-            break; // 不越过 home 向上
+            break;
         const parent = path.dirname(dir);
         if (parent === dir)
-            break; // 已到文件系统根
+            break;
         dir = parent;
     }
-    // 根→叶收集规则文件；每层内 override 优先。
     const files = [];
     for (const d of chain) {
         for (const name of RULE_FILE_NAMES) {
-            const p = path.join(d, name);
+            const file = path.join(d, name);
             try {
-                if (fs.statSync(p).isFile())
-                    files.push(p);
+                if (fs.statSync(file).isFile())
+                    files.push(file);
             }
             catch {
-                // 不存在或不可读——跳过该文件。
+                // missing or unreadable
             }
             if (files.length >= MAX_RULE_FILES)
                 break;
@@ -72,6 +72,10 @@ export function loadProjectRuleFiles(folderPath) {
         if (files.length >= MAX_RULE_FILES)
             break;
     }
+    return files;
+}
+export function loadProjectRuleFiles(folderPath) {
+    const files = listProjectRuleFiles(folderPath);
     if (files.length === 0)
         return EMPTY;
     // 拼接并施加总量上限。

package/dist/scenario/pack.d.ts

@@ -5,4 +5,4 @@
  *
  * 契约全文与设计约束见 packages/pack-sdk/types/index.d.ts 头注释。
  */
-export type { ScenarioId, ToolMode, ToolExposure, PackToolContext, PackToolHandler, ToolContribution, ServiceFactory, ServiceCreateContext, MigrationContribution, SkillContribution, AgentSeedIdentity, AgentSeed, HttpRouteContribution, HttpRouteRequest, MainContribution, ComponentRef, SettingsPanelContribution, RouteContribution, ChatSlotContribution, CardRendererContribution, RendererContribution, BrandSpec, PackagingSpec, CliCommandIO, CliCommandSpec, ScenarioPack, PackBackendRouteResponse, PackBackendRouteRequest, PackBackendRoute, PackTurnObserver, PackTurnHooks, } from '@steerable/pack-sdk';
+export type { ScenarioId, ToolMode, ToolExposure, PackToolContext, PackToolHandler, ToolApprovalSpec, ToolContribution, ServiceFactory, ServiceCreateContext, MigrationContribution, SkillContribution, AgentSeedIdentity, AgentSeed, HttpRouteContribution, HttpRouteRequest, MainContribution, ComponentRef, SettingsPanelContribution, RouteContribution, ChatSlotContribution, CardRendererContribution, RendererContribution, BrandSpec, PackagingSpec, CliCommandIO, CliCommandSpec, ScenarioPack, PackBackendRouteResponse, PackBackendRouteRequest, PackBackendRoute, PackTurnObserver, PackTurnHooks, } from '@steerable/pack-sdk';

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

@@ -0,0 +1,55 @@
+export interface ApprovalCategoryLabelInput {
+    locale: string;
+    category: string;
+    toolName: string;
+    declaredLabel?: Readonly<Record<string, string>>;
+    translate: (message: string) => string;
+}
+/**
+ * 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 declare function resolveApprovalCategoryLabel(input: ApprovalCategoryLabelInput): string | undefined;
+/** English source string for the approval card. The web view translates it. */
+export declare function hostApprovalCategoryLabel(input: {
+    category: string;
+    toolName: string;
+    declaredLabel?: Readonly<Record<string, string>>;
+}): string | undefined;
+export type CwdFence = 'project' | 'workspace';
+/**
+ * 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 declare function approvalCwdFence(input: {
+    toolName: string;
+    cwd: unknown;
+    projectRoot: string | null;
+    workspaceRoot: string | null;
+    sourceFolders: readonly string[];
+    home?: string;
+}): CwdFence | false;
+/**
+ * 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 declare function shellCwdOutsideProject(input: {
+    toolName: string;
+    cwd: unknown;
+    projectRoot: string | null;
+    sourceFolders: readonly string[];
+    home?: string;
+}): boolean;