feat(coding-agent): add user_bash event and theme API extensions

- user_bash event for intercepting ! and !! commands (#528)
- Extensions can return { operations } or { result } to redirect/replace
- executeBashWithOperations() for custom BashOperations execution
- session.recordBashResult() for extensions handling bash themselves
- Theme API: getAllThemes(), getTheme(), setTheme() on ctx.ui
- mac-system-theme.ts example: sync with macOS dark/light mode
- Updated ssh.ts to use user_bash event

packages/coding-agent/src/core/agent-session.ts

@@ -24,7 +24,7 @@ import type {
 import type { AssistantMessage, ImageContent, Message, Model, TextContent } from "@mariozechner/pi-ai";
 import { isContextOverflow, modelsAreEqual, supportsXhigh } from "@mariozechner/pi-ai";
 import { getAuthPath } from "../config.js";
-import { type BashResult, executeBash as executeBashCommand } from "./bash-executor.js";
+import { type BashResult, executeBash as executeBashCommand, executeBashWithOperations } from "./bash-executor.js";
 import {
 	type CompactionResult,
 	calculateContextTokens,
@@ -50,6 +50,7 @@ import type { ModelRegistry } from "./model-registry.js";
 import { expandPromptTemplate, type PromptTemplate } from "./prompt-templates.js";
 import type { BranchSummaryEntry, CompactionEntry, NewSessionOptions, SessionManager } from "./session-manager.js";
 import type { SettingsManager, SkillsSettings } from "./settings-manager.js";
+import type { BashOperations } from "./tools/bash.js";
 
 /** Session-specific events that extend the core AgentEvent */
 export type AgentSessionEvent =
@@ -1617,51 +1618,63 @@ export class AgentSession {
 	 * @param command The bash command to execute
 	 * @param onChunk Optional streaming callback for output
 	 * @param options.excludeFromContext If true, command output won't be sent to LLM (!! prefix)
+	 * @param options.operations Custom BashOperations for remote execution
 	 */
 	async executeBash(
 		command: string,
 		onChunk?: (chunk: string) => void,
-		options?: { excludeFromContext?: boolean },
+		options?: { excludeFromContext?: boolean; operations?: BashOperations },
 	): Promise<BashResult> {
 		this._bashAbortController = new AbortController();
 
 		try {
-			const result = await executeBashCommand(command, {
-				onChunk,
-				signal: this._bashAbortController.signal,
-			});
-
-			// Create and save message
-			const bashMessage: BashExecutionMessage = {
-				role: "bashExecution",
-				command,
-				output: result.output,
-				exitCode: result.exitCode,
-				cancelled: result.cancelled,
-				truncated: result.truncated,
-				fullOutputPath: result.fullOutputPath,
-				timestamp: Date.now(),
-				excludeFromContext: options?.excludeFromContext,
-			};
-
-			// If agent is streaming, defer adding to avoid breaking tool_use/tool_result ordering
-			if (this.isStreaming) {
-				// Queue for later - will be flushed on agent_end
-				this._pendingBashMessages.push(bashMessage);
-			} else {
-				// Add to agent state immediately
-				this.agent.appendMessage(bashMessage);
-
-				// Save to session
-				this.sessionManager.appendMessage(bashMessage);
-			}
+			const result = options?.operations
+				? await executeBashWithOperations(command, process.cwd(), options.operations, {
+						onChunk,
+						signal: this._bashAbortController.signal,
+					})
+				: await executeBashCommand(command, {
+						onChunk,
+						signal: this._bashAbortController.signal,
+					});
 
+			this.recordBashResult(command, result, options);
 			return result;
 		} finally {
 			this._bashAbortController = undefined;
 		}
 	}
 
+	/**
+	 * Record a bash execution result in session history.
+	 * Used by executeBash and by extensions that handle bash execution themselves.
+	 */
+	recordBashResult(command: string, result: BashResult, options?: { excludeFromContext?: boolean }): void {
+		const bashMessage: BashExecutionMessage = {
+			role: "bashExecution",
+			command,
+			output: result.output,
+			exitCode: result.exitCode,
+			cancelled: result.cancelled,
+			truncated: result.truncated,
+			fullOutputPath: result.fullOutputPath,
+			timestamp: Date.now(),
+			excludeFromContext: options?.excludeFromContext,
+		};
+
+		// If agent is streaming, defer adding to avoid breaking tool_use/tool_result ordering
+		if (this.isStreaming) {
+			// Queue for later - will be flushed on agent_end
+			this._pendingBashMessages.push(bashMessage);
+		} else {
+			// Add to agent state immediately
+			this.agent.appendMessage(bashMessage);
+
+			// Save to session
+			this.sessionManager.appendMessage(bashMessage);
+		}
+	}
+
 	/**
 	 * Cancel running bash command.
 	 */

packages/coding-agent/src/core/bash-executor.ts

@@ -13,6 +13,7 @@ import { join } from "node:path";
 import { type ChildProcess, spawn } from "child_process";
 import stripAnsi from "strip-ansi";
 import { getShellConfig, killProcessTree, sanitizeBinaryOutput } from "../utils/shell.js";
+import type { BashOperations } from "./tools/bash.js";
 import { DEFAULT_MAX_BYTES, truncateTail } from "./tools/truncate.js";
 
 // ============================================================================
@@ -177,3 +178,98 @@ export function executeBash(command: string, options?: BashExecutorOptions): Pro
 		});
 	});
 }
+
+/**
+ * Execute a bash command using custom BashOperations.
+ * Used for remote execution (SSH, containers, etc.).
+ */
+export async function executeBashWithOperations(
+	command: string,
+	cwd: string,
+	operations: BashOperations,
+	options?: BashExecutorOptions,
+): Promise<BashResult> {
+	const outputChunks: string[] = [];
+	let outputBytes = 0;
+	const maxOutputBytes = DEFAULT_MAX_BYTES * 2;
+
+	let tempFilePath: string | undefined;
+	let tempFileStream: WriteStream | undefined;
+	let totalBytes = 0;
+
+	const onData = (data: Buffer) => {
+		totalBytes += data.length;
+
+		// Sanitize: strip ANSI, replace binary garbage, normalize newlines
+		const text = sanitizeBinaryOutput(stripAnsi(data.toString("utf-8"))).replace(/\r/g, "");
+
+		// Start writing to temp file if exceeds threshold
+		if (totalBytes > DEFAULT_MAX_BYTES && !tempFilePath) {
+			const id = randomBytes(8).toString("hex");
+			tempFilePath = join(tmpdir(), `pi-bash-${id}.log`);
+			tempFileStream = createWriteStream(tempFilePath);
+			for (const chunk of outputChunks) {
+				tempFileStream.write(chunk);
+			}
+		}
+
+		if (tempFileStream) {
+			tempFileStream.write(text);
+		}
+
+		// Keep rolling buffer
+		outputChunks.push(text);
+		outputBytes += text.length;
+		while (outputBytes > maxOutputBytes && outputChunks.length > 1) {
+			const removed = outputChunks.shift()!;
+			outputBytes -= removed.length;
+		}
+
+		// Stream to callback
+		if (options?.onChunk) {
+			options.onChunk(text);
+		}
+	};
+
+	try {
+		const result = await operations.exec(command, cwd, {
+			onData,
+			signal: options?.signal,
+		});
+
+		if (tempFileStream) {
+			tempFileStream.end();
+		}
+
+		const fullOutput = outputChunks.join("");
+		const truncationResult = truncateTail(fullOutput);
+		const cancelled = options?.signal?.aborted ?? false;
+
+		return {
+			output: truncationResult.truncated ? truncationResult.content : fullOutput,
+			exitCode: cancelled ? undefined : (result.exitCode ?? undefined),
+			cancelled,
+			truncated: truncationResult.truncated,
+			fullOutputPath: tempFilePath,
+		};
+	} catch (err) {
+		if (tempFileStream) {
+			tempFileStream.end();
+		}
+
+		// Check if it was an abort
+		if (options?.signal?.aborted) {
+			const fullOutput = outputChunks.join("");
+			const truncationResult = truncateTail(fullOutput);
+			return {
+				output: truncationResult.truncated ? truncationResult.content : fullOutput,
+				exitCode: undefined,
+				cancelled: true,
+				truncated: truncationResult.truncated,
+				fullOutputPath: tempFilePath,
+			};
+		}
+
+		throw err;
+	}
+}

packages/coding-agent/src/core/extensions/index.ts

@@ -103,6 +103,9 @@ export type {
 	TreePreparation,
 	TurnEndEvent,
 	TurnStartEvent,
+	// Events - User Bash
+	UserBashEvent,
+	UserBashEventResult,
 	WriteToolResultEvent,
 } from "./types.js";
 // Type guards

packages/coding-agent/src/core/extensions/runner.ts

@@ -5,7 +5,7 @@
 import type { AgentMessage } from "@mariozechner/pi-agent-core";
 import type { ImageContent, Model } from "@mariozechner/pi-ai";
 import type { KeyId } from "@mariozechner/pi-tui";
-import { theme } from "../../modes/interactive/theme/theme.js";
+import { type Theme, theme } from "../../modes/interactive/theme/theme.js";
 import type { ModelRegistry } from "../model-registry.js";
 import type { SessionManager } from "../session-manager.js";
 import type {
@@ -33,6 +33,8 @@ import type {
 	ToolCallEvent,
 	ToolCallEventResult,
 	ToolResultEventResult,
+	UserBashEvent,
+	UserBashEventResult,
 } from "./types.js";
 
 /** Combined result from all before_agent_start handlers */
@@ -89,6 +91,9 @@ const noOpUIContext: ExtensionUIContext = {
 	get theme() {
 		return theme;
 	},
+	getAllThemes: () => [],
+	getTheme: () => undefined,
+	setTheme: (_theme: string | Theme) => ({ success: false, error: "UI not available" }),
 };
 
 export class ExtensionRunner {
@@ -399,6 +404,35 @@ export class ExtensionRunner {
 		return result;
 	}
 
+	async emitUserBash(event: UserBashEvent): Promise<UserBashEventResult | undefined> {
+		const ctx = this.createContext();
+
+		for (const ext of this.extensions) {
+			const handlers = ext.handlers.get("user_bash");
+			if (!handlers || handlers.length === 0) continue;
+
+			for (const handler of handlers) {
+				try {
+					const handlerResult = await handler(event, ctx);
+					if (handlerResult) {
+						return handlerResult as UserBashEventResult;
+					}
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					const stack = err instanceof Error ? err.stack : undefined;
+					this.emitError({
+						extensionPath: ext.path,
+						event: "user_bash",
+						error: message,
+						stack,
+					});
+				}
+			}
+		}
+
+		return undefined;
+	}
+
 	async emitContext(messages: AgentMessage[]): Promise<AgentMessage[]> {
 		const ctx = this.createContext();
 		let currentMessages = structuredClone(messages);

packages/coding-agent/src/core/extensions/types.ts

@@ -18,6 +18,7 @@ import type { ImageContent, Model, TextContent, ToolResultMessage } from "@mario
 import type { Component, EditorComponent, EditorTheme, KeyId, TUI } from "@mariozechner/pi-tui";
 import type { Static, TSchema } from "@sinclair/typebox";
 import type { Theme } from "../../modes/interactive/theme/theme.js";
+import type { BashResult } from "../bash-executor.js";
 import type { CompactionPreparation, CompactionResult } from "../compaction/index.js";
 import type { EventBus } from "../event-bus.js";
 import type { ExecOptions, ExecResult } from "../exec.js";
@@ -31,6 +32,7 @@ import type {
 	SessionEntry,
 	SessionManager,
 } from "../session-manager.js";
+import type { BashOperations } from "../tools/bash.js";
 import type { EditToolDetails } from "../tools/edit.js";
 import type {
 	BashToolDetails,
@@ -147,6 +149,15 @@ export interface ExtensionUIContext {
 
 	/** Get the current theme for styling. */
 	readonly theme: Theme;
+
+	/** Get all available themes with their names and file paths. */
+	getAllThemes(): { name: string; path: string | undefined }[];
+
+	/** Load a theme by name without switching to it. Returns undefined if not found. */
+	getTheme(name: string): Theme | undefined;
+
+	/** Set the current theme by name or Theme object. */
+	setTheme(theme: string | Theme): { success: boolean; error?: string };
 }
 
 // ============================================================================
@@ -378,6 +389,21 @@ export interface TurnEndEvent {
 	toolResults: ToolResultMessage[];
 }
 
+// ============================================================================
+// User Bash Events
+// ============================================================================
+
+/** Fired when user executes a bash command via ! or !! prefix */
+export interface UserBashEvent {
+	type: "user_bash";
+	/** The command to execute */
+	command: string;
+	/** True if !! prefix was used (excluded from LLM context) */
+	excludeFromContext: boolean;
+	/** Current working directory */
+	cwd: string;
+}
+
 // ============================================================================
 // Tool Events
 // ============================================================================
@@ -481,6 +507,7 @@ export type ExtensionEvent =
 	| AgentEndEvent
 	| TurnStartEvent
 	| TurnEndEvent
+	| UserBashEvent
 	| ToolCallEvent
 	| ToolResultEvent;
 
@@ -497,6 +524,14 @@ export interface ToolCallEventResult {
 	reason?: string;
 }
 
+/** Result from user_bash event handler */
+export interface UserBashEventResult {
+	/** Custom operations to use for execution */
+	operations?: BashOperations;
+	/** Full replacement: extension handled execution, use this result */
+	result?: BashResult;
+}
+
 export interface ToolResultEventResult {
 	content?: (TextContent | ImageContent)[];
 	details?: unknown;
@@ -598,6 +633,7 @@ export interface ExtensionAPI {
 	on(event: "turn_end", handler: ExtensionHandler<TurnEndEvent>): void;
 	on(event: "tool_call", handler: ExtensionHandler<ToolCallEvent, ToolCallEventResult>): void;
 	on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): void;
+	on(event: "user_bash", handler: ExtensionHandler<UserBashEvent, UserBashEventResult>): void;
 
 	// =========================================================================
 	// Tool Registration

packages/coding-agent/src/core/index.ts

@@ -11,7 +11,7 @@ export {
 	type PromptOptions,
 	type SessionStats,
 } from "./agent-session.js";
-export { type BashExecutorOptions, type BashResult, executeBash } from "./bash-executor.js";
+export { type BashExecutorOptions, type BashResult, executeBash, executeBashWithOperations } from "./bash-executor.js";
 export type { CompactionResult } from "./compaction/index.js";
 export { createEventBus, type EventBus, type EventBusController } from "./event-bus.js";