Bash Execution & Pty
Relevant source files
The following files were used as context for generating this wiki page:
The Bash Execution & Pty system provides the Oh My Pi environment with the capability to execute real binaries and shell commands within a controlled terminal environment. It utilizes a Pseudo-Terminal (Pty) to manage interactive and non-interactive workloads, ensuring that the agent can interact with standard command-line interfaces (CLIs) while maintaining observability and safety constraints.
This subsystem is primarily integrated into the coding-agent package, serving as the backend for the bash tool. It handles process spawning, environment variable persistence, output streaming, and timeout management. The system is designed to prefer Bun APIs for efficiency while falling back to native Rust-based components for performance-critical operations like Pty management.
Sources: packages/coding-agent/DEVELOPMENT.md:57, AGENTS.md:73-86, packages/coding-agent/test/tools.test.ts:365-370
Architecture and Components
The Bash execution architecture is divided into the high-level tool interface used by agents and the low-level execution backends that handle the actual process lifecycle.
Component Overview
| Component | Responsibility |
|---|---|
| BashTool | High-level tool interface that validates inputs, applies interceptors, and formats results for the agent. |
| BashExecutor | Orchestrates the execution logic, including environment setup and output capture. |
| PtySession | A native binding (Rust-based) that manages the lifecycle of a Pseudo-Terminal session. |
| AsyncJobManager | Manages long-running or auto-backgrounded bash tasks. |
Sources: packages/coding-agent/DEVELOPMENT.md:65, packages/coding-agent/test/tools.test.ts:25-30, packages/natives/test/native.test.ts:20
Logic Flow
The following diagram illustrates the flow from a tool call to the execution of a bash command.
The system includes a Bash Interceptor that blocks certain commands (like cat, grep, or ls) to force the agent to use specialized tools (like read or glob) which are more efficient or provides better structured data.
Sources: packages/coding-agent/test/tools.test.ts:384-405, AGENTS.md:76-80
Execution Management
Timeouts and Lifecycle
Commands executed through the bash tool are subject to strict timeout management. The default timeout is 300 seconds, but this can be adjusted by the caller within a defined range (typically 1 to 3600 seconds). If a command exceeds its timeout, the system attempts to terminate the process group, starting with SIGTERM and escalating to SIGKILL if necessary.
Sources: packages/coding-agent/test/tools.test.ts:368, packages/coding-agent/test/tools.test.ts:503-510, packages/natives/test/native.test.ts:476-485
Background Tasks and Auto-Backgrounding
The system supports asynchronous execution for long-running tasks. "Auto-backgrounding" is a feature where the BashTool monitors a command's execution time; if it exceeds a configured threshold (e.g., 2 seconds), the tool yields a "Background job" result and hands control to the AsyncJobManager.
Native Pty Integration
The core terminal management relies on the PtySession class provided by pi-natives. This native integration allows the system to:
- Maintain a persistent shell environment (if configured).
- Handle terminal column/row sizing (e.g.,
cols: 120, rows: 40). - Manage complex background workloads and detached processes without hanging the main application.
const session = new PtySession();
const result = await session.start({
command: 'bash -lc "sleep 30"',
cwd: testDir,
timeoutMs: 150,
cols: 120,
rows: 40,
});
Sources: packages/natives/test/native.test.ts:445-455, packages/coding-agent/test/tools.test.ts:436-444
Environment Persistence
When PI_SHELL_PERSIST is enabled, the system maintains environment variables across separate tool calls. This allows the agent to export a variable in one turn and read it in the next, simulating a continuous shell session.
Sources: packages/coding-agent/test/tools.test.ts:427-434, AGENTS.md:143-145
Output Sanitization and Truncation
To prevent terminal corruption and context window flooding, the system applies strict sanitization to all bash output:
- Tab Replacement: Tabs are converted to spaces to avoid "visual holes."
- Column Truncation: Lines are truncated at a predefined width (e.g., 768 characters).
- Artifact Spilling: If output is heavily truncated, the full content is written to an artifact file (e.g.,
session/artifact-id.bash.log) for later retrieval.
Sources: AGENTS.md:175-185, packages/coding-agent/test/tools.test.ts:376-382, packages/coding-agent/test/tools.test.ts:436-444
Summary
The Bash Execution and Pty system provides a robust bridge between the AI agent and the host operating system. By combining high-level tool policies (interceptors and auto-backgrounding) with low-level native Pty management, it enables safe, observable, and persistent command-line interactions. The architecture prioritizes speed via Bun APIs while maintaining the stability required for load-bearing code changes.