@tencent-ai/agent-harness 0.2.0-beta.6 → 0.2.0-beta.8

package/cli/dist-server/types/node/permission/directory-trust-service.d.ts

@@ -0,0 +1,45 @@
+import { Logger } from '@celljs/core';
+import { SettingsManager } from '../settings';
+import { DirectoryTrustService } from './permission-protocol';
+export declare class DirectoryTrustServiceImpl implements DirectoryTrustService {
+    protected readonly logger: Logger;
+    protected readonly settingsManager: SettingsManager;
+    private trustedDirectories;
+    private trustAll;
+    private initializedDeferred;
+    private trustDirDeferred;
+    isTrustDirectoryPromise: Promise<void>;
+    initialized: Promise<void>;
+    isTrustDirectory: boolean;
+    protected init(): void;
+    /**
+     * 检查目录是否为危险目录
+     */
+    isDangerousDirectory(dirPath: string): boolean;
+    private normalizePath;
+    /**
+     * 判断目标路径是否匹配信任规则（支持 glob 通配符）
+     * @param pattern 信任规则，可以是精确路径或 glob 模式（如 /path/** 表示递归信任）
+     * @param targetPath 要检查的目标路径
+     */
+    private matchTrustPattern;
+    /**
+     * 检查目录是否需要显示授权提示
+     */
+    needsAuthorization(dirPath: string): boolean;
+    /**
+     * 信任目录
+     * @param dirPath 要信任的目录路径
+     * @param permanent 是否永久保存（危险目录建议为 false）
+     * @param recursive 是否递归信任子目录（为 true 时会添加 /** 后缀）
+     */
+    trustDirectory(dirPath: string, permanent?: boolean, recursive?: boolean): void;
+    /**
+     * 加载已信任的目录
+     */
+    private doInit;
+    /**
+     * 保存已信任的目录
+     */
+    private saveTrustedDirectories;
+}

package/cli/dist-server/types/node/permission/file-policy-assessment.d.ts

@@ -0,0 +1,35 @@
+import type { DecisionRecord } from '../../workspace/sandbox-cli/lib/common/protocol.generated.js';
+import type { FileBlockRecord } from '../sandbox-cli/sandbox-cli-protocol';
+/** Approval/audit presentation only. Access decisions belong to Sandbox Center. */
+export type RiskLevel = 'low' | 'medium' | 'unknown' | 'high';
+export type SandboxExecutionMode = 'default' | 'bypass';
+export interface FilePolicyMatch {
+    pathPattern: string;
+    level: RiskLevel;
+    /** Legacy audit labels; the native matchRule still determines the verdict. */
+    source?: 'builtin' | 'user-allowlist' | 'user-blocklist';
+}
+export interface RiskAssessment {
+    record: FileBlockRecord;
+    level: RiskLevel;
+    matchedRule?: FilePolicyMatch;
+}
+export interface FilePolicyClassification {
+    autoApprove: RiskAssessment[];
+    needsApproval: RiskAssessment[];
+    denied: RiskAssessment[];
+    /** Kept for the existing audit DTO; command rules no longer downgrade file policy. */
+    commandAllowDowngradedCount: number;
+}
+export type BrokeredFileOperation = 'read' | 'write' | 'delete';
+export type BrokeredFileDecision = 'grant-token' | 'host-op' | 'deny' | 'prompt' | 'sandbox';
+export interface BrokeredFileAccessDecision {
+    /** Original Center verdict, carried unchanged into post-exec attribution. */
+    decisionRecord?: DecisionRecord;
+    decision: BrokeredFileDecision;
+    operation: BrokeredFileOperation;
+    path: string;
+    normalisedPath: string;
+    level: RiskLevel;
+    matchedRule?: FilePolicyMatch;
+}

package/cli/dist-server/types/node/permission/index.d.ts

@@ -0,0 +1,16 @@
+export * from './canonicalize-command';
+export * from './codebuddy-sandbox-env';
+export * from './directory-trust-service';
+export * from './permission-protocol';
+export * from '../../vendor/cbc-core/node/index.js';
+export * from './sandbox-attribution-analyzer';
+export * from './sandbox-audit-service';
+export * from './sandbox-exec-policy';
+export * from './sandbox-exec-policy-builtin';
+export * from './sandbox-exec-policy-protocol';
+export * from './sandbox-orchestrator';
+export * from './sandbox-orchestrator-protocol';
+export * from './sandbox-permission-gateway';
+export * from './file-policy-assessment';
+export * from './sandbox-telemetry-context';
+export * from './sensitive-command-detector';

package/cli/dist-server/types/node/permission/permission-protocol.d.ts

@@ -0,0 +1,9 @@
+export declare const DirectoryTrustService: unique symbol;
+export interface DirectoryTrustService {
+    initialized: Promise<void>;
+    isTrustDirectory: boolean;
+    isTrustDirectoryPromise: Promise<void>;
+    needsAuthorization(dirPath: string): boolean;
+    trustDirectory(dirPath: string, permanent?: boolean, recursive?: boolean): void;
+    isDangerousDirectory(dirPath: string): boolean;
+}

package/cli/dist-server/types/node/permission/sandbox-attribution-analyzer.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Sandbox Attribution Analyzer — 失败归因分析器。
+ *
+ * 设计文档 § 五-⑤ 定位：
+ * - 命令失败是"代码写错了"还是"沙箱拦住了"？只有后者才进入沙箱裁决处理。
+ * - 归因只做因果判断；文件权限由后续流程消费 Center 原始裁决。
+ *
+ * 归因矩阵（权限系统只关注硬拦截，越界写入到影子区不进入此矩阵）：
+ *
+ * | exitCode      | EPERM 拦截记录                                       | 归因             |
+ * |---------------|-----------------------------------------------------|-----------------|
+ * | 0 或 null     | 无 / 仅 `process-exec*` / 已知启动缓存噪声 / 仅 `sysctl/ioctl/IOKit` | ✅ `success`    |
+ * | 0             | 仅 `file-read-metadata`                            | ✅ `success`    |
+ * | 任意           | 有可操作文件拦截或网络拦截                              | 🔒 `sandbox_denied` |
+ * | ≠0            | 无可操作文件拦截且无网络拦截                            | ❌ `error`      |
+ *
+ * 过滤规则：
+ * - `reason=forbidden_program` → non_actionable（程序黑名单硬拦截，不可通过文件授权修复）
+ * - `process-exec*`      → 默认归因为 `error`（进程执行权限不足，弹提权 UI 也修不了）
+ *   但 safe-delete helper（`genie-trash` / `osascript`）或带 `SAFE_DELETE`
+ *   签名的包装进程（如 perl）例外，进入 `sandbox_denied` 以支持无弹窗本地重跑降级。
+ * - PowerShell 启动缓存等已知进程副作用 → ignore（不计入 blocked 列表）
+ * - `sysctl/ioctl/IOKit`  → ignore（静默丢弃，不上报遥测，不计入 blocked 列表）
+ * - 命令成功且有效拦截仅为 `file-read-metadata` → ignore（保留原始记录，不升级提权）
+ * - 其余（`file-write*`, `file-read-data` 等）→ 可操作，进入裁决处理
+ *
+ * 边界：
+ * - Linux (bwrap) 无结构化拦截记录，1 期不弹提权 UI → 返回 error
+ * - 越界写入到影子区（全局投影模式）不进入此矩阵——命令正常完成（exitCode=0）
+ */
+import type { DecisionRecord } from '../../workspace/sandbox-cli/lib/common/protocol.generated.js';
+import { type FileBlockRecord } from '../sandbox-cli/sandbox-cli-protocol';
+import type { ShellResult } from '../shell';
+import type { ShellNetworkBlockRecord } from '../shell/shell-protocol';
+/**
+ * Attribution status — the causal judgement for a command execution.
+ *
+ * - `success`:        command succeeded (exitCode 0 / null), no actionable escalation needed.
+ * - `error`:          command failed for non-sandbox reasons (code bug, missing dep, etc.).
+ * - `sandbox_denied`: command failed because the sandbox blocked actionable file or network operations.
+ */
+export type AttributionStatus = 'success' | 'error' | 'sandbox_denied';
+/**
+ * Input for the attribution analyzer.
+ *
+ * Directly sourced from {@link ShellResult} fields after sandbox execution.
+ */
+export interface AttributionInput {
+    /** Process exit code. 0 or null means success. */
+    exitCode: number | null;
+    /** Structured file block records from the IPC compatibility boundary. */
+    fileBlockRecords?: FileBlockRecord[];
+    /** Structured network block records from the IPC compatibility boundary. */
+    networkBlockRecords?: ShellNetworkBlockRecord[];
+    /** Center authority records from the current execution (may be empty or undefined). */
+    decisionRecords?: DecisionRecord[];
+}
+/**
+ * Result of the attribution analysis.
+ */
+export interface AttributionResult {
+    /** The causal judgement. */
+    status: AttributionStatus;
+    /**
+     * Actionable file evidence — only populated when `status === 'sandbox_denied'`.
+     *
+     * These are the records that passed filtering (excluded `process-exec*` and
+     * `sysctl/ioctl/IOKit` entries). Downstream policy handling joins these
+     * subjects to native Center verdicts.
+     */
+    actionableFileBlocks: FileBlockRecord[];
+    /**
+     * Network evidence — passed through as-is for post-exec ask/deny handling.
+     */
+    networkBlockRecords: ShellNetworkBlockRecord[];
+    /** Center authority records preserved alongside their internal evidence projection. */
+    decisionRecords: DecisionRecord[];
+    /** Non-allow Center decisions that must not be silently treated as command errors. */
+    actionableDecisionRecords: DecisionRecord[];
+    /** Subject 不完整或 domain 暂无审批映射的非 allow 决策，调用方必须 fail-closed。 */
+    unmappedDecisionRecords: DecisionRecord[];
+    /**
+     * File evidence that was filtered out as non-actionable
+     * (`process-exec*` or program-blacklist hits). Kept for diagnostics / telemetry.
+     */
+    filteredNonActionable: FileBlockRecord[];
+    /**
+     * File evidence that was silently ignored
+     * (known runtime cache writes, `sysctl/ioctl/IOKit`, or successful
+     * metadata-only probes). Kept for diagnostics only.
+     */
+    filteredIgnored: FileBlockRecord[];
+}
+type AttributionShellResult = Pick<ShellResult, 'exitCode' | 'fileBlockRecords' | 'networkBlockRecords' | 'decisionRecords'>;
+/** 保证所有 ShellResult 消费链都把 Center 权威记录纳入归因。 */
+export declare function analyzeShellResultAttribution(result: AttributionShellResult): AttributionResult;
+/**
+ * Analyze the attribution of a sandboxed command execution.
+ *
+ * This is a **pure function** — no side effects, no DI dependencies.
+ * It is the single source of truth for "why did this command fail?"
+ * in the new permission path.
+ *
+ * @param input - Execution result from the sandbox (exitCode + attribution evidence).
+ * @returns Attribution result with status and filtered evidence.
+ */
+export declare function analyzeAttribution(input: AttributionInput): AttributionResult;
+export {};

package/cli/dist-server/types/node/permission/sandbox-audit-service.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Sandbox Audit Service — fire-and-forget command audit via AgentDR SDK.
+ *
+ * Observe mode only. Collects command data after sandbox policy handling;
+ * does NOT participate in allow/deny decisions. Historical wire field names
+ * remain compatible even though the local SafetyFilter has been removed.
+ *
+ * Configuration priority: process.env > built-in defaults.
+ */
+export declare const SandboxAuditService: unique symbol;
+export interface SandboxAuditParams {
+    command: string;
+    cwd: string;
+    stage: 'post_exec_safety_filter';
+    safetyFilterResult?: {
+        autoApproveCount: number;
+        needsApprovalCount: number;
+        riskLevels: string[];
+    };
+    /** 沙箱首跑回调数据，透传给科恩 SDK context.wb_sandbox.attempt */
+    sandboxAttempt?: Record<string, unknown>;
+}
+export interface SandboxAuditService {
+    /**
+     * Fire-and-forget audit. Never throws, never blocks the caller.
+     */
+    auditCommand(params: SandboxAuditParams): Promise<void>;
+}
+export declare class SandboxAuditServiceImpl implements SandboxAuditService {
+    private readonly clientInfoProvider?;
+    private readonly sessionManager;
+    private readonly logger;
+    private initPromise;
+    auditCommand(params: SandboxAuditParams): Promise<void>;
+    private _initSdk;
+    private _getDeviceId;
+    private _buildWbSandboxContext;
+    private _getWorkbuddyDesktopVersion;
+    private _normalizeVersion;
+}

package/cli/dist-server/types/node/permission/sandbox-exec-policy-builtin.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Built-in rule table for {@link SandboxExecPolicy}.
+ *
+ * Keep this table deliberately small and defensive:
+ *
+ *   - Allow-list only covers commands whose effects are purely observational
+ *     (print state, read files, search). If in doubt, leave it as `prompt` so
+ *     the user (and the post-exec sandbox attempt) get the final say.
+ *   - Forbid-list only covers actions that can irrecoverably destroy the host
+ *     or terminate the user's session, where no sane use case exists inside a
+ *     coding assistant. Everyday "dangerous" commands (plain `rm -rf`,
+ *     `sudo <anything else>`, `git push --force`, ...) are intentionally
+ *     **not** forbidden: they may well be legitimate and the prompt flow +
+ *     sandbox can handle them safely.
+ *
+ * Matching semantics are defined in `sandbox-exec-policy.ts`.
+ */
+import type { SandboxExecPolicyRule } from './sandbox-exec-policy-protocol';
+export declare const BUILTIN_ALLOW_RULES: SandboxExecPolicyRule[];
+/**
+ * Commands that are never valid inside a coding assistant context.
+ *
+ * Intentional non-inclusions (see §3.3 of `20-sandbox-exec-policy-plan.md`):
+ *   - Plain `rm -rf <path>` where path is not `/`: too common legitimately.
+ *   - Plain `sudo <anything>` except `rm -rf /`: may install deps, etc.
+ *   - `curl URL | sh`, `eval`, `$()` — prefix matching can't identify them.
+ *   - `cmd.exe rd /s /q C:\` — argv order is variable, high false-positive
+ *     risk; deferred to v2.
+ */
+export declare const BUILTIN_FORBIDDEN_RULES: SandboxExecPolicyRule[];

package/cli/dist-server/types/node/permission/sandbox-exec-policy-protocol.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Static command-level pre-approval policy, inspired by Codex's `ExecPolicy`
+ * (codex-rs/exec-policy/...). See
+ * `apps/workbuddy-desktop/docs/refactor/win-cli-sandbox/20-sandbox-exec-policy-plan.md`
+ * for the design rationale.
+ *
+ * The policy returns a bounded decision for every command the
+ * {@link SandboxOrchestrator} is about to run:
+ *
+ * - `allow`     — known-safe command; execute directly via `LocalShellService`
+ *                 without sandboxing or any approval UI.
+ * - `forbidden` — known-dangerous command; reject synthetically without any
+ *                 execution, sandbox attempt, or approval UI.
+ * - `prompt`    — no rule matches; fall through to the orchestrator's normal
+ *                 `dangerouslyDisableSandbox` / session-cache / sandbox-first
+ *                 / escalation pipeline.
+ *
+ * Matching is prefix-based on argv tokens (see
+ * {@link SandboxExecPolicyRule.prefix}). We deliberately avoid Codex's Starlark
+ * DSL: prefix matching is simpler, cheap to reason about, and sufficient for
+ * the coarse "it's just `ls`" vs "it's `rm -rf /`" buckets we care about.
+ */
+import type { SandboxExecPolicyRuleConfig, SandboxExecPolicyUserConfig } from '../bash-sandbox/bash-sandbox-protocol';
+/** DI symbol for the policy. */
+export declare const SandboxExecPolicy: unique symbol;
+export type SandboxExecDecision = 'allow' | 'prompt' | 'forbidden';
+/** A parsed allow/forbidden rule in the policy table. */
+export interface SandboxExecPolicyRule extends SandboxExecPolicyRuleConfig {
+    /** Whether this rule grants allow or forbidden; `prompt` is the default
+     *  (no rule). */
+    decision: Exclude<SandboxExecDecision, 'prompt'>;
+    /** Where this rule came from; useful for diagnostics. */
+    source?: 'builtin' | 'user';
+}
+/** Outcome of matching a command against the policy. */
+export interface SandboxExecPolicyMatch {
+    decision: SandboxExecDecision;
+    /** The rule that produced the decision, or undefined when `prompt`. */
+    rule?: SandboxExecPolicyRule;
+}
+/** User-authored rules loaded from `settings.sandbox.execPolicy`. */
+export type SandboxExecPolicyUserRules = SandboxExecPolicyUserConfig;
+export interface SandboxExecPolicy {
+    /**
+     * Classify a raw command string.
+     *
+     * Compound commands (chained with `&&`, `||`, `;`, or `|`) are split into
+     * sub-commands and each sub-command is matched independently. Compound
+     * resolution rules:
+     *
+     *   - Any sub-command forbidden → `forbidden` (forbidden-wins).
+     *   - All sub-commands allow    → `allow`.
+     *   - Otherwise                       → `prompt` (downgrade to manual review).
+     *
+     * Unrecognisable shell constructs (command substitution `$(...)`, `eval`,
+     * nested `bash -c` scripts that themselves compose commands, etc.) are
+     * treated as `prompt`; we refuse to make confident decisions about
+     * payloads we can't parse.
+     */
+    match(command: string): SandboxExecPolicyMatch;
+    /**
+     * Replace the currently loaded user rules. Called by
+     * `BashSandboxManager` whenever `settings.sandbox.execPolicy` changes.
+     * Implementations must keep builtin rules unaffected by this call.
+     */
+    setUserRules(rules: SandboxExecPolicyUserRules | undefined): void;
+}

package/cli/dist-server/types/node/permission/sandbox-exec-policy.d.ts

@@ -0,0 +1,13 @@
+import { Logger } from '@celljs/core';
+import { type SandboxExecPolicy as ISandboxExecPolicy, type SandboxExecPolicyMatch, type SandboxExecPolicyUserRules } from './sandbox-exec-policy-protocol';
+export declare class SandboxExecPolicyImpl implements ISandboxExecPolicy {
+    protected readonly logger: Logger;
+    private readonly builtinAllow;
+    private readonly builtinForbidden;
+    private userAllow;
+    private userForbidden;
+    setUserRules(rules: SandboxExecPolicyUserRules | undefined): void;
+    match(command: string): SandboxExecPolicyMatch;
+    private matchArgv;
+    private toRule;
+}

package/cli/dist-server/types/node/permission/sandbox-orchestrator-protocol.d.ts

@@ -0,0 +1,239 @@
+import type { FileApprovalScope, SandboxRuleContext } from '../../workspace/agent-client-protocol/lib/common/index.js';
+import type { Session } from '../../vendor/cbc-core/node/index.js';
+import type { SandboxCorrelationFields, SandboxTurnDisabledReason } from '../../workspace/telemetry/lib/common/index.js';
+import type { SafeDeleteBulkConfirmInfo } from '../shell/safe-delete';
+import type { ShellExecuteParams, ShellExecutionHandle, ShellResult } from '../shell/shell-protocol';
+/** DI symbol for the sandbox orchestrator. */
+export declare const SandboxOrchestrator: unique symbol;
+/**
+ * Why a particular invocation ended up bypassing the sandbox.
+ *
+ * - `dangerously-disable-sandbox` — model explicitly asked for bypass and the
+ *   user approved the request before first execution (Codex `RequireEscalated`).
+ * - `session-approved` — this (canonical command, cwd) was previously approved
+ *   with `allow_session`; we skipped the first sandboxed attempt entirely.
+ * - `escalation-approved` — first attempt failed inside the sandbox with real
+ *   denials; the user approved post-exec escalation with `allow_once` or
+ *   `allow_session` and we re-ran outside the sandbox.
+ * - `exec-policy-allow` — {@link SandboxExecPolicy} classified the command as
+ *   known-safe (builtin or user allow rule), so we ran it locally without
+ *   any sandbox attempt or approval UI.
+ */
+export type SandboxBypassReason = 'dangerously-disable-sandbox' | 'session-approved' | 'escalation-approved' | 'exec-policy-allow' | 'system-tool-approved';
+/**
+ * Context the UI layer needs to render a SandboxInterceptCard.
+ *
+ * `pre-exec` is raised for model-requested bypass (`dangerouslyDisableSandbox`)
+ * before any execution; `post-exec` is raised after the sandbox rejected the
+ * first attempt and we need user consent to retry without the sandbox.
+ */
+export interface SandboxApprovalRequest {
+    ruleContext?: SandboxRuleContext;
+    fileApprovalScope?: FileApprovalScope;
+    /** Trusted host-side target used for Center revalidation; never forwarded to UI metadata. */
+    fileApprovalTargetPath?: string;
+    /** Native sandbox session, which may be the parent of the logical approval session. */
+    fileApprovalSandboxSessionId?: string;
+    /** Captured native-session epoch; stale pending requests cannot grant after restart/close. */
+    fileApprovalSessionGeneration?: number;
+    /** Raw command the model wants to execute (not canonicalised). */
+    command: string;
+    /** Canonicalised command string — same value used as the cache key. */
+    canonicalCommand: string;
+    /** Absolute cwd the command will run in. */
+    cwd: string;
+    /** Distinguishes first-time bypass request from post-denial escalation. */
+    mode: 'pre-exec' | 'post-exec';
+    /**
+     * For `post-exec`: the ShellResult returned by the sandboxed attempt.
+     * For `pre-exec`: undefined.
+     */
+    sandboxResult?: ShellResult;
+    /**
+     * When `true`, this approval request was raised by the new permission
+     * path's sandbox policy (Center verdict or local bulk approval). The
+     * `requestApproval` callback should **not** perform a second
+     * `CommandUtils.checkCommandSafety` check and must surface the
+     * approval UI unconditionally.
+     *
+     * When absent or `false`, the legacy CommandUtils-based auto-approval
+     * logic in `_createApprovalRequester` is still applicable.
+     */
+    sandboxPolicyEvaluated?: boolean;
+    /** false 表示审批只授权本次操作，不得将 allow_session 复用于其他排队调用。 */
+    sessionApprovalReusable?: boolean;
+    /**
+     * Optional legacy/future pre-exec sensitive-command metadata. The current
+     * new sandbox path does not set this field; credential paths are handled by
+     * native file rules and Center verdicts.
+     */
+    sensitiveCommandInfo?: SensitiveCommandInfo;
+    /**
+     * 沙箱拦截原因，用于在审批卡片中显示可读的拦截说明。
+     *
+     * - `file-external`    — 命令试图修改工作空间外部文件，被沙箱拦截。
+     * - `file-blocklist`   — 命令试图访问用户在安全中心配置的黑名单路径。
+     * - `command-rule-ask` — 命令命中安全中心的询问规则。
+     *
+     * 仅拦截类审批设置。普通有序命令 ask 仍不设此字段，卡片用模型描述。
+     * `unsafe-delete` 是 pre-exec：不安全删除（当前为 find -delete）。
+     * post-exec 沙箱拦截用于区分文件和网络原因；pre-exec 命令询问规则
+     * 使用 `command-rule-ask`，以便审批卡片展示准确的命中原因。
+     */
+    interceptReason?: 'file-external' | 'file-blocklist' | 'file-rule-ask' | 'network-external' | 'command-rule-ask' | 'bulk-delete-threshold' | 'unsafe-delete';
+    /** 文件询问规则对应的明确操作；混合或无法识别时不设置。 */
+    fileOperation?: 'read' | 'write' | 'delete';
+    bulkDeleteInfo?: SafeDeleteBulkConfirmInfo;
+    /**
+     * HTTP 明文拦截弹窗所需信息。仅拦截成因为 `http_intercept_ask` 时设置
+     * （post-exec 网络拦截的子集），用于构造审批卡片的 target/description 文案。
+     */
+    httpInterceptInfo?: SandboxHttpInterceptInfo;
+}
+/**
+ * HTTP 明文拦截弹窗信息。由 `sandbox-orchestrator` 的 post-exec 网络拦截
+ * 审批路径填充（`networkBlockRecords` 中 reason='http_intercept_ask' 的记录），
+ * 供 `bash-sandbox-approval-requester` 构造 HTTP 专属的审批卡片文案。
+ */
+export interface SandboxHttpInterceptInfo {
+    /** 拼接的 HTTP URL，形如 `http://host[:port]`，用于弹窗文案展示。 */
+    url: string;
+}
+/**
+ * Extra context attached to a {@link SandboxApprovalRequest} for legacy/future
+ * sensitive-command approval flows.
+ */
+export interface SensitiveCommandInfo {
+    /** Human-readable reason for the sensitive-command prompt. */
+    reason: string;
+    /** The credential paths that were matched. */
+    matchedPaths: string[];
+}
+/** The approval choice returned by the UI or an automatic approval path. */
+export type SandboxApprovalChoice = 'allow_once' | 'allow_session' | 'deny';
+/** Where an approval choice came from. */
+export type SandboxApprovalSource = 'user' | 'auto';
+/** The approval result for a sandbox approval request. */
+export type SandboxApprovalDecision = SandboxApprovalChoice | {
+    decision: SandboxApprovalChoice;
+    source: SandboxApprovalSource;
+    /** True only after an actual capable ACP response and native directory grant. */
+    fileDirectoryApprovalGranted?: boolean;
+};
+/** Callback supplied by the tool layer to surface the approval UI. */
+export type SandboxApprovalRequester = (request: SandboxApprovalRequest) => Promise<SandboxApprovalDecision>;
+/** ToolCall 入口固化的上报关联上下文；任何字段都不得参与执行或审批决策。 */
+export interface SandboxTelemetryContext extends SandboxCorrelationFields {
+    agentType?: 'main' | 'sub-agent';
+    turnSandboxDisabledReason?: SandboxTurnDisabledReason;
+}
+/** Parameters for {@link SandboxOrchestrator.execute}. */
+export interface SandboxOrchestratorParams {
+    /** Shell params to forward to whichever backend ultimately runs. */
+    shellParams: ShellExecuteParams;
+    /**
+     * 执行所属会话（权限判断、审批记录与埋点）。Server/多会话入口必须显式传入；
+     * CLI 缺省时在 execute 入口捕获当前会话，等待审批后不再重新读取全局槽位。
+     */
+    session?: Session;
+    /**
+     * Absolute cwd used as part of the approval cache key. When omitted, the
+     * orchestrator resolves `shellParams.cwd` against the current workspace
+     * folder — matching the cwd that `SandboxShellService` would compute — so
+     * tests that want deterministic keys should pass this explicitly.
+     */
+    cwd?: string;
+    /**
+     * Model-level bypass request. When true, we skip the sandboxed first
+     * attempt and go straight to the approval UI; user consent means we run
+     * with `LocalShellService`.
+     */
+    dangerouslyDisableSandbox: boolean;
+    /** Callback that shows the approval UI and resolves with the user's choice. */
+    requestApproval: SandboxApprovalRequester;
+    /** 仅供上报区分真实 UI 与自动决策；不参与审批结果。 */
+    approvalUiAvailable?: boolean;
+    /** ToolCall 入口固化的旁路上报上下文；不得参与任何执行或审批判定。 */
+    telemetryContext?: SandboxTelemetryContext;
+    /**
+     * When true, the orchestrator skips all pre-exec checks (ExecPolicy
+     * forbidden/allow and dangerouslyDisableSandbox pre-exec approval UI),
+     * going directly to sandbox execution + post-exec escalation only.
+     *
+     * Used by the new permission system to implement "pure post-exec approval":
+     * no command is pre-judged or pre-blocked — everything enters the sandbox
+     * first, and the user is only prompted after the sandbox reports a denial.
+     */
+    skipPreExecChecks?: boolean;
+    /**
+     * The user-facing command **before** any tool-level wrapping.
+     *
+     * PowerShellTool wraps the model's command into
+     * `pwsh.exe -NoProfile -NonInteractive -Command "..."`, making the
+     * actual intent invisible to canonicalization when it only sees
+     * `shellParams.command`.
+     *
+     * When set, the orchestrator uses this value for:
+     *   - {@link canonicalizeCommand} (produce a stable approval-cache key
+     *     that doesn't depend on the PowerShell executable path)
+     *   - safety checks and audit records that need the user-facing command.
+     */
+    originalCommand?: string;
+    /**
+     * 后台执行模式。为 true 时，orchestrator 在沙箱内启动命令后立即返回
+     * handle，跳过 await sandboxHandle.wait() 及后续的归因分析和提权流程。
+     * 沙箱拒绝的操作会直接导致命令失败，不弹提权窗。
+     *
+     * 适用于 run_in_background 场景：pre-exec 安全检查（SystemToolPolicy、
+     * ExecPolicy、有序命令 ask 等）照常执行，只跳过 post-exec 阶段。
+     */
+    background?: boolean;
+    /**
+     * Logical tool name that drove this execution (`'Bash'` | `'PowerShell'` | `'Grep'`).
+     *
+     * Threaded through to `sandbox.tool_call.*` telemetry as `tags.toolName`
+     * so BI can split metrics by tool. The orchestrator is
+     * tool-agnostic and cannot infer this on its own, so the tool layer must
+     * pass it. Optional for non-tool callers (tests / internal) — absent means
+     * the attribute is simply not reported.
+     */
+    toolName?: string;
+}
+/** Result of {@link SandboxOrchestrator.execute}. */
+export interface SandboxOrchestratorResult {
+    /** The live execution handle the caller should `await .wait()` on. */
+    handle: ShellExecutionHandle;
+    /** True iff the command ended up executing outside the sandbox. */
+    bypassed: boolean;
+    /** Populated iff `bypassed` is true. */
+    bypassReason?: SandboxBypassReason;
+    /**
+     * The `ShellResult` from the sandboxed first attempt, when one occurred.
+     * Useful for diagnostics and for callers that want to differentiate
+     * "failed in sandbox, then bypassed" from "failed after bypass".
+     */
+    sandboxAttemptResult?: ShellResult;
+}
+export interface SandboxOrchestrator {
+    /**
+     * Run a shell command applying the Codex-style
+     * "sandbox-first, bypass on approval" policy.
+     *
+     * Implementations must:
+     *   1. If `dangerouslyDisableSandbox`, ask the user first and either run
+     *      locally (bypass) or reject.
+     *   2. Consult the session's `SandboxApprovalStore` for a cached
+     *      `allow_session` approval and skip straight to local execution on
+     *      hit.
+     *   3. Otherwise attempt the command in the sandbox. Return the handle
+     *      immediately for successful attempts.
+     *   4. On post-exec denial (see `_parseFileBlockRecords`), request
+     *      approval. On `deny` return the sandboxed (failing) handle; on
+     *      `allow_*` drop the first-attempt buffers, update the store for
+     *      `allow_session`, and run locally.
+     *
+     * Thrown errors propagate to the caller; approval timeouts should be
+     * surfaced by `requestApproval` itself.
+     */
+    execute(params: SandboxOrchestratorParams): Promise<SandboxOrchestratorResult>;
+}