@oh-my-pi/pi-coding-agent 1.341.0 → 2.0.1337

package/CHANGELOG.md

@@ -2,6 +2,79 @@
 
 ## [Unreleased]
 
+## [2.0.1337] - 2026-01-03
+### Added
+
+- Added shell environment snapshot to preserve user aliases, functions, and shell options when executing bash commands
+- Added support for `PI_BASH_NO_CI`, `PI_BASH_NO_LOGIN`, and `PI_SHELL_PREFIX` environment variables for shell customization
+- Added zsh support alongside bash for shell detection and configuration
+
+### Changed
+
+- Changed shell detection to prefer user's `$SHELL` when it's bash or zsh, with improved fallback path resolution
+- Changed Edit tool to reject `.ipynb` files with guidance to use NotebookEdit tool instead
+
+## [1.500.0] - 2026-01-03
+### Added
+
+- Added provider tabs to model selector with Tab/Arrow navigation for filtering models by provider
+- Added context menu to model selector for choosing model role (Default, Smol, Slow) instead of keyboard shortcuts
+- Added LSP diagnostics display in tool execution output showing errors and warnings after file edits
+- Added centralized file logger with daily rotation to `~/.pi/logs/` for debugging production issues
+- Added `logger` property to hook and custom tool APIs for error/warning/debug logging
+- Added `output` tool to read full agent/task outputs by ID when truncated previews are insufficient
+- Added `task` tool to reviewer agent, enabling parallel exploration of large codebases during reviews
+- Added subprocess tool registry for extracting and rendering tool data from subprocess agents in real-time
+- Added combined review result rendering showing verdict and findings in a tree structure
+- Auto-read file mentions: Reference files with `@path/to/file.ext` syntax in prompts to automatically inject their contents, eliminating manual Read tool calls
+- Added `hidden` property for custom tools to exclude them from default tool list unless explicitly requested
+- Added `explicitTools` option to `createAgentSession` for enabling hidden tools by name
+- Added example review tools (`report_finding`, `submit_review`) with structured findings accumulation and verdict rendering
+- Added `/review` example command for interactive code review with branch comparison, uncommitted changes, and commit review modes
+- Custom TypeScript slash commands: Create programmable commands at `~/.pi/agent/commands/[name]/index.ts` or `.pi/commands/[name]/index.ts`. Commands export a factory returning `{ name, description, execute(args, ctx) }`. Return a string to send as LLM prompt, or void for fire-and-forget actions. Full access to `HookCommandContext` for UI dialogs, session control, and shell execution.
+- Claude command directories: Markdown slash commands now also load from `~/.claude/commands/` and `.claude/commands/` (parallel to existing `.pi/commands/` support)
+- `commands.enableClaudeUser` and `commands.enableClaudeProject` settings to disable Claude command directory loading
+- `/export --copy` option to copy entire session as formatted text to clipboard
+
+### Changed
+
+- Changed model selector keyboard shortcuts from S/L keys to a context menu opened with Enter
+- Changed model role indicators from symbols (✓ ⚡ 🧠) to labeled badges ([ DEFAULT ] [ SMOL ] [ SLOW ])
+- Changed model list sorting to include secondary sort by model ID within each provider
+- Changed silent error suppression to log warnings and debug info for tool errors, theme loading, and command loading failures
+- Changed Task tool progress display to show agent index (e.g., `reviewer(0)`) for easier Output tool ID derivation
+- Changed Task tool output to only include file paths when Output tool is unavailable, providing Read tool fallback
+- Changed Task tool output references to use simpler ID format (e.g., `reviewer_0`) with line/char counts for Output tool integration
+- Changed subagent recursion prevention from blanket blocking to same-agent blocking. Non-recursive agents can now spawn other agent types (e.g., reviewer can spawn explore agents) but cannot spawn themselves.
+- Changed `/review` command from markdown to interactive TypeScript with mode selection menu (branch comparison, uncommitted changes, commit review, custom)
+- Changed bundled commands to be overridable by user/project commands with same name
+- Changed subprocess termination to wait for message_end event to capture accurate token counts
+- Changed token counting in subprocess to accumulate across messages instead of overwriting
+- Updated bundled `reviewer` agent to use structured review tools with priority-based findings (P0-P3) and formal verdict submission
+- Task tool now streams artifacts in real-time: input written before spawn, session jsonl written by subprocess, output written at completion
+
+### Removed
+
+- Removed separate Exa error logger in favor of centralized logging system
+- Removed `findings_count` parameter from `submit_review` tool - findings are now counted automatically
+- Removed artifacts location display from task tool output
+
+### Fixed
+
+- Fixed race condition in event listener iteration by copying array before iteration to prevent mutation during callbacks
+- Fixed potential memory leak from orphaned abort controllers by properly aborting existing controllers before replacement
+- Fixed stream reader resource leak by adding proper `releaseLock()` calls in finally blocks
+- Fixed hook API methods throwing clear errors when handlers are not initialized instead of silently failing
+- Fixed LSP client race conditions with concurrent client creation and file operations using proper locking
+- Fixed Task tool progress display showing stale data by cloning progress objects before passing to callbacks
+- Fixed Task tool missing final progress events by waiting for readline to close before resolving
+- Fixed RPC mode race condition with concurrent prompt commands by serializing execution
+- Fixed pre-commit hook race condition causing `index.lock` errors when GitKraken/IDE git integrations detect file changes during formatting
+- Fixed Task tool output artifacts (`out.md`) containing duplicated text from streaming updates
+- Fixed Task tool progress display showing repeated nearly-identical lines during streaming
+- Fixed Task tool subprocess model selection ignoring agent's configured model and falling back to settings default. The `--model` flag now accepts `provider/model` format directly.
+- Fixed Task tool showing "done + succeeded" when aborted; now correctly displays "⊘ aborted" status
+
 ## [1.341.0] - 2026-01-03
 ### Added
 

package/README.md

@@ -192,7 +192,7 @@ The agent reads, writes, and edits files, and executes commands via bash.
 | ------------------------- | --------------------------------------------------------------------------- |
 | `/settings`               | Open settings menu (thinking, theme, queue mode, toggles)                   |
 | `/model`                  | Switch models mid-session (fuzzy search, arrow keys, Enter to select)       |
-| `/export [file]`          | Export session to self-contained HTML                                       |
+| `/export [file\|--copy]`  | Export session to HTML file or copy to clipboard                            |
 | `/share`                  | Upload session as secret GitHub gist, get shareable URL (requires `gh` CLI) |
 | `/session`                | Show session info: path, message counts, token usage, cost                  |
 | `/hotkeys`                | Show all keyboard shortcuts                                                 |

package/examples/custom-tools/subagent/index.ts

@@ -18,7 +18,7 @@ import * as path from "node:path";
 import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import type { Message } from "@oh-my-pi/pi-ai";
 import type { CustomTool, CustomToolAPI, CustomToolFactory } from "@oh-my-pi/pi-coding-agent";
-import { type AgentConfig, type AgentScope, discoverAgents, formatAgentList } from "./agents.js";
+import { type AgentConfig, type AgentScope, discoverAgents, formatAgentList } from "./agents";
 
 const MAX_PARALLEL_TASKS = 8;
 const MAX_CONCURRENCY = 4;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "1.341.0",
+	"version": "2.0.1337",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"piConfig": {
@@ -33,7 +33,7 @@
 		"clean": "rm -rf dist",
 		"build": "tsgo -p tsconfig.build.json && chmod +x dist/cli.js && npm run copy-assets",
 		"build:binary": "npm run build && bun build --compile ./dist/cli.js --outfile dist/pi && npm run copy-binary-assets",
-		"copy-assets": "mkdir -p dist/modes/interactive/theme && cp src/modes/interactive/theme/*.json dist/modes/interactive/theme/ && mkdir -p dist/core/export-html && cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/core/export-html/",
+		"copy-assets": "mkdir -p dist/modes/interactive/theme && cp src/modes/interactive/theme/*.json dist/modes/interactive/theme/ && mkdir -p dist/core/export-html && cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/core/export-html/ && mkdir -p dist/core/tools/task/bundled-agents && cp src/core/tools/task/bundled-agents/*.md dist/core/tools/task/bundled-agents/",
 		"copy-binary-assets": "cp package.json dist/ && cp README.md dist/ && cp CHANGELOG.md dist/ && mkdir -p dist/theme && cp src/modes/interactive/theme/*.json dist/theme/ && mkdir -p dist/export-html && cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/export-html/ && cp -r docs dist/ && cp -r examples dist/",
 		"test": "vitest --run",
 		"prepublishOnly": "npm run clean && npm run build"
@@ -53,7 +53,9 @@
 		"highlight.js": "^11.11.1",
 		"marked": "^15.0.12",
 		"minimatch": "^10.1.1",
-		"strip-ansi": "^7.1.2"
+		"strip-ansi": "^7.1.2",
+		"winston": "^3.17.0",
+		"winston-daily-rotate-file": "^5.0.0"
 	},
 	"devDependencies": {
 		"@types/diff": "^7.0.2",

package/src/cli/args.ts

@@ -4,8 +4,8 @@
 
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import chalk from "chalk";
-import { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR } from "../config.js";
-import { allTools, type ToolName } from "../core/tools/index.js";
+import { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR } from "../config";
+import { allTools, type ToolName } from "../core/tools/index";
 
 export type Mode = "text" | "json" | "rpc";
 
@@ -152,8 +152,7 @@ ${chalk.bold("Usage:")}
   ${APP_NAME} [options] [@files...] [messages...]
 
 ${chalk.bold("Options:")}
-  --provider <name>              Provider name (default: google)
-  --model <id>                   Model ID (default: gemini-2.5-flash)
+  --model <pattern>              Model to use (fuzzy match: "opus", "gpt-5.2", or "p-openai/gpt-5.2")
   --smol <id>                    Smol/fast model for lightweight tasks (or PI_SMOL_MODEL env)
   --slow <id>                    Slow/reasoning model for thorough analysis (or PI_SLOW_MODEL env)
   --api-key <key>                API key (defaults to env vars)
@@ -199,8 +198,8 @@ ${chalk.bold("Examples:")}
   # Continue previous session
   ${APP_NAME} --continue "What did we discuss?"
 
-  # Use different model
-  ${APP_NAME} --provider openai --model gpt-4o-mini "Help me refactor this code"
+  # Use different model (fuzzy matching)
+  ${APP_NAME} --model opus "Help me refactor this code"
 
   # Limit model cycling to specific models
   ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o

package/src/cli/file-processor.ts

@@ -3,11 +3,11 @@
  */
 
 import { access, readFile, stat } from "node:fs/promises";
+import { resolve } from "node:path";
 import type { ImageContent } from "@oh-my-pi/pi-ai";
 import chalk from "chalk";
-import { resolve } from "path";
-import { resolveReadPath } from "../core/tools/path-utils.js";
-import { detectSupportedImageMimeTypeFromFile } from "../utils/mime.js";
+import { resolveReadPath } from "../core/tools/path-utils";
+import { detectSupportedImageMimeTypeFromFile } from "../utils/mime";
 
 export interface ProcessedFiles {
 	text: string;

package/src/cli/list-models.ts

@@ -3,8 +3,8 @@
  */
 
 import type { Api, Model } from "@oh-my-pi/pi-ai";
-import type { ModelRegistry } from "../core/model-registry.js";
-import { fuzzyFilter } from "../utils/fuzzy.js";
+import type { ModelRegistry } from "../core/model-registry";
+import { fuzzyFilter } from "../utils/fuzzy";
 
 /**
  * Format a number as human-readable (e.g., 200000 -> "200K", 1000000 -> "1M")

package/src/cli/plugin-cli.ts

@@ -5,7 +5,7 @@
  */
 
 import chalk from "chalk";
-import { PluginManager, parseSettingValue, validateSetting } from "../core/plugins/index.js";
+import { PluginManager, parseSettingValue, validateSetting } from "../core/plugins/index";
 
 // =============================================================================
 // Types

package/src/cli/session-picker.ts

@@ -3,8 +3,8 @@
  */
 
 import { ProcessTerminal, TUI } from "@oh-my-pi/pi-tui";
-import type { SessionInfo } from "../core/session-manager.js";
-import { SessionSelectorComponent } from "../modes/interactive/components/session-selector.js";
+import type { SessionInfo } from "../core/session-manager";
+import { SessionSelectorComponent } from "../modes/interactive/components/session-selector";
 
 /** Show TUI session selector and return selected session path or null if cancelled */
 export async function selectSession(sessions: SessionInfo[]): Promise<string | null> {

package/src/cli.ts

@@ -5,6 +5,6 @@
  *
  * Test with: npx tsx src/cli-new.ts [args...]
  */
-import { main } from "./main.js";
+import { main } from "./main";
 
 main(process.argv.slice(2));

package/src/config.ts

@@ -1,6 +1,6 @@
-import { existsSync, readFileSync } from "fs";
-import { homedir } from "os";
-import { dirname, join, resolve } from "path";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
 
 // =============================================================================
 // Package Detection

package/src/core/agent-session.ts

@@ -16,8 +16,8 @@
 import type { Agent, AgentEvent, AgentMessage, AgentState, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { AssistantMessage, ImageContent, Message, Model, TextContent } from "@oh-my-pi/pi-ai";
 import { isContextOverflow, modelsAreEqual, supportsXhigh } from "@oh-my-pi/pi-ai";
-import { getAuthPath } from "../config.js";
-import { type BashResult, executeBash as executeBashCommand } from "./bash-executor.js";
+import { getAuthPath } from "../config";
+import { type BashResult, executeBash as executeBashCommand } from "./bash-executor";
 import {
 	type CompactionResult,
 	calculateContextTokens,
@@ -26,9 +26,11 @@ import {
 	generateBranchSummary,
 	prepareCompaction,
 	shouldCompact,
-} from "./compaction/index.js";
-import type { CustomToolContext, CustomToolSessionEvent, LoadedCustomTool } from "./custom-tools/index.js";
-import { exportSessionToHtml } from "./export-html/index.js";
+} from "./compaction/index";
+import type { LoadedCustomCommand } from "./custom-commands/index";
+import type { CustomToolContext, CustomToolSessionEvent, LoadedCustomTool } from "./custom-tools/index";
+import { exportSessionToHtml } from "./export-html/index";
+import { extractFileMentions, generateFileMentionMessages } from "./file-mentions";
 import type {
 	HookRunner,
 	SessionBeforeBranchResult,
@@ -38,12 +40,13 @@ import type {
 	TreePreparation,
 	TurnEndEvent,
 	TurnStartEvent,
-} from "./hooks/index.js";
-import type { BashExecutionMessage, HookMessage } from "./messages.js";
-import type { ModelRegistry } from "./model-registry.js";
-import type { BranchSummaryEntry, CompactionEntry, NewSessionOptions, SessionManager } from "./session-manager.js";
-import type { SettingsManager, SkillsSettings } from "./settings-manager.js";
-import { expandSlashCommand, type FileSlashCommand } from "./slash-commands.js";
+} from "./hooks/index";
+import { logger } from "./logger";
+import type { BashExecutionMessage, HookMessage } from "./messages";
+import type { ModelRegistry } from "./model-registry";
+import type { BranchSummaryEntry, CompactionEntry, NewSessionOptions, SessionManager } from "./session-manager";
+import type { SettingsManager, SkillsSettings } from "./settings-manager";
+import { expandSlashCommand, type FileSlashCommand, parseCommandArgs } from "./slash-commands";
 
 /** Session-specific events that extend the core AgentEvent */
 export type AgentSessionEvent =
@@ -72,6 +75,8 @@ export interface AgentSessionConfig {
 	hookRunner?: HookRunner;
 	/** Custom tools for session lifecycle events */
 	customTools?: LoadedCustomTool[];
+	/** Custom commands (TypeScript slash commands) */
+	customCommands?: LoadedCustomCommand[];
 	skillsSettings?: Required<SkillsSettings>;
 	/** Model registry for API key resolution and model discovery */
 	modelRegistry: ModelRegistry;
@@ -166,6 +171,9 @@ export class AgentSession {
 	// Custom tools for session lifecycle
 	private _customTools: LoadedCustomTool[] = [];
 
+	// Custom commands (TypeScript slash commands)
+	private _customCommands: LoadedCustomCommand[] = [];
+
 	private _skillsSettings: Required<SkillsSettings> | undefined;
 
 	// Model registry for API key resolution
@@ -179,6 +187,7 @@ export class AgentSession {
 		this._fileCommands = config.fileCommands ?? [];
 		this._hookRunner = config.hookRunner;
 		this._customTools = config.customTools ?? [];
+		this._customCommands = config.customCommands ?? [];
 		this._skillsSettings = config.skillsSettings;
 		this._modelRegistry = config.modelRegistry;
 
@@ -198,7 +207,9 @@ export class AgentSession {
 
 	/** Emit an event to all listeners */
 	private _emit(event: AgentSessionEvent): void {
-		for (const l of this._eventListeners) {
+		// Copy array before iteration to avoid mutation during iteration
+		const listeners = [...this._eventListeners];
+		for (const l of listeners) {
 			l(event);
 		}
 	}
@@ -449,6 +460,11 @@ export class AgentSession {
 		return this._fileCommands;
 	}
 
+	/** Custom commands (TypeScript slash commands) */
+	get customCommands(): ReadonlyArray<LoadedCustomCommand> {
+		return this._customCommands;
+	}
+
 	// =========================================================================
 	// Prompting
 	// =========================================================================
@@ -473,6 +489,17 @@ export class AgentSession {
 				// Hook command executed, no prompt to send
 				return;
 			}
+
+			// Try custom commands (TypeScript slash commands)
+			const customResult = await this._tryExecuteCustomCommand(text);
+			if (customResult !== null) {
+				if (customResult === "") {
+					// Command handled, nothing to send
+					return;
+				}
+				// Command returned a prompt - use it instead of the original text
+				text = customResult;
+			}
 		}
 
 		// Validate model
@@ -516,6 +543,13 @@ export class AgentSession {
 			timestamp: Date.now(),
 		});
 
+		// Auto-read @filepath mentions
+		const fileMentions = extractFileMentions(expandedText);
+		if (fileMentions.length > 0) {
+			const fileMentionMessages = await generateFileMentionMessages(fileMentions, this.sessionManager.getCwd());
+			messages.push(...fileMentionMessages);
+		}
+
 		// Emit before_agent_start hook event
 		if (this._hookRunner) {
 			const result = await this._hookRunner.emitBeforeAgentStart(expandedText, options?.images);
@@ -566,6 +600,43 @@ export class AgentSession {
 		}
 	}
 
+	/**
+	 * Try to execute a custom command. Returns the prompt string if found, null otherwise.
+	 * If the command returns void, returns empty string to indicate it was handled.
+	 */
+	private async _tryExecuteCustomCommand(text: string): Promise<string | null> {
+		if (this._customCommands.length === 0) return null;
+		if (!this._hookRunner) return null; // Need hook runner for command context
+
+		// Parse command name and args
+		const spaceIndex = text.indexOf(" ");
+		const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+		const argsString = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1);
+
+		// Find matching command
+		const loaded = this._customCommands.find((c) => c.command.name === commandName);
+		if (!loaded) return null;
+
+		// Get command context from hook runner (includes session control methods)
+		const ctx = this._hookRunner.createCommandContext();
+
+		try {
+			const args = parseCommandArgs(argsString);
+			const result = await loaded.command.execute(args, ctx);
+			// If result is a string, it's a prompt to send to LLM
+			// If void/undefined, command handled everything
+			return result ?? "";
+		} catch (err) {
+			// Emit error via hook runner
+			this._hookRunner.emitError({
+				hookPath: `custom-command:${commandName}`,
+				event: "command",
+				error: err instanceof Error ? err.message : String(err),
+			});
+			return ""; // Command was handled (with error)
+		}
+	}
+
 	/**
 	 * Queue a message to be sent after the current response completes.
 	 * Use when agent is currently streaming.
@@ -1058,6 +1129,10 @@ export class AgentSession {
 		const settings = this.settingsManager.getCompactionSettings();
 
 		this._emit({ type: "auto_compaction_start", reason });
+		// Properly abort and null existing controller before replacing
+		if (this._autoCompactionAbortController) {
+			this._autoCompactionAbortController.abort();
+		}
 		this._autoCompactionAbortController = new AbortController();
 
 		try {
@@ -1231,7 +1306,8 @@ export class AgentSession {
 		this._retryAttempt++;
 
 		// Create retry promise on first attempt so waitForRetry() can await it
-		if (this._retryAttempt === 1 && !this._retryPromise) {
+		// Ensure only one promise exists (avoid orphaned promises from concurrent calls)
+		if (!this._retryPromise) {
 			this._retryPromise = new Promise((resolve) => {
 				this._retryResolve = resolve;
 			});
@@ -1267,6 +1343,10 @@ export class AgentSession {
 		}
 
 		// Wait with exponential backoff (abortable)
+		// Properly abort and null existing controller before replacing
+		if (this._retryAbortController) {
+			this._retryAbortController.abort();
+		}
 		this._retryAbortController = new AbortController();
 		try {
 			await this._sleep(delayMs, this._retryAbortController.signal);
@@ -1858,6 +1938,68 @@ export class AgentSession {
 		return text.trim() || undefined;
 	}
 
+	/**
+	 * Format the entire session as plain text for clipboard export.
+	 * Includes user messages, assistant text, thinking blocks, tool calls, and tool results.
+	 */
+	formatSessionAsText(): string {
+		const lines: string[] = [];
+
+		for (const msg of this.messages) {
+			if (msg.role === "user") {
+				lines.push("## User\n");
+				if (typeof msg.content === "string") {
+					lines.push(msg.content);
+				} else {
+					for (const c of msg.content) {
+						if (c.type === "text") {
+							lines.push(c.text);
+						} else if (c.type === "image") {
+							lines.push("[Image]");
+						}
+					}
+				}
+				lines.push("\n");
+			} else if (msg.role === "assistant") {
+				const assistantMsg = msg as AssistantMessage;
+				lines.push("## Assistant\n");
+
+				for (const c of assistantMsg.content) {
+					if (c.type === "text") {
+						lines.push(c.text);
+					} else if (c.type === "thinking") {
+						lines.push("<thinking>");
+						lines.push(c.thinking);
+						lines.push("</thinking>\n");
+					} else if (c.type === "toolCall") {
+						lines.push(`### Tool: ${c.name}`);
+						lines.push("```json");
+						lines.push(JSON.stringify(c.arguments, null, 2));
+						lines.push("```\n");
+					}
+				}
+				lines.push("");
+			} else if (msg.role === "toolResult") {
+				lines.push(`### Tool Result: ${msg.toolName}`);
+				if (msg.isError) {
+					lines.push("(error)");
+				}
+				for (const c of msg.content) {
+					if (c.type === "text") {
+						lines.push("```");
+						lines.push(c.text);
+						lines.push("```");
+					} else if (c.type === "image") {
+						lines.push("[Image output]");
+					}
+				}
+				lines.push("");
+			}
+		}
+
+		return lines.join("\n").trim();
+	}
+
 	// =========================================================================
 	// Hook System
 	// =========================================================================
@@ -1909,8 +2051,8 @@ export class AgentSession {
 			if (tool.onSession) {
 				try {
 					await tool.onSession(event, ctx);
-				} catch (_err) {
-					// Silently ignore tool errors during session events
+				} catch (err) {
+					logger.warn("Tool onSession error", { error: String(err) });
 				}
 			}
 		}

package/src/core/bash-executor.ts

@@ -11,14 +11,19 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Subprocess } from "bun";
 import stripAnsi from "strip-ansi";
-import { getShellConfig, killProcessTree, sanitizeBinaryOutput } from "../utils/shell.js";
-import { DEFAULT_MAX_BYTES, truncateTail } from "./tools/truncate.js";
+import { getShellConfig, killProcessTree, sanitizeBinaryOutput } from "../utils/shell";
+import { getOrCreateSnapshot, getSnapshotSourceCommand } from "../utils/shell-snapshot";
+import { DEFAULT_MAX_BYTES, truncateTail } from "./tools/truncate";
 
 // ============================================================================
 // Types
 // ============================================================================
 
 export interface BashExecutorOptions {
+	/** Working directory for command execution */
+	cwd?: string;
+	/** Timeout in milliseconds */
+	timeout?: number;
 	/** Callback for streaming output chunks (already sanitized) */
 	onChunk?: (chunk: string) => void;
 	/** AbortSignal for cancellation */
@@ -56,13 +61,24 @@ export interface BashResult {
  * @param options - Optional streaming callback and abort signal
  * @returns Promise resolving to execution result
  */
-export function executeBash(command: string, options?: BashExecutorOptions): Promise<BashResult> {
+export async function executeBash(command: string, options?: BashExecutorOptions): Promise<BashResult> {
+	const { shell, args, env, prefix } = getShellConfig();
+
+	// Get or create shell snapshot (for aliases, functions, options)
+	const snapshotPath = await getOrCreateSnapshot(shell, env);
+	const snapshotPrefix = getSnapshotSourceCommand(snapshotPath);
+
+	// Build final command: snapshot + prefix + command
+	const prefixedCommand = prefix ? `${prefix} ${command}` : command;
+	const finalCommand = `${snapshotPrefix}${prefixedCommand}`;
+
 	return new Promise((resolve, reject) => {
-		const { shell, args } = getShellConfig();
-		const child: Subprocess = Bun.spawn([shell, ...args, command], {
+		const child: Subprocess = Bun.spawn([shell, ...args, finalCommand], {
+			cwd: options?.cwd,
 			stdin: "ignore",
 			stdout: "pipe",
 			stderr: "pipe",
+			env,
 		});
 
 		// Track sanitized output for truncation
@@ -74,16 +90,27 @@ export function executeBash(command: string, options?: BashExecutorOptions): Pro
 		let tempFilePath: string | undefined;
 		let tempFileStream: WriteStream | undefined;
 		let totalBytes = 0;
+		let timedOut = false;
 
-		// Handle abort signal
+		// Handle abort signal and timeout
 		const abortHandler = () => {
 			killProcessTree(child.pid);
 		};
 
+		// Set up timeout if specified
+		let timeoutHandle: Timer | undefined;
+		if (options?.timeout && options.timeout > 0) {
+			timeoutHandle = setTimeout(() => {
+				timedOut = true;
+				abortHandler();
+			}, options.timeout);
+		}
+
 		if (options?.signal) {
 			if (options.signal.aborted) {
 				// Already aborted, don't even start
 				child.kill();
+				if (timeoutHandle) clearTimeout(timeoutHandle);
 				resolve({
 					output: "",
 					exitCode: undefined,
@@ -156,11 +183,11 @@ export function executeBash(command: string, options?: BashExecutorOptions): Pro
 
 				const exitCode = await child.exited;
 
-				// Clean up abort listener
+				// Clean up
+				if (timeoutHandle) clearTimeout(timeoutHandle);
 				if (options?.signal) {
 					options.signal.removeEventListener("abort", abortHandler);
 				}
-
 				if (tempFileStream) {
 					tempFileStream.end();
 				}
@@ -169,6 +196,19 @@ export function executeBash(command: string, options?: BashExecutorOptions): Pro
 				const fullOutput = outputChunks.join("");
 				const truncationResult = truncateTail(fullOutput);
 
+				// Handle timeout
+				if (timedOut) {
+					const timeoutSecs = Math.round((options?.timeout || 0) / 1000);
+					resolve({
+						output: `${fullOutput}\n\nCommand timed out after ${timeoutSecs} seconds`,
+						exitCode: undefined,
+						cancelled: true,
+						truncated: truncationResult.truncated,
+						fullOutputPath: tempFilePath,
+					});
+					return;
+				}
+
 				// Non-zero exit codes or signal-killed processes are considered cancelled if killed via signal
 				const cancelled = exitCode === null || (exitCode !== 0 && (options?.signal?.aborted ?? false));
 
@@ -180,11 +220,11 @@ export function executeBash(command: string, options?: BashExecutorOptions): Pro
 					fullOutputPath: tempFilePath,
 				});
 			} catch (err) {
-				// Clean up abort listener
+				// Clean up
+				if (timeoutHandle) clearTimeout(timeoutHandle);
 				if (options?.signal) {
 					options.signal.removeEventListener("abort", abortHandler);
 				}
-
 				if (tempFileStream) {
 					tempFileStream.end();
 				}