fix(pi-bash-bg): stop replacing the bash tool so shellCommandPrefix keeps working (#43)

## Problem

Since 0.1.0, `pi-bash-bg` calls `createBashTool(process.cwd())` and
`pi.registerTool(...)` to append a background-job note to the bash tool
description:

```ts
const bashTool = createBashTool(process.cwd());
pi.registerTool({
    ...bashTool,
    description: `${bashTool.description} ${BASH_DESCRIPTION_APPENDIX}`,
});
```

The freshly-constructed `bashTool` is created **without** the
`commandPrefix`, `shellPath`, or `spawnHook` options pi wires onto its
built-in `bash` tool. In pi's `_refreshToolRegistry`,
extension-registered tools win over built-in ones with the same name, so
that replacement silently drops those options.

Concretely, any user with something like this in
`~/.pi/agent/settings.json`:

```json
{ "shellCommandPrefix": "export PI_ROOT=..." }
```

sees their prefix stop running as soon as `pi-bash-bg` is loaded. Same
for `shellPath`. I hit this while setting `PI_ROOT` for agent bash
sessions and traced it through `getShellCommandPrefix` ->
`createAllToolDefinitions({ bash: { commandPrefix } })` -> the registry
override above.

## Fix

Move the background-job guidance into the system prompt via a
`before_agent_start` hook (same mechanism the extension already uses for
other prompt tweaks), and stop registering a replacement bash tool. Pi's
built-in `bash` stays put, so `shellCommandPrefix`, `shellPath`, and any
`spawnHook` keep working.

The guidance section injected into the system prompt:

```markdown
## 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.
```

It's exported as `BASH_BG_SYSTEM_PROMPT_SECTION` and the handler no-ops
if it's already present, so repeated `before_agent_start` events don't
duplicate it.

## Verification

- `yarn test --run packages/bash-bg`: 76/76 pass (new test covers that
no tool is registered, handlers are wired up, and the system prompt is
augmented once).
- `yarn lint`: clean.
- End-to-end: with this built locally and `shellCommandPrefix` set, `env
| grep ^PI_ROOT` in agent bash now returns the expected value; before
the fix it was empty.

## Changeset

Included as a patch bump on `pi-bash-bg`.

Co-authored-by: mgabor3141 <mgabor3141@users.noreply.github.com>

Author: mgabor3141

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

@@ -0,0 +1,5 @@
+---
+"pi-bash-bg": patch
+---
+
+Stop replacing pi's built-in `bash` tool so `shellCommandPrefix`, `shellPath`, and `spawnHook` keep working; background-job guidance is now injected into the system prompt instead.

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,17 @@
  */
 
 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 =
+	"`command &` in bash returns immediately; output is captured to a log file shown in the `[bg] pid=<PID> label=<LABEL> log=<PATH>` line.";
 
 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 +36,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("`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();
 	});
 });