pi-bash-bg: stop replacing the bash tool so shellCommandPrefix keeps working

createBashTool(process.cwd()) + pi.registerTool(...) was used to append a
background-job note to the tool description, but the freshly-constructed
bash tool shadowed pi's built-in one in the registry, silently dropping
the shellCommandPrefix, shellPath, and spawnHook that pi wires onto the
built-in tool. Any user with "shellCommandPrefix": "..." in settings
saw their prefix stop running as soon as pi-bash-bg was loaded.

Move the guidance into the system prompt via before_agent_start so the
built-in bash tool is left untouched. Add a changeset.

Author: mgabor3141

.changeset/bash-bg-preserve-command-prefix.md

@@ -0,0 +1,7 @@
+---
+"pi-bash-bg": patch
+---
+
+Stop re-registering the `bash` tool. Previously the extension called `createBashTool(process.cwd())` and `pi.registerTool(...)` to append a background-job note to the tool description. That freshly-constructed tool replaced pi's built-in `bash`, silently dropping the `shellCommandPrefix`, `shellPath`, and any `spawnHook` options pi configures on the built-in tool — so settings like `"shellCommandPrefix": "..."` never ran for any bash invocation once this extension was loaded.
+
+The background-job guidance now goes into the system prompt via a `before_agent_start` hook instead, leaving the built-in bash tool untouched.

packages/bash-bg/README.md

@@ -8,7 +8,7 @@ The bash tool pipes stdout/stderr from the spawned shell. When a command backgro
 
 ## Solution
 
-This extension intercepts bash tool calls, parses the command with [@aliou/sh](https://github.com/nicolo-ribaudo/sh) to detect background processes (`stmt.background === true`), appends background-job guidance to the bash tool description, and rewrites the command to:
+This extension intercepts bash tool calls, parses the command with [@aliou/sh](https://github.com/nicolo-ribaudo/sh) to detect background processes (`stmt.background === true`), appends background-job guidance to the system prompt, and rewrites the command to:
 
 1. **Redirect output** to temp log files with human-readable names based on the command label, so background processes release the pipes
 2. **Add `disown`** to detach from job control (if not already present)
@@ -78,9 +78,9 @@ echo "[bg] pid=$! label=npm start log=/tmp/pi-bg-npm-start-3.log"
 
 If the command already has `disown` after the `&`, no duplicate is added.
 
-### Bash tool description
+### System prompt guidance
 
-The extension appends a short background-job summary to the bash tool description, so the model sees it directly in tool metadata.
+The extension appends a short background-job section to the system prompt via the `before_agent_start` hook, so the model sees how to use `command &`, where to find log files, and how to stop processes. The built-in `bash` tool definition is left untouched so pi's `shellCommandPrefix`, `shellPath`, and any `spawnHook` wiring continue to apply.
 
 ## Supported patterns
 

packages/bash-bg/src/index.ts

@@ -15,23 +15,23 @@
  */
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { createBashTool, isToolCallEventType } from "@mariozechner/pi-coding-agent";
+import { isToolCallEventType } from "@mariozechner/pi-coding-agent";
 import { detectBackground } from "./detect.js";
 import { rewriteCommand } from "./rewrite.js";
 
 export { detectBackground, type BgStatement, type DetectResult } from "./detect.js";
 export { rewriteCommand, findBgOperatorPositions, type BgProcessInfo, type RewriteResult } from "./rewrite.js";
 
-const BASH_DESCRIPTION_APPENDIX =
-	"Background jobs continue running after the command returns. Their output is captured to a log file even without explicit redirection. The PID and log path will be returned.";
+export const BASH_BG_SYSTEM_PROMPT_SECTION = [
+	"## Background jobs (`command &`)",
+	"",
+	"The bash tool supports backgrounding processes with `&`.",
+	"Background process stdout/stderr is captured to a temp log file.",
+	"Each rewritten command reports `[bg] pid=<PID> label=<LABEL> log=<PATH>` in its output.",
+	"Use `cat <PATH>` to check output and `kill <PID>` to stop the process.",
+].join("\n");
 
 export default function (pi: ExtensionAPI) {
-	const bashTool = createBashTool(process.cwd());
-	pi.registerTool({
-		...bashTool,
-		description: `${bashTool.description} ${BASH_DESCRIPTION_APPENDIX}`,
-	});
-
 	pi.on("tool_call", async (event) => {
 		if (!isToolCallEventType("bash", event)) return;
 
@@ -42,4 +42,15 @@ export default function (pi: ExtensionAPI) {
 		const { command: rewritten } = rewriteCommand(command, bgStatements);
 		event.input.command = rewritten;
 	});
+
+	pi.on("before_agent_start", async (event) => {
+		// Inject background-job guidance into the system prompt once per turn.
+		// We avoid re-registering the bash tool because that would drop the
+		// commandPrefix/shellPath/spawnHook options that pi's built-in bash
+		// tool is constructed with, silently breaking `shellCommandPrefix`.
+		if (event.systemPrompt.includes(BASH_BG_SYSTEM_PROMPT_SECTION)) return;
+		return {
+			systemPrompt: `${event.systemPrompt}\n\n${BASH_BG_SYSTEM_PROMPT_SECTION}`,
+		};
+	});
 }

packages/bash-bg/test/index.test.ts

@@ -1,25 +1,82 @@
-import type { ExtensionAPI, ToolDefinition } from "@mariozechner/pi-coding-agent";
-import { describe, expect, it, vi } from "vitest";
-import extension from "../src/index.js";
+import type {
+	BeforeAgentStartEvent,
+	ExtensionAPI,
+	ExtensionHandler,
+	ToolDefinition,
+} from "@mariozechner/pi-coding-agent";
+import { describe, expect, it } from "vitest";
+import extension, { BASH_BG_SYSTEM_PROMPT_SECTION } from "../src/index.js";
+
+type HandlerMap = Map<string, ExtensionHandler<never>[]>;
+
+function makeFakePi(): { pi: ExtensionAPI; handlers: HandlerMap; tools: ToolDefinition[] } {
+	const handlers: HandlerMap = new Map();
+	const tools: ToolDefinition[] = [];
+	const pi = {
+		on(event: string, handler: ExtensionHandler<never>) {
+			const list = handlers.get(event) ?? [];
+			list.push(handler);
+			handlers.set(event, list);
+		},
+		registerTool(tool: ToolDefinition) {
+			tools.push(tool);
+		},
+	} as unknown as ExtensionAPI;
+	return { pi, handlers, tools };
+}
 
 describe("pi-bash-bg extension", () => {
-	it("appends background job guidance to the bash tool description", () => {
-		const tools: ToolDefinition[] = [];
-		const pi = {
-			registerTool(tool) {
-				tools.push(tool);
-			},
-			on: vi.fn(),
-		} as unknown as ExtensionAPI;
+	it("does not re-register the bash tool (preserves pi's commandPrefix/shellPath/spawnHook)", () => {
+		const { pi, tools } = makeFakePi();
+		extension(pi);
+		expect(tools.find((tool) => tool.name === "bash")).toBeUndefined();
+		// The extension must not register any tool; it only hooks events.
+		expect(tools).toHaveLength(0);
+	});
+
+	it("registers tool_call and before_agent_start handlers", () => {
+		const { pi, handlers } = makeFakePi();
+		extension(pi);
+		expect(handlers.get("tool_call")?.length).toBe(1);
+		expect(handlers.get("before_agent_start")?.length).toBe(1);
+	});
 
+	it("appends background-job guidance to the system prompt", async () => {
+		const { pi, handlers } = makeFakePi();
 		extension(pi);
+		const handler = handlers.get("before_agent_start")?.[0];
+		expect(handler).toBeDefined();
+
+		const event: BeforeAgentStartEvent = {
+			type: "before_agent_start",
+			prompt: "hello",
+			systemPrompt: "You are a coding agent.",
+			systemPromptOptions: {} as BeforeAgentStartEvent["systemPromptOptions"],
+		};
+		const result = await (handler as (e: BeforeAgentStartEvent) => Promise<{ systemPrompt?: string } | undefined>)(
+			event,
+		);
 
-		const bashTool = tools.find((tool) => tool.name === "bash");
-		expect(bashTool).toBeDefined();
-		expect(bashTool?.description).toContain("Background jobs continue running after the command returns.");
-		expect(bashTool?.description).toContain(
-			"Their output is captured to a log file even without explicit redirection.",
+		expect(result?.systemPrompt).toBeDefined();
+		expect(result?.systemPrompt).toContain("You are a coding agent.");
+		expect(result?.systemPrompt).toContain(BASH_BG_SYSTEM_PROMPT_SECTION);
+		expect(result?.systemPrompt).toContain("Background jobs (`command &`)");
+		expect(result?.systemPrompt).toContain("[bg] pid=");
+	});
+
+	it("does not duplicate the guidance if it is already present", async () => {
+		const { pi, handlers } = makeFakePi();
+		extension(pi);
+		const handler = handlers.get("before_agent_start")?.[0];
+		const event: BeforeAgentStartEvent = {
+			type: "before_agent_start",
+			prompt: "hello",
+			systemPrompt: `You are a coding agent.\n\n${BASH_BG_SYSTEM_PROMPT_SECTION}`,
+			systemPromptOptions: {} as BeforeAgentStartEvent["systemPromptOptions"],
+		};
+		const result = await (handler as (e: BeforeAgentStartEvent) => Promise<{ systemPrompt?: string } | undefined>)(
+			event,
 		);
-		expect(bashTool?.description).toContain("The PID and log path will be returned.");
+		expect(result).toBeUndefined();
 	});
 });