@caupulican/pi-adaptative 0.81.40 → 0.81.42

package/dist/core/tools/bash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../../src/core/tools/bash.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { constants } from \"node:fs\";\nimport { access as fsAccess } from \"node:fs/promises\";\nimport { type AgentTool, createSilenceWatchdog } from \"@caupulican/pi-agent-core\";\nimport {\n\tDEFAULT_MAX_BYTES,\n\tDEFAULT_MAX_LINES,\n\tformatSize,\n\ttype TruncationResult,\n} from \"@caupulican/pi-agent-core/node\";\nimport { Container, Text, truncateToWidth } from \"@caupulican/pi-tui\";\nimport { spawn } from \"child_process\";\nimport { type Static, Type } from \"typebox\";\nimport { keyHint } from \"../../modes/interactive/components/keybinding-hints.ts\";\nimport { truncateToVisualLines } from \"../../modes/interactive/components/visual-truncate.ts\";\nimport { theme } from \"../../modes/interactive/theme/theme.ts\";\nimport { waitForChildProcessWithTermination } from \"../../utils/child-process.ts\";\nimport {\n\tgetPlatformShellToolName,\n\tgetShellConfig,\n\tgetShellEnv,\n\ttype PlatformShellToolName,\n\tprefixPowerShellCommand,\n\ttrackDetachedChildPid,\n\tuntrackDetachedChildPid,\n} from \"../../utils/shell.ts\";\nimport type { ToolDefinition, ToolRenderResultOptions } from \"../extensions/types.ts\";\nimport { withExclusiveMutationBarrier } from \"./file-mutation-queue.ts\";\nimport { classifyGitCommand, executeFilteredGit } from \"./git-filter.ts\";\nimport { OutputAccumulator } from \"./output-accumulator.ts\";\nimport { getTextOutput, invalidArgText, str } from \"./render-utils.ts\";\nimport { routeShellContract } from \"./shell-contract-router.ts\";\nimport { acquirePersistentShellSession } from \"./shell-session.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\nimport { createWindowsShellEngineOperations, type WindowsShellEngineOptions } from \"./windows-shell-engine.ts\";\nimport { getOrCreateWindowsShellState, mergeEffectiveEnv, resolveEffectiveCwd } from \"./windows-shell-state.ts\";\n\n/** Default per-session key for the engine tier when a caller does not pass an explicit sessionKey\n * (e.g. the RPC `createLocalPlatformShellOperations` path); a stable key keeps `cd`/`export` state\n * persisting across calls even without an agent-scoped session key. */\nconst DEFAULT_WINDOWS_SHELL_ENGINE_SESSION_KEY = \"platform-shell-operations\";\n\n/** Low-level silence bound retained for direct shell-operation consumers. Agent tool calls always pass a wall-clock bound. */\nconst DEFAULT_COMMAND_SILENCE_MS = 600_000;\n/** Agent-facing wall-clock bound: continuously producing output must not make a command immortal. */\nexport const DEFAULT_COMMAND_TIMEOUT_SECONDS = 120;\nexport const MAX_COMMAND_TIMEOUT_SECONDS = 3600;\nconst MIN_COMMAND_TIMEOUT_SECONDS = 0.1;\nlet commandSilenceMsOverride: number | undefined;\nlet commandTimeoutMsOverride: number | undefined;\n\n/** Test hook: override the low-level silence threshold. Pass undefined to restore the default. */\nexport function setCommandSilenceMsForTests(ms: number | undefined): void {\n\tcommandSilenceMsOverride = ms;\n}\n\n/** Test hook: override the agent tool's default wall-clock bound. Pass undefined to restore it. */\nexport function setCommandTimeoutMsForTests(ms: number | undefined): void {\n\tcommandTimeoutMsOverride = ms;\n}\n\nexport function resolveCommandTimeoutSeconds(timeout: number | undefined): number {\n\tif (typeof timeout !== \"number\" || !Number.isFinite(timeout) || timeout <= 0) {\n\t\treturn DEFAULT_COMMAND_TIMEOUT_SECONDS;\n\t}\n\treturn Math.max(MIN_COMMAND_TIMEOUT_SECONDS, Math.min(timeout, MAX_COMMAND_TIMEOUT_SECONDS));\n}\n\nconst bashSchema = Type.Object({\n\tcommand: Type.String({ description: \"Shell command to execute\" }),\n\ttimeout: Type.Optional(\n\t\tType.Number({\n\t\t\tdescription: `Wall-clock timeout in seconds. Defaults to ${DEFAULT_COMMAND_TIMEOUT_SECONDS}; positive overrides are capped at ${MAX_COMMAND_TIMEOUT_SECONDS}. Zero or negative values use the default.`,\n\t\t}),\n\t),\n});\n\nexport type BashToolInput = Static<typeof bashSchema>;\n\nexport interface BashToolDetails {\n\ttruncation?: TruncationResult;\n\tfullOutputPath?: string;\n\tfullOutputError?: string;\n\tpreview?: {\n\t\tcontent: string;\n\t\tskippedLines: number;\n\t};\n}\n\n/**\n * Pluggable operations for the bash tool.\n * Override these to delegate command execution to remote systems (for example SSH).\n */\nexport interface BashOperations {\n\t/**\n\t * Execute a command and stream output.\n\t * @param command The command to execute\n\t * @param cwd Working directory\n\t * @param options Execution options\n\t * @returns Promise resolving to exit code (null if killed)\n\t */\n\texec: (\n\t\tcommand: string,\n\t\tcwd: string,\n\t\toptions: {\n\t\t\tonData: (data: Buffer) => void;\n\t\t\tsignal?: AbortSignal;\n\t\t\ttimeout?: number;\n\t\t\tenv?: NodeJS.ProcessEnv;\n\t\t},\n\t) => Promise<{ exitCode: number | null }>;\n}\n\nfunction createLocalShellOperations(\n\tshellName: PlatformShellToolName,\n\toptions?: { shellPath?: string; sessionKey?: string },\n): BashOperations {\n\t// A session key selects the persistent per-agent backend. An explicit custom shell path keeps\n\t// per-command spawning: persistent sessions assume the resolved platform shell's flag set.\n\tconst sessionKey = options?.sessionKey;\n\tif (sessionKey !== undefined && !options?.shellPath) {\n\t\treturn {\n\t\t\texec: async (command, cwd, { onData, signal, timeout, env }) => {\n\t\t\t\ttry {\n\t\t\t\t\tawait fsAccess(cwd, constants.F_OK);\n\t\t\t\t} catch {\n\t\t\t\t\tthrow new Error(`Working directory does not exist: ${cwd}\\nCannot execute ${shellName} commands.`);\n\t\t\t\t}\n\t\t\t\tif (signal?.aborted) throw new Error(\"aborted\");\n\t\t\t\tconst session = acquirePersistentShellSession(sessionKey, shellName);\n\t\t\t\tconst silenceMs = commandSilenceMsOverride ?? DEFAULT_COMMAND_SILENCE_MS;\n\t\t\t\tconst hasWallClock = timeout !== undefined && timeout > 0;\n\t\t\t\treturn session.exec(command, cwd, {\n\t\t\t\t\tonData,\n\t\t\t\t\tsignal,\n\t\t\t\t\tenv,\n\t\t\t\t\ttimeoutSeconds: hasWallClock ? timeout : undefined,\n\t\t\t\t\tsilenceMs: !hasWallClock && silenceMs > 0 ? silenceMs : undefined,\n\t\t\t\t});\n\t\t\t},\n\t\t};\n\t}\n\treturn {\n\t\texec: async (command, cwd, { onData, signal, timeout, env }) => {\n\t\t\tconst { shell, args } = getShellConfig(options?.shellPath, shellName);\n\t\t\ttry {\n\t\t\t\tawait fsAccess(cwd, constants.F_OK);\n\t\t\t} catch {\n\t\t\t\tthrow new Error(`Working directory does not exist: ${cwd}\\nCannot execute ${shellName} commands.`);\n\t\t\t}\n\t\t\tif (signal?.aborted) throw new Error(\"aborted\");\n\n\t\t\tconst child = spawn(shell, [...args, command], {\n\t\t\t\tcwd,\n\t\t\t\tdetached: process.platform !== \"win32\",\n\t\t\t\tenv: env ?? getShellEnv(),\n\t\t\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t\t\t\twindowsHide: true,\n\t\t\t});\n\t\t\tif (child.pid) trackDetachedChildPid(child.pid);\n\t\t\tconst terminationController = new AbortController();\n\t\t\tconst onAbort = () => terminationController.abort();\n\t\t\tlet silenceKilled = false;\n\t\t\tconst silenceMs = commandSilenceMsOverride ?? DEFAULT_COMMAND_SILENCE_MS;\n\t\t\tconst silenceWatchdog =\n\t\t\t\t(timeout === undefined || timeout <= 0) && silenceMs > 0\n\t\t\t\t\t? createSilenceWatchdog({\n\t\t\t\t\t\t\tsilenceMs,\n\t\t\t\t\t\t\tonSilence: () => {\n\t\t\t\t\t\t\t\tsilenceKilled = true;\n\t\t\t\t\t\t\t\tterminationController.abort();\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t})\n\t\t\t\t\t: undefined;\n\t\t\tconst onChunk = (data: Buffer) => {\n\t\t\t\tsilenceWatchdog?.touch();\n\t\t\t\tonData(data);\n\t\t\t};\n\n\t\t\ttry {\n\t\t\t\tchild.stdout?.on(\"data\", onChunk);\n\t\t\t\tchild.stderr?.on(\"data\", onChunk);\n\t\t\t\tif (signal) {\n\t\t\t\t\tif (signal.aborted) onAbort();\n\t\t\t\t\telse signal.addEventListener(\"abort\", onAbort, { once: true });\n\t\t\t\t}\n\t\t\t\tconst terminal = await waitForChildProcessWithTermination(child, {\n\t\t\t\t\tsignal: terminationController.signal,\n\t\t\t\t\ttimeoutMs: timeout !== undefined && timeout > 0 ? timeout * 1000 : undefined,\n\t\t\t\t\tkillGraceMs: 2_000,\n\t\t\t\t});\n\t\t\t\tif (signal?.aborted) throw new Error(\"aborted\");\n\t\t\t\tif (terminal.reason === \"timeout\") throw new Error(`timeout:${timeout}`);\n\t\t\t\tif (silenceKilled) throw new Error(`silence:${silenceMs / 1000}`);\n\t\t\t\treturn { exitCode: terminal.code };\n\t\t\t} finally {\n\t\t\t\tsilenceWatchdog?.disarm();\n\t\t\t\tif (child.pid) untrackDetachedChildPid(child.pid);\n\t\t\t\tif (signal) signal.removeEventListener(\"abort\", onAbort);\n\t\t\t}\n\t\t},\n\t};\n}\n\n/**\n * Create bash operations using pi's built-in local shell execution backend.\n *\n * This is useful for extensions that intercept user_bash and still want pi's\n * standard local shell behavior while wrapping or rewriting commands.\n */\nexport function createLocalBashOperations(options?: { shellPath?: string; sessionKey?: string }): BashOperations {\n\treturn createLocalShellOperations(\"bash\", options);\n}\n\n/** Create PowerShell operations using pi's built-in local execution backend. */\nexport function createLocalPowerShellOperations(options?: { shellPath?: string; sessionKey?: string }): BashOperations {\n\treturn createLocalShellOperations(\"powershell\", options);\n}\n\n/** Create the platform shell backend without requiring callers or the model to choose a shell. */\nexport function createLocalPlatformShellOperations(\n\toptions: {\n\t\tshellPath?: string;\n\t\tcommandPrefix?: string;\n\t\toperations?: BashOperations;\n\t\tsessionKey?: string;\n\t\t/** Route complex/state-mutating Bash constructs to the Python engine on Windows. Default: true. */\n\t\tpythonEngine?: boolean;\n\t\t/** Test/embedding hook: overrides the engine tier's runtime/spawn/state resolution. */\n\t\tengineOptions?: WindowsShellEngineOptions;\n\t} = {},\n\tplatform: NodeJS.Platform = process.platform,\n): BashOperations {\n\tconst operations =\n\t\toptions.operations ??\n\t\tcreateLocalShellOperations(getPlatformShellToolName(platform), {\n\t\t\tshellPath: options.shellPath,\n\t\t\tsessionKey: options.sessionKey,\n\t\t});\n\tconst pythonEngineEnabled = options.pythonEngine !== false;\n\tconst engineSessionKey = options.sessionKey ?? DEFAULT_WINDOWS_SHELL_ENGINE_SESSION_KEY;\n\tconst engineOperations = createWindowsShellEngineOperations(engineSessionKey, options.engineOptions);\n\treturn {\n\t\tasync exec(command, cwd, execOptions) {\n\t\t\tlet resolvedCommand = command;\n\t\t\tlet resolvedCwd = cwd;\n\t\t\tlet resolvedExecOptions = execOptions;\n\t\t\tif (platform === \"win32\") {\n\t\t\t\tconst route = routeShellContract(command, platform, { pythonEngine: pythonEngineEnabled });\n\t\t\t\tif (route.kind === \"unsupported\") throw new Error(route.error);\n\t\t\t\t// The engine is the sole state mutator (D4); every Windows call — engine or PS\n\t\t\t\t// tier — reads the SAME session state so a `cd`/`export` in one call is observed\n\t\t\t\t// by the very next call regardless of which tier runs it.\n\t\t\t\tconst state = getOrCreateWindowsShellState(engineSessionKey);\n\t\t\t\tresolvedCwd = resolveEffectiveCwd(state, cwd);\n\t\t\t\tresolvedExecOptions = { ...execOptions, env: mergeEffectiveEnv(state, execOptions.env ?? getShellEnv()) };\n\t\t\t\tif (route.kind === \"python-engine\") {\n\t\t\t\t\t// The engine owns the state transition and resolves the original host cwd\n\t\t\t\t\t// exactly once. Passing the already state-adjusted cwd here would make the\n\t\t\t\t\t// engine mistake its own `cd` result for a host cwd change on the next call.\n\t\t\t\t\treturn engineOperations.exec(route.command, cwd, execOptions);\n\t\t\t\t}\n\t\t\t\tif (route.kind === \"powershell\") resolvedCommand = route.command;\n\t\t\t}\n\t\t\tif (options.commandPrefix) resolvedCommand = `${options.commandPrefix}\\n${resolvedCommand}`;\n\t\t\tif (platform === \"win32\") resolvedCommand = prefixPowerShellCommand(resolvedCommand);\n\t\t\treturn operations.exec(resolvedCommand, resolvedCwd, resolvedExecOptions);\n\t\t},\n\t};\n}\n\nexport interface BashSpawnContext {\n\tcommand: string;\n\tcwd: string;\n\tenv: NodeJS.ProcessEnv;\n}\n\nexport type BashSpawnHook = (context: BashSpawnContext) => BashSpawnContext;\n\nfunction resolveSpawnContext(command: string, cwd: string, spawnHook?: BashSpawnHook): BashSpawnContext {\n\tconst baseContext: BashSpawnContext = { command, cwd, env: { ...getShellEnv() } };\n\treturn spawnHook ? spawnHook(baseContext) : baseContext;\n}\n\nexport interface BashToolOptions {\n\t/** Platform used to choose the default backend and contract router. Defaults to process.platform. */\n\tplatform?: NodeJS.Platform;\n\t/** Custom operations for command execution. Default: local platform shell */\n\toperations?: BashOperations;\n\t/** Command prefix prepended to every command (for example shell setup commands) */\n\tcommandPrefix?: string;\n\t/** Optional explicit shell path from settings */\n\tshellPath?: string;\n\t/** Hook to adjust command, cwd, or env before execution */\n\tspawnHook?: BashSpawnHook;\n\t/**\n\t * Stable key for this agent's persistent shell session. The host passes its per-agent key so\n\t * the session survives runtime reloads and user `!` commands share it; separately created\n\t * tool instances (subagents) auto-generate their own key and stay isolated.\n\t */\n\tsessionKey?: string;\n\t/** Route complex/state-mutating Bash constructs to the Python engine on Windows. Default: true. */\n\twindowsShellPythonEngine?: boolean;\n\t/** Test/embedding hook: overrides the engine tier's runtime/spawn/state resolution. */\n\twindowsShellEngineOptions?: WindowsShellEngineOptions;\n}\n\nconst BASH_PREVIEW_LINES = 5;\nconst BASH_PREVIEW_BYTES = 8 * 1024;\nconst BASH_UPDATE_THROTTLE_MS = 100;\n\ntype BashRenderState = {\n\tstartedAt: number | undefined;\n\tendedAt: number | undefined;\n\tinterval: NodeJS.Timeout | undefined;\n};\n\ntype BashResultRenderState = {\n\tcachedWidth: number | undefined;\n\tcachedLines: string[] | undefined;\n\tcachedSkipped: number | undefined;\n};\n\nclass BashResultRenderComponent extends Container {\n\tstate: BashResultRenderState = {\n\t\tcachedWidth: undefined,\n\t\tcachedLines: undefined,\n\t\tcachedSkipped: undefined,\n\t};\n}\n\nfunction formatDuration(ms: number): string {\n\treturn `${(ms / 1000).toFixed(1)}s`;\n}\n\nfunction formatBashCall(\n\targs: { command?: string; timeout?: number } | undefined,\n\tshellName: PlatformShellToolName,\n): string {\n\tconst command = str(args?.command);\n\tconst timeout = args?.timeout as number | undefined;\n\tconst timeoutSuffix = timeout ? theme.fg(\"muted\", ` (timeout ${timeout}s)`) : \"\";\n\tconst commandDisplay = command === null ? invalidArgText(theme) : command ? command : theme.fg(\"toolOutput\", \"...\");\n\tconst prompt = shellName === \"powershell\" ? \"PS>\" : \"$\";\n\treturn theme.fg(\"toolTitle\", theme.bold(`${prompt} ${commandDisplay}`)) + timeoutSuffix;\n}\n\nfunction rebuildBashResultRenderComponent(\n\tcomponent: BashResultRenderComponent,\n\tresult: {\n\t\tcontent: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;\n\t\tdetails?: BashToolDetails;\n\t},\n\toptions: ToolRenderResultOptions,\n\tshowImages: boolean,\n\tstartedAt: number | undefined,\n\tendedAt: number | undefined,\n): void {\n\tconst state = component.state;\n\tcomponent.clear();\n\n\tconst renderPreview = !options.expanded ? result.details?.preview : undefined;\n\tlet output = (renderPreview ? renderPreview.content : getTextOutput(result as any, showImages)).trim();\n\tconst truncation = result.details?.truncation;\n\tconst fullOutputPath = result.details?.fullOutputPath;\n\tconst fullOutputError = result.details?.fullOutputError;\n\tif (!options.isPartial && truncation?.truncated && fullOutputPath && output.endsWith(\"]\")) {\n\t\tconst footerStart = output.lastIndexOf(\"\\n\\n[\");\n\t\tif (footerStart !== -1 && output.slice(footerStart).includes(fullOutputPath)) {\n\t\t\toutput = output.slice(0, footerStart).trimEnd();\n\t\t}\n\t}\n\n\tif (output) {\n\t\tif (options.expanded) {\n\t\t\tconst styledOutput = output\n\t\t\t\t.split(\"\\n\")\n\t\t\t\t.map((line) => theme.fg(\"toolOutput\", line))\n\t\t\t\t.join(\"\\n\");\n\t\t\tcomponent.addChild(new Text(`\\n${styledOutput}`, 0, 0));\n\t\t} else {\n\t\t\tcomponent.addChild({\n\t\t\t\trender: (width: number) => {\n\t\t\t\t\tif (state.cachedLines === undefined || state.cachedWidth !== width) {\n\t\t\t\t\t\tconst preview = truncateToVisualLines(output, BASH_PREVIEW_LINES, width);\n\t\t\t\t\t\tstate.cachedLines = preview.visualLines.map((line) => theme.fg(\"toolOutput\", line));\n\t\t\t\t\t\tstate.cachedSkipped = (result.details?.preview?.skippedLines ?? 0) + preview.skippedCount;\n\t\t\t\t\t\tstate.cachedWidth = width;\n\t\t\t\t\t}\n\t\t\t\t\tif (state.cachedSkipped && state.cachedSkipped > 0) {\n\t\t\t\t\t\tconst hint =\n\t\t\t\t\t\t\ttheme.fg(\"muted\", `... (${state.cachedSkipped} earlier lines,`) +\n\t\t\t\t\t\t\t` ${keyHint(\"app.tools.expand\", \"to expand\")})`;\n\t\t\t\t\t\treturn [\"\", truncateToWidth(hint, width, \"...\"), ...(state.cachedLines ?? [])];\n\t\t\t\t\t}\n\t\t\t\t\treturn [\"\", ...(state.cachedLines ?? [])];\n\t\t\t\t},\n\t\t\t\tinvalidate: () => {\n\t\t\t\t\tstate.cachedWidth = undefined;\n\t\t\t\t\tstate.cachedLines = undefined;\n\t\t\t\t\tstate.cachedSkipped = undefined;\n\t\t\t\t},\n\t\t\t});\n\t\t}\n\t}\n\n\tif (truncation?.truncated || fullOutputPath || fullOutputError) {\n\t\tconst warnings: string[] = [];\n\t\tif (fullOutputPath) {\n\t\t\twarnings.push(`Full output: ${fullOutputPath}`);\n\t\t} else if (fullOutputError) {\n\t\t\twarnings.push(`Full output unavailable: ${fullOutputError}`);\n\t\t}\n\t\tif (truncation?.truncated) {\n\t\t\tif (truncation.truncatedBy === \"lines\") {\n\t\t\t\twarnings.push(`Truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines`);\n\t\t\t} else {\n\t\t\t\twarnings.push(\n\t\t\t\t\t`Truncated: ${truncation.outputLines} lines shown (${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit)`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t\tcomponent.addChild(new Text(`\\n${theme.fg(\"warning\", `[${warnings.join(\". \")}]`)}`, 0, 0));\n\t}\n\n\tif (startedAt !== undefined) {\n\t\tconst label = options.isPartial ? \"Elapsed\" : \"Took\";\n\t\tconst endTime = endedAt ?? Date.now();\n\t\tcomponent.addChild(new Text(`\\n${theme.fg(\"muted\", `${label} ${formatDuration(endTime - startedAt)}`)}`, 0, 0));\n\t}\n}\n\nfunction createShellToolDefinition(\n\tcwd: string,\n\tbackendShell: PlatformShellToolName,\n\tcontractPlatform: NodeJS.Platform,\n\toptions?: BashToolOptions,\n): ToolDefinition<typeof bashSchema, BashToolDetails | undefined, BashRenderState> {\n\tconst toolName = \"bash\";\n\tconst sessionKey = options?.sessionKey ?? `bash-tool:${randomUUID()}`;\n\tconst ops =\n\t\toptions?.operations ??\n\t\t(backendShell === \"powershell\"\n\t\t\t? createLocalPowerShellOperations({ shellPath: options?.shellPath, sessionKey })\n\t\t\t: createLocalBashOperations({ shellPath: options?.shellPath, sessionKey }));\n\tconst commandPrefix = options?.commandPrefix;\n\tconst spawnHook = options?.spawnHook;\n\tconst hasExecutionOverrides = Boolean(options?.operations || options?.shellPath || commandPrefix || spawnHook);\n\tconst canFilterCommand = !hasExecutionOverrides;\n\tconst routesWindowsContract = contractPlatform === \"win32\";\n\tconst pythonEngineEnabled = options?.windowsShellPythonEngine !== false;\n\tconst engineOperations = routesWindowsContract\n\t\t? createWindowsShellEngineOperations(sessionKey, options?.windowsShellEngineOptions)\n\t\t: undefined;\n\tconst contractDescription = routesWindowsContract\n\t\t? \"Execute Pi's stable Bash-like command contract in a persistent per-agent shell session (current directory and environment variables persist across calls, including across the PowerShell and Python engine tiers). On Windows, a deterministic router converts simple commands directly to PowerShell and routes pipelines, redirection, expansion, chaining, and state-mutating commands (cd/export/unset) through a bundled Python engine that implements the supported Bash grammar; named unsupported constructs (job control, process substitution, heredocs, nested shells, and similar) fail closed instead of being guessed.\"\n\t\t: \"Execute a Bash command in a persistent per-agent shell session: the current directory and environment variables persist across calls, and a timed-out or aborted command resets the session.\";\n\treturn {\n\t\tname: toolName,\n\t\tlabel: toolName,\n\t\tdescription: `${contractDescription} Returns stdout and stderr. Output is truncated to last ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). If truncated, full output is saved to a temp file. Commands have a ${DEFAULT_COMMAND_TIMEOUT_SECONDS}-second wall-clock default, including commands that keep producing output; use a positive timeout only when a scoped operation justifies a larger bound (maximum ${MAX_COMMAND_TIMEOUT_SECONDS} seconds).`,\n\t\tpromptSnippet: routesWindowsContract\n\t\t\t? \"Execute Bash-like commands; Pi routes them deterministically to PowerShell or a bundled Python engine on Windows\"\n\t\t\t: \"Execute Bash commands (ls, grep, find, etc.)\",\n\t\tpromptGuidelines: routesWindowsContract\n\t\t\t? [\n\t\t\t\t\t\"Use ordinary Bash-like commands on Windows; do not write PowerShell or ask the user to choose a shell.\",\n\t\t\t\t\t\"Pipelines, redirection, expansion (variables, command substitution, globs), chaining (&&/||/;), and cd/export/unset are supported and routed to a bundled Python engine; a fixed set of named constructs (job control, process substitution, heredocs, arithmetic expansion, nested shells, and similar) fail closed with an actionable message instead of being guessed.\",\n\t\t\t\t\t\"Working directory and environment changes from cd/export/unset persist across subsequent bash calls, including calls that route to the PowerShell tier.\",\n\t\t\t\t\t\"Supported Bash-like file commands are converted with literal-path operations; verify targets before recursive rm, cp, or mv calls.\",\n\t\t\t\t\t\"Keep searches scoped and purpose-driven: discover paths first, pass an explicit root and filters, prefer rg over broad find, and increase the timeout only for a justified bounded search.\",\n\t\t\t\t]\n\t\t\t: [\n\t\t\t\t\t\"Keep searches scoped and purpose-driven: discover paths first, pass an explicit root and filters, prefer rg over broad find, and increase the timeout only for a justified bounded search.\",\n\t\t\t\t],\n\t\tparameters: bashSchema,\n\t\tasync execute(\n\t\t\t_toolCallId,\n\t\t\t{ command, timeout }: { command: string; timeout?: number },\n\t\t\tsignal?: AbortSignal,\n\t\t\tonUpdate?,\n\t\t\t_ctx?,\n\t\t) {\n\t\t\tconst output = new OutputAccumulator({ tempFilePrefix: `pi-${toolName}` });\n\t\t\tlet updateTimer: NodeJS.Timeout | undefined;\n\t\t\tlet updateDirty = false;\n\t\t\tlet lastUpdateAt = 0;\n\n\t\t\tconst emitOutputUpdate = () => {\n\t\t\t\tif (!onUpdate || !updateDirty) return;\n\t\t\t\tupdateDirty = false;\n\t\t\t\tlastUpdateAt = Date.now();\n\t\t\t\tconst snapshot = output.previewSnapshot(BASH_PREVIEW_LINES, BASH_PREVIEW_BYTES, {\n\t\t\t\t\tpersistIfFullTruncated: true,\n\t\t\t\t});\n\t\t\t\tconst preview = {\n\t\t\t\t\tcontent: snapshot.content.replace(/\\r/g, \"\"),\n\t\t\t\t\tskippedLines: Math.max(0, snapshot.truncation.totalLines - snapshot.truncation.outputLines),\n\t\t\t\t};\n\t\t\t\tonUpdate({\n\t\t\t\t\tcontent: [{ type: \"text\", text: preview.content || \"\" }],\n\t\t\t\t\tdetails: {\n\t\t\t\t\t\ttruncation: snapshot.truncation.truncated ? snapshot.truncation : undefined,\n\t\t\t\t\t\tfullOutputPath: snapshot.fullOutputPath,\n\t\t\t\t\t\tfullOutputError: snapshot.fullOutputError,\n\t\t\t\t\t\tpreview,\n\t\t\t\t\t},\n\t\t\t\t});\n\t\t\t};\n\n\t\t\tconst clearUpdateTimer = () => {\n\t\t\t\tif (updateTimer) {\n\t\t\t\t\tclearTimeout(updateTimer);\n\t\t\t\t\tupdateTimer = undefined;\n\t\t\t\t}\n\t\t\t};\n\n\t\t\tconst scheduleOutputUpdate = () => {\n\t\t\t\tif (!onUpdate) return;\n\t\t\t\tupdateDirty = true;\n\t\t\t\tconst delay = BASH_UPDATE_THROTTLE_MS - (Date.now() - lastUpdateAt);\n\t\t\t\tif (delay <= 0) {\n\t\t\t\t\tclearUpdateTimer();\n\t\t\t\t\temitOutputUpdate();\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tupdateTimer ??= setTimeout(() => {\n\t\t\t\t\tupdateTimer = undefined;\n\t\t\t\t\temitOutputUpdate();\n\t\t\t\t}, delay);\n\t\t\t};\n\n\t\t\tif (onUpdate) {\n\t\t\t\tonUpdate({ content: [], details: undefined });\n\t\t\t}\n\n\t\t\tconst handleData = (data: Buffer) => {\n\t\t\t\toutput.append(data);\n\t\t\t\tscheduleOutputUpdate();\n\t\t\t};\n\n\t\t\tconst finishOutput = async () => {\n\t\t\t\toutput.finish();\n\t\t\t\tclearUpdateTimer();\n\t\t\t\temitOutputUpdate();\n\t\t\t\treturn output.snapshot({ persistIfTruncated: true });\n\t\t\t};\n\n\t\t\tconst formatOutput = (snapshot: Awaited<ReturnType<typeof finishOutput>>, emptyText = \"(no output)\") => {\n\t\t\t\tconst truncation = snapshot.truncation;\n\t\t\t\tlet text = snapshot.content.replace(/\\r/g, \"\") || emptyText;\n\t\t\t\tlet details: BashToolDetails | undefined;\n\t\t\t\tconst preview = output.preview(BASH_PREVIEW_LINES, BASH_PREVIEW_BYTES);\n\t\t\t\tconst fullOutputNotice = snapshot.fullOutputPath\n\t\t\t\t\t? `Full output: ${snapshot.fullOutputPath}`\n\t\t\t\t\t: snapshot.fullOutputError\n\t\t\t\t\t\t? `Full output unavailable: ${snapshot.fullOutputError}`\n\t\t\t\t\t\t: \"Full output unavailable\";\n\t\t\t\tif (truncation.truncated || preview.skippedLines > 0) {\n\t\t\t\t\tdetails = { preview };\n\t\t\t\t}\n\t\t\t\tif (snapshot.fullOutputPath || snapshot.fullOutputError) {\n\t\t\t\t\tdetails = {\n\t\t\t\t\t\t...(details ?? {}),\n\t\t\t\t\t\tfullOutputPath: snapshot.fullOutputPath,\n\t\t\t\t\t\tfullOutputError: snapshot.fullOutputError,\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\tif (truncation.truncated) {\n\t\t\t\t\tdetails = {\n\t\t\t\t\t\t...(details ?? {}),\n\t\t\t\t\t\ttruncation,\n\t\t\t\t\t\tfullOutputPath: snapshot.fullOutputPath,\n\t\t\t\t\t\tfullOutputError: snapshot.fullOutputError,\n\t\t\t\t\t};\n\t\t\t\t\tconst startLine = truncation.totalLines - truncation.outputLines + 1;\n\t\t\t\t\tconst endLine = truncation.totalLines;\n\t\t\t\t\tif (truncation.lastLinePartial) {\n\t\t\t\t\t\tconst lastLineSize = formatSize(output.getLastLineBytes());\n\t\t\t\t\t\ttext += `\\n\\n[Showing last ${formatSize(truncation.outputBytes)} of line ${endLine} (line is ${lastLineSize}). ${fullOutputNotice}]`;\n\t\t\t\t\t} else if (truncation.truncatedBy === \"lines\") {\n\t\t\t\t\t\ttext += `\\n\\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines}. ${fullOutputNotice}]`;\n\t\t\t\t\t} else {\n\t\t\t\t\t\ttext += `\\n\\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). ${fullOutputNotice}]`;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn { text, details };\n\t\t\t};\n\n\t\t\tconst appendStatus = (text: string, status: string) => `${text ? `${text}\\n\\n` : \"\"}${status}`;\n\t\t\tconst effectiveTimeoutSeconds =\n\t\t\t\ttypeof timeout === \"number\" && Number.isFinite(timeout) && timeout > 0\n\t\t\t\t\t? resolveCommandTimeoutSeconds(timeout)\n\t\t\t\t\t: (commandTimeoutMsOverride ?? DEFAULT_COMMAND_TIMEOUT_SECONDS * 1000) / 1000;\n\n\t\t\ttry {\n\t\t\t\tif (canFilterCommand) {\n\t\t\t\t\tconst classification = classifyGitCommand(command, getShellEnv());\n\t\t\t\t\tif (classification.eligible && classification.subcommand) {\n\t\t\t\t\t\tconst res = await executeFilteredGit(\n\t\t\t\t\t\t\tcwd,\n\t\t\t\t\t\t\tclassification.subcommand,\n\t\t\t\t\t\t\tclassification.globalOptions || [],\n\t\t\t\t\t\t\tclassification.subcommandArgs || [],\n\t\t\t\t\t\t\t{ signal, timeout: effectiveTimeoutSeconds },\n\t\t\t\t\t\t);\n\t\t\t\t\t\tif (res.exitCode !== -100) {\n\t\t\t\t\t\t\toutput.append(res.rawBytes ?? Buffer.from(res.rawOut, \"utf-8\"));\n\t\t\t\t\t\t\tconst snapshot = await finishOutput();\n\t\t\t\t\t\t\tif (res.exitCode !== 0) {\n\t\t\t\t\t\t\t\tconst { text: rawOutputText } = formatOutput(snapshot);\n\t\t\t\t\t\t\t\tthrow new Error(appendStatus(rawOutputText, `Command exited with code ${res.exitCode}`));\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tconst details = snapshot.truncation.truncated\n\t\t\t\t\t\t\t\t? {\n\t\t\t\t\t\t\t\t\t\ttruncation: snapshot.truncation,\n\t\t\t\t\t\t\t\t\t\tfullOutputPath: snapshot.fullOutputPath,\n\t\t\t\t\t\t\t\t\t\tfullOutputError: snapshot.fullOutputError,\n\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t: snapshot.fullOutputPath || snapshot.fullOutputError\n\t\t\t\t\t\t\t\t\t? { fullOutputPath: snapshot.fullOutputPath, fullOutputError: snapshot.fullOutputError }\n\t\t\t\t\t\t\t\t\t: undefined;\n\t\t\t\t\t\t\treturn { content: [{ type: \"text\", text: res.output }], details };\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\tlet backendCommand = command;\n\t\t\t\tlet engineRoute = false;\n\t\t\t\tlet effectiveCwd = cwd;\n\t\t\t\tif (routesWindowsContract) {\n\t\t\t\t\tconst route = routeShellContract(command, contractPlatform, { pythonEngine: pythonEngineEnabled });\n\t\t\t\t\tif (route.kind === \"unsupported\") throw new Error(route.error);\n\t\t\t\t\tif (route.kind === \"python-engine\") engineRoute = true;\n\t\t\t\t\tbackendCommand = route.command;\n\t\t\t\t\t// The engine is the sole state mutator (D4); every Windows call — engine or PS\n\t\t\t\t\t// tier — reads the SAME session state so a `cd`/`export` in one call is observed\n\t\t\t\t\t// by the very next call regardless of which tier runs it.\n\t\t\t\t\teffectiveCwd = resolveEffectiveCwd(getOrCreateWindowsShellState(sessionKey), cwd);\n\t\t\t\t}\n\t\t\t\t// The engine executes the RAW Bash source unchanged: no commandPrefix (arbitrary\n\t\t\t\t// PowerShell setup would not parse as Bash grammar) and no PowerShell UTF-8 prefix.\n\t\t\t\tconst resolvedCommand = engineRoute\n\t\t\t\t\t? backendCommand\n\t\t\t\t\t: backendShell === \"powershell\"\n\t\t\t\t\t\t? prefixPowerShellCommand(commandPrefix ? `${commandPrefix}\\n${backendCommand}` : backendCommand)\n\t\t\t\t\t\t: commandPrefix\n\t\t\t\t\t\t\t? `${commandPrefix}\\n${backendCommand}`\n\t\t\t\t\t\t\t: backendCommand;\n\t\t\t\tconst spawnContext = resolveSpawnContext(resolvedCommand, effectiveCwd, spawnHook);\n\t\t\t\tif (routesWindowsContract) {\n\t\t\t\t\tspawnContext.env = mergeEffectiveEnv(getOrCreateWindowsShellState(sessionKey), spawnContext.env);\n\t\t\t\t}\n\n\t\t\t\tlet exitCode: number | null;\n\t\t\t\ttry {\n\t\t\t\t\t// Shell commands cannot statically declare which files they mutate, so the\n\t\t\t\t\t// actual execution takes the coarse exclusive barrier: it waits for\n\t\t\t\t\t// in-flight edit/write mutations to drain and blocks new ones meanwhile.\n\t\t\t\t\tconst result = await withExclusiveMutationBarrier(() =>\n\t\t\t\t\t\t(engineRoute && engineOperations ? engineOperations : ops).exec(\n\t\t\t\t\t\t\tspawnContext.command,\n\t\t\t\t\t\t\tspawnContext.cwd,\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\tonData: handleData,\n\t\t\t\t\t\t\t\tsignal,\n\t\t\t\t\t\t\t\ttimeout: effectiveTimeoutSeconds,\n\t\t\t\t\t\t\t\tenv: spawnContext.env,\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t),\n\t\t\t\t\t);\n\t\t\t\t\texitCode = result.exitCode;\n\t\t\t\t} catch (err) {\n\t\t\t\t\tconst snapshot = await finishOutput();\n\t\t\t\t\tconst { text } = formatOutput(snapshot, \"\");\n\t\t\t\t\tif (err instanceof Error && err.message === \"aborted\") {\n\t\t\t\t\t\tthrow new Error(appendStatus(text, \"Command aborted\"));\n\t\t\t\t\t}\n\t\t\t\t\tif (err instanceof Error && err.message.startsWith(\"timeout:\")) {\n\t\t\t\t\t\tconst timeoutSecs = err.message.split(\":\")[1];\n\t\t\t\t\t\tthrow new Error(appendStatus(text, `Command timed out after ${timeoutSecs} seconds`));\n\t\t\t\t\t}\n\t\t\t\t\tif (err instanceof Error && err.message.startsWith(\"silence:\")) {\n\t\t\t\t\t\tconst secs = err.message.split(\":\")[1];\n\t\t\t\t\t\tconst recovery =\n\t\t\t\t\t\t\tbackendShell === \"bash\"\n\t\t\t\t\t\t\t\t? \"re-run it with an explicit timeout, or run it in the background with '&'.\"\n\t\t\t\t\t\t\t\t: \"re-run it with an explicit timeout.\";\n\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\tappendStatus(\n\t\t\t\t\t\t\t\ttext,\n\t\t\t\t\t\t\t\t`Command killed after ${secs}s of silence (no output). If the command is legitimately quiet for long stretches, ${recovery}`,\n\t\t\t\t\t\t\t),\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\tthrow err;\n\t\t\t\t}\n\n\t\t\t\tconst snapshot = await finishOutput();\n\t\t\t\tconst { text: outputText, details } = formatOutput(snapshot);\n\t\t\t\tif (exitCode !== 0 && exitCode !== null) {\n\t\t\t\t\tthrow new Error(appendStatus(outputText, `Command exited with code ${exitCode}`));\n\t\t\t\t}\n\t\t\t\treturn { content: [{ type: \"text\", text: outputText }], details };\n\t\t\t} finally {\n\t\t\t\tclearUpdateTimer();\n\t\t\t\tawait output.closeTempFile();\n\t\t\t}\n\t\t},\n\t\trenderCall(args, _theme, context) {\n\t\t\tconst state = context.state;\n\t\t\tif (context.executionStarted && state.startedAt === undefined) {\n\t\t\t\tstate.startedAt = Date.now();\n\t\t\t\tstate.endedAt = undefined;\n\t\t\t}\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatBashCall(args, toolName));\n\t\t\treturn text;\n\t\t},\n\t\trenderResult(result, options, _theme, context) {\n\t\t\tconst state = context.state;\n\t\t\tif (state.startedAt !== undefined && options.isPartial && !state.interval) {\n\t\t\t\tstate.interval = setInterval(() => context.invalidate(), 1000);\n\t\t\t}\n\t\t\tif (!options.isPartial || context.isError) {\n\t\t\t\tstate.endedAt ??= Date.now();\n\t\t\t\tif (state.interval) {\n\t\t\t\t\tclearInterval(state.interval);\n\t\t\t\t\tstate.interval = undefined;\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst component =\n\t\t\t\t(context.lastComponent as BashResultRenderComponent | undefined) ?? new BashResultRenderComponent();\n\t\t\trebuildBashResultRenderComponent(\n\t\t\t\tcomponent,\n\t\t\t\tresult as any,\n\t\t\t\toptions,\n\t\t\t\tcontext.showImages,\n\t\t\t\tstate.startedAt,\n\t\t\t\tstate.endedAt,\n\t\t\t);\n\t\t\tcomponent.invalidate();\n\t\t\treturn component;\n\t\t},\n\t};\n}\n\nexport function createBashToolDefinition(\n\tcwd: string,\n\toptions?: BashToolOptions,\n): ToolDefinition<typeof bashSchema, BashToolDetails | undefined, BashRenderState> {\n\tconst platform = options?.platform ?? process.platform;\n\treturn createShellToolDefinition(cwd, getPlatformShellToolName(platform), platform, options);\n}\n\nexport function createBashTool(cwd: string, options?: BashToolOptions): AgentTool<typeof bashSchema> {\n\treturn wrapToolDefinition(createBashToolDefinition(cwd, options));\n}\n"]}
+{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../../src/core/tools/bash.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { constants } from \"node:fs\";\nimport { access as fsAccess } from \"node:fs/promises\";\nimport { type AgentTool, createSilenceWatchdog } from \"@caupulican/pi-agent-core\";\nimport {\n\tDEFAULT_MAX_BYTES,\n\tDEFAULT_MAX_LINES,\n\tformatSize,\n\ttype TruncationResult,\n} from \"@caupulican/pi-agent-core/node\";\nimport { Container, Text, truncateToWidth } from \"@caupulican/pi-tui\";\nimport { spawn } from \"child_process\";\nimport { type Static, Type } from \"typebox\";\nimport { keyHint } from \"../../modes/interactive/components/keybinding-hints.ts\";\nimport { truncateToVisualLines } from \"../../modes/interactive/components/visual-truncate.ts\";\nimport { theme } from \"../../modes/interactive/theme/theme.ts\";\nimport { waitForChildProcessWithTermination } from \"../../utils/child-process.ts\";\nimport {\n\tgetPlatformShellToolName,\n\tgetShellConfig,\n\tgetShellEnv,\n\ttype PlatformShellToolName,\n\tprefixPowerShellCommand,\n\ttrackDetachedChildPid,\n\tuntrackDetachedChildPid,\n} from \"../../utils/shell.ts\";\nimport type { ToolDefinition, ToolRenderResultOptions } from \"../extensions/types.ts\";\nimport { withExclusiveMutationBarrier } from \"./file-mutation-queue.ts\";\nimport { classifyGitCommand, executeFilteredGit } from \"./git-filter.ts\";\nimport { OutputAccumulator } from \"./output-accumulator.ts\";\nimport { getTextOutput, invalidArgText, str } from \"./render-utils.ts\";\nimport { assessShellSearchScope, BROAD_SEARCH_OUTPUT_ROUTE } from \"./search-command-guard.ts\";\nimport { routeShellContract } from \"./shell-contract-router.ts\";\nimport { acquirePersistentShellSession } from \"./shell-session.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\nimport { createWindowsShellEngineOperations, type WindowsShellEngineOptions } from \"./windows-shell-engine.ts\";\nimport { getOrCreateWindowsShellState, mergeEffectiveEnv, resolveEffectiveCwd } from \"./windows-shell-state.ts\";\n\n/** Default per-session key for the engine tier when a caller does not pass an explicit sessionKey\n * (e.g. the RPC `createLocalPlatformShellOperations` path); a stable key keeps `cd`/`export` state\n * persisting across calls even without an agent-scoped session key. */\nconst DEFAULT_WINDOWS_SHELL_ENGINE_SESSION_KEY = \"platform-shell-operations\";\n\n/** Low-level silence bound retained for direct shell-operation consumers. Agent tool calls always pass a wall-clock bound. */\nconst DEFAULT_COMMAND_SILENCE_MS = 600_000;\n/** Agent-facing wall-clock bound: continuously producing output must not make a command immortal. */\nexport const DEFAULT_COMMAND_TIMEOUT_SECONDS = 120;\nexport const MAX_COMMAND_TIMEOUT_SECONDS = 3600;\nconst MIN_COMMAND_TIMEOUT_SECONDS = 0.1;\nlet commandSilenceMsOverride: number | undefined;\nlet commandTimeoutMsOverride: number | undefined;\n\n/** Test hook: override the low-level silence threshold. Pass undefined to restore the default. */\nexport function setCommandSilenceMsForTests(ms: number | undefined): void {\n\tcommandSilenceMsOverride = ms;\n}\n\n/** Test hook: override the agent tool's default wall-clock bound. Pass undefined to restore it. */\nexport function setCommandTimeoutMsForTests(ms: number | undefined): void {\n\tcommandTimeoutMsOverride = ms;\n}\n\nexport function resolveCommandTimeoutSeconds(timeout: number | undefined): number {\n\tif (typeof timeout !== \"number\" || !Number.isFinite(timeout) || timeout <= 0) {\n\t\treturn DEFAULT_COMMAND_TIMEOUT_SECONDS;\n\t}\n\treturn Math.max(MIN_COMMAND_TIMEOUT_SECONDS, Math.min(timeout, MAX_COMMAND_TIMEOUT_SECONDS));\n}\n\nconst bashSchema = Type.Object({\n\tcommand: Type.String({ description: \"Shell command to execute\" }),\n\ttimeout: Type.Optional(\n\t\tType.Number({\n\t\t\tdescription: `Wall-clock timeout in seconds. Defaults to ${DEFAULT_COMMAND_TIMEOUT_SECONDS}; positive overrides are capped at ${MAX_COMMAND_TIMEOUT_SECONDS}. Zero or negative values use the default.`,\n\t\t}),\n\t),\n\tbroadSearch: Type.Optional(\n\t\tType.Literal(BROAD_SEARCH_OUTPUT_ROUTE, {\n\t\t\tdescription:\n\t\t\t\t\"Explicit override for a broad rg/grep/find/fd scan that cannot be narrowed. The command runs, but its complete output is routed to a file and excluded from model context.\",\n\t\t}),\n\t),\n});\n\nexport type BashToolInput = Static<typeof bashSchema>;\n\nexport interface BashToolDetails {\n\ttruncation?: TruncationResult;\n\tfullOutputPath?: string;\n\tfullOutputError?: string;\n\tpersistedOutputTruncated?: boolean;\n\tpersistedOutputBytes?: number;\n\tpreview?: {\n\t\tcontent: string;\n\t\tskippedLines: number;\n\t};\n}\n\n/**\n * Pluggable operations for the bash tool.\n * Override these to delegate command execution to remote systems (for example SSH).\n */\nexport interface BashOperations {\n\t/**\n\t * Execute a command and stream output.\n\t * @param command The command to execute\n\t * @param cwd Working directory\n\t * @param options Execution options\n\t * @returns Promise resolving to exit code (null if killed)\n\t */\n\texec: (\n\t\tcommand: string,\n\t\tcwd: string,\n\t\toptions: {\n\t\t\tonData: (data: Buffer) => void;\n\t\t\tsignal?: AbortSignal;\n\t\t\ttimeout?: number;\n\t\t\tenv?: NodeJS.ProcessEnv;\n\t\t},\n\t) => Promise<{ exitCode: number | null }>;\n}\n\nfunction createLocalShellOperations(\n\tshellName: PlatformShellToolName,\n\toptions?: { shellPath?: string; sessionKey?: string },\n): BashOperations {\n\t// A session key selects the persistent per-agent backend. An explicit custom shell path keeps\n\t// per-command spawning: persistent sessions assume the resolved platform shell's flag set.\n\tconst sessionKey = options?.sessionKey;\n\tif (sessionKey !== undefined && !options?.shellPath) {\n\t\treturn {\n\t\t\texec: async (command, cwd, { onData, signal, timeout, env }) => {\n\t\t\t\ttry {\n\t\t\t\t\tawait fsAccess(cwd, constants.F_OK);\n\t\t\t\t} catch {\n\t\t\t\t\tthrow new Error(`Working directory does not exist: ${cwd}\\nCannot execute ${shellName} commands.`);\n\t\t\t\t}\n\t\t\t\tif (signal?.aborted) throw new Error(\"aborted\");\n\t\t\t\tconst session = acquirePersistentShellSession(sessionKey, shellName);\n\t\t\t\tconst silenceMs = commandSilenceMsOverride ?? DEFAULT_COMMAND_SILENCE_MS;\n\t\t\t\tconst hasWallClock = timeout !== undefined && timeout > 0;\n\t\t\t\treturn session.exec(command, cwd, {\n\t\t\t\t\tonData,\n\t\t\t\t\tsignal,\n\t\t\t\t\tenv,\n\t\t\t\t\ttimeoutSeconds: hasWallClock ? timeout : undefined,\n\t\t\t\t\tsilenceMs: !hasWallClock && silenceMs > 0 ? silenceMs : undefined,\n\t\t\t\t});\n\t\t\t},\n\t\t};\n\t}\n\treturn {\n\t\texec: async (command, cwd, { onData, signal, timeout, env }) => {\n\t\t\tconst { shell, args } = getShellConfig(options?.shellPath, shellName);\n\t\t\ttry {\n\t\t\t\tawait fsAccess(cwd, constants.F_OK);\n\t\t\t} catch {\n\t\t\t\tthrow new Error(`Working directory does not exist: ${cwd}\\nCannot execute ${shellName} commands.`);\n\t\t\t}\n\t\t\tif (signal?.aborted) throw new Error(\"aborted\");\n\n\t\t\tconst child = spawn(shell, [...args, command], {\n\t\t\t\tcwd,\n\t\t\t\tdetached: process.platform !== \"win32\",\n\t\t\t\tenv: env ?? getShellEnv(),\n\t\t\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t\t\t\twindowsHide: true,\n\t\t\t});\n\t\t\tif (child.pid) trackDetachedChildPid(child.pid);\n\t\t\tconst terminationController = new AbortController();\n\t\t\tconst onAbort = () => terminationController.abort();\n\t\t\tlet silenceKilled = false;\n\t\t\tconst silenceMs = commandSilenceMsOverride ?? DEFAULT_COMMAND_SILENCE_MS;\n\t\t\tconst silenceWatchdog =\n\t\t\t\t(timeout === undefined || timeout <= 0) && silenceMs > 0\n\t\t\t\t\t? createSilenceWatchdog({\n\t\t\t\t\t\t\tsilenceMs,\n\t\t\t\t\t\t\tonSilence: () => {\n\t\t\t\t\t\t\t\tsilenceKilled = true;\n\t\t\t\t\t\t\t\tterminationController.abort();\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t})\n\t\t\t\t\t: undefined;\n\t\t\tconst onChunk = (data: Buffer) => {\n\t\t\t\tsilenceWatchdog?.touch();\n\t\t\t\tonData(data);\n\t\t\t};\n\n\t\t\ttry {\n\t\t\t\tchild.stdout?.on(\"data\", onChunk);\n\t\t\t\tchild.stderr?.on(\"data\", onChunk);\n\t\t\t\tif (signal) {\n\t\t\t\t\tif (signal.aborted) onAbort();\n\t\t\t\t\telse signal.addEventListener(\"abort\", onAbort, { once: true });\n\t\t\t\t}\n\t\t\t\tconst terminal = await waitForChildProcessWithTermination(child, {\n\t\t\t\t\tsignal: terminationController.signal,\n\t\t\t\t\ttimeoutMs: timeout !== undefined && timeout > 0 ? timeout * 1000 : undefined,\n\t\t\t\t\tkillGraceMs: 2_000,\n\t\t\t\t});\n\t\t\t\tif (signal?.aborted) throw new Error(\"aborted\");\n\t\t\t\tif (terminal.reason === \"timeout\") throw new Error(`timeout:${timeout}`);\n\t\t\t\tif (silenceKilled) throw new Error(`silence:${silenceMs / 1000}`);\n\t\t\t\treturn { exitCode: terminal.code };\n\t\t\t} finally {\n\t\t\t\tsilenceWatchdog?.disarm();\n\t\t\t\tif (child.pid) untrackDetachedChildPid(child.pid);\n\t\t\t\tif (signal) signal.removeEventListener(\"abort\", onAbort);\n\t\t\t}\n\t\t},\n\t};\n}\n\n/**\n * Create bash operations using pi's built-in local shell execution backend.\n *\n * This is useful for extensions that intercept user_bash and still want pi's\n * standard local shell behavior while wrapping or rewriting commands.\n */\nexport function createLocalBashOperations(options?: { shellPath?: string; sessionKey?: string }): BashOperations {\n\treturn createLocalShellOperations(\"bash\", options);\n}\n\n/** Create PowerShell operations using pi's built-in local execution backend. */\nexport function createLocalPowerShellOperations(options?: { shellPath?: string; sessionKey?: string }): BashOperations {\n\treturn createLocalShellOperations(\"powershell\", options);\n}\n\n/** Create the platform shell backend without requiring callers or the model to choose a shell. */\nexport function createLocalPlatformShellOperations(\n\toptions: {\n\t\tshellPath?: string;\n\t\tcommandPrefix?: string;\n\t\toperations?: BashOperations;\n\t\tsessionKey?: string;\n\t\t/** Route complex/state-mutating Bash constructs to the Python engine on Windows. Default: true. */\n\t\tpythonEngine?: boolean;\n\t\t/** Test/embedding hook: overrides the engine tier's runtime/spawn/state resolution. */\n\t\tengineOptions?: WindowsShellEngineOptions;\n\t} = {},\n\tplatform: NodeJS.Platform = process.platform,\n): BashOperations {\n\tconst operations =\n\t\toptions.operations ??\n\t\tcreateLocalShellOperations(getPlatformShellToolName(platform), {\n\t\t\tshellPath: options.shellPath,\n\t\t\tsessionKey: options.sessionKey,\n\t\t});\n\tconst pythonEngineEnabled = options.pythonEngine !== false;\n\tconst engineSessionKey = options.sessionKey ?? DEFAULT_WINDOWS_SHELL_ENGINE_SESSION_KEY;\n\tconst engineOperations = createWindowsShellEngineOperations(engineSessionKey, options.engineOptions);\n\treturn {\n\t\tasync exec(command, cwd, execOptions) {\n\t\t\tlet resolvedCommand = command;\n\t\t\tlet resolvedCwd = cwd;\n\t\t\tlet resolvedExecOptions = execOptions;\n\t\t\tif (platform === \"win32\") {\n\t\t\t\tconst route = routeShellContract(command, platform, { pythonEngine: pythonEngineEnabled });\n\t\t\t\tif (route.kind === \"unsupported\") throw new Error(route.error);\n\t\t\t\t// The engine is the sole state mutator (D4); every Windows call — engine or PS\n\t\t\t\t// tier — reads the SAME session state so a `cd`/`export` in one call is observed\n\t\t\t\t// by the very next call regardless of which tier runs it.\n\t\t\t\tconst state = getOrCreateWindowsShellState(engineSessionKey);\n\t\t\t\tresolvedCwd = resolveEffectiveCwd(state, cwd);\n\t\t\t\tresolvedExecOptions = { ...execOptions, env: mergeEffectiveEnv(state, execOptions.env ?? getShellEnv()) };\n\t\t\t\tif (route.kind === \"python-engine\") {\n\t\t\t\t\t// The engine owns the state transition and resolves the original host cwd\n\t\t\t\t\t// exactly once. Passing the already state-adjusted cwd here would make the\n\t\t\t\t\t// engine mistake its own `cd` result for a host cwd change on the next call.\n\t\t\t\t\treturn engineOperations.exec(route.command, cwd, execOptions);\n\t\t\t\t}\n\t\t\t\tif (route.kind === \"powershell\") resolvedCommand = route.command;\n\t\t\t}\n\t\t\tif (options.commandPrefix) resolvedCommand = `${options.commandPrefix}\\n${resolvedCommand}`;\n\t\t\tif (platform === \"win32\") resolvedCommand = prefixPowerShellCommand(resolvedCommand);\n\t\t\treturn operations.exec(resolvedCommand, resolvedCwd, resolvedExecOptions);\n\t\t},\n\t};\n}\n\nexport interface BashSpawnContext {\n\tcommand: string;\n\tcwd: string;\n\tenv: NodeJS.ProcessEnv;\n}\n\nexport type BashSpawnHook = (context: BashSpawnContext) => BashSpawnContext;\n\nfunction resolveSpawnContext(command: string, cwd: string, spawnHook?: BashSpawnHook): BashSpawnContext {\n\tconst baseContext: BashSpawnContext = { command, cwd, env: { ...getShellEnv() } };\n\treturn spawnHook ? spawnHook(baseContext) : baseContext;\n}\n\nexport interface BashToolOptions {\n\t/** Platform used to choose the default backend and contract router. Defaults to process.platform. */\n\tplatform?: NodeJS.Platform;\n\t/** Custom operations for command execution. Default: local platform shell */\n\toperations?: BashOperations;\n\t/** Command prefix prepended to every command (for example shell setup commands) */\n\tcommandPrefix?: string;\n\t/** Optional explicit shell path from settings */\n\tshellPath?: string;\n\t/** Hook to adjust command, cwd, or env before execution */\n\tspawnHook?: BashSpawnHook;\n\t/**\n\t * Stable key for this agent's persistent shell session. The host passes its per-agent key so\n\t * the session survives runtime reloads and user `!` commands share it; separately created\n\t * tool instances (subagents) auto-generate their own key and stay isolated.\n\t */\n\tsessionKey?: string;\n\t/** Route complex/state-mutating Bash constructs to the Python engine on Windows. Default: true. */\n\twindowsShellPythonEngine?: boolean;\n\t/** Test/embedding hook: overrides the engine tier's runtime/spawn/state resolution. */\n\twindowsShellEngineOptions?: WindowsShellEngineOptions;\n\t/** Test/embedding hook: override the managed directory used for complete command output. */\n\toutputDirectory?: string;\n}\n\nconst BASH_PREVIEW_LINES = 5;\nconst BASH_PREVIEW_BYTES = 8 * 1024;\nconst BASH_UPDATE_THROTTLE_MS = 100;\nconst BROAD_SEARCH_MAX_PERSISTED_BYTES = 8 * 1024 * 1024;\n\ntype BashRenderState = {\n\tstartedAt: number | undefined;\n\tendedAt: number | undefined;\n\tinterval: NodeJS.Timeout | undefined;\n};\n\ntype BashResultRenderState = {\n\tcachedWidth: number | undefined;\n\tcachedLines: string[] | undefined;\n\tcachedSkipped: number | undefined;\n};\n\nclass BashResultRenderComponent extends Container {\n\tstate: BashResultRenderState = {\n\t\tcachedWidth: undefined,\n\t\tcachedLines: undefined,\n\t\tcachedSkipped: undefined,\n\t};\n}\n\nfunction formatDuration(ms: number): string {\n\treturn `${(ms / 1000).toFixed(1)}s`;\n}\n\nfunction formatBashCall(\n\targs: { command?: string; timeout?: number } | undefined,\n\tshellName: PlatformShellToolName,\n): string {\n\tconst command = str(args?.command);\n\tconst timeout = args?.timeout as number | undefined;\n\tconst timeoutSuffix = timeout ? theme.fg(\"muted\", ` (timeout ${timeout}s)`) : \"\";\n\tconst commandDisplay = command === null ? invalidArgText(theme) : command ? command : theme.fg(\"toolOutput\", \"...\");\n\tconst prompt = shellName === \"powershell\" ? \"PS>\" : \"$\";\n\treturn theme.fg(\"toolTitle\", theme.bold(`${prompt} ${commandDisplay}`)) + timeoutSuffix;\n}\n\nfunction rebuildBashResultRenderComponent(\n\tcomponent: BashResultRenderComponent,\n\tresult: {\n\t\tcontent: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;\n\t\tdetails?: BashToolDetails;\n\t},\n\toptions: ToolRenderResultOptions,\n\tshowImages: boolean,\n\tstartedAt: number | undefined,\n\tendedAt: number | undefined,\n): void {\n\tconst state = component.state;\n\tcomponent.clear();\n\n\tconst renderPreview = !options.expanded ? result.details?.preview : undefined;\n\tlet output = (renderPreview ? renderPreview.content : getTextOutput(result as any, showImages)).trim();\n\tconst truncation = result.details?.truncation;\n\tconst fullOutputPath = result.details?.fullOutputPath;\n\tconst fullOutputError = result.details?.fullOutputError;\n\tif (!options.isPartial && truncation?.truncated && fullOutputPath && output.endsWith(\"]\")) {\n\t\tconst footerStart = output.lastIndexOf(\"\\n\\n[\");\n\t\tif (footerStart !== -1 && output.slice(footerStart).includes(fullOutputPath)) {\n\t\t\toutput = output.slice(0, footerStart).trimEnd();\n\t\t}\n\t}\n\n\tif (output) {\n\t\tif (options.expanded) {\n\t\t\tconst styledOutput = output\n\t\t\t\t.split(\"\\n\")\n\t\t\t\t.map((line) => theme.fg(\"toolOutput\", line))\n\t\t\t\t.join(\"\\n\");\n\t\t\tcomponent.addChild(new Text(`\\n${styledOutput}`, 0, 0));\n\t\t} else {\n\t\t\tcomponent.addChild({\n\t\t\t\trender: (width: number) => {\n\t\t\t\t\tif (state.cachedLines === undefined || state.cachedWidth !== width) {\n\t\t\t\t\t\tconst preview = truncateToVisualLines(output, BASH_PREVIEW_LINES, width);\n\t\t\t\t\t\tstate.cachedLines = preview.visualLines.map((line) => theme.fg(\"toolOutput\", line));\n\t\t\t\t\t\tstate.cachedSkipped = (result.details?.preview?.skippedLines ?? 0) + preview.skippedCount;\n\t\t\t\t\t\tstate.cachedWidth = width;\n\t\t\t\t\t}\n\t\t\t\t\tif (state.cachedSkipped && state.cachedSkipped > 0) {\n\t\t\t\t\t\tconst hint =\n\t\t\t\t\t\t\ttheme.fg(\"muted\", `... (${state.cachedSkipped} earlier lines,`) +\n\t\t\t\t\t\t\t` ${keyHint(\"app.tools.expand\", \"to expand\")})`;\n\t\t\t\t\t\treturn [\"\", truncateToWidth(hint, width, \"...\"), ...(state.cachedLines ?? [])];\n\t\t\t\t\t}\n\t\t\t\t\treturn [\"\", ...(state.cachedLines ?? [])];\n\t\t\t\t},\n\t\t\t\tinvalidate: () => {\n\t\t\t\t\tstate.cachedWidth = undefined;\n\t\t\t\t\tstate.cachedLines = undefined;\n\t\t\t\t\tstate.cachedSkipped = undefined;\n\t\t\t\t},\n\t\t\t});\n\t\t}\n\t}\n\n\tif (truncation?.truncated || fullOutputPath || fullOutputError) {\n\t\tconst warnings: string[] = [];\n\t\tif (fullOutputPath) {\n\t\t\twarnings.push(`Full output: ${fullOutputPath}`);\n\t\t} else if (fullOutputError) {\n\t\t\twarnings.push(`Full output unavailable: ${fullOutputError}`);\n\t\t}\n\t\tif (truncation?.truncated) {\n\t\t\tif (truncation.truncatedBy === \"lines\") {\n\t\t\t\twarnings.push(`Truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines`);\n\t\t\t} else {\n\t\t\t\twarnings.push(\n\t\t\t\t\t`Truncated: ${truncation.outputLines} lines shown (${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit)`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t\tcomponent.addChild(new Text(`\\n${theme.fg(\"warning\", `[${warnings.join(\". \")}]`)}`, 0, 0));\n\t}\n\n\tif (startedAt !== undefined) {\n\t\tconst label = options.isPartial ? \"Elapsed\" : \"Took\";\n\t\tconst endTime = endedAt ?? Date.now();\n\t\tcomponent.addChild(new Text(`\\n${theme.fg(\"muted\", `${label} ${formatDuration(endTime - startedAt)}`)}`, 0, 0));\n\t}\n}\n\nfunction createShellToolDefinition(\n\tcwd: string,\n\tbackendShell: PlatformShellToolName,\n\tcontractPlatform: NodeJS.Platform,\n\toptions?: BashToolOptions,\n): ToolDefinition<typeof bashSchema, BashToolDetails | undefined, BashRenderState> {\n\tconst toolName = \"bash\";\n\tconst sessionKey = options?.sessionKey ?? `bash-tool:${randomUUID()}`;\n\tconst ops =\n\t\toptions?.operations ??\n\t\t(backendShell === \"powershell\"\n\t\t\t? createLocalPowerShellOperations({ shellPath: options?.shellPath, sessionKey })\n\t\t\t: createLocalBashOperations({ shellPath: options?.shellPath, sessionKey }));\n\tconst commandPrefix = options?.commandPrefix;\n\tconst spawnHook = options?.spawnHook;\n\tconst hasExecutionOverrides = Boolean(options?.operations || options?.shellPath || commandPrefix || spawnHook);\n\tconst canFilterCommand = !hasExecutionOverrides;\n\tconst routesWindowsContract = contractPlatform === \"win32\";\n\tconst pythonEngineEnabled = options?.windowsShellPythonEngine !== false;\n\tconst engineOperations = routesWindowsContract\n\t\t? createWindowsShellEngineOperations(sessionKey, options?.windowsShellEngineOptions)\n\t\t: undefined;\n\tconst contractDescription = routesWindowsContract\n\t\t? \"Execute Pi's stable Bash-like command contract in a persistent per-agent shell session (current directory and environment variables persist across calls, including across the PowerShell and Python engine tiers). On Windows, a deterministic router converts simple commands directly to PowerShell and routes pipelines, redirection, expansion, chaining, and state-mutating commands (cd/export/unset) through a bundled Python engine that implements the supported Bash grammar; named unsupported constructs (job control, process substitution, heredocs, nested shells, and similar) fail closed instead of being guessed.\"\n\t\t: \"Execute a Bash command in a persistent per-agent shell session: the current directory and environment variables persist across calls, and a timed-out or aborted command resets the session.\";\n\treturn {\n\t\tname: toolName,\n\t\tlabel: toolName,\n\t\tdescription: `${contractDescription} Returns stdout and stderr. Output is truncated to last ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). If truncated, full output is saved to a managed file. Broad rg/grep/find/fd scans are rejected before execution; when an exhaustive scan is unavoidable, set broadSearch=\"${BROAD_SEARCH_OUTPUT_ROUTE}\" to route all output to a managed file instead of model context. Commands have a ${DEFAULT_COMMAND_TIMEOUT_SECONDS}-second wall-clock default, including commands that keep producing output; use a positive timeout only when a scoped operation justifies a larger bound (maximum ${MAX_COMMAND_TIMEOUT_SECONDS} seconds).`,\n\t\tpromptSnippet: routesWindowsContract\n\t\t\t? \"Execute Bash-like commands; Pi routes them deterministically to PowerShell or a bundled Python engine on Windows\"\n\t\t\t: \"Execute Bash commands (ls, grep, find, etc.)\",\n\t\tpromptGuidelines: routesWindowsContract\n\t\t\t? [\n\t\t\t\t\t\"Use ordinary Bash-like commands on Windows; do not write PowerShell or ask the user to choose a shell.\",\n\t\t\t\t\t\"Pipelines, redirection, expansion (variables, command substitution, globs), chaining (&&/||/;), and cd/export/unset are supported and routed to a bundled Python engine; a fixed set of named constructs (job control, process substitution, heredocs, arithmetic expansion, nested shells, and similar) fail closed with an actionable message instead of being guessed.\",\n\t\t\t\t\t\"Working directory and environment changes from cd/export/unset persist across subsequent bash calls, including calls that route to the PowerShell tier.\",\n\t\t\t\t\t\"Supported Bash-like file commands are converted with literal-path operations; verify targets before recursive rm, cp, or mv calls.\",\n\t\t\t\t\t`Keep searches scoped and purpose-driven: discover paths first, pass an explicit root and filters, and prefer the bounded grep/find tools. Broad shell searches are rejected; use broadSearch=\"${BROAD_SEARCH_OUTPUT_ROUTE}\" only for an unavoidable exhaustive scan, then inspect the returned file with bounded reads or narrower searches.`,\n\t\t\t\t]\n\t\t\t: [\n\t\t\t\t\t`Keep searches scoped and purpose-driven: discover paths first, pass an explicit root and filters, and prefer the bounded grep/find tools. Broad shell searches are rejected; use broadSearch=\"${BROAD_SEARCH_OUTPUT_ROUTE}\" only for an unavoidable exhaustive scan, then inspect the returned file with bounded reads or narrower searches.`,\n\t\t\t\t],\n\t\tparameters: bashSchema,\n\t\tasync execute(\n\t\t\t_toolCallId,\n\t\t\t{\n\t\t\t\tcommand,\n\t\t\t\ttimeout,\n\t\t\t\tbroadSearch,\n\t\t\t}: { command: string; timeout?: number; broadSearch?: typeof BROAD_SEARCH_OUTPUT_ROUTE },\n\t\t\tsignal?: AbortSignal,\n\t\t\tonUpdate?,\n\t\t\t_ctx?,\n\t\t) {\n\t\t\tconst searchScope = assessShellSearchScope(command, cwd);\n\t\t\tif (searchScope.kind === \"broad\" && broadSearch !== BROAD_SEARCH_OUTPUT_ROUTE) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Broad search blocked before execution: ${searchScope.reason}. Narrow the path, glob, type, or pattern; prefer the grep/find tool with explicit path/glob/limit. If an exhaustive scan is required, retry with broadSearch=\"${BROAD_SEARCH_OUTPUT_ROUTE}\"; Pi will keep its output out of context and return a managed file path for bounded read or search follow-up.`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst routeBroadSearchOutput = searchScope.kind === \"broad\";\n\t\t\tconst output = new OutputAccumulator({\n\t\t\t\ttempFilePrefix: `pi-${toolName}`,\n\t\t\t\ttempDirectory: options?.outputDirectory,\n\t\t\t\tpersistAllOutput: routeBroadSearchOutput,\n\t\t\t\tmaxPersistedBytes: routeBroadSearchOutput ? BROAD_SEARCH_MAX_PERSISTED_BYTES : undefined,\n\t\t\t});\n\t\t\tlet updateTimer: NodeJS.Timeout | undefined;\n\t\t\tlet updateDirty = false;\n\t\t\tlet lastUpdateAt = 0;\n\n\t\t\tconst emitOutputUpdate = () => {\n\t\t\t\tif (!onUpdate || !updateDirty) return;\n\t\t\t\tupdateDirty = false;\n\t\t\t\tlastUpdateAt = Date.now();\n\t\t\t\tconst snapshot = output.previewSnapshot(BASH_PREVIEW_LINES, BASH_PREVIEW_BYTES, {\n\t\t\t\t\tpersistIfFullTruncated: true,\n\t\t\t\t});\n\t\t\t\tif (routeBroadSearchOutput) {\n\t\t\t\t\tconst notice = snapshot.fullOutputPath\n\t\t\t\t\t\t? `Broad search running. Output is being routed to ${snapshot.fullOutputPath}`\n\t\t\t\t\t\t: \"Broad search running. Output is being routed to a managed file\";\n\t\t\t\t\tonUpdate({\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: notice }],\n\t\t\t\t\t\tdetails: {\n\t\t\t\t\t\t\tfullOutputPath: snapshot.fullOutputPath,\n\t\t\t\t\t\t\tfullOutputError: snapshot.fullOutputError,\n\t\t\t\t\t\t\tpersistedOutputTruncated: snapshot.persistedOutputTruncated,\n\t\t\t\t\t\t\tpersistedOutputBytes: snapshot.persistedOutputBytes,\n\t\t\t\t\t\t},\n\t\t\t\t\t});\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tconst preview = {\n\t\t\t\t\tcontent: snapshot.content.replace(/\\r/g, \"\"),\n\t\t\t\t\tskippedLines: Math.max(0, snapshot.truncation.totalLines - snapshot.truncation.outputLines),\n\t\t\t\t};\n\t\t\t\tonUpdate({\n\t\t\t\t\tcontent: [{ type: \"text\", text: preview.content || \"\" }],\n\t\t\t\t\tdetails: {\n\t\t\t\t\t\ttruncation: snapshot.truncation.truncated ? snapshot.truncation : undefined,\n\t\t\t\t\t\tfullOutputPath: snapshot.fullOutputPath,\n\t\t\t\t\t\tfullOutputError: snapshot.fullOutputError,\n\t\t\t\t\t\tpreview,\n\t\t\t\t\t},\n\t\t\t\t});\n\t\t\t};\n\n\t\t\tconst clearUpdateTimer = () => {\n\t\t\t\tif (updateTimer) {\n\t\t\t\t\tclearTimeout(updateTimer);\n\t\t\t\t\tupdateTimer = undefined;\n\t\t\t\t}\n\t\t\t};\n\n\t\t\tconst scheduleOutputUpdate = () => {\n\t\t\t\tif (!onUpdate) return;\n\t\t\t\tupdateDirty = true;\n\t\t\t\tconst delay = BASH_UPDATE_THROTTLE_MS - (Date.now() - lastUpdateAt);\n\t\t\t\tif (delay <= 0) {\n\t\t\t\t\tclearUpdateTimer();\n\t\t\t\t\temitOutputUpdate();\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tupdateTimer ??= setTimeout(() => {\n\t\t\t\t\tupdateTimer = undefined;\n\t\t\t\t\temitOutputUpdate();\n\t\t\t\t}, delay);\n\t\t\t};\n\n\t\t\tif (onUpdate) {\n\t\t\t\tonUpdate({ content: [], details: undefined });\n\t\t\t}\n\n\t\t\tconst handleData = (data: Buffer) => {\n\t\t\t\toutput.append(data);\n\t\t\t\tscheduleOutputUpdate();\n\t\t\t};\n\n\t\t\tconst finishOutput = async () => {\n\t\t\t\toutput.finish();\n\t\t\t\tclearUpdateTimer();\n\t\t\t\temitOutputUpdate();\n\t\t\t\treturn output.snapshot({ persistIfTruncated: true });\n\t\t\t};\n\n\t\t\tconst formatOutput = (snapshot: Awaited<ReturnType<typeof finishOutput>>, emptyText = \"(no output)\") => {\n\t\t\t\tconst truncation = snapshot.truncation;\n\t\t\t\tif (routeBroadSearchOutput) {\n\t\t\t\t\tif (snapshot.fullOutputPath) {\n\t\t\t\t\t\tconst persistenceNotice = snapshot.persistedOutputTruncated\n\t\t\t\t\t\t\t? `The managed ${formatSize(BROAD_SEARCH_MAX_PERSISTED_BYTES)} file limit was reached; later output was discarded.`\n\t\t\t\t\t\t\t: \"\";\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\ttext: `Broad search output routed to ${snapshot.fullOutputPath}. ${persistenceNotice} Inspect it with bounded read offsets or a narrower search.`,\n\t\t\t\t\t\t\tdetails: {\n\t\t\t\t\t\t\t\t...(truncation.truncated ? { truncation } : {}),\n\t\t\t\t\t\t\t\tfullOutputPath: snapshot.fullOutputPath,\n\t\t\t\t\t\t\t\tpersistedOutputTruncated: snapshot.persistedOutputTruncated,\n\t\t\t\t\t\t\t\tpersistedOutputBytes: snapshot.persistedOutputBytes,\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst boundedTail = snapshot.content.replace(/\\r/g, \"\") || emptyText;\n\t\t\t\t\treturn {\n\t\t\t\t\t\ttext: `Broad search output could not be routed to a managed file${snapshot.fullOutputError ? `: ${snapshot.fullOutputError}` : \"\"}. Bounded tail:\\n${boundedTail}`,\n\t\t\t\t\t\tdetails: {\n\t\t\t\t\t\t\t...(truncation.truncated ? { truncation } : {}),\n\t\t\t\t\t\t\tfullOutputError: snapshot.fullOutputError ?? \"managed output file unavailable\",\n\t\t\t\t\t\t},\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\tlet text = snapshot.content.replace(/\\r/g, \"\") || emptyText;\n\t\t\t\tlet details: BashToolDetails | undefined;\n\t\t\t\tconst preview = output.preview(BASH_PREVIEW_LINES, BASH_PREVIEW_BYTES);\n\t\t\t\tconst fullOutputNotice = snapshot.fullOutputPath\n\t\t\t\t\t? `Full output: ${snapshot.fullOutputPath}`\n\t\t\t\t\t: snapshot.fullOutputError\n\t\t\t\t\t\t? `Full output unavailable: ${snapshot.fullOutputError}`\n\t\t\t\t\t\t: \"Full output unavailable\";\n\t\t\t\tif (truncation.truncated || preview.skippedLines > 0) {\n\t\t\t\t\tdetails = { preview };\n\t\t\t\t}\n\t\t\t\tif (snapshot.fullOutputPath || snapshot.fullOutputError) {\n\t\t\t\t\tdetails = {\n\t\t\t\t\t\t...(details ?? {}),\n\t\t\t\t\t\tfullOutputPath: snapshot.fullOutputPath,\n\t\t\t\t\t\tfullOutputError: snapshot.fullOutputError,\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\tif (truncation.truncated) {\n\t\t\t\t\tdetails = {\n\t\t\t\t\t\t...(details ?? {}),\n\t\t\t\t\t\ttruncation,\n\t\t\t\t\t\tfullOutputPath: snapshot.fullOutputPath,\n\t\t\t\t\t\tfullOutputError: snapshot.fullOutputError,\n\t\t\t\t\t};\n\t\t\t\t\tconst startLine = truncation.totalLines - truncation.outputLines + 1;\n\t\t\t\t\tconst endLine = truncation.totalLines;\n\t\t\t\t\tif (truncation.lastLinePartial) {\n\t\t\t\t\t\tconst lastLineSize = formatSize(output.getLastLineBytes());\n\t\t\t\t\t\ttext += `\\n\\n[Showing last ${formatSize(truncation.outputBytes)} of line ${endLine} (line is ${lastLineSize}). ${fullOutputNotice}]`;\n\t\t\t\t\t} else if (truncation.truncatedBy === \"lines\") {\n\t\t\t\t\t\ttext += `\\n\\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines}. ${fullOutputNotice}]`;\n\t\t\t\t\t} else {\n\t\t\t\t\t\ttext += `\\n\\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). ${fullOutputNotice}]`;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn { text, details };\n\t\t\t};\n\n\t\t\tconst appendStatus = (text: string, status: string) => `${text ? `${text}\\n\\n` : \"\"}${status}`;\n\t\t\tconst effectiveTimeoutSeconds =\n\t\t\t\ttypeof timeout === \"number\" && Number.isFinite(timeout) && timeout > 0\n\t\t\t\t\t? resolveCommandTimeoutSeconds(timeout)\n\t\t\t\t\t: (commandTimeoutMsOverride ?? DEFAULT_COMMAND_TIMEOUT_SECONDS * 1000) / 1000;\n\n\t\t\ttry {\n\t\t\t\tif (canFilterCommand) {\n\t\t\t\t\tconst classification = classifyGitCommand(command, getShellEnv());\n\t\t\t\t\tif (classification.eligible && classification.subcommand) {\n\t\t\t\t\t\tconst res = await executeFilteredGit(\n\t\t\t\t\t\t\tcwd,\n\t\t\t\t\t\t\tclassification.subcommand,\n\t\t\t\t\t\t\tclassification.globalOptions || [],\n\t\t\t\t\t\t\tclassification.subcommandArgs || [],\n\t\t\t\t\t\t\t{ signal, timeout: effectiveTimeoutSeconds },\n\t\t\t\t\t\t);\n\t\t\t\t\t\tif (res.exitCode !== -100) {\n\t\t\t\t\t\t\toutput.append(res.rawBytes ?? Buffer.from(res.rawOut, \"utf-8\"));\n\t\t\t\t\t\t\tconst snapshot = await finishOutput();\n\t\t\t\t\t\t\tif (res.exitCode !== 0) {\n\t\t\t\t\t\t\t\tconst { text: rawOutputText } = formatOutput(snapshot);\n\t\t\t\t\t\t\t\tthrow new Error(appendStatus(rawOutputText, `Command exited with code ${res.exitCode}`));\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tconst details = snapshot.truncation.truncated\n\t\t\t\t\t\t\t\t? {\n\t\t\t\t\t\t\t\t\t\ttruncation: snapshot.truncation,\n\t\t\t\t\t\t\t\t\t\tfullOutputPath: snapshot.fullOutputPath,\n\t\t\t\t\t\t\t\t\t\tfullOutputError: snapshot.fullOutputError,\n\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t: snapshot.fullOutputPath || snapshot.fullOutputError\n\t\t\t\t\t\t\t\t\t? { fullOutputPath: snapshot.fullOutputPath, fullOutputError: snapshot.fullOutputError }\n\t\t\t\t\t\t\t\t\t: undefined;\n\t\t\t\t\t\t\treturn { content: [{ type: \"text\", text: res.output }], details };\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\tlet backendCommand = command;\n\t\t\t\tlet engineRoute = false;\n\t\t\t\tlet effectiveCwd = cwd;\n\t\t\t\tif (routesWindowsContract) {\n\t\t\t\t\tconst route = routeShellContract(command, contractPlatform, { pythonEngine: pythonEngineEnabled });\n\t\t\t\t\tif (route.kind === \"unsupported\") throw new Error(route.error);\n\t\t\t\t\tif (route.kind === \"python-engine\") engineRoute = true;\n\t\t\t\t\tbackendCommand = route.command;\n\t\t\t\t\t// The engine is the sole state mutator (D4); every Windows call — engine or PS\n\t\t\t\t\t// tier — reads the SAME session state so a `cd`/`export` in one call is observed\n\t\t\t\t\t// by the very next call regardless of which tier runs it.\n\t\t\t\t\teffectiveCwd = resolveEffectiveCwd(getOrCreateWindowsShellState(sessionKey), cwd);\n\t\t\t\t}\n\t\t\t\t// The engine executes the RAW Bash source unchanged: no commandPrefix (arbitrary\n\t\t\t\t// PowerShell setup would not parse as Bash grammar) and no PowerShell UTF-8 prefix.\n\t\t\t\tconst resolvedCommand = engineRoute\n\t\t\t\t\t? backendCommand\n\t\t\t\t\t: backendShell === \"powershell\"\n\t\t\t\t\t\t? prefixPowerShellCommand(commandPrefix ? `${commandPrefix}\\n${backendCommand}` : backendCommand)\n\t\t\t\t\t\t: commandPrefix\n\t\t\t\t\t\t\t? `${commandPrefix}\\n${backendCommand}`\n\t\t\t\t\t\t\t: backendCommand;\n\t\t\t\tconst spawnContext = resolveSpawnContext(resolvedCommand, effectiveCwd, spawnHook);\n\t\t\t\tif (routesWindowsContract) {\n\t\t\t\t\tspawnContext.env = mergeEffectiveEnv(getOrCreateWindowsShellState(sessionKey), spawnContext.env);\n\t\t\t\t}\n\n\t\t\t\tlet exitCode: number | null;\n\t\t\t\ttry {\n\t\t\t\t\t// Shell commands cannot statically declare which files they mutate, so the\n\t\t\t\t\t// actual execution takes the coarse exclusive barrier: it waits for\n\t\t\t\t\t// in-flight edit/write mutations to drain and blocks new ones meanwhile.\n\t\t\t\t\tconst result = await withExclusiveMutationBarrier(() =>\n\t\t\t\t\t\t(engineRoute && engineOperations ? engineOperations : ops).exec(\n\t\t\t\t\t\t\tspawnContext.command,\n\t\t\t\t\t\t\tspawnContext.cwd,\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\tonData: handleData,\n\t\t\t\t\t\t\t\tsignal,\n\t\t\t\t\t\t\t\ttimeout: effectiveTimeoutSeconds,\n\t\t\t\t\t\t\t\tenv: spawnContext.env,\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t),\n\t\t\t\t\t);\n\t\t\t\t\texitCode = result.exitCode;\n\t\t\t\t} catch (err) {\n\t\t\t\t\tconst snapshot = await finishOutput();\n\t\t\t\t\tconst { text } = formatOutput(snapshot, \"\");\n\t\t\t\t\tif (err instanceof Error && err.message === \"aborted\") {\n\t\t\t\t\t\tthrow new Error(appendStatus(text, \"Command aborted\"));\n\t\t\t\t\t}\n\t\t\t\t\tif (err instanceof Error && err.message.startsWith(\"timeout:\")) {\n\t\t\t\t\t\tconst timeoutSecs = err.message.split(\":\")[1];\n\t\t\t\t\t\tthrow new Error(appendStatus(text, `Command timed out after ${timeoutSecs} seconds`));\n\t\t\t\t\t}\n\t\t\t\t\tif (err instanceof Error && err.message.startsWith(\"silence:\")) {\n\t\t\t\t\t\tconst secs = err.message.split(\":\")[1];\n\t\t\t\t\t\tconst recovery =\n\t\t\t\t\t\t\tbackendShell === \"bash\"\n\t\t\t\t\t\t\t\t? \"re-run it with an explicit timeout, or run it in the background with '&'.\"\n\t\t\t\t\t\t\t\t: \"re-run it with an explicit timeout.\";\n\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\tappendStatus(\n\t\t\t\t\t\t\t\ttext,\n\t\t\t\t\t\t\t\t`Command killed after ${secs}s of silence (no output). If the command is legitimately quiet for long stretches, ${recovery}`,\n\t\t\t\t\t\t\t),\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\tthrow err;\n\t\t\t\t}\n\n\t\t\t\tconst snapshot = await finishOutput();\n\t\t\t\tconst { text: outputText, details } = formatOutput(snapshot);\n\t\t\t\tif (exitCode !== 0 && exitCode !== null) {\n\t\t\t\t\tthrow new Error(appendStatus(outputText, `Command exited with code ${exitCode}`));\n\t\t\t\t}\n\t\t\t\treturn { content: [{ type: \"text\", text: outputText }], details };\n\t\t\t} finally {\n\t\t\t\tclearUpdateTimer();\n\t\t\t\tawait output.closeTempFile();\n\t\t\t}\n\t\t},\n\t\trenderCall(args, _theme, context) {\n\t\t\tconst state = context.state;\n\t\t\tif (context.executionStarted && state.startedAt === undefined) {\n\t\t\t\tstate.startedAt = Date.now();\n\t\t\t\tstate.endedAt = undefined;\n\t\t\t}\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatBashCall(args, toolName));\n\t\t\treturn text;\n\t\t},\n\t\trenderResult(result, options, _theme, context) {\n\t\t\tconst state = context.state;\n\t\t\tif (state.startedAt !== undefined && options.isPartial && !state.interval) {\n\t\t\t\tstate.interval = setInterval(() => context.invalidate(), 1000);\n\t\t\t}\n\t\t\tif (!options.isPartial || context.isError) {\n\t\t\t\tstate.endedAt ??= Date.now();\n\t\t\t\tif (state.interval) {\n\t\t\t\t\tclearInterval(state.interval);\n\t\t\t\t\tstate.interval = undefined;\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst component =\n\t\t\t\t(context.lastComponent as BashResultRenderComponent | undefined) ?? new BashResultRenderComponent();\n\t\t\trebuildBashResultRenderComponent(\n\t\t\t\tcomponent,\n\t\t\t\tresult as any,\n\t\t\t\toptions,\n\t\t\t\tcontext.showImages,\n\t\t\t\tstate.startedAt,\n\t\t\t\tstate.endedAt,\n\t\t\t);\n\t\t\tcomponent.invalidate();\n\t\t\treturn component;\n\t\t},\n\t};\n}\n\nexport function createBashToolDefinition(\n\tcwd: string,\n\toptions?: BashToolOptions,\n): ToolDefinition<typeof bashSchema, BashToolDetails | undefined, BashRenderState> {\n\tconst platform = options?.platform ?? process.platform;\n\treturn createShellToolDefinition(cwd, getPlatformShellToolName(platform), platform, options);\n}\n\nexport function createBashTool(cwd: string, options?: BashToolOptions): AgentTool<typeof bashSchema> {\n\treturn wrapToolDefinition(createBashToolDefinition(cwd, options));\n}\n"]}

package/dist/core/tools/bash.js

@@ -15,6 +15,7 @@ import { withExclusiveMutationBarrier } from "./file-mutation-queue.js";
 import { classifyGitCommand, executeFilteredGit } from "./git-filter.js";
 import { OutputAccumulator } from "./output-accumulator.js";
 import { getTextOutput, invalidArgText, str } from "./render-utils.js";
+import { assessShellSearchScope, BROAD_SEARCH_OUTPUT_ROUTE } from "./search-command-guard.js";
 import { routeShellContract } from "./shell-contract-router.js";
 import { acquirePersistentShellSession } from "./shell-session.js";
 import { wrapToolDefinition } from "./tool-definition-wrapper.js";
@@ -51,6 +52,9 @@ const bashSchema = Type.Object({
     timeout: Type.Optional(Type.Number({
         description: `Wall-clock timeout in seconds. Defaults to ${DEFAULT_COMMAND_TIMEOUT_SECONDS}; positive overrides are capped at ${MAX_COMMAND_TIMEOUT_SECONDS}. Zero or negative values use the default.`,
     })),
+    broadSearch: Type.Optional(Type.Literal(BROAD_SEARCH_OUTPUT_ROUTE, {
+        description: "Explicit override for a broad rg/grep/find/fd scan that cannot be narrowed. The command runs, but its complete output is routed to a file and excluded from model context.",
+    })),
 });
 function createLocalShellOperations(shellName, options) {
     // A session key selects the persistent per-agent backend. An explicit custom shell path keeps
@@ -211,6 +215,7 @@ function resolveSpawnContext(command, cwd, spawnHook) {
 const BASH_PREVIEW_LINES = 5;
 const BASH_PREVIEW_BYTES = 8 * 1024;
 const BASH_UPDATE_THROTTLE_MS = 100;
+const BROAD_SEARCH_MAX_PERSISTED_BYTES = 8 * 1024 * 1024;
 class BashResultRenderComponent extends Container {
     state = {
         cachedWidth: undefined,
@@ -321,7 +326,7 @@ function createShellToolDefinition(cwd, backendShell, contractPlatform, options)
     return {
         name: toolName,
         label: toolName,
-        description: `${contractDescription} Returns stdout and stderr. Output is truncated to last ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). If truncated, full output is saved to a temp file. Commands have a ${DEFAULT_COMMAND_TIMEOUT_SECONDS}-second wall-clock default, including commands that keep producing output; use a positive timeout only when a scoped operation justifies a larger bound (maximum ${MAX_COMMAND_TIMEOUT_SECONDS} seconds).`,
+        description: `${contractDescription} Returns stdout and stderr. Output is truncated to last ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). If truncated, full output is saved to a managed file. Broad rg/grep/find/fd scans are rejected before execution; when an exhaustive scan is unavoidable, set broadSearch="${BROAD_SEARCH_OUTPUT_ROUTE}" to route all output to a managed file instead of model context. Commands have a ${DEFAULT_COMMAND_TIMEOUT_SECONDS}-second wall-clock default, including commands that keep producing output; use a positive timeout only when a scoped operation justifies a larger bound (maximum ${MAX_COMMAND_TIMEOUT_SECONDS} seconds).`,
         promptSnippet: routesWindowsContract
             ? "Execute Bash-like commands; Pi routes them deterministically to PowerShell or a bundled Python engine on Windows"
             : "Execute Bash commands (ls, grep, find, etc.)",
@@ -331,14 +336,24 @@ function createShellToolDefinition(cwd, backendShell, contractPlatform, options)
                 "Pipelines, redirection, expansion (variables, command substitution, globs), chaining (&&/||/;), and cd/export/unset are supported and routed to a bundled Python engine; a fixed set of named constructs (job control, process substitution, heredocs, arithmetic expansion, nested shells, and similar) fail closed with an actionable message instead of being guessed.",
                 "Working directory and environment changes from cd/export/unset persist across subsequent bash calls, including calls that route to the PowerShell tier.",
                 "Supported Bash-like file commands are converted with literal-path operations; verify targets before recursive rm, cp, or mv calls.",
-                "Keep searches scoped and purpose-driven: discover paths first, pass an explicit root and filters, prefer rg over broad find, and increase the timeout only for a justified bounded search.",
+                `Keep searches scoped and purpose-driven: discover paths first, pass an explicit root and filters, and prefer the bounded grep/find tools. Broad shell searches are rejected; use broadSearch="${BROAD_SEARCH_OUTPUT_ROUTE}" only for an unavoidable exhaustive scan, then inspect the returned file with bounded reads or narrower searches.`,
             ]
             : [
-                "Keep searches scoped and purpose-driven: discover paths first, pass an explicit root and filters, prefer rg over broad find, and increase the timeout only for a justified bounded search.",
+                `Keep searches scoped and purpose-driven: discover paths first, pass an explicit root and filters, and prefer the bounded grep/find tools. Broad shell searches are rejected; use broadSearch="${BROAD_SEARCH_OUTPUT_ROUTE}" only for an unavoidable exhaustive scan, then inspect the returned file with bounded reads or narrower searches.`,
             ],
         parameters: bashSchema,
-        async execute(_toolCallId, { command, timeout }, signal, onUpdate, _ctx) {
-            const output = new OutputAccumulator({ tempFilePrefix: `pi-${toolName}` });
+        async execute(_toolCallId, { command, timeout, broadSearch, }, signal, onUpdate, _ctx) {
+            const searchScope = assessShellSearchScope(command, cwd);
+            if (searchScope.kind === "broad" && broadSearch !== BROAD_SEARCH_OUTPUT_ROUTE) {
+                throw new Error(`Broad search blocked before execution: ${searchScope.reason}. Narrow the path, glob, type, or pattern; prefer the grep/find tool with explicit path/glob/limit. If an exhaustive scan is required, retry with broadSearch="${BROAD_SEARCH_OUTPUT_ROUTE}"; Pi will keep its output out of context and return a managed file path for bounded read or search follow-up.`);
+            }
+            const routeBroadSearchOutput = searchScope.kind === "broad";
+            const output = new OutputAccumulator({
+                tempFilePrefix: `pi-${toolName}`,
+                tempDirectory: options?.outputDirectory,
+                persistAllOutput: routeBroadSearchOutput,
+                maxPersistedBytes: routeBroadSearchOutput ? BROAD_SEARCH_MAX_PERSISTED_BYTES : undefined,
+            });
             let updateTimer;
             let updateDirty = false;
             let lastUpdateAt = 0;
@@ -350,6 +365,21 @@ function createShellToolDefinition(cwd, backendShell, contractPlatform, options)
                 const snapshot = output.previewSnapshot(BASH_PREVIEW_LINES, BASH_PREVIEW_BYTES, {
                     persistIfFullTruncated: true,
                 });
+                if (routeBroadSearchOutput) {
+                    const notice = snapshot.fullOutputPath
+                        ? `Broad search running. Output is being routed to ${snapshot.fullOutputPath}`
+                        : "Broad search running. Output is being routed to a managed file";
+                    onUpdate({
+                        content: [{ type: "text", text: notice }],
+                        details: {
+                            fullOutputPath: snapshot.fullOutputPath,
+                            fullOutputError: snapshot.fullOutputError,
+                            persistedOutputTruncated: snapshot.persistedOutputTruncated,
+                            persistedOutputBytes: snapshot.persistedOutputBytes,
+                        },
+                    });
+                    return;
+                }
                 const preview = {
                     content: snapshot.content.replace(/\r/g, ""),
                     skippedLines: Math.max(0, snapshot.truncation.totalLines - snapshot.truncation.outputLines),
@@ -400,6 +430,30 @@ function createShellToolDefinition(cwd, backendShell, contractPlatform, options)
             };
             const formatOutput = (snapshot, emptyText = "(no output)") => {
                 const truncation = snapshot.truncation;
+                if (routeBroadSearchOutput) {
+                    if (snapshot.fullOutputPath) {
+                        const persistenceNotice = snapshot.persistedOutputTruncated
+                            ? `The managed ${formatSize(BROAD_SEARCH_MAX_PERSISTED_BYTES)} file limit was reached; later output was discarded.`
+                            : "";
+                        return {
+                            text: `Broad search output routed to ${snapshot.fullOutputPath}. ${persistenceNotice} Inspect it with bounded read offsets or a narrower search.`,
+                            details: {
+                                ...(truncation.truncated ? { truncation } : {}),
+                                fullOutputPath: snapshot.fullOutputPath,
+                                persistedOutputTruncated: snapshot.persistedOutputTruncated,
+                                persistedOutputBytes: snapshot.persistedOutputBytes,
+                            },
+                        };
+                    }
+                    const boundedTail = snapshot.content.replace(/\r/g, "") || emptyText;
+                    return {
+                        text: `Broad search output could not be routed to a managed file${snapshot.fullOutputError ? `: ${snapshot.fullOutputError}` : ""}. Bounded tail:\n${boundedTail}`,
+                        details: {
+                            ...(truncation.truncated ? { truncation } : {}),
+                            fullOutputError: snapshot.fullOutputError ?? "managed output file unavailable",
+                        },
+                    };
+                }
                 let text = snapshot.content.replace(/\r/g, "") || emptyText;
                 let details;
                 const preview = output.preview(BASH_PREVIEW_LINES, BASH_PREVIEW_BYTES);