feat: add pi-bash-bg package (#29)

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

Author: mgabor3141

.changeset/add-bash-bg.md

@@ -0,0 +1,5 @@
+---
+"pi-bash-bg": minor
+---
+
+New package: pi-bash-bg. Makes `command &` work in pi's bash tool by intercepting bash tool calls, detecting background processes via AST parsing (@aliou/sh), and rewriting commands to redirect output to temp log files and disown. Compound commands (&&, ||, pipelines) are wrapped in braces so the redirect applies to the entire background subshell. The agent sees the PID, label, and log file path in the tool output.

.changeset/bash-bg-bash-tool-description.md

@@ -0,0 +1,5 @@
+---
+"pi-bash-bg": patch
+---
+
+Append background-job behavior guidance to the bash tool description so models see that background jobs keep running, output is captured to a log file, and the PID plus log path are returned.

.changeset/friendly-bash-bg-logs.md

@@ -0,0 +1,5 @@
+---
+"pi-bash-bg": patch
+---
+
+Make background log file names human-readable by basing them on the detected command label and using a simple numeric suffix for uniqueness.

AGENTS.md

@@ -22,6 +22,7 @@ Monorepo of extensions and libraries for [pi](https://pi.dev). Managed with Yarn
 | pi-budget-model | `packages/budget-model/` | library |
 | pi-no-soft-cursor | `packages/no-soft-cursor/` | pi extension |
 | pi-jujutsu | `packages/jujutsu/` | pi extension |
+| pi-bash-bg | `packages/bash-bg/` | pi extension |
 
 ## Workflow
 

packages/bash-bg/README.md

@@ -0,0 +1,99 @@
+# pi-bash-bg
+
+Makes `command &` work in pi's bash tool by detaching background processes from pipes.
+
+## Problem
+
+The bash tool pipes stdout/stderr from the spawned shell. When a command backgrounds a process with `&`, the background process inherits these pipe file descriptors and keeps them open. Node.js waits for all pipe readers to close, so the tool hangs until the background process exits.
+
+## 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:
+
+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)
+3. **Append echo** reporting PID, label, and log path
+
+The agent sees something like:
+
+```
+[bg] pid=12345 label=npm run dev log=/tmp/pi-bg-npm-run-dev-1.log
+```
+
+It can then `cat` the log file or `kill` the PID.
+
+## Install
+
+```bash
+pi install pi-bash-bg
+```
+
+## How it works
+
+### Simple commands
+
+```bash
+# Before:
+npm run dev &
+# After:
+npm run dev > /tmp/pi-bg-npm-run-dev-1.log 2>&1 & disown $!;
+echo "[bg] pid=$! label=npm run dev log=/tmp/pi-bg-npm-run-dev-1.log"
+```
+
+### Compound commands (&&, ||, pipelines)
+
+Compound commands are wrapped in braces so the redirect applies to the entire background subshell, not just the last command in the chain:
+
+```bash
+# Before:
+cd /app && npm start &
+# After:
+{ cd /app && npm start; } > /tmp/pi-bg-npm-start-2.log 2>&1 & disown $!;
+echo "[bg] pid=$! label=npm start log=/tmp/pi-bg-npm-start-2.log"
+```
+
+### Existing redirections
+
+If a simple command already redirects both stdout and stderr, the extension only adds `disown` (no log file is created):
+
+```bash
+# Before:
+node server.js > /dev/null 2>&1 &
+# After:
+node server.js > /dev/null 2>&1 & disown $!;
+echo "[bg] pid=$! label=node server.js"
+```
+
+Compound commands are always wrapped in braces, even if their inner commands have redirections. This is necessary because the background subshell itself holds the pipe file descriptors open regardless of what its child commands do:
+
+```bash
+# Before:
+cd /app && npm start > /dev/null 2>&1 &
+# After:
+{ cd /app && npm start > /dev/null 2>&1; } > /tmp/pi-bg-npm-start-3.log 2>&1 & disown $!;
+echo "[bg] pid=$! label=npm start log=/tmp/pi-bg-npm-start-3.log"
+```
+
+### Existing disown
+
+If the command already has `disown` after the `&`, no duplicate is added.
+
+### Bash tool description
+
+The extension appends a short background-job summary to the bash tool description, so the model sees it directly in tool metadata.
+
+## Supported patterns
+
+| Pattern | Handled |
+|---------|---------|
+| `npm run dev &` | Yes |
+| `cd /dir && npm start &` | Yes (wrapped in braces) |
+| `tail -f log \| grep error &` | Yes (wrapped in braces) |
+| `nohup node server.js &` | Yes |
+| `PORT=3000 node server.js &` | Yes |
+| `while true; do sleep 1; done &` | Yes (wrapped in braces) |
+| `(sleep 10 && echo done) &` | Yes (wrapped in braces) |
+| `cmd &> /dev/null &` | Yes (skips adding redirects for simple commands) |
+| `cmd & disown $!` | Yes (skips adding disown) |
+| `echo "foo & bar"` | Ignored (& inside string) |
+| `cmd1 && cmd2` | Ignored (no background) |

packages/bash-bg/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "pi-bash-bg",
+  "version": "0.0.1",
+  "description": "Makes command & work in pi's bash tool by detaching background processes from pipes · from yapp",
+  "author": "mgabor3141",
+  "license": "MIT",
+  "repository": {
+    "url": "git+https://github.com/mgabor3141/yapp.git",
+    "directory": "packages/bash-bg"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "yapp"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup"
+  },
+  "pi": {
+    "extensions": [
+      "dist/index.js"
+    ]
+  },
+  "dependencies": {
+    "@aliou/sh": "^0.1.0",
+    "valibot": "^1.2.0"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.57.0",
+    "@types/node": "^25.3.5",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}