qlogicagent 2.11.3 → 2.11.5

package/dist/types/cli/permission-bootstrap.d.ts

@@ -15,6 +15,13 @@ export interface PermissionBootstrapDeps {
     sessionId: string;
     getTurnId(): string;
     getActiveProjectRoot(): string;
+    /**
+     * The live active tool workdir (where file/exec relative paths resolve). The
+     * cross-workspace classifier compares tool target paths against THIS, not
+     * getActiveProjectRoot — the latter is a (possibly snapshotted) project root
+     * used for memory/sessions and does not track the per-turn tool workdir.
+     */
+    getActiveWorkdir(): string;
     getAcpPermissionSession(): {
         sessionId: string;
         requestPermission(params: AcpPermissionRequestParams): Promise<{

package/dist/types/cli/session-coordinator.d.ts

@@ -8,5 +8,14 @@ export declare class CliPathService extends DefaultPathService implements PathSe
     constructor(mediaPersistence: MediaPersistence, toolBootstrap: ToolBootstrap);
     getActiveProjectRoot(): string;
     setActiveWorkdir(dir: string): void;
+    /**
+     * The exact directory the file/exec tools resolve relative paths against:
+     * setActiveWorkdir pushes this same value into toolBootstrap.setWorkdir
+     * (tool-bootstrap `workdir` + exec initCwd). The permission pipeline must
+     * classify cross-workspace ops against THIS, not getActiveProjectRoot()
+     * (which is also used for memory/sessions and may report a stale projectStore
+     * dir). Falls back to getActiveProjectRoot() before the first setActiveWorkdir.
+     */
+    getActiveWorkdir(): string;
     resolveProjectDir(projectId?: string): string | undefined;
 }

package/dist/types/cli/tool-bootstrap.d.ts

@@ -1,4 +1,5 @@
 import type { PortableTool } from "../skills/portable-tool.js";
+import type { PermissionMode } from "../runtime/ports/permission-contracts.js";
 import { type TaskToolHooks } from "../skills/tools/task-tool.js";
 import { type ExecProgress } from "../skills/tools/exec-tool.js";
 import type { AgentLogger } from "../agent/types.js";
@@ -7,6 +8,15 @@ import type { PathService, ToolCatalog } from "../runtime/ports/index.js";
 export { setMediaClientConfig, setProviderToolAPI } from "./media-runtime-facade.js";
 /** Enable or disable group security mode (blocks sensitive file access). */
 export declare function setGroupSecurityMode(enabled: boolean): void;
+export interface SandboxPermissionSnapshot {
+    mode: PermissionMode;
+    workdir: string;
+    allowedDirs: string[];
+    /** cut7c: current turn is an untrusted community-skill turn → tighten the sandbox. */
+    communityTurn: boolean;
+}
+/** Wire the OS-sandbox permission source (live rule-engine snapshot), or null to clear. */
+export declare function setSandboxPermissionSource(source: (() => SandboxPermissionSnapshot | undefined) | null): void;
 /** Set callback invoked after LLM-driven project switch. */
 export declare function setProjectSwitchCallback(cb: ((project: {
     id: string;
@@ -24,9 +34,30 @@ export declare function setTaskToolHooks(hooks: TaskToolHooks | undefined): void
  * If null, ask_user returns "user declined" to the LLM.
  */
 export declare function setAskUserCallback(callback: ((questions: AskUserQuestion[]) => Promise<Record<string, string> | null>) | null): void;
-/** Enable full-access mode for trusted sessions that may operate outside the workspace. */
-export declare function setBypassWorkspaceBoundary(bypass: boolean): void;
 export declare function setBootstrapWorkdir(newWorkdir: string): void;
+/**
+ * Enforce absolute, mode-independent floors. Returns an error message only for
+ * dangers that are NEVER allowed regardless of permission mode, null otherwise.
+ *
+ * Workspace membership is NO LONGER decided here: cross-workspace access is owned
+ * by the permission pipeline (the `tool.before_invoke` hook), which prompts in
+ * `default` mode and allows in `auto`/`full_access`. This function only blocks
+ * device/system paths that no mode should ever touch via file tools.
+ */
+export declare function enforceAbsoluteFloors(resolved: string): string | null;
+/**
+ * Validate a shell command string before execution.
+ *
+ * Cross-workspace access is NO LONGER blocked here — that decision is now owned
+ * by the permission pipeline (classifyOperation + hook-runner), which prompts in
+ * `default` mode and allows in `auto`/`full_access`.
+ *
+ * This function only enforces the absolute, mode-independent floor: device and
+ * system paths (/dev/* except /dev/null, /proc/*, /sys/*) that must never be
+ * accessible regardless of mode. Returns an error string on violation, null on
+ * pass.
+ */
+export declare function validateExecCommand(command: string, _workdir: string): string | null;
 export interface BootstrapConfig {
     workdir?: string;
     toolCatalog?: ToolCatalog;

package/dist/types/cli/turn-permission-sync.d.ts

@@ -1,7 +1,6 @@
-import type { PermissionBehavior, PermissionEngineConfig, PermissionMode, PermissionRuleEntry } from "../runtime/ports/index.js";
+import type { PermissionEngineConfig, PermissionMode, PermissionRuleEntry } from "../runtime/ports/index.js";
 export interface TurnPermissionRuleEngine {
     setMode(mode: PermissionMode): void;
     replaceRules(rules: PermissionRuleEntry[]): void;
-    setDefaultBehavior(behavior: PermissionBehavior): void;
 }
 export declare function syncTurnPermissionConfig(ruleEngine: TurnPermissionRuleEngine, rawPermissions: unknown): PermissionEngineConfig;

package/dist/types/protocol/wire/acp-protocol.d.ts

@@ -298,6 +298,7 @@ export interface AcpPermissionRequestParams {
         rawInput: Record<string, unknown>;
     };
     message?: string;
+    category?: string;
     options: AcpPermissionOption[];
 }
 export interface AcpPermissionOption {

package/dist/types/protocol/wire/chat-types.d.ts

@@ -96,5 +96,11 @@ export interface ToolDefinition {
         isReadOnly?: boolean;
         /** Tool can cause irreversible side-effects — force approval in default mode. */
         isDangerous?: boolean;
+        /** Tool deletes data (files, records, cloud resources). */
+        isDelete?: boolean;
+        /** Tool sends data or requests to an external service. */
+        isEgress?: boolean;
+        /** Egress carries user data (true) vs. read-only external query (false). */
+        egressCarriesData?: boolean;
     };
 }

package/dist/types/protocol/wire/notification-payloads.d.ts

@@ -271,6 +271,18 @@ export interface ToolApprovalRequestNotification {
     arguments: string;
     message?: string;
     suggestions?: string[];
+    category?: "cross_workspace" | "high_risk_delete" | "high_risk_egress" | "destructive";
+    reason?: string;
+    options?: Array<{
+        optionId: string;
+        name: string;
+        kind: string;
+        scope?: string;
+    }>;
+    rememberScope?: {
+        kind: "directory";
+        path: string;
+    };
 }
 /** Skill instruction directive. */
 export interface TurnSkillInstructionNotification {

package/dist/types/runtime/infra/default-path-service.d.ts

@@ -6,9 +6,12 @@ export interface DefaultPathServiceOptions {
 }
 export declare class DefaultPathService implements PathService {
     private readonly options;
+    /** Last directory set via setActiveWorkdir — the dir tool paths resolve against. */
+    private lastActiveWorkdir;
     constructor(options?: DefaultPathServiceOptions);
     getActiveProjectRoot(): string;
     setActiveWorkdir(dir: string): void;
+    getActiveWorkdir(): string;
     resolveProjectDir(projectId?: string): string | undefined;
     resolveActiveOwnerUserId(): string;
     getUserAgentHome(): string;

package/dist/types/runtime/infra/model-registry.d.ts

@@ -1,3 +1,4 @@
+import { type ReasoningMode } from "./provider-catalog-adapter.js";
 import { type KeyConfig, type KeyHandle, type LoadBalanceStrategy, type PoolStatus, type ProviderPoolConfig } from "./key-pool.js";
 export type RegistryChangeCallback = () => void;
 export type ModelPurpose = "textGeneration" | "smallModel" | "stt" | "tts" | "imageGeneration" | "imageUnderstanding" | "videoGeneration" | "videoUnderstanding" | "threeDGeneration" | "embedding" | "voiceClone" | "musicGeneration" | "realtimeAudio" | "realtimeVideo";
@@ -34,6 +35,8 @@ export interface ModelEntry {
     streamRequired?: boolean;
     capabilities?: string[];
     pricing?: Record<string, unknown>;
+    /** Thinking-strength control class for the UI (see ReasoningMode). */
+    reasoningMode?: ReasoningMode;
 }
 export type PurposeBindings = Partial<Record<ModelPurpose, string>>;
 export interface ModelRegistryConfig {

package/dist/types/runtime/infra/provider-catalog-adapter.d.ts

@@ -1,5 +1,17 @@
 import { type ProviderVariantCapability } from "@xiaozhiclaw/provider-core";
 export type RuntimeProviderVariantCapability = ProviderVariantCapability;
+/**
+ * How a model's thinking depth can be controlled, derived from provider-core
+ * capabilities + quirks. The UI maps each mode to a different effort option set:
+ *   - none      : model has no reasoning/thinking → hide the strength control
+ *   - adaptive  : model self-regulates depth natively (Anthropic Opus/Sonnet
+ *                 type:"adaptive") → only "智能"
+ *   - collapsed : provider collapses effort levels (DeepSeek: low/medium→high,
+ *                 high/xhigh→max) → "标准 / 最大" only
+ *   - effort    : full granular control honored (o-series/Kimi reasoning_effort,
+ *                 Anthropic budget thinking) → full 5 options
+ */
+export type ReasoningMode = "none" | "adaptive" | "collapsed" | "effort";
 export interface RuntimeProviderCatalogProvider {
     id: string;
     name: string;
@@ -24,6 +36,8 @@ export interface RuntimeProviderCatalogModel {
     costCacheRead?: number;
     costCacheWrite?: number;
     pricing?: Record<string, unknown>;
+    /** Derived control class for thinking strength (see ReasoningMode). */
+    reasoningMode?: ReasoningMode;
 }
 export interface RuntimeProviderVariantResolutionInput {
     publicModel: string;

package/dist/types/runtime/permission-model.d.ts

@@ -0,0 +1,19 @@
+import type { PermissionMode, PermissionPromptCategory } from "./ports/permission-contracts.js";
+export interface PermissionPromptOption {
+    optionId: string;
+    name: string;
+    kind: "allow_once" | "allow_always" | "reject_once" | "reject_always";
+    scope?: "once" | "directory";
+}
+export interface PermissionModeDescriptor {
+    id: PermissionMode;
+    label: string;
+    summary: string;
+    description: string;
+}
+export interface PermissionModelContract {
+    modes: PermissionModeDescriptor[];
+    promptOptions: Record<PermissionPromptCategory, PermissionPromptOption[]>;
+}
+export declare function promptOptionsForCategory(category: PermissionPromptCategory): PermissionPromptOption[];
+export declare function buildPermissionModel(): PermissionModelContract;

package/dist/types/runtime/ports/path-service.d.ts

@@ -1,6 +1,16 @@
 export interface PathService {
     getActiveProjectRoot(): string;
     setActiveWorkdir(dir: string): void;
+    /**
+     * The directory the file/exec tools actually operate in (where relative tool
+     * paths resolve and the shell session's cwd lives). This is the value last set
+     * via setActiveWorkdir — it is the authoritative "active workdir" used by the
+     * permission pipeline to classify cross-workspace operations. It can differ
+     * from getActiveProjectRoot() (which feeds memory/sessions/project-agent-dir):
+     * getActiveProjectRoot may be a captured snapshot, while this always tracks the
+     * live tool workdir. Falls back to getActiveProjectRoot() if never set.
+     */
+    getActiveWorkdir(): string;
     resolveProjectDir(projectId?: string): string | undefined;
     resolveActiveOwnerUserId(): string;
     getUserAgentHome(): string;

package/dist/types/runtime/ports/permission-contracts.d.ts

@@ -1,12 +1,20 @@
 export type PermissionMode = "default" | "auto" | "full_access";
 export declare const PERMISSION_MODES: readonly PermissionMode[];
 export type PermissionBehavior = "allow" | "ask" | "deny";
+export type PermissionPromptCategory = "cross_workspace" | "high_risk_delete" | "high_risk_egress" | "destructive";
 export type PermissionRiskLevel = "read" | "write" | "system" | "external_egress";
 export interface PermissionRuleEntry {
     pattern: string;
+    pathPrefix?: string;
     behavior: PermissionBehavior;
     reason?: string;
     source?: string;
+    /**
+     * When set, the rule only matches if this operation-classification flag is true
+     * (in addition to pattern/pathPrefix). Lets a rule target an operation property
+     * (e.g. a shell command that performs network egress) rather than just a tool name.
+     */
+    requireOp?: "commandNetworkEgress";
 }
 export type PermissionDecisionReason = {
     type: "rule";
@@ -45,6 +53,12 @@ export interface PermissionAskResult {
     message: string;
     toolName: string;
     input?: Record<string, unknown>;
+    category?: PermissionPromptCategory;
+    semanticCheck?: "delete" | "egress";
+    rememberScope?: {
+        kind: "directory";
+        path: string;
+    };
     decisionReason?: PermissionDecisionReason;
 }
 export interface PermissionDenyResult {
@@ -58,7 +72,6 @@ export interface PermissionConfig {
 }
 export interface PermissionEngineConfig extends PermissionConfig {
     rules: PermissionRuleEntry[];
-    defaultBehavior: PermissionBehavior;
 }
 export interface ToolPermissionCheckInput {
     toolName: string;
@@ -69,6 +82,9 @@ export interface ToolPermissionCheckInput {
         isDangerous?: boolean;
         requiresApproval?: boolean;
         parallelSafe?: boolean;
+        isDelete?: boolean;
+        isEgress?: boolean;
+        egressCarriesData?: boolean;
     };
 }
 export interface ApprovalRequest {
@@ -77,19 +93,26 @@ export interface ApprovalRequest {
     toolName: string;
     arguments?: Record<string, unknown>;
     message: string;
+    /** Prompt category carried through from the decision pipeline (UI hint). */
+    category?: PermissionPromptCategory;
+    /** When set, the host may offer a "remember this directory" scope option. */
+    rememberScope?: {
+        kind: "directory";
+        path: string;
+    };
 }
 export interface ApprovalResponse {
     approvalId: string;
     decision: "allow" | "deny";
     updatedInput?: Record<string, unknown>;
+    /** Approval scope chosen by the user: just this call, or the whole directory. */
+    scope?: "once" | "directory";
 }
 export interface PermissionRuleEnginePort {
     getMode(): PermissionMode;
     setMode(mode: PermissionMode): void;
     getRules(): readonly PermissionRuleEntry[];
     replaceRules(rules: PermissionRuleEntry[]): void;
-    getDefaultBehavior(): PermissionBehavior;
-    setDefaultBehavior(behavior: PermissionBehavior): void;
 }
 export interface PermissionApprovalResolver {
     resolveApproval(response: ApprovalResponse): void;

package/dist/types/runtime/ports/tool-contracts.d.ts

@@ -21,6 +21,9 @@ export interface RuntimeToolContract {
     isConcurrencySafe?: boolean;
     isReadOnly?: boolean;
     riskLevel?: PermissionRiskLevel;
+    isDelete?: boolean;
+    isEgress?: boolean;
+    egressCarriesData?: boolean;
     isEnabled?: () => boolean;
     shouldDefer?: boolean;
     execute?(toolCallId: string, params: any, signal?: AbortSignal): Promise<{

package/dist/types/runtime/ports/tool-risk.d.ts

@@ -0,0 +1,7 @@
+import type { PermissionRiskLevel, ToolPermissionCheckInput } from "./permission-contracts.js";
+/**
+ * 唯一风险分级核心。优先级:显式 riskLevel > isDangerous("system") > isReadOnly("read") > isEgress("external_egress") > 默认 "write"。
+ * isDangerous 优先于 isReadOnly:工具不应同时为二者,冲突时取更危险的分级。
+ * 调用点(tools.ts 的 manifest 构建、tool-eligibility 的资格判定)各自在其上叠加专属逻辑(category 推断 / name-pattern 升级)。
+ */
+export declare function resolveToolRisk(meta: ToolPermissionCheckInput["meta"]): PermissionRiskLevel;

package/dist/types/skills/permissions/community-sandbox-policy.d.ts

@@ -1,3 +1,3 @@
 import type { PermissionRuleEntry } from "./types.js";
 export type CommunitySandboxRuleId = "community-l1-shell" | "community-l1-file-read" | "community-l1-file-write" | "community-l1-network" | "community-l1-mcp" | "community-l1-host-control" | "community-l2-host-side-effect" | "community-l2-data-egress" | "community-l2-provider-prompt-egress" | "community-l2-provider-media-egress";
-export declare function createCommunityL1SandboxRules(): PermissionRuleEntry[];
+export declare function createCommunitySandboxScopedRules(): PermissionRuleEntry[];

package/dist/types/skills/permissions/hook-runner.d.ts

@@ -9,6 +9,8 @@ export type PermissionRole = "interactive" | "coordinator" | "worker";
 export interface PermissionCheckerDeps {
     ruleEngine: PermissionRuleEngine;
     hookRegistry: HookRegistry;
+    /** Returns the current workspace root for operation classification. */
+    getWorkspaceRoot(): string;
     /**
      * Callback to send an approval request to the host (Gateway/Electron).
      * Must return a promise that resolves when the user responds.
@@ -52,6 +54,7 @@ export interface PermissionCheckerDeps {
 export declare class PermissionChecker {
     private readonly ruleEngine;
     private readonly hookRegistry;
+    private readonly getWorkspaceRoot;
     private readonly onRequestApproval;
     private readonly onDenied;
     private readonly classifierLLMCall;
@@ -63,7 +66,13 @@ export declare class PermissionChecker {
     private readonly getTurnId;
     private readonly communityTelemetryRecorder;
     private readonly communitySandboxTurnIds;
-    private readonly communitySandboxRuleEngine;
+    /**
+     * cut7c — community-skill (untrusted) scoped deny/ask rules, passed per-call as
+     * `ruleEngine.check(..., { extraRules })` for community turns. NOT a second engine:
+     * the single rule engine evaluates these alongside the base rules. FS/exec tools are
+     * absent here → they flow through the unified pipeline (workspace + prompt + OS sandbox).
+     */
+    private readonly communityScopedRules;
     private unregisterHook;
     /** Tool meta cache — populated from ToolDefinition[] at agent creation */
     private toolMetaCache;
@@ -86,7 +95,12 @@ export declare class PermissionChecker {
      */
     setToolMeta(tools: ToolDefinition[]): void;
     get ruleEngineRef(): PermissionRuleEngine;
-    private checkCommunitySandboxThenBase;
+    /**
+     * cut7c — whether the CURRENT turn is a community-skill (untrusted) turn. Consumed by
+     * the OS-sandbox builder to tighten community execs (netPolicy=deny: no outbound network
+     * from the sandboxed child) as defense-in-depth on POSIX.
+     */
+    isCommunitySandboxTurn(): boolean;
     /** Fire permission.denied hook + onDenied callback + audit log */
     private fireDenied;
     private handleResult;

package/dist/types/skills/permissions/operation-classifier.d.ts

@@ -0,0 +1,43 @@
+import type { ToolPermissionCheckInput } from "../../runtime/ports/permission-contracts.js";
+/**
+ * 确定性操作归类。注意两个危险信号是分工的、互不包含:
+ * - `isDestructive`:shell 破坏性操作(rm -rf、dd、管道下载执行等)+ 递归删除 → 下游走"无条件保底必弹"。
+ * - `isDelete`:任意删除(含 meta 标注的删除工具)→ 下游单独走"该文件是否有用"的语义复核,不并入 isDestructive。
+ * 消费方(决策流水线)分别独立检查 isDestructive 与 isDelete。
+ */
+export interface OperationClassification {
+    targetPaths: string[];
+    inWorkspace: boolean;
+    crossWorkspace: boolean;
+    isDelete: boolean;
+    isRecursiveDelete: boolean;
+    isEgress: boolean;
+    egressCarriesData: boolean;
+    isDestructive: boolean;
+    /**
+     * Shell command performs network egress (curl/wget/nc/scp/...). Used to gate
+     * untrusted community-skill shell commands (which would otherwise bypass the
+     * web_fetch/web_search deny via raw shell). Best-effort detection; the OS sandbox
+     * (netPolicy=deny on community turns) is the robust second layer on POSIX.
+     */
+    commandNetworkEgress: boolean;
+}
+export interface ClassifyContext {
+    workspaceRoot: string;
+}
+/**
+ * Canonical set of shell-command tool names. This is the single source of truth,
+ * imported and used by BOTH `classifyOperation` (below) AND hook-runner's bash
+ * pre-filter, so the two stay aligned. Includes the `Bash` case-variant.
+ */
+export declare const SHELL_TOOL_NAMES: Set<string>;
+export declare function isWithinWorkspace(resolved: string, root: string): boolean;
+/**
+ * 提取 shell 命令引用的路径(重定向目标 + Unix/Windows/相对路径),解析为绝对路径。
+ * 移植自 exec validateCommand;win32 下把 /c/Users → C:\Users;跳过单字母 flag(/c /s …);
+ * /dev/null 不计入(由绝对底线另处理)。供 classifyOperation 与 exec validateCommand 共用(单一源)。
+ * 扫描层用聚焦 shell tokenizer(替代正则):正确处理带空格的引号路径、管道/&& 后的路径、
+ * 以及单/双引号内的字面 `>`(不当作重定向)。push() 的过滤/解析逻辑保持不变。
+ */
+export declare function extractCommandPaths(command: string, root: string): string[];
+export declare function classifyOperation(input: ToolPermissionCheckInput, ctx: ClassifyContext): OperationClassification;

package/dist/types/skills/permissions/rule-engine.d.ts

@@ -1,34 +1,48 @@
+import type { OperationClassification } from "./operation-classifier.js";
 import type { PermissionMode, PermissionBehavior, PermissionResult, PermissionRuleEntry, PermissionEngineConfig, ToolPermissionCheckInput } from "./types.js";
 export declare class PermissionRuleEngine {
     private mode;
     private rules;
-    private defaultBehavior;
+    private sessionRules;
     private compiledPatterns;
     constructor(config: PermissionEngineConfig);
     getMode(): PermissionMode;
     setMode(mode: PermissionMode): void;
     getRules(): readonly PermissionRuleEntry[];
-    getDefaultBehavior(): PermissionBehavior;
-    /** Replace all rules at once (for settings hot-reload). */
+    /** Replace all persistent rules at once (for settings hot-reload). Session rules are preserved. */
     replaceRules(rules: PermissionRuleEntry[]): void;
-    /** Update the default behavior (for settings hot-reload). */
-    setDefaultBehavior(behavior: PermissionBehavior): void;
     addRule(rule: PermissionRuleEntry): void;
+    /** Add a session-scoped rule (e.g. "remember directory" approvals). */
+    addSessionRule(rule: {
+        pathPrefix?: string;
+        pattern?: string;
+        behavior?: PermissionBehavior;
+    }): void;
+    /** sandbox 可写根:rules + sessionRules 中 allow 且带 pathPrefix 的目录(去重)。 */
+    getAllowedWriteDirectories(): string[];
     /**
-     * 4-layer permission check (cc hasPermissionsToUseTool parity).
+     * Workspace + danger decision pipeline.
      *
-     * Layer 0: Mode override
-     * Layer 1: Explicit rules (first match wins)
-     * Layer 2: Unified tool risk metadata
-     * Layer 3: Default behavior
+     * `op` is optional and defaults to an all-false classification so callers
+     * that have not yet been wired to the classifier keep compiling.
      */
-    check(input: ToolPermissionCheckInput): PermissionResult;
-    private compileRules;
+    check(input: ToolPermissionCheckInput, op?: OperationClassification, ctx?: {
+        extraRules?: readonly PermissionRuleEntry[];
+    }): PermissionResult;
+    /** Rebuild compiledPatterns: [persistent-deny] → [session] → [persistent non-deny]. */
+    private recompile;
+    /**
+     * Match a caller-supplied rule set (deny-first) against this call, using the SAME
+     * matching semantics as the base rules (pathPrefix prefix-match, else toolName glob).
+     * Returns the first hit's result, or null if none match. Used for per-call scoped
+     * rules (community-skill turns) so trust-level restrictions stay in the one engine.
+     */
+    private matchRuleSet;
 }
 /**
  * Parse permission config from Gateway-injected or local settings.
  *
- * Accepts only the user-facing permission mode. Historical rules/defaultBehavior
- * fields are ignored so old config cannot create a fourth user permission mode.
+ * Accepts the user-facing permission mode plus the persistent `rules` channel.
+ * Legacy top-level alias keys (allow/deny/ask arrays, default) are still rejected.
  */
 export declare function parsePermissionConfig(raw: unknown): PermissionEngineConfig;

package/dist/types/skills/portable-tool.d.ts

@@ -104,6 +104,24 @@ export interface PortableTool<TParams = Record<string, unknown>> {
      * Used by permission system to require confirmation.
      */
     isDestructive?: boolean;
+    /**
+     * Whether this tool deletes data (files, records, resources).
+     * Distinct from isDestructive (shell-level) — this is a semantic annotation
+     * on tools that explicitly delete. Downstream uses separate delete-specific
+     * confirmation logic from the general destructive-shell path.
+     */
+    isDelete?: boolean;
+    /**
+     * Whether this tool sends data to an external service (egress).
+     * When true, the tool is classified as external_egress risk.
+     */
+    isEgress?: boolean;
+    /**
+     * Whether egress carries user data (as opposed to read-only queries).
+     * Only meaningful when isEgress is true.
+     * Examples: send_message (true), web_search (false).
+     */
+    egressCarriesData?: boolean;
     /**
      * Tool-specific permission check before execution.
      * CC parity: Tool.checkPermissions — returns allow/deny with reason.

package/dist/types/skills/tools/exec-tool.d.ts

@@ -1,5 +1,6 @@
 import type { PortableTool } from "../portable-tool.js";
 import type { CommandClassification } from "./shell/command-classification.js";
+import type { SandboxConfig } from "./shell/sandbox/sandbox-types.js";
 export declare const EXEC_TOOL_NAME: "exec";
 export interface ExecToolParams {
     command: string;
@@ -72,6 +73,12 @@ export interface ExecToolHost {
      * Returns null/undefined if allowed, or an error message if blocked.
      */
     validateCommand?(command: string): Promise<string | null | undefined>;
+    /**
+     * Resolve the OS-sandbox context for this exec (snapshot of the permission
+     * single-source: mode + active workdir + approved dirs + helper availability).
+     * Returns undefined to disable the OS sandbox (degrade to prompt-only).
+     */
+    resolveSandbox?(): SandboxConfig | undefined;
     /**
      * Interpret a non-zero exit code.
      * E.g. 127 → "command not found", 137 → "killed by SIGKILL".

package/dist/types/skills/tools/patch-tool.d.ts

@@ -41,5 +41,12 @@ interface MatchResult {
     strategy: MatchStrategy;
 }
 declare function fuzzyFind(content: string, search: string, replaceAll: boolean): MatchResult[];
+export interface PatchTargets {
+    /** Every file path the patch adds, updates, deletes, or moves (source + destination). */
+    paths: string[];
+    /** Paths removed via a *** Delete File: directive. */
+    deletes: string[];
+}
+export declare function extractPatchTargets(input: string): PatchTargets;
 export declare function createPatchTool(deps: PatchToolDeps): PortableTool<PatchToolParams>;
 export { fuzzyFind, type MatchResult };

package/dist/types/skills/tools/shell/sandbox/helper-resolver.d.ts

@@ -0,0 +1,7 @@
+interface ResolveOpts {
+    env?: string;
+    exists?: (p: string) => boolean;
+}
+/** 定位 landlock-exec:env 覆盖 → dist/native 默认 → null(降级)。 */
+export declare function resolveLandlockHelper(opts?: ResolveOpts): string | null;
+export {};

package/dist/types/skills/tools/shell/sandbox/landlock-argv.d.ts

@@ -0,0 +1,6 @@
+import type { NetPolicy } from "./sandbox-types.js";
+/**
+ * 构造 landlock helper 调用:`<helper> --allow-write R ... [--deny-net] -- <bin> <args>`。
+ * helper 在真实路径上加 landlock 写限制(读不 handle=放开),restrict_self 后 execve 原命令。
+ */
+export declare function buildLandlockArgv(helperPath: string, writableRoots: string[], netPolicy: NetPolicy, bin: string, args: string[]): string[];

package/dist/types/skills/tools/shell/sandbox/platform.d.ts

@@ -0,0 +1,3 @@
+export type SandboxPlatform = "win32" | "darwin" | "linux" | "other";
+/** 集中平台判定(仅 sandbox 模块用,不全局重构)。 */
+export declare function currentPlatform(): SandboxPlatform;

package/dist/types/skills/tools/shell/sandbox/sandbox-launcher.d.ts

@@ -0,0 +1,15 @@
+import type { DecideSandboxInput, SandboxConfig, SandboxDecision } from "./sandbox-types.js";
+import type { SandboxPlatform } from "./platform.js";
+/**
+ * 纯决策:平台 + 模式 + 可用性 → 包裹或降级。
+ * 降级永不抛、永不拒执行(spec「降级安全」)。
+ */
+export declare function decideSandbox(input: DecideSandboxInput): SandboxDecision;
+/** shell-exec 单次入口:派生 scope → 决策 → 返回 spawn 应用的 bin/args + useSandbox。 */
+export declare function applySandboxToSpawn(platform: SandboxPlatform, config: SandboxConfig, bin: string, args: string[]): {
+    bin: string;
+    args: string[];
+    useSandbox: boolean;
+    sandboxTmpDir?: string;
+    reason: string;
+};

package/dist/types/skills/tools/shell/sandbox/sandbox-scope.d.ts

@@ -0,0 +1,6 @@
+import type { SandboxConfig } from "./sandbox-types.js";
+/**
+ * 沙箱可写根集 = active workdir + 批准/持久 allow 目录 + 工具记账目录 + 沙箱临时目录。
+ * 读全放开,故无读根。resolve + 去重。
+ */
+export declare function deriveWritableRoots(config: SandboxConfig): string[];

package/dist/types/skills/tools/shell/sandbox/sandbox-types.d.ts

@@ -0,0 +1,47 @@
+import type { PermissionMode } from "../../../../runtime/ports/permission-contracts.js";
+import type { SandboxPlatform } from "./platform.js";
+/** 网络出站策略:allow=放开;deny=禁非回环出站(细粒度留后)。 */
+export type NetPolicy = "allow" | "deny";
+/**
+ * Host 在每次 exec 前注入的沙箱上下文(权限单一真相的快照)。
+ * undefined 表示 host 不启用沙箱(由调用方决定)。
+ */
+export interface SandboxConfig {
+    mode: PermissionMode;
+    /** active workdir(pathService.getActiveWorkdir()),恒为可写根。 */
+    workdir: string;
+    /** 已批准/持久 allow 的目录(rule-engine.getAllowedWriteDirectories())。 */
+    allowedDirs: string[];
+    /** 工具记账可写目录(taskOutputDir + snapshot 目录),恒可写。 */
+    bookkeepingDirs: string[];
+    /** 沙箱内 cwd/snapshot 临时目录(可写;= sandboxTmpDir)。 */
+    tmpDir: string;
+    /** Linux landlock helper 路径(null=不可用→降级)。 */
+    helperPath: string | null;
+    /** sandbox-exec 是否可用(macOS;由 host 探测)。 */
+    sandboxExecAvailable: boolean;
+    netPolicy: NetPolicy;
+}
+/** decideSandbox 的输出:是否包裹 + 最终 spawn 的 bin/args。 */
+export interface SandboxDecision {
+    /** 是否实际包裹(false=降级,直接用原 bin/args)。 */
+    wrapped: boolean;
+    bin: string;
+    args: string[];
+    /** 传给 provider.buildExecCommand 的 useSandbox。 */
+    useSandbox: boolean;
+    /** 包裹时的可写临时目录(cwdFile 落点);未包裹=undefined。 */
+    sandboxTmpDir?: string;
+    /** 决策原因(日志/可观测;降级时写 warn)。 */
+    reason: string;
+}
+/** decideSandbox 的纯输入(平台/可用性显式传入以便跨平台单测)。 */
+export interface DecideSandboxInput {
+    platform: SandboxPlatform;
+    config: SandboxConfig;
+    /** 原始 spawn 目标。 */
+    bin: string;
+    args: string[];
+    /** 派生好的可写根(deriveWritableRoots 结果)。 */
+    writableRoots: string[];
+}