feat(coding-agent): intercept bash execution

Author: mitsuhiko

packages/coding-agent/CHANGELOG.md

@@ -13,6 +13,7 @@
 - Extension package management with `pi install`, `pi remove`, `pi update`, and `pi list` commands ([#645](https://github.com/badlogic/pi-mono/issues/645))
 - `/reload` command to reload extensions, skills, prompts, and themes ([#645](https://github.com/badlogic/pi-mono/issues/645))
 - CLI flags for `--skill`, `--prompt-template`, `--theme`, `--no-prompt-templates`, and `--no-themes` ([#645](https://github.com/badlogic/pi-mono/issues/645))
+- `tool_result` handlers can return `errorMessage` to override tool errors or force a failure
 
 ### Changed
 

packages/coding-agent/README.md

@@ -1101,7 +1101,23 @@ export default function (pi: ExtensionAPI) {
   pi.on("tool_result", async (event, ctx) => {
     if (event.toolName === "read") {
       // Redact secrets from file contents
-      return { modifiedResult: event.result.replace(/API_KEY=\w+/g, "API_KEY=***") };
+      return {
+        content: event.content.map((item) =>
+          item.type === "text"
+            ? { ...item, text: item.text.replace(/API_KEY=\w+/g, "API_KEY=***") }
+            : item
+        ),
+      };
+    }
+
+    if (event.isError) {
+      // Override the thrown error message (optional)
+      return { errorMessage: "Custom error message" };
+    }
+
+    if (event.toolName === "bash" && event.content.length > 0) {
+      // Force a successful tool to be treated as an error
+      return { errorMessage: "Tool output rejected by policy" };
     }
   });
 

packages/coding-agent/docs/extensions.md

@@ -549,9 +549,34 @@ pi.on("tool_call", async (event, ctx) => {
 
 **Examples:** [chalk-logger.ts](../examples/extensions/chalk-logger.ts), [permission-gate.ts](../examples/extensions/permission-gate.ts), [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts), [protected-paths.ts](../examples/extensions/protected-paths.ts)
 
+#### before_bash_exec
+
+Fired before a bash command executes (tool calls and user `!`/`!!`). Use it to rewrite commands or override execution settings. You can also block execution by returning `{ block: true, reason?: string }`. For follow-up hints based on output, pair this with `tool_result`.
+
+```typescript
+pi.on("before_bash_exec", async (event) => {
+  if (event.command.includes("rm -rf")) {
+    return { block: true, reason: "Blocked by policy" };
+  }
+
+  if (event.source === "tool") {
+    return {
+      cwd: "/tmp",
+      env: {
+        ...event.env,
+        MY_VAR: "1",
+        PATH: undefined, // remove PATH
+      },
+    };
+  }
+});
+```
+
+Return a `BashExecOverrides` object to override fields, or return `{ block: true, reason?: string }` to reject the command. Any field set to a non-undefined value replaces the original (`command`, `cwd`, `env`, `shell`, `args`, `timeout`). For `env`, set a key to `undefined` to remove it.
+
 #### tool_result
 
-Fired after tool executes. **Can modify result.**
+Fired after tool executes. **Can modify result.** Use this to post-process outputs (for example, append hints or redact secrets) before the result is sent to the model.
 
 ```typescript
 import { isBashToolResult } from "@mariozechner/pi-coding-agent";
@@ -565,10 +590,12 @@ pi.on("tool_result", async (event, ctx) => {
   }
 
   // Modify result:
-  return { content: [...], details: {...}, isError: false };
+  return { content: [...], details: {...} };
 });
 ```
 
+If `event.isError` is true, return `{ errorMessage: "..." }` to override the thrown error message (optionally alongside `content`). Returning `errorMessage` on a successful tool result forces the tool to be treated as an error.
+
 **Examples:** [git-checkpoint.ts](../examples/extensions/git-checkpoint.ts), [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts)
 
 ### User Bash Events

packages/coding-agent/examples/extensions/uv.ts

@@ -0,0 +1,76 @@
+/**
+ * uv Python Interceptor
+ *
+ * Demonstrates before_bash_exec by redirecting python invocations through uv.
+ * This is a simple example that assumes basic whitespace-separated arguments.
+ *
+ * Usage:
+ *   pi -e examples/extensions/uv.ts
+ */
+
+import { type ExtensionAPI, isBashToolResult } from "@mariozechner/pi-coding-agent";
+
+const PYTHON_PREFIX = /^python3?(\s+|$)/;
+const UV_RUN_PYTHON_PREFIX = /^uv\s+run\s+python3?(\s+|$)/;
+const PIP_PREFIX = /^pip3?(\s+|$)/;
+const PIP_MODULE_PATTERN = /\s-m\s+pip3?(\s|$)/;
+const TRACEBACK_PATTERN = /Traceback \(most recent call last\):/;
+const IMPORT_ERROR_PATTERN = /\b(ModuleNotFoundError|ImportError):/;
+const MODULE_NOT_FOUND_PATTERN = /No module named ['"]([^'"]+)['"]/;
+
+const PIP_BLOCK_REASON =
+	"pip is disabled. Use uv run instead, particularly --with and --script for throwaway work. Do not use uv pip!";
+
+export default function (pi: ExtensionAPI) {
+	pi.on("before_bash_exec", (event) => {
+		const trimmed = event.originalCommand.trim();
+		const isPythonCommand = PYTHON_PREFIX.test(trimmed);
+		const isUvRunPythonCommand = UV_RUN_PYTHON_PREFIX.test(trimmed);
+		const isPipModule = PIP_MODULE_PATTERN.test(trimmed);
+
+		if (PIP_PREFIX.test(trimmed) || (isPipModule && (isPythonCommand || isUvRunPythonCommand))) {
+			return {
+				block: true,
+				reason: PIP_BLOCK_REASON,
+			};
+		}
+
+		if (!isPythonCommand) {
+			return;
+		}
+
+		const normalizedCommand = trimmed.replace(PYTHON_PREFIX, "python ").trimEnd();
+		const uvCommand = `uv run ${normalizedCommand}`;
+
+		return {
+			command: uvCommand,
+		};
+	});
+
+	pi.on("tool_result", (event) => {
+		if (!isBashToolResult(event)) return;
+
+		const text = event.content
+			.filter((item) => item.type === "text")
+			.map((item) => item.text)
+			.join("");
+
+		if (!TRACEBACK_PATTERN.test(text) || !IMPORT_ERROR_PATTERN.test(text)) {
+			return;
+		}
+
+		const moduleMatch = text.match(MODULE_NOT_FOUND_PATTERN);
+		const moduleName = moduleMatch?.[1];
+		const hintTarget = moduleName ? ` --with ${moduleName}` : "";
+		const hint =
+			"\n\nHint: Python import failed. Consider running with uv to fetch dependencies, " +
+			`e.g. \`uv run${hintTarget} python -c '...'\` or \`uv run --script\` for throwaway scripts.`;
+
+		const message = text + hint;
+
+		return {
+			content: [...event.content, { type: "text", text: hint }],
+			errorMessage: message,
+		};
+	});
+}

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

@@ -27,6 +27,7 @@ import { isContextOverflow, modelsAreEqual, supportsXhigh } from "@mariozechner/
 import { getAuthPath } from "../config.js";
 import { theme } from "../modes/interactive/theme/theme.js";
 import { stripFrontmatter } from "../utils/frontmatter.js";
+import { getShellConfig, getShellEnv } from "../utils/shell.js";
 import { type BashResult, executeBash as executeBashCommand, executeBashWithOperations } from "./bash-executor.js";
 import {
 	type CompactionResult,
@@ -41,6 +42,7 @@ import {
 import { exportSessionToHtml, type ToolHtmlRenderer } from "./export-html/index.js";
 import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
 import {
+	type BeforeBashExecEvent,
 	type ContextUsage,
 	type ExtensionCommandContextActions,
 	type ExtensionErrorListener,
@@ -2018,19 +2020,48 @@ export class AgentSession {
 	): Promise<BashResult> {
 		this._bashAbortController = new AbortController();
 
-		// Apply command prefix if configured (e.g., "shopt -s expand_aliases" for alias support)
-		const prefix = this.settingsManager.getShellCommandPrefix();
-		const resolvedCommand = prefix ? `${prefix}\n${command}` : command;
-
 		try {
+			// Apply command prefix if configured (e.g., "shopt -s expand_aliases" for alias support)
+			const prefix = this.settingsManager.getShellCommandPrefix();
+			const resolvedCommand = prefix ? `${prefix}\n${command}` : command;
+			const shellConfig = getShellConfig();
+			const baseEvent: BeforeBashExecEvent = {
+				type: "before_bash_exec",
+				source: "user_bash",
+				command: resolvedCommand,
+				originalCommand: command,
+				cwd: process.cwd(),
+				env: { ...getShellEnv() },
+				shell: shellConfig.shell,
+				args: [...shellConfig.args],
+			};
+			const execEvent = this._extensionRunner?.hasHandlers("before_bash_exec")
+				? await this._extensionRunner.emitBeforeBashExec(baseEvent)
+				: baseEvent;
+			const execCommand = execEvent.command;
+			const execCwd = execEvent.cwd;
+			const execEnv = execEvent.env;
+			const execShell = execEvent.shell;
+			const execArgs = execEvent.args;
+			const execTimeout = execEvent.timeout;
+
 			const result = options?.operations
-				? await executeBashWithOperations(resolvedCommand, process.cwd(), options.operations, {
+				? await executeBashWithOperations(execCommand, execCwd, options.operations, {
 						onChunk,
 						signal: this._bashAbortController.signal,
+						env: execEnv,
+						shell: execShell,
+						args: execArgs,
+						timeout: execTimeout,
 					})
-				: await executeBashCommand(resolvedCommand, {
+				: await executeBashCommand(execCommand, {
 						onChunk,
 						signal: this._bashAbortController.signal,
+						cwd: execCwd,
+						env: execEnv,
+						shell: execShell,
+						args: execArgs,
+						timeout: execTimeout,
 					});
 
 			this.recordBashResult(command, result, options);

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

@@ -25,6 +25,16 @@ export interface BashExecutorOptions {
 	onChunk?: (chunk: string) => void;
 	/** AbortSignal for cancellation */
 	signal?: AbortSignal;
+	/** Working directory override */
+	cwd?: string;
+	/** Environment override */
+	env?: NodeJS.ProcessEnv;
+	/** Shell executable override */
+	shell?: string;
+	/** Shell argument override */
+	args?: string[];
+	/** Timeout in seconds */
+	timeout?: number;
 }
 
 export interface BashResult {
@@ -60,13 +70,29 @@ export interface BashResult {
  */
 export function executeBash(command: string, options?: BashExecutorOptions): Promise<BashResult> {
 	return new Promise((resolve, reject) => {
-		const { shell, args } = getShellConfig();
-		const child: ChildProcess = spawn(shell, [...args, command], {
+		const shellConfig = getShellConfig();
+		const resolvedShell = options?.shell ?? shellConfig.shell;
+		const resolvedArgs = options?.args ?? shellConfig.args;
+		const resolvedCwd = options?.cwd ?? process.cwd();
+		const resolvedEnv = { ...getShellEnv(), ...(options?.env ?? {}) };
+		const child: ChildProcess = spawn(resolvedShell, [...resolvedArgs, command], {
+			cwd: resolvedCwd,
+			env: resolvedEnv,
 			detached: true,
-			env: getShellEnv(),
 			stdio: ["ignore", "pipe", "pipe"],
 		});
 
+		let timedOut = false;
+		let timeoutHandle: NodeJS.Timeout | undefined;
+		if (options?.timeout !== undefined && options.timeout > 0) {
+			timeoutHandle = setTimeout(() => {
+				timedOut = true;
+				if (child.pid) {
+					killProcessTree(child.pid);
+				}
+			}, options.timeout * 1000);
+		}
+
 		// Track sanitized output for truncation
 		const outputChunks: string[] = [];
 		let outputBytes = 0;
@@ -88,6 +114,9 @@ export function executeBash(command: string, options?: BashExecutorOptions): Pro
 			if (options.signal.aborted) {
 				// Already aborted, don't even start
 				child.kill();
+				if (timeoutHandle) {
+					clearTimeout(timeoutHandle);
+				}
 				resolve({
 					output: "",
 					exitCode: undefined,
@@ -144,6 +173,9 @@ export function executeBash(command: string, options?: BashExecutorOptions): Pro
 			if (options?.signal) {
 				options.signal.removeEventListener("abort", abortHandler);
 			}
+			if (timeoutHandle) {
+				clearTimeout(timeoutHandle);
+			}
 
 			if (tempFileStream) {
 				tempFileStream.end();
@@ -153,8 +185,7 @@ export function executeBash(command: string, options?: BashExecutorOptions): Pro
 			const fullOutput = outputChunks.join("");
 			const truncationResult = truncateTail(fullOutput);
 
-			// code === null means killed (cancelled)
-			const cancelled = code === null;
+			const cancelled = code === null || timedOut;
 
 			resolve({
 				output: truncationResult.truncated ? truncationResult.content : fullOutput,
@@ -170,6 +201,9 @@ export function executeBash(command: string, options?: BashExecutorOptions): Pro
 			if (options?.signal) {
 				options.signal.removeEventListener("abort", abortHandler);
 			}
+			if (timeoutHandle) {
+				clearTimeout(timeoutHandle);
+			}
 
 			if (tempFileStream) {
 				tempFileStream.end();
@@ -238,6 +272,10 @@ export async function executeBashWithOperations(
 		const result = await operations.exec(command, cwd, {
 			onData,
 			signal: options?.signal,
+			timeout: options?.timeout,
+			env: options?.env,
+			shell: options?.shell,
+			args: options?.args,
 		});
 
 		if (tempFileStream) {

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

@@ -25,9 +25,14 @@ export type {
 	// App keybindings (for custom editors)
 	AppAction,
 	AppendEntryHandler,
+	BashExecEvent,
+	BashExecOverrides,
+	BashExecSource,
 	BashToolResultEvent,
 	BeforeAgentStartEvent,
 	BeforeAgentStartEventResult,
+	BeforeBashExecEvent,
+	BeforeBashExecEventResult,
 	// Context
 	CompactOptions,
 	// Events - Agent