can1357--oh-my-pi/docs/bash-tool-runtime.md

Bash tool runtime

This document describes the bash tool runtime path used by agent tool calls, from command normalization to execution, truncation/artifacts, and rendering.

It also calls out where behavior diverges in interactive TUI, print mode, RPC mode, and user-initiated bang (!) shell execution.

Scope and runtime surfaces

There are two different bash execution surfaces in coding-agent:

1. Tool-call surface (toolName: "bash"): used when the model calls the bash tool.
   • Entry point: BashTool.execute().
   • Parameters include command, optional env, timeout, cwd, pty, and, when async.enabled is true, async.
2. User bang-command surface (!cmd from interactive input or RPC bash command): session-level helper path.
   • Entry point: AgentSession.executeBash().

Both eventually use executeBash() in src/exec/bash-executor.ts for non-PTY execution, but only the tool-call path runs normalization/interception, optional managed background-job handling, and tool renderer logic.

Set bash.enabled: false in settings to remove the model-facing bash tool from the active tool registry. This does not disable user-initiated bang commands or RPC bash requests.

End-to-end tool-call pipeline

1) Input handling and parameter merge

BashTool.execute() currently handles input before execution as follows:

• validates optional env names against shell-variable syntax,
• extracts a leading single-line cd <path> && ... into cwd when cwd was not supplied,
• rejects async: true when async.enabled is false.

There are no structured head or tail tool parameters in the current schema, and commands run exactly as written — no pre-execution rewrites. Output limiting is handled by OutputSink truncation/artifacts.

2) Optional interception (blocked-command path)

If bashInterceptor.enabled is true, BashTool loads rules from settings (getBashInterceptorRules()) and runs checkBashInterception() against the command — checking both the original and the cwd-normalized form (after a leading cd … && is extracted) when they differ.

Interception behavior:

• command is blocked only when:
  • regex rule matches, and
  • the suggested tool is present in ctx.toolNames.
• invalid regex rules are silently skipped.
• on block, BashTool throws ToolError with message:
  • Blocked: ...
  • original command included.

Default rule patterns (defined in code) target common misuses:

• file readers (cat, head, tail, ...)
• search tools (grep, rg, ...)
• file finders (find, fd, ...)
• in-place editors (sed -i, perl -i, awk -i inplace)
• shell redirection writes (echo ... > file, heredoc redirection)

Caveat

InterceptionResult includes suggestedTool, but BashTool currently surfaces only the message text (no structured suggested-tool field in details).

3) CWD validation and timeout clamping

cwd is resolved relative to session cwd (resolveToCwd), then validated via stat:

• missing path -> ToolError("Working directory does not exist: ...")
• non-directory -> ToolError("Working directory is not a directory: ...")

Timeout is clamped to [1, 3600] seconds and converted to milliseconds.

4) Artifact allocation

Before execution, the tool allocates an artifact path/id (best-effort) for truncated output storage.

• artifact allocation failure is non-fatal (execution continues without artifact spill file),
• artifact id/path are passed into execution path for full-output persistence on truncation.

5) PTY vs non-PTY execution selection

PTY eligibility is decided by canUseInteractiveBashPty(pty, ctx) (src/tools/bash-pty-selection.ts); the local PTY overlay runs only when all are true:

• tool input pty === true
• PI_NO_PTY !== "1"
• tool context has UI (ctx.hasUI === true and ctx.ui set)

If pty is requested but unavailable, the call falls back to non-PTY and appends a pty requested but unavailable … notice.

Before the local PTY/non-PTY choice, a foreground (async: false) call can route to a managed background job (auto-backgrounding; see below) or — when the session's client advertises a terminal capability (clientBridge.capabilities.terminal + createTerminal, with pty false) — to a client-bridge editor terminal that runs the command remotely (streaming terminalId updates, killing on timeout, mapping a signal kill to exit code 137). Otherwise it uses non-interactive executeBash().

That means print mode and non-UI RPC/tool contexts always use non-PTY.

Non-interactive execution engine (executeBash)

Shell session reuse model

executeBash() caches native Shell instances in a process-global map keyed by:

• shell path,
• configured command prefix,
• snapshot path,
• serialized shell env,
• optional agent session key,
• minimizer configuration.

Session-level bang-command executions pass sessionKey: this.sessionId.

Tool-call executions pass sessionKey: this.session.getSessionId?.(), when available. In both surfaces, a session key isolates shell reuse per session; without one, reuse falls back to shell config/snapshot/env.

Concurrent calls never share one Shell: the native session runs one command at a time and Shell.abort() kills every in-flight run on it. executeBash() tracks in-flight keys in shellSessionsInUse; while a key is busy, overlapping calls skip the cache and run through one-shot executeShell() (same isolation as quarantined sessions). Only the owning call releases the in-use flag or deletes the cached session in its finally.

Shell config and snapshot behavior

At each call, executor loads settings shell config (shell, env, optional prefix).

If selected shell includes bash, it attempts getOrCreateSnapshot():

• snapshot captures aliases/functions/options from user rc,
• snapshot creation is best-effort,
• failure falls back to no snapshot.

If prefix is configured, command becomes:

<prefix> <command>

The per-command child environment is built by buildNonInteractiveEnv() (src/exec/non-interactive-env.ts), which layers non-interactive hardening defaults under the caller's env overrides:

• pagers disabled (PAGER=cat, GIT_PAGER=cat, … and LESS=FRX),
• editor prompts disabled (GIT_EDITOR=true, EDITOR=true, VISUAL=true),
• terminal/credential prompts reduced (TERM=dumb, GIT_TERMINAL_PROMPT=0, SSH_ASKPASS=/usr/bin/false, NO_COLOR=1, CI=1),
• package-manager/tooling automation flags for non-interactive behavior (npm/pnpm/yarn/pip/cargo/terraform/gh, …),
• on Windows, UTF-8 locale/codepage defaults are added when absent.

Streaming and cancellation

Shell.run() streams chunks to OutputSink and optional onChunk callback.

Cancellation:

• aborted signal triggers shellSession.abort(...),
• timeout from native result is mapped to cancelled: true + annotation text,
• explicit cancellation similarly returns cancelled: true + annotation.

No exception is thrown inside executor for timeout/cancel; it returns structured BashResult and lets caller map error semantics.

Interactive PTY path (runInteractiveBashPty)

When PTY is enabled, tool runs runInteractiveBashPty() which opens an overlay console component and drives a native PtySession.

Behavior highlights:

• xterm-headless virtual terminal renders viewport in overlay,
• keyboard input is normalized (including Kitty sequences and application cursor mode handling),
• esc while running kills the PTY session,
• terminal resize propagates to PTY (session.resize(cols, rows)).

Unlike the non-PTY engine, the interactive PTY path does not apply the non-interactive hardening. It inherits the user's environment and sets a real TERM=xterm-256color (applied as an override on the Rust side) so editors, pagers, and TUIs behave like a normal terminal.

PTY output is normalized (CRLF/CR to LF, sanitizeText) and written into OutputSink, including artifact spill support.

On PTY startup/runtime error, sink receives PTY error: ... line and command finalizes with undefined exit code.

Output handling: streaming, truncation, artifact spill

Both PTY and non-PTY paths use OutputSink.

OutputSink semantics

The bash executor builds the sink with headBytes and maxColumns from settings (resolveOutputSinkHeadBytes / resolveOutputMaxColumns).

• keeps a UTF-8-safe rolling tail window (spillThreshold, DEFAULT_MAX_BYTES, currently 50KB); on overflow it trims to the tail (UTF-8 boundary safe) and marks truncated,
• when headBytes > 0 (tools.artifactHeadBytes, default 20KB) it also retains a head window and elides the middle, splicing an elision marker between head and tail in dump(),
• per-line column cap: when maxColumns > 0 (tools.outputMaxColumns, default 768 bytes) over-wide lines are ellipsis-truncated at write time and the rest of the line is dropped,
• tracks total bytes/lines seen,
• mirrors the raw, uncapped stream to the artifact file when output overflows, a column cap dropped bytes, or the file is already active,
• marks truncated on tail overflow, middle elision, column-cap drops, or file spill.

dump() returns:

• output (possibly annotated prefix),
• truncated,
• totalLines/totalBytes,
• outputLines/outputBytes,
• elidedBytes/elidedLines when the middle was elided,
• columnDroppedBytes/columnTruncatedLines when the per-line cap fired,
• artifactId if artifact file was active.

Long-output caveat

Runtime truncation is byte-threshold based in OutputSink (50KB tail window by default, plus an optional head window for middle elision). It does not enforce a hard line-count cap in this code path.

Shell output minimizer

Non-PTY execution also passes shell-minimizer settings into the native Shell session. When the minimizer rewrites verbose output, the executor replaces the sink's visible text with the minimized text and, when possible, saves the raw original capture as a separate bash-original artifact referenced by a [raw output: artifact://<id>] footer.

Live tool updates and async jobs

For non-PTY foreground execution, BashTool uses a separate TailBuffer for partial updates and emits onUpdate snapshots while command is running.

For PTY execution, live rendering is handled by custom UI overlay, not by onUpdate text chunks.

When async.enabled is true and the call passes async: true, BashTool starts a managed bash job, returns a running job result with a job id, and stores completion through the session managed-job path. Auto-backgrounding can also start this path after bash.autoBackground.thresholdMs.

Result shaping, metadata, and error mapping

After execution:

1. cancelled handling:
   • if abort signal is aborted -> throw ToolAbortError (abort semantics),
   • else -> throw ToolError (treated as tool failure).
2. PTY timedOut -> throw ToolError.
3. empty output becomes (no output).
4. attach truncation metadata via toolResult(...).truncationFromSummary(result, { direction: "tail" }).
5. exit-code mapping:
   • missing exit code -> throw ToolError("... missing exit status")
   • non-zero exit -> error result with "Command exited with code N" and details.exitCode
   • zero exit -> success result.

Success payload structure:

• content: text output,
• details.meta.truncation when truncated, including:
  • direction, truncatedBy, total/output line+byte counts,
  • shownRange,
  • artifactId when available.

Because built-in tools are wrapped with wrapToolWithMetaNotice(), truncation notice text is appended to final text content automatically (for example: Read artifact://<id> for full output).

Rendering paths

Tool-call renderer (bashToolRenderer)

bashToolRenderer is used for tool-call messages (toolCall / toolResult):

• collapsed mode shows visual-line-truncated preview,
• expanded mode shows all currently available output text,
• warning line includes truncation reason and artifact://<id> when truncated,
• timeout value (from args) is shown in footer metadata line.

Caveat: full artifact expansion

BashRenderContext has isFullOutput, but current renderer context builder does not set it for bash tool results. Expanded view still uses the text already in result content (tail/truncated output) unless another caller provides full artifact content.

User bang-command component (BashExecutionComponent)

BashExecutionComponent is for user ! commands in interactive mode (not model tool calls):

• streams chunks live,
• collapsed preview keeps last 20 logical lines,
• line clamp at 4000 chars per line,
• shows truncation + artifact warnings when metadata is present,
• marks cancelled/error/exit state separately.

This component is wired by CommandController.handleBashCommand() and fed from AgentSession.executeBash().

Mode-specific behavior differences

Surface	Entry path	PTY eligible	Live output UX	Error surfacing
Interactive tool call	BashTool.execute	Yes, when pty=true and UI exists and PI_NO_PTY!=1	PTY overlay (interactive) or streamed tail updates	Tool errors become toolResult.isError
Print mode tool call	BashTool.execute	No (no UI context)	No TUI overlay; output appears in event stream/final assistant text flow	Same tool error mapping
RPC tool call (agent tooling)	BashTool.execute	Usually no UI -> non-PTY	Structured tool events/results	Same tool error mapping
Interactive bang command (!)	AgentSession.executeBash + BashExecutionComponent	No (uses executor directly)	Dedicated bash execution component	Controller catches exceptions and shows UI error
RPC bash command	rpc-mode -> session.executeBash	No	Returns BashResult directly	Consumer handles returned fields

Operational caveats

• Interceptor only blocks commands when suggested tool is currently available in context.
• If artifact allocation fails, truncation still occurs but no artifact:// back-reference is available.
• Shell session cache has no explicit eviction in this module; lifetime is process-scoped.
• PTY and non-PTY timeout surfaces differ:
  • PTY exposes explicit timedOut result field,
  • non-PTY maps timeout into cancelled + annotation summary.

Implementation files

• src/tools/bash.ts — tool entrypoint, input handling/interception, async and PTY/non-PTY selection, result/error mapping, bash tool renderer.
• src/tools/bash-pty-selection.ts — canUseInteractiveBashPty predicate for choosing the local PTY overlay.
• src/tools/bash-interceptor.ts — interceptor rule matching and blocked-command messages.
• src/exec/bash-executor.ts — non-PTY executor, shell session reuse, cancellation wiring, output sink integration.
• src/exec/non-interactive-env.ts — non-interactive child-process env defaults (buildNonInteractiveEnv) used by the non-PTY executor.
• src/tools/bash-interactive.ts — PTY runtime, overlay UI, input normalization, and interactive TERM setup.
• src/session/streaming-output.ts — OutputSink, TailBuffer, truncation/artifact spill, and summary metadata.
• src/tools/output-meta.ts — truncation metadata shape + notice injection wrapper.
• src/session/agent-session.ts — session-level executeBash, message recording, abort lifecycle.
• src/modes/components/bash-execution.ts — interactive ! command execution component.
• src/modes/controllers/command-controller.ts — wiring for interactive ! command UI stream/update completion.
• src/modes/rpc/rpc-mode.ts — RPC bash and abort_bash command surface.
• src/internal-urls/artifact-protocol.ts — artifact://<id> resolution.