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

package/cli/dist-server/types/node/tools/notebook-read-tool.d.ts

@@ -0,0 +1,55 @@
+import { Workspace } from '../../workspace/runtime/lib/common/index.js';
+import type { RunContext } from '@openai/agents';
+import { z } from 'zod';
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { BaseTool } from './base-tool';
+import { Tool, ToolCallArgumentRenderer, ToolResult } from './tool-protocol';
+import { ToolArg, ToolNames } from '../../vendor/cbc-shared/node/index.js';
+declare const NotebookReadParameters: z.ZodObject<{
+    notebook_path: z.ZodString;
+    cell_id: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    notebook_path: string;
+    cell_id?: string | undefined;
+}, {
+    notebook_path: string;
+    cell_id?: string | undefined;
+}>;
+export declare class NotebookReadTool extends BaseTool implements Tool {
+    protected readonly workspace: Workspace;
+    name: ToolNames;
+    aliases: string[];
+    parameters: z.ZodObject<{
+        notebook_path: z.ZodString;
+        cell_id: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        notebook_path: string;
+        cell_id?: string | undefined;
+    }, {
+        notebook_path: string;
+        cell_id?: string | undefined;
+    }>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    resolveNeedPermissionArgs(runContext: RunContext, input: z.infer<typeof NotebookReadParameters>, callId?: string): ToolArg[];
+    /**
+     * 验证工具参数
+     */
+    private validateToolParams;
+    /**
+     * 读取和解析 Jupyter notebook 文件
+     */
+    private readNotebookFile;
+    /**
+     * 格式化单个 cell 内容
+     */
+    private formatCell;
+    /**
+     * 根据 cell_id 查找特定的 cell
+     */
+    private findCellById;
+    /**
+     * 执行 notebook 读取操作
+     */
+    execute(params: z.infer<typeof NotebookReadParameters>, context: RunContext<Session>): Promise<ToolResult>;
+}
+export {};

package/cli/dist-server/types/node/tools/notebook-write-tool.d.ts

@@ -0,0 +1,7 @@
+import { NotebookEditTool } from './notebook-edit-tool';
+import { Tool } from './tool-protocol';
+export declare class NotebookWriteTool extends NotebookEditTool implements Tool {
+    name: string;
+    defer_loading: boolean;
+    aliases: string[];
+}

package/cli/dist-server/types/node/tools/plan-storage-service.d.ts

@@ -0,0 +1,68 @@
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+export declare const PlanStorageService: unique symbol;
+/**
+ * Interface for Plan content persistence
+ */
+export interface PlanStorageService {
+    /**
+     * Initialize plan file path for a session
+     * Generates a unique plan file path and stores it in session.meta.planFilePath
+     * @param session The session
+     * @returns The generated plan file path
+     */
+    initializePlanFilePath(session: Session): string;
+    /**
+     * Get plan file path from session
+     * @param session The session
+     * @returns The plan file path or undefined if not initialized
+     */
+    getPlanFilePath(session: Session): string | undefined;
+    /**
+     * Write plan content to file
+     * @param session The session
+     * @param content The plan content to write
+     */
+    write(session: Session, content: string): Promise<void>;
+    /**
+     * Read plan content from file
+     * @param session The session
+     * @returns The plan content or undefined if not found
+     */
+    read(session: Session): Promise<string | undefined>;
+    /**
+     * Read plan content from file
+     * @param session The session
+     * @returns The plan content or undefined if not found
+     */
+    syncRead(session: Session): string | undefined;
+    /**
+     * Check if plan file exists
+     * @param session The session
+     */
+    exists(session: Session): Promise<boolean>;
+}
+export declare class PlanStorageServiceImpl implements PlanStorageService {
+    protected readonly logger: Logger;
+    /**
+     * Initialize plan file path for a session
+     */
+    initializePlanFilePath(session: Session): string;
+    /**
+     * Get plan file path from session
+     */
+    getPlanFilePath(session: Session): string | undefined;
+    /**
+     * Write plan content to file
+     */
+    write(session: Session, content: string): Promise<void>;
+    /**
+     * Read plan content from file
+     */
+    read(session: Session): Promise<string | undefined>;
+    syncRead(session: Session): string | undefined;
+    /**
+     * Check if plan file exists
+     */
+    exists(session: Session): Promise<boolean>;
+}

package/cli/dist-server/types/node/tools/powershell-clm-types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * PowerShell Constrained Language Mode (CLM) allowed types.
+ *
+ * Microsoft's CLM restricts .NET type usage to this allowlist when PowerShell
+ * runs under AppLocker/WDAC system lockdown. Any type NOT in this set is
+ * considered unsafe for untrusted code execution.
+ *
+ * We invert this: type literals not in this set -> ask. One canonical check
+ * replaces enumerating individual dangerous types (named pipes, reflection,
+ * process spawning, P/Invoke marshaling, etc.). Microsoft maintains the list.
+ *
+ * Source: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_language_modes
+ *
+ * Aligned with Claude Code's clmTypes.ts.
+ *
+ * Normalization: entries stored lowercase, short AND full names where both
+ * exist (PS resolves type accelerators like [int] -> System.Int32 at runtime;
+ * we match against the literal text from the command).
+ */
+export declare const CLM_ALLOWED_TYPES: ReadonlySet<string>;
+/**
+ * Normalize a type name from command text.
+ * Handles array suffix ([]) and generic brackets.
+ */
+export declare function normalizeTypeName(name: string): string;
+/**
+ * True if typeName is in Microsoft's CLM allowlist.
+ * Types NOT in this set trigger ask — they access system APIs CLM blocks.
+ */
+export declare function isClmAllowedType(typeName: string): boolean;

package/cli/dist-server/types/node/tools/powershell-command-semantics.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Windows command exit code semantic interpretation.
+ *
+ * Some Windows commands use non-zero exit codes for non-error conditions.
+ * Without this mapping, the model (and user) would interpret any non-zero
+ * exit code as a failure, leading to unnecessary retries.
+ *
+ * Reference: Claude Code's commandSemantics.ts
+ */
+export interface CommandSemantic {
+    /** Whether this exit code represents an actual error */
+    isError: boolean;
+    /** Human-readable explanation of the exit code */
+    message?: string;
+}
+/**
+ * Interpret the exit code of a command, accounting for Windows-specific semantics.
+ *
+ * @param command - The original command string
+ * @param exitCode - The process exit code
+ * @returns Semantic interpretation, or null if no special handling needed
+ */
+export declare function interpretCommandResult(command: string, exitCode: number | null): CommandSemantic | null;

package/cli/dist-server/types/node/tools/powershell-dangerous-cmdlets.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared constants for PowerShell cmdlets that execute arbitrary code.
+ *
+ * These lists are consumed by the security checker (powershell-security.ts)
+ * and future permission UI components. Keeping them here avoids duplicating
+ * the lists and prevents sync drift.
+ *
+ * Aligned with Claude Code's dangerousCmdlets.ts.
+ */
+/**
+ * PowerShell common alias -> canonical cmdlet name mapping.
+ * Used for resolving aliases before security checks.
+ *
+ * Lowercase keys and values for case-insensitive matching.
+ */
+export declare const COMMON_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Cmdlets that accept a -FilePath (or positional path) and execute the
+ * file's contents as a script.
+ */
+export declare const FILEPATH_EXECUTION_CMDLETS: Set<string>;
+/**
+ * Cmdlets where a scriptblock argument executes arbitrary code (not just
+ * filtering/transforming pipeline input like Where-Object).
+ */
+export declare const DANGEROUS_SCRIPT_BLOCK_CMDLETS: Set<string>;
+/**
+ * Cmdlets that load and execute module/script code. .psm1 files run
+ * their top-level body on import — same code-execution risk as iex.
+ */
+export declare const MODULE_LOADING_CMDLETS: Set<string>;
+/**
+ * Network cmdlets — wildcard rules for these enable exfil/download without prompt.
+ */
+export declare const NETWORK_CMDLETS: Set<string>;
+/**
+ * Alias/variable mutation cmdlets — Set-Alias rebinds command resolution,
+ * Set-Variable can poison $PSDefaultParameterValues.
+ */
+export declare const ALIAS_HIJACK_CMDLETS: Set<string>;
+/**
+ * WMI/CIM process spawn — Invoke-WmiMethod -Class Win32_Process -Name Create
+ * is a Start-Process equivalent that bypasses normal process checks.
+ */
+export declare const WMI_CIM_CMDLETS: Set<string>;
+/**
+ * Shells and interpreters whose child processes do NOT go through
+ * checkPowerShellSecurity. Spawning any of these means the child runs
+ * arbitrary code outside the validation surface (issue #42604).
+ */
+export declare const SHELLS_AND_INTERPRETERS: readonly ["pwsh", "powershell", "cmd", "wsl", "bash", "sh", "zsh", "busybox"];
+/**
+ * Windows native binaries that are MITRE-classified LOLBins.
+ * They can perform actions equivalent to BLOCKed cmdlets (process creation,
+ * persistence, in-memory code compilation/loading) without matching any
+ * PowerShell-cmdlet regex (issue #42604).
+ *
+ * Note: read-only subcommands (e.g. `reg query`, `sc query`, `schtasks /Query`)
+ * are deliberately handled by more specific patterns in powershell-security.ts
+ * so they are not blanket-blocked here.
+ */
+export declare const WINDOWS_LOLBINS: readonly ["csc", "installutil", "regsvr32", "rundll32", "mshta", "wscript", "cscript", "msbuild", "bitsadmin", "certutil"];
+/**
+ * Commands to never suggest as a wildcard prefix in the permission dialog.
+ * Derived from the above lists plus shells and interpreters.
+ */
+export declare const NEVER_SUGGEST: ReadonlySet<string>;
+/**
+ * Resolve a command name through COMMON_ALIASES to its canonical cmdlet.
+ * Returns the canonical lowercase name, or the lowercased input if no alias.
+ */
+export declare function resolveAlias(name: string): string;

package/cli/dist-server/types/node/tools/powershell-destructive-warning.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Detects potentially destructive PowerShell commands and returns a warning
+ * string for display in the permission dialog. This is purely informational
+ * -- it doesn't affect permission logic or auto-approval.
+ *
+ * Aligned with Claude Code's destructiveCommandWarning.ts.
+ */
+/**
+ * Checks if a PowerShell command matches known destructive patterns.
+ * Returns a human-readable warning string, or null if no destructive pattern is detected.
+ */
+export declare function getDestructiveCommandWarning(command: string): string | null;

package/cli/dist-server/types/node/tools/powershell-detection.d.ts

@@ -0,0 +1,51 @@
+/**
+ * PowerShell edition information
+ */
+export type PowerShellEdition = 'core' | 'desktop';
+/**
+ * Detected PowerShell information
+ */
+export interface PowerShellInfo {
+    /** Full path to the PowerShell executable */
+    path: string;
+    /** PowerShell version string (e.g. "7.4.1"), or null if detection failed */
+    version: string | null;
+    /** Whether this is PowerShell 7+ (pwsh) */
+    isPwsh7: boolean;
+    /** Edition: 'core' (pwsh 7+) or 'desktop' (powershell 5.1) */
+    edition: PowerShellEdition;
+}
+/**
+ * Find and cache PowerShell installation.
+ *
+ * Discovery order:
+ *   1. Environment variable CODEBUDDY_POWERSHELL_PATH (user override)
+ *   2. pwsh in PATH (PowerShell 7+, cross-platform)
+ *   3. powershell in PATH (Windows PowerShell 5.1)
+ *   4. Well-known default paths on Windows
+ *
+ * Returns null if PowerShell is not found.
+ */
+export declare function findPowerShell(): PowerShellInfo | null;
+/**
+ * Get the cached PowerShell path, or null if not available.
+ */
+export declare function getCachedPowerShellPath(): string | null;
+export declare function findPowerShellSandboxSafe(): PowerShellInfo | null;
+/**
+ * Get the PowerShell edition, or null if not available.
+ */
+export declare function getPowerShellEdition(): PowerShellEdition | null;
+/**
+ * Check if PowerShell tool should be enabled.
+ *
+ * Enabled when:
+ *   - Running on Windows AND
+ *   - PowerShell is available AND
+ *   - Not explicitly disabled via CODEBUDDY_USE_POWERSHELL_TOOL=0
+ */
+export declare function isPowerShellToolEnabled(): boolean;
+/**
+ * Clear cached detection result (for testing).
+ */
+export declare function clearPowerShellCache(): void;

package/cli/dist-server/types/node/tools/powershell-git-safety.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Git safety checks for PowerShell commands.
+ *
+ * Git can be weaponized for sandbox escape via two vectors:
+ * 1. Bare-repo attack: if cwd contains HEAD + objects/ + refs/ but no valid
+ *    .git/HEAD, Git treats cwd as a bare repository and runs hooks from cwd.
+ * 2. Git-internal write + git: a compound command creates HEAD/objects/refs/
+ *    hooks/ then runs git — the git subcommand executes the freshly-created
+ *    malicious hooks.
+ *
+ * This is a regex-based approximation of Claude Code's AST-based gitSafety.ts.
+ * It cannot be as precise without AST parameter binding, but covers the common
+ * attack vectors through heuristic command/path analysis.
+ *
+ * Aligned with Claude Code's gitSafety.ts.
+ */
+import type { SecurityCheckResult } from './powershell-security';
+/**
+ * Normalize a PowerShell argument to a canonical path for git-internal matching.
+ *
+ * Order: structural strips (quotes, backtick escapes, provider prefix),
+ * then NTFS per-component trailing-strip (spaces always; dots only if not ./..),
+ * then normalize separators, then case-fold.
+ */
+export declare function normalizeGitPathArg(arg: string): string;
+/**
+ * True if arg (raw PS arg text) resolves to a git-internal path.
+ * Covers both bare-repo paths (hooks/, refs/) and standard-repo paths
+ * (.git/hooks/, .git/config).
+ */
+export declare function isGitInternalPath(arg: string): boolean;
+/**
+ * True if arg resolves to a path inside .git/ (standard-repo metadata dir).
+ * Unlike isGitInternalPath, does NOT match bare-repo-style root-level
+ * hooks/, refs/ etc. — those are common project directory names.
+ */
+export declare function isDotGitPath(arg: string): boolean;
+/**
+ * Cmdlets that can place a file at a caller-specified path. The
+ * git-internal-paths guard checks whether any arg is a git-internal path.
+ */
+export declare const GIT_SAFETY_WRITE_CMDLETS: Set<string>;
+/**
+ * External archive-extraction applications that write files to cwd with
+ * archive-controlled paths. Archive contents are opaque — any extraction
+ * preceding git must ask.
+ */
+export declare const GIT_SAFETY_ARCHIVE_EXTRACTORS: Set<string>;
+/**
+ * Check if a compound PowerShell command contains a dangerous git-write pattern.
+ *
+ * Detects two patterns:
+ * 1. Write cmdlet targeting a git-internal path + git command in same compound
+ * 2. Archive extraction + git command in same compound (TOCTOU)
+ *
+ * This is a regex heuristic — it splits the command by statement separators
+ * and checks each segment. Less precise than Claude Code's AST-based check
+ * but covers the common attack vectors.
+ */
+export declare function checkGitSafety(command: string): SecurityCheckResult;

package/cli/dist-server/types/node/tools/powershell-security.d.ts

@@ -0,0 +1,93 @@
+/**
+ * PowerShell command security checker.
+ *
+ * Aligned with Claude Code's 24 security validators using regex-based
+ * pattern matching + CLM type whitelist + git safety + destructive warnings.
+ *
+ * Multi-layer security:
+ *   Layer 1: BLOCK/ASK pattern matching (24/24 Claude Code validators)
+ *   Layer 2: CLM type whitelist (~90 types, inverted check)
+ *   Layer 3: Git safety (compound command git-write detection)
+ *   Layer 4: CMD syntax compatibility checks (avoid cmd.exe semantics in PowerShell)
+ *   Layer 5: Read-only validation (explicit whitelist, no dangerous Get-*)
+ *   Layer 6: Destructive command warnings (informational UI hints)
+ *
+ * Enhancements:
+ *   - Unicode dash support (en-dash U+2013, em-dash U+2014, horizontal-bar U+2015)
+ *   - Full CLM type whitelist (~90 types) replacing 6 hardcoded type checks
+ *   - Alias resolution via COMMON_ALIASES before read-only checks
+ *   - Explicit Get-* whitelist (excludes Get-Command, Get-Help, Get-WmiObject, Get-CimInstance)
+ *   - External command flag validation (git, docker, dotnet, node, python)
+ *   - Git safety checks for compound commands
+ *   - Destructive command warnings in SecurityCheckResult
+ *   - bitsadmin /transfer detection (Claude Code #6 completeness)
+ *
+ * Claude Code validator mapping (24/24 covered):
+ *   1.  checkInvokeExpression         -> BLOCK: Invoke-Expression / iex
+ *   2.  checkDynamicCommandName       -> BLOCK: $() as command name
+ *   3.  checkEncodedCommand           -> BLOCK: -EncodedCommand / -enc (+ Unicode dashes)
+ *   4.  checkPwshCommandOrFile        -> ASK:   pwsh/powershell as command or Start-Process target
+ *   5.  checkDownloadCradles          -> BLOCK: IWR|IEX, IRM|IEX, WebClient
+ *   6.  checkDownloadUtilities        -> BLOCK: certutil, Start-BitsTransfer, bitsadmin
+ *   7.  checkAddType                  -> BLOCK: Add-Type
+ *   8.  checkComObject                -> BLOCK: New-Object -ComObject (+ Unicode dashes)
+ *   9.  checkDangerousFilePathExecution -> BLOCK: -FilePath/-LiteralPath (+ Unicode dashes)
+ *   10. checkForEachMemberName        -> ASK:   ForEach-Object -MemberName (+ positional + aliases)
+ *   11. checkStartProcess             -> ASK:   Start-Process -Verb RunAs (+ Unicode dashes + colon-bound)
+ *   12. checkScriptBlockInjection     -> BLOCK: Invoke-Command {, Start-Job {
+ *   13. checkSubExpressions           -> ASK:   $() sub-expressions
+ *   14. checkExpandableStrings        -> ASK:   "$($expr)" expandable strings
+ *   15. checkSplatting                -> ASK:   @variable splatting
+ *   16. checkStopParsing              -> ASK:   --% stop-parsing token
+ *   17. checkMemberInvocations        -> ASK:   .Method() / ::StaticMethod()
+ *   18. checkTypeLiterals             -> ASK:   CLM whitelist check (~90 types)
+ *   19. checkInvokeItem               -> ASK:   Invoke-Item / ii
+ *   20. checkScheduledTask            -> ASK:   Register-ScheduledTask / schtasks (+ New-ScheduledTask*)
+ *   21. checkEnvVarManipulation       -> ASK:   [Environment]::SetEnvironmentVariable Machine
+ *   22. checkModuleLoading            -> ASK:   Install-Module / Import-Module (+ Update/Save-Script)
+ *   23. checkRuntimeStateManipulation -> ASK:   Set-Alias / Set-Variable / New-Variable (hijacking)
+ *   24. checkWmiProcessSpawn          -> BLOCK: Invoke-WmiMethod Win32_Process
+ *
+ *   Issue #42604 hardening (Windows-only):
+ *     - BLOCK Start-Process when target is a shell/interpreter/LOLBin/system-tool
+ *       (covers `Start-Process powershell -File` child-process escape)
+ *     - BLOCK Windows native LOLBins:
+ *         csc / InstallUtil / regsvr32 / rundll32 / mshta / wscript / cscript / msbuild
+ *       (wmic/sc/reg/schtasks 直接执行由 SystemToolPolicy 管控，
+ *        但 Start-Process 创建的子进程脱离沙箱，仍需 block)
+ *     - BLOCK non-PowerShell shells at line start: bash / sh / zsh / busybox
+ *       (wsl 直接执行由 SystemToolPolicy 管控)
+ *     - BLOCK .NET runtime APIs equivalent to existing BLOCKs:
+ *         [Diagnostics.Process]::Start            (== Start-Process)
+ *         New-Object Diagnostics.Process          (== Start-Process)
+ *         [Reflection.Assembly]::Load*            (== Add-Type)
+ *         [AppDomain]::*ExecuteAssembly           (== Add-Type)
+ *         [PowerShell]::Create()...AddScript      (== IEX)
+ *         $ExecutionContext.InvokeCommand.*       (== IEX)
+ *     - ASK reg export/save (registry hive dump for offline cred extraction)
+ *
+ *   Known limitations tracked separately:
+ *     - Sandbox path bypasses checkPowerShellSecurity entirely
+ *     - `-File <script>` content is not recursively scanned
+ */
+export type SecurityBehavior = 'allow' | 'ask' | 'block';
+export interface SecurityCheckResult {
+    /** Whether the command is safe to run */
+    behavior: SecurityBehavior;
+    /** Human-readable reason for the decision */
+    reason?: string;
+    /** Informational warning for display in permission dialog (does not affect behavior) */
+    warning?: string;
+}
+/**
+ * Check if a PowerShell command is safe to run.
+ *
+ * Returns:
+ *   - { behavior: 'block' } for dangerous commands
+ *   - { behavior: 'ask' }   for commands needing confirmation
+ *   - { behavior: 'allow' } for safe read-only commands
+ *   - { behavior: 'ask' }   as default for unknown commands
+ *
+ * The `warning` field is populated for destructive commands regardless of behavior.
+ */
+export declare function checkPowerShellSecurity(command: string): SecurityCheckResult;

package/cli/dist-server/types/node/tools/powershell-tool.d.ts

@@ -0,0 +1,174 @@
+import { Logger } from '@celljs/core';
+import { Session, SessionManager } from '../../vendor/cbc-core/node/index.js';
+import { FunctionCallItem, ToolArg, ToolNames } from '../../vendor/cbc-shared/node/index.js';
+import type { RunContext, ToolExecuteArgument } from '@openai/agents';
+import { z } from 'zod';
+import { type AcpTerminalPublisher } from '../acp/acp-protocol';
+import { BackgroundTaskNotifier } from '../agent-task/agent-task-protocol';
+import { ToolResultBlobService } from '../blob-store/tool-result-blob-service';
+import { type SandboxOrchestrator as ISandboxOrchestrator, type SandboxPermissionGateway as ISandboxPermissionGateway } from '../permission';
+import { SettingsManager } from '../settings';
+import { ShortcutManager } from '../shortcut/shortcut-protocol';
+import { type SandboxTelemetryReporter as ISandboxTelemetryReporter } from '../telemetry/sandbox-telemetry-protocol';
+import { BaseTool } from './base-tool';
+import { Tool, ToolCallArgumentRenderer, ToolResult } from './tool-protocol';
+type ShellServiceType = import('../shell/index.js').ShellService;
+type BashSandboxManagerType = import('../bash-sandbox/bash-sandbox-protocol.js').BashSandboxManager;
+declare const PowerShellParameters: z.ZodObject<{
+    command: z.ZodString;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    description: z.ZodOptional<z.ZodString>;
+    run_in_background: z.ZodOptional<z.ZodBoolean>;
+    dangerouslyDisableSandbox: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    command: string;
+    timeout?: number | undefined;
+    description?: string | undefined;
+    run_in_background?: boolean | undefined;
+    dangerouslyDisableSandbox?: boolean | undefined;
+}, {
+    command: string;
+    timeout?: number | undefined;
+    description?: string | undefined;
+    run_in_background?: boolean | undefined;
+    dangerouslyDisableSandbox?: boolean | undefined;
+}>;
+type PowerShellInput = z.infer<typeof PowerShellParameters>;
+export declare class PowerShellTool extends BaseTool implements Tool {
+    protected readonly shortcutManager: ShortcutManager;
+    protected readonly logger: Logger;
+    protected readonly settingsManager: SettingsManager;
+    protected readonly toolResultBlobService: ToolResultBlobService;
+    protected readonly shellService: ShellServiceType;
+    protected readonly sandboxOrchestrator: ISandboxOrchestrator;
+    protected readonly sandboxTelemetryReporter?: ISandboxTelemetryReporter;
+    protected readonly sandboxPermissionGateway: ISandboxPermissionGateway;
+    protected readonly sessionManager: SessionManager;
+    protected readonly backgroundTaskNotifier: BackgroundTaskNotifier;
+    protected readonly bashSandboxManager: BashSandboxManagerType;
+    /**
+     * ACP v2 终端推送器。惰性解析而非 @Autowired：纯 TUI / SDK 运行时不会加载 acp 模块，
+     * 此时容器里没有这个绑定，取不到就整体降级为不推送。与 BashTool 同款。
+     */
+    private terminalPublisherRef?;
+    protected get terminalPublisher(): AcpTerminalPublisher | undefined;
+    /**
+     * 发一条终端创建通知。整段自吞异常：这是尽力而为的旁路观测，绝不能让它的失败
+     * 掀翻已经 spawn 成功的后台任务（与 BashTool 的两处 try/catch 强度对齐）。
+     *
+     * `command` 传的是**脱敏后**的命令：`redactPowerShellCommand` 的产物同时用于
+     * `task.title`，上 wire 的那份必须同源，否则会把内联凭据推给客户端。
+     */
+    private notifyTerminalCreated;
+    /**
+     * 发一条终端退出通知。任何终止分支都必须调用：`exitStatus` 是客户端判定"已结束"
+     * 的唯一依据，漏一条就会让卡片永远停在运行中。
+     */
+    private notifyTerminalExit;
+    /**
+     * 把一段后台输出投给 ACP 客户端。
+     *
+     * 保真度：PowerShell 的后台执行没有文件 fd 通道，输出一律经 ConPTY / child_process
+     * 解码成字符串后才到这里，原始字节在上游就没了，只能重新编码回 UTF-8。这与
+     * BashTool 的 pipe 兜底路径同级，弱于 BashTool 的 file-fd 通道（那条是字节保真）。
+     * 不是 bug，是已知取舍——前台链路本就需要字符串去拼 ToolResult。
+     */
+    private publishTerminalOutput;
+    name: ToolNames;
+    aliases: string[];
+    /**
+     * Dynamic schema (method, not static field) so ToolManager.get()
+     * re-evaluates it against the current env. When
+     * CODEBUDDY_CODE_DISABLE_BACKGROUND_TASKS is truthy the `run_in_background`
+     * field is omitted from what the model sees (issue #63114). The runtime
+     * guard in `execute()` coerces stale/cached `run_in_background=true` back to
+     * foreground. Note: the foreground-timeout auto-background path is a
+     * separate lifecycle safeguard and is not governed by this env.
+     */
+    parameters(): z.ZodTypeAny;
+    argumentRenderer: ToolCallArgumentRenderer;
+    /**
+     * Only enabled on Windows when PowerShell is available.
+     */
+    isEnabled: () => boolean;
+    resolveNeedPermissionArgs(_runContext: RunContext, input: PowerShellInput, _callId?: string): ToolArg[];
+    /** Auto mode classifier projection: the command is the action's risk surface. */
+    toAutoClassifierInput(input: unknown): string;
+    needsApproval: (runContext: RunContext<Session>, input: ToolExecuteArgument<any>, callId?: string) => Promise<boolean>;
+    execute(input: PowerShellInput, context: RunContext<Session>, details?: {
+        toolCall: FunctionCallItem;
+    }): Promise<ToolResult>;
+    private executeForeground;
+    /** 补齐未进入 Orchestrator 的 PowerShell 本机执行路由，不参与执行控制。 */
+    private _scheduleDirectNativeOutcome;
+    private _logOutcomeTelemetryFailure;
+    /**
+     * Route PowerShell execution through the SandboxOrchestrator. The
+     * orchestrator owns the sandbox-first / bypass-on-approval policy, so this
+     * method's job is limited to:
+     *   - wrapping the user command into the `pwsh -NoProfile -NonInteractive -Command "..."`
+     *     form that sandbox-cli executes with `rawCommand: true`;
+     *   - routing the orchestrator's approval requests through
+     *     `session.interruptionSubject` so the Desktop UI (SandboxInterceptCard)
+     *     picks them up;
+     *   - shaping the resulting ShellResult into the PowerShell tool's
+     *     `buildResult`-equivalent output.
+     */
+    private executeForegroundViaOrchestrator;
+    /**
+     * 后台执行走 Orchestrator，对齐 Bash 后台的实现。
+     * 构建 rawCommand（pwsh -Command "..."）交给 orchestrator.execute()，
+     * 拿到 handle 后用 handle.wait() 追踪完成状态。
+     */
+    private executeInBackgroundViaOrchestrator;
+    /**
+     * Construct an approval requester that surfaces orchestrator prompts via
+     * the standard RunToolApprovalItem flow. Mirrors BashTool's requester but
+     * renders under the `PowerShell` tool name so the UI can label correctly.
+     */
+    private _createApprovalRequester;
+    private executeInBackground;
+    /**
+     * 创建 BackgroundTask 并注册到 ToolManager / session.backgroundTaskSubject。
+     * 供前台超时自动后台化、Ctrl+B 转后台、显式 run_in_background 三条路径共用。
+     *
+     * NOTE: 与 BashTool 的 `createBackgroundTask` 实现重叠约 80%，后续独立 PR 抽出
+     * `ShellToolBase` 基类统一（见 task #10）。
+     */
+    private registerBackgroundTask;
+    /**
+     * 翻 BackgroundTask 终态并推送完成事件。
+     *
+     * **必须**由调用方传入 task 启动时的 session 快照（`sessionAtRegister`），
+     * 不能在这里 `sessionManager.sessionSubject.value` 即时读 —— 后台任务跨 turn
+     * 完成时 session 可能已被切走，即时读会把通知推到错误的会话或丢失。
+     * 对齐 `BackgroundTaskNotifier` 文档承诺："传入的 session 必须是 task 启动时所在的那个"。
+     */
+    private updateBackgroundTaskStatus;
+    private buildBackgroundResult;
+    private spawnPowerShellPty;
+    private spawnPowerShell;
+    private buildResult;
+    validateRuntimeInput(input: unknown): ToolResult | undefined;
+    private invalidInputResult;
+    private errorResult;
+    private generateTaskId;
+    /**
+     * Build a model-readable description of sandbox interception, mirroring
+     * BashTool's `Append sandbox intercept information` block. Returns an
+     * empty string when no interception happened, so the foreground orchestrator
+     * path can append it conditionally without leaking noise into normal runs.
+     *
+     * Cases:
+     * - `sandboxDenied + sandboxEscalationDenied` → user explicitly rejected
+     *   the approval prompt; tell the model so it stops retrying silently.
+     * - `sandboxDenied` with a non-zero exit → sandbox blocked the operation;
+     *   model should adjust approach.
+     * - `fileBlockRecords` / `networkBlockRecords` without `sandboxDenied` →
+     *   non-blocking intercepts (e.g. `strip_write` that didn't surface as a
+     *   denial); attach as informational so the model knows side effects may
+     *   not have happened.
+     */
+    private _buildSandboxInterceptInfo;
+}
+export {};