@rjshrjndrn/pi-sandbox 0.1.0

package/Makefile

@@ -0,0 +1,63 @@
+.PHONY: install test typecheck build publish patch minor major clean help
+
+# ── Config ───────────────────────────────────────────────────────────────────
+
+PACKAGE_NAME := $(shell node -p "require('./package.json').name" 2>/dev/null)
+VERSION      := $(shell node -p "require('./package.json').version" 2>/dev/null)
+
+# ── Default ──────────────────────────────────────────────────────────────────
+
+help:
+	@echo "pi-sandbox — $(PACKAGE_NAME) v$(VERSION)"
+	@echo ""
+	@echo "  make install     Install dependencies"
+	@echo "  make test        Run tests"
+	@echo "  make typecheck   Type-check TypeScript (no emit)"
+	@echo "  make build       install + typecheck + test"
+	@echo "  make patch       Bump patch version (0.1.0 → 0.1.1) and publish"
+	@echo "  make minor       Bump minor version (0.1.0 → 0.2.0) and publish"
+	@echo "  make major       Bump major version (0.1.0 → 1.0.0) and publish"
+	@echo "  make publish     Publish current version to npm"
+	@echo "  make clean       Remove node_modules"
+
+# ── Core tasks ───────────────────────────────────────────────────────────────
+
+install:
+	npm install
+
+test:
+	npm test
+
+typecheck:
+	npx tsc --noEmit --strict --skipLibCheck --moduleResolution bundler --module esnext \
+		--target esnext --allowImportingTsExtensions \
+		extensions/index.ts $(wildcard src/*.ts)
+
+build: install typecheck test
+	@echo "✓ Build complete — $(PACKAGE_NAME) v$(VERSION)"
+
+# ── Publishing ───────────────────────────────────────────────────────────────
+
+publish: build
+	npm publish --access public
+	@echo "✓ Published $(PACKAGE_NAME) v$(VERSION)"
+
+patch: build
+	npm version patch
+	npm publish --access public
+	@echo "✓ Published $(PACKAGE_NAME) v$(shell node -p "require('./package.json').version")"
+
+minor: build
+	npm version minor
+	npm publish --access public
+	@echo "✓ Published $(PACKAGE_NAME) v$(shell node -p "require('./package.json').version")"
+
+major: build
+	npm version major
+	npm publish --access public
+	@echo "✓ Published $(PACKAGE_NAME) v$(shell node -p "require('./package.json').version")"
+
+# ── Cleanup ──────────────────────────────────────────────────────────────────
+
+clean:
+	rm -rf node_modules

package/README.md

@@ -0,0 +1,56 @@
+# pi-sandbox
+
+Filesystem boundary enforcement for [pi](https://github.com/badlogic/pi-mono). Prompts you before the agent reads or writes files outside your project.
+
+## How it works
+
+On session start, `pi-sandbox` detects your project boundary:
+
+1. Runs `git rev-parse --show-toplevel` to find the git worktree root
+2. Falls back to the current working directory if not in a git repo
+
+Then it intercepts every file tool call (`read`, `write`, `edit`, `grep`, `find`, `ls`):
+
+- **Inside boundary** → allowed silently
+- **Outside boundary** → you get a confirmation prompt
+- **Previously approved directory** → allowed silently (remembered for the session)
+
+```
+🔒 pi-sandbox: path outside project
+
+Tool: read
+Path: /Users/you/.ssh/config
+Boundary: /Users/you/project
+
+Allow this access? (y/n)
+```
+
+When you approve, the parent directory is remembered for the rest of the session.
+
+## Install
+
+```bash
+# As a pi package
+pi install @rjshrjndrn/pi-sandbox
+
+# Or test locally
+pi -e ./pi-sandbox/extensions/index.ts
+```
+
+## Limitations
+
+- **No bash coverage** — the `bash` tool is not intercepted. The agent can still access files outside the boundary via shell commands. This will be addressed in a future version.
+- **Session-scoped memory only** — approvals reset when you start a new session.
+- **No configuration** — the boundary is always the git worktree root (or CWD). Custom boundaries and allow/deny patterns are planned for a future version.
+
+## Development
+
+```bash
+cd pi-sandbox
+npm install
+npm test
+```
+
+## License
+
+MIT

package/extensions/index.ts

@@ -0,0 +1,11 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"
+import { registerBoundaryDetection } from "../src/boundary.js"
+import { registerGuard } from "../src/guard.js"
+
+export default function (pi: ExtensionAPI) {
+  // Boundary detection — must be first so guard has the boundary available
+  registerBoundaryDetection(pi)
+
+  // Tool call guard — intercepts file tools and checks containment
+  registerGuard(pi)
+}

package/openspec/changes/pi-sandbox-mvp/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-17

package/openspec/changes/pi-sandbox-mvp/design.md

@@ -0,0 +1,67 @@
+## Context
+
+pi is a coding agent CLI that ships with built-in tools (`read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`). These tools have no filesystem boundary enforcement — they operate with the full permissions of the user's OS account. The extension API provides `tool_call` event interception that can block tool calls before execution, and `ctx.ui.confirm()` for interactive permission prompts. The sibling extension `pi-acm` in the same monorepo demonstrates the package structure, build setup, and pi extension patterns we'll follow.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Detect the project boundary automatically from git worktree root
+- Block file tool calls that escape the boundary unless the user approves
+- Remember approvals per-directory for the session lifetime
+- Resolve symlinks to prevent traversal attacks
+- Work as a standard pi extension package (installable via `pi packages`)
+- Zero configuration required — works out of the box
+
+**Non-Goals:**
+- Bash command path analysis (future change)
+- Persistent approval storage across sessions
+- Per-file or glob-based allow/deny rules
+- Configuration files or custom boundary definitions
+- Sandboxing at the OS level (namespaces, containers, etc.)
+
+## Decisions
+
+### 1. Use `tool_call` event interception, not tool overrides
+
+**Decision**: Intercept via `pi.on("tool_call")` rather than overriding each built-in tool with `pi.registerTool()`.
+
+**Rationale**: One handler covers all six file tools. Tool overrides would require matching each tool's exact result shape and re-implementing rendering. The `tool_call` event can block with `{ block: true, reason: "..." }` which is all we need — we don't need to modify paths or results.
+
+**Alternative considered**: Tool overrides would give us the ability to rewrite paths or enrich results, but that's unnecessary for the MVP.
+
+### 2. Use `git rev-parse --show-toplevel` for boundary detection
+
+**Decision**: Run `git rev-parse --show-toplevel` on session start via `pi.exec()`. Fall back to `ctx.cwd` if the command fails (not a git repo).
+
+**Rationale**: Git worktree root is the natural project boundary for most development workflows. It's what OpenCode uses successfully. CWD fallback ensures the extension works for non-git projects.
+
+**Alternative considered**: Always use CWD — too narrow for projects where you `cd` into subdirectories. Config-driven boundaries — adds complexity without clear MVP value.
+
+### 3. Resolve real paths before containment checks
+
+**Decision**: Use `fs.realpath()` on both the boundary and the target path before checking containment.
+
+**Rationale**: Symlinks can escape the boundary silently. `/project/link → /outside/secret` would pass a naive prefix check. Resolving both sides prevents this.
+
+**Edge case**: If `realpath()` fails (broken symlink, no permission), treat as outside boundary and prompt.
+
+### 4. Per-directory session approval memory
+
+**Decision**: When a user approves access to `/outside/some/file.txt`, store the directory `/outside/some/` in an in-memory `Set<string>`. Future accesses to files in that directory are auto-approved.
+
+**Rationale**: Per-file memory would be too noisy — the agent often reads multiple files in the same directory. Per-directory strikes a balance between convenience and security. In-memory storage means approvals reset on session restart, which is the safe default.
+
+**Alternative considered**: Per-path (exact file) — too many prompts. Persistent storage — premature for MVP, raises security questions.
+
+### 5. Notify on session start with detected boundary
+
+**Decision**: Show a `ctx.ui.notify()` message on session start indicating the detected boundary path.
+
+**Rationale**: Users should know the extension is active and what it considers the project root. Especially important when the detection falls back to CWD.
+
+## Risks / Trade-offs
+
+- **[Symlink race condition]** → A symlink could be changed between `realpath()` and actual tool execution. Mitigation: acceptable for MVP — this is defense-in-depth, not a security sandbox.
+- **[CWD fallback too narrow]** → If user launches pi from a subdirectory in a non-git project, the boundary may be too restrictive. Mitigation: acceptable — prompts still allow access, just requires confirmation.
+- **[No bash coverage]** → The agent can still escape via `bash` tool (`cat /etc/passwd`). Mitigation: documented as out of scope. Future change will add best-effort bash path extraction.
+- **[realpath failure on non-existent paths]** → `write` tool targets may not exist yet, so `realpath()` will fail. Mitigation: for non-existent paths, resolve the parent directory, or fall back to `path.resolve()` without symlink resolution.

package/openspec/changes/pi-sandbox-mvp/proposal.md

@@ -0,0 +1,32 @@
+## Why
+
+pi (the coding agent) has unrestricted filesystem access — it can read, write, and edit any file the user's OS account can reach. This means an agent can accidentally (or via prompt injection) wander outside the project, overwriting files in unrelated directories, leaking secrets from `~/.ssh`, or modifying system config. OpenCode solves this with a built-in permission system anchored to the git worktree. pi has no equivalent today. We need a lightweight extension that establishes a filesystem boundary and prompts the user before any tool crosses it.
+
+## What Changes
+
+- New pi extension package `pi-sandbox` that enforces filesystem boundaries.
+- On session start, detects the project boundary via `git rev-parse --show-toplevel` (falls back to CWD if not a git repo).
+- Intercepts all file-touching tool calls (`read`, `write`, `edit`, `grep`, `find`, `ls`) via the `tool_call` event.
+- Paths inside the boundary are allowed silently.
+- Paths outside the boundary trigger an interactive `ctx.ui.confirm()` prompt.
+- User approvals are remembered per-directory for the rest of the session (in-memory).
+- Symlinks are resolved via `realpath()` before containment checks to prevent traversal.
+- Bash is **out of scope** for the MVP — it will be addressed in a future change.
+- No configuration file — pure convention based on git worktree detection.
+
+## Capabilities
+
+### New Capabilities
+- `boundary-detection`: Detect the project filesystem boundary using git worktree root, with CWD fallback for non-git projects.
+- `path-guard`: Intercept file tool calls, check path containment against the boundary, and prompt the user for out-of-boundary access.
+- `session-approval`: Remember user-approved directories in-memory for the duration of the session to avoid repeated prompts.
+
+### Modified Capabilities
+<!-- None — this is a new extension -->
+
+## Impact
+
+- New package: `pi-sandbox/` alongside existing `pi-acm/` in the `pi-term` monorepo.
+- No changes to pi core — uses only public extension APIs (`pi.on("tool_call")`, `ctx.ui.confirm()`, `pi.exec()`).
+- Applies to all file-touching built-in tools: `read`, `write`, `edit`, `grep`, `find`, `ls`.
+- Users who install this extension will see confirmation prompts when the agent tries to access files outside their project root.

package/openspec/changes/pi-sandbox-mvp/specs/boundary-detection/spec.md

@@ -0,0 +1,30 @@
+## ADDED Requirements
+
+### Requirement: Detect boundary from git worktree
+The system SHALL detect the project filesystem boundary by running `git rev-parse --show-toplevel` on session start and storing the result as the boundary path.
+
+#### Scenario: Git repository detected
+- **WHEN** pi starts a session in a directory that is part of a git repository
+- **THEN** the boundary SHALL be set to the git worktree root (the output of `git rev-parse --show-toplevel`)
+
+#### Scenario: Nested subdirectory of git repo
+- **WHEN** pi starts a session in a subdirectory of a git repository (e.g., `project/src/lib/`)
+- **THEN** the boundary SHALL be set to the git worktree root, not the subdirectory
+
+### Requirement: Fall back to CWD for non-git projects
+The system SHALL fall back to using the current working directory as the boundary when `git rev-parse --show-toplevel` fails.
+
+#### Scenario: Not a git repository
+- **WHEN** pi starts a session in a directory that is not part of any git repository
+- **THEN** the boundary SHALL be set to the current working directory (`ctx.cwd`)
+
+#### Scenario: Git command not available
+- **WHEN** `git` is not installed or not on PATH
+- **THEN** the boundary SHALL be set to the current working directory (`ctx.cwd`)
+
+### Requirement: Notify user of detected boundary
+The system SHALL display a notification on session start indicating the detected boundary path and whether it was detected from git or CWD fallback.
+
+#### Scenario: Boundary notification on start
+- **WHEN** a session starts and the boundary is detected
+- **THEN** the system SHALL display a notification with the boundary path (e.g., "🔒 pi-sandbox: boundary set to /Users/you/project")

package/openspec/changes/pi-sandbox-mvp/specs/path-guard/spec.md

@@ -0,0 +1,57 @@
+## ADDED Requirements
+
+### Requirement: Intercept file tool calls
+The system SHALL intercept `tool_call` events for the following built-in tools: `read`, `write`, `edit`, `grep`, `find`, `ls`.
+
+#### Scenario: File tool call is intercepted
+- **WHEN** the LLM invokes any of `read`, `write`, `edit`, `grep`, `find`, or `ls`
+- **THEN** the system SHALL extract the path parameter from the tool input and evaluate it against the boundary before execution proceeds
+
+### Requirement: Allow paths inside the boundary
+The system SHALL allow tool calls whose resolved path is inside the boundary without prompting the user.
+
+#### Scenario: Path inside boundary
+- **WHEN** a file tool targets a path that resolves to a location inside the boundary
+- **THEN** the tool call SHALL proceed without any user prompt
+
+#### Scenario: Relative path resolving inside boundary
+- **WHEN** a file tool targets a relative path (e.g., `./src/index.ts`) that resolves inside the boundary
+- **THEN** the tool call SHALL proceed without any user prompt
+
+### Requirement: Prompt for paths outside the boundary
+The system SHALL prompt the user with `ctx.ui.confirm()` when a file tool targets a path that resolves outside the boundary.
+
+#### Scenario: Path outside boundary — user approves
+- **WHEN** a file tool targets a path outside the boundary
+- **AND** the user approves the confirmation prompt
+- **THEN** the tool call SHALL proceed
+
+#### Scenario: Path outside boundary — user denies
+- **WHEN** a file tool targets a path outside the boundary
+- **AND** the user denies the confirmation prompt
+- **THEN** the tool call SHALL be blocked with `{ block: true, reason: "..." }`
+- **AND** the reason SHALL include the blocked path and the boundary
+
+### Requirement: Resolve symlinks before containment check
+The system SHALL resolve symlinks using `realpath()` on both the boundary and the target path before performing the containment check.
+
+#### Scenario: Symlink escaping boundary
+- **WHEN** a file tool targets `/project/link` which is a symlink to `/outside/secret`
+- **THEN** the system SHALL resolve the symlink and detect that the real path is outside the boundary
+- **AND** the user SHALL be prompted
+
+#### Scenario: Realpath failure on non-existent target
+- **WHEN** a file tool targets a path that does not yet exist (e.g., `write` to a new file)
+- **THEN** the system SHALL resolve the nearest existing parent directory
+- **AND** if the resolved parent is inside the boundary, the tool call SHALL proceed
+
+#### Scenario: Realpath failure with no resolvable parent
+- **WHEN** `realpath()` fails for the target path and no parent can be resolved
+- **THEN** the system SHALL fall back to `path.resolve()` without symlink resolution
+
+### Requirement: Do not intercept bash tool
+The system SHALL NOT intercept the `bash` tool in this version.
+
+#### Scenario: Bash tool call
+- **WHEN** the LLM invokes the `bash` tool
+- **THEN** the system SHALL not evaluate or block the call

package/openspec/changes/pi-sandbox-mvp/specs/session-approval/spec.md

@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Remember approvals per directory
+The system SHALL store approved directories in an in-memory set when the user approves an out-of-boundary access. Future tool calls targeting files in an approved directory SHALL be auto-allowed without prompting.
+
+#### Scenario: Subsequent access to approved directory
+- **WHEN** the user approves access to `/outside/some/file.txt`
+- **AND** later the LLM requests access to `/outside/some/other.txt`
+- **THEN** the second access SHALL be auto-allowed without prompting (because `/outside/some/` was already approved)
+
+#### Scenario: Subdirectory of approved directory
+- **WHEN** the user approves access to `/outside/some/file.txt` (approving `/outside/some/`)
+- **AND** later the LLM requests access to `/outside/some/deep/nested/file.txt`
+- **THEN** the access SHALL be auto-allowed (subdirectories of approved directories are included)
+
+#### Scenario: Different directory not approved
+- **WHEN** the user approves access to `/outside/some/file.txt`
+- **AND** later the LLM requests access to `/outside/other/file.txt`
+- **THEN** the user SHALL be prompted (different directory, not covered by previous approval)
+
+### Requirement: Approvals are session-scoped
+The system SHALL clear all approval memory when the session ends. Approvals SHALL NOT persist across sessions.
+
+#### Scenario: New session starts clean
+- **WHEN** a new session starts
+- **THEN** the approval set SHALL be empty regardless of previous session approvals
+
+### Requirement: Approval granularity is the parent directory
+The system SHALL derive the approved directory from the parent directory of the approved file path (`path.dirname()`).
+
+#### Scenario: Approval derived from file path
+- **WHEN** the user approves access to `/tmp/output/result.json`
+- **THEN** the approved directory SHALL be `/tmp/output/`
+- **AND** all future accesses to files under `/tmp/output/` SHALL be auto-allowed

package/openspec/changes/pi-sandbox-mvp/tasks.md

@@ -0,0 +1,37 @@
+## 1. Project Setup
+
+- [x] 1.1 Create `pi-sandbox/package.json` with pi extension metadata, peer dependencies (`@mariozechner/pi-coding-agent`, `@sinclair/typebox`), and dev dependencies (`typescript`, `vitest`)
+- [x] 1.2 Create `pi-sandbox/extensions/index.ts` entry point that imports and registers all modules
+- [x] 1.3 Create `pi-sandbox/tsconfig.json` and basic project structure (`src/`, `tests/`)
+
+## 2. Boundary Detection
+
+- [x] 2.1 Implement `src/boundary.ts` — `detectBoundary(pi, cwd)` function that runs `git rev-parse --show-toplevel` via `pi.exec()` and returns the absolute path, falling back to `cwd` on failure
+- [x] 2.2 Register `session_start` handler that calls `detectBoundary()`, stores the result in module state, and displays a `ctx.ui.notify()` message with the detected boundary
+- [x] 2.3 Write tests for `detectBoundary()` — git repo case, non-git fallback, git-not-installed fallback
+
+## 3. Path Containment
+
+- [x] 3.1 Implement `src/containment.ts` — `isInsideBoundary(boundary, targetPath, cwd)` function that resolves the target path (handling relative paths via `path.resolve(cwd, ...)`), resolves symlinks via `fs.realpath()`, and checks if the resolved path starts with the resolved boundary
+- [x] 3.2 Handle non-existent paths (for `write` tool) by walking up to the nearest existing parent directory for `realpath()` resolution, falling back to `path.resolve()` if no parent resolves
+- [x] 3.3 Write tests for containment — inside paths, outside paths, relative paths, symlink escapes, non-existent target paths, broken symlinks
+
+## 4. Session Approval Memory
+
+- [x] 4.1 Implement `src/approvals.ts` — `ApprovalStore` with `approve(dirPath)`, `isApproved(filePath)`, and `clear()` methods, backed by an in-memory `Set<string>` of approved directory prefixes
+- [x] 4.2 `isApproved()` SHALL check if the file's resolved path starts with any approved directory prefix (supporting subdirectories)
+- [x] 4.3 `approve()` SHALL store `path.dirname(filePath)` as the approved directory
+- [x] 4.4 Write tests for approval store — approve file adds directory, subdirectory access allowed, different directory not approved, clear resets
+
+## 5. Tool Call Guard
+
+- [x] 5.1 Implement `src/guard.ts` — `tool_call` event handler that extracts the `path` param from file tool inputs (`read`, `write`, `edit`, `grep`, `find`, `ls`), skips non-file tools
+- [x] 5.2 For each intercepted call: resolve the path, check containment, check approval store, and if outside boundary and not approved, call `ctx.ui.confirm()` with tool name, path, and boundary info
+- [x] 5.3 On user approval, add the directory to the approval store and allow. On denial, return `{ block: true, reason }` with the path and boundary in the reason message
+- [x] 5.4 Register the `tool_call` handler in the extension entry point
+- [x] 5.5 Write tests for guard logic — inside path allowed, outside path prompts, approved path skips prompt, denied path blocks
+
+## 6. Integration & Polish
+
+- [x] 6.1 End-to-end manual test: install extension locally with `pi -e ./pi-sandbox/extensions/index.ts`, verify boundary detection notification, verify prompt on out-of-boundary `read`, verify approval memory
+- [x] 6.2 Add `README.md` with installation instructions, what it does, and limitations (no bash coverage)

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@rjshrjndrn/pi-sandbox",
+  "version": "0.1.0",
+  "description": "Filesystem boundary enforcement for pi — prompts before the agent escapes your project",
+  "keywords": ["pi-package", "pi-extension", "sandbox", "filesystem", "permissions"],
+  "license": "MIT",
+  "type": "module",
+  "pi": {
+    "extensions": ["./extensions"]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0",
+    "vitest": "^1.6.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/approvals.ts

@@ -0,0 +1,47 @@
+import { dirname, sep } from "node:path"
+
+/**
+ * In-memory store of approved directories for the current session.
+ * When a user approves access to a file outside the boundary,
+ * its parent directory is stored. Future accesses to files in
+ * approved directories (including subdirectories) are auto-allowed.
+ */
+export class ApprovalStore {
+  private approved = new Set<string>()
+
+  /**
+   * Approve a file path by storing its parent directory.
+   * The directory is normalized to end with a path separator.
+   */
+  approve(filePath: string): void {
+    const dir = dirname(filePath)
+    const normalized = dir.endsWith(sep) ? dir : dir + sep
+    this.approved.add(normalized)
+  }
+
+  /**
+   * Check if a file path is in an approved directory.
+   * Returns true if the file's path starts with any approved directory prefix,
+   * which includes subdirectories.
+   */
+  isApproved(filePath: string): boolean {
+    for (const dir of this.approved) {
+      if (filePath === dir.slice(0, -1) || filePath.startsWith(dir)) {
+        return true
+      }
+    }
+    return false
+  }
+
+  /**
+   * Clear all approvals (e.g. on session end).
+   */
+  clear(): void {
+    this.approved.clear()
+  }
+
+  /** Number of approved directories (for testing) */
+  get size(): number {
+    return this.approved.size
+  }
+}

package/src/boundary.ts

@@ -0,0 +1,42 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"
+import { state } from "./state.js"
+
+/**
+ * Detect the project filesystem boundary.
+ *
+ * Runs `git rev-parse --show-toplevel` to find the git worktree root.
+ * Falls back to `cwd` if git is not available or the directory is not a git repo.
+ */
+export async function detectBoundary(
+  pi: ExtensionAPI,
+  cwd: string
+): Promise<{ boundary: string; source: "git" | "cwd" }> {
+  try {
+    const result = await pi.exec("git", ["rev-parse", "--show-toplevel"], {
+      timeout: 5000,
+    })
+    const toplevel = result.stdout.trim()
+    if (result.code === 0 && toplevel.length > 0) {
+      return { boundary: toplevel, source: "git" }
+    }
+  } catch {
+    // git not available or other error — fall through to CWD
+  }
+  return { boundary: cwd, source: "cwd" }
+}
+
+/**
+ * Register the session_start handler that detects the boundary on startup.
+ */
+export function registerBoundaryDetection(pi: ExtensionAPI) {
+  pi.on("session_start", async (_event, ctx) => {
+    const { boundary, source } = await detectBoundary(pi, ctx.cwd)
+    state.boundary = boundary
+
+    const label =
+      source === "git"
+        ? `🔒 pi-sandbox: boundary set to ${boundary} (git worktree)`
+        : `🔒 pi-sandbox: boundary set to ${boundary} (cwd fallback)`
+    ctx.ui.notify(label, "info")
+  })
+}

package/src/containment.ts

@@ -0,0 +1,63 @@
+import { realpath } from "node:fs/promises"
+import { resolve, dirname, sep } from "node:path"
+
+/**
+ * Resolve a path to its real location, handling symlinks.
+ * For non-existent paths (e.g. write targets), walks up to the
+ * nearest existing parent and resolves from there.
+ * Falls back to path.resolve() if nothing resolves.
+ */
+async function resolveReal(targetPath: string): Promise<string> {
+  try {
+    return await realpath(targetPath)
+  } catch {
+    // Path doesn't exist — walk up to find the nearest existing parent
+    let current = dirname(targetPath)
+    const seen = new Set<string>()
+    while (current && !seen.has(current)) {
+      seen.add(current)
+      try {
+        const resolvedParent = await realpath(current)
+        // Re-append the relative suffix under the resolved parent
+        const suffix = targetPath.slice(current.length)
+        return resolvedParent + suffix
+      } catch {
+        const parent = dirname(current)
+        if (parent === current) break // reached filesystem root
+        current = parent
+      }
+    }
+    // Nothing resolved — fall back to plain resolve
+    return resolve(targetPath)
+  }
+}
+
+/**
+ * Check if a target path is inside the given boundary.
+ *
+ * Resolves symlinks on both boundary and target.
+ * Returns true if the resolved target starts with the resolved boundary.
+ */
+export async function isInsideBoundary(
+  boundary: string,
+  targetPath: string,
+  cwd: string
+): Promise<boolean> {
+  // Resolve relative paths against cwd
+  const absoluteTarget = resolve(cwd, targetPath)
+
+  // Resolve symlinks
+  const resolvedBoundary = await resolveReal(boundary)
+  const resolvedTarget = await resolveReal(absoluteTarget)
+
+  // Normalize: ensure boundary ends with separator for prefix check
+  const boundaryPrefix = resolvedBoundary.endsWith(sep)
+    ? resolvedBoundary
+    : resolvedBoundary + sep
+
+  // Target is inside if it equals the boundary or starts with boundary + sep
+  return (
+    resolvedTarget === resolvedBoundary ||
+    resolvedTarget.startsWith(boundaryPrefix)
+  )
+}

package/src/guard.ts

@@ -0,0 +1,61 @@
+import {
+  type ExtensionAPI,
+  isToolCallEventType,
+} from "@mariozechner/pi-coding-agent"
+import { resolve } from "node:path"
+import { isInsideBoundary } from "./containment.js"
+import { state } from "./state.js"
+
+/** Tools that take a `path` parameter and touch the filesystem */
+const FILE_TOOLS = ["read", "write", "edit", "grep", "find", "ls"] as const
+
+/**
+ * Extract the path from a file tool's input.
+ * All built-in file tools use `path` as the parameter name.
+ */
+function extractPath(toolName: string, input: Record<string, any>): string | null {
+  if (!FILE_TOOLS.includes(toolName as any)) return null
+  const p = input?.path
+  return typeof p === "string" ? p : null
+}
+
+/**
+ * Register the tool_call event handler that enforces filesystem boundaries.
+ */
+export function registerGuard(pi: ExtensionAPI) {
+  pi.on("tool_call", async (event, ctx) => {
+    // Skip if boundary not yet detected (shouldn't happen, but be safe)
+    if (!state.boundary) return
+
+    const targetPath = extractPath(event.toolName, event.input as Record<string, any>)
+    if (targetPath === null) return // Not a file tool or no path param
+
+    // Resolve to absolute
+    const absolutePath = resolve(ctx.cwd, targetPath)
+
+    // Check containment
+    const inside = await isInsideBoundary(state.boundary, targetPath, ctx.cwd)
+    if (inside) return // Inside boundary — allow silently
+
+    // Check approval store
+    if (state.approvals.isApproved(absolutePath)) return // Previously approved
+
+    // Outside boundary and not approved — ask the user
+    const allowed = await ctx.ui.confirm(
+      "🔒 pi-sandbox: path outside project",
+      `Tool: ${event.toolName}\nPath: ${absolutePath}\nBoundary: ${state.boundary}\n\nAllow this access?`
+    )
+
+    if (allowed) {
+      // Remember the directory for this session
+      state.approvals.approve(absolutePath)
+      return // Allow
+    }
+
+    // Denied — block the tool call
+    return {
+      block: true,
+      reason: `pi-sandbox: access denied to ${absolutePath} (outside boundary ${state.boundary})`,
+    }
+  })
+}

package/src/state.ts

@@ -0,0 +1,12 @@
+import { ApprovalStore } from "./approvals.js"
+
+/**
+ * Shared module-level state for pi-sandbox.
+ * Set during session_start, read by the guard.
+ */
+export const state = {
+  /** The resolved project boundary (absolute path) */
+  boundary: "",
+  /** In-memory approval store for the current session */
+  approvals: new ApprovalStore(),
+}

package/tests/approvals.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect, beforeEach } from "vitest"
+import { ApprovalStore } from "../src/approvals.js"
+
+describe("ApprovalStore", () => {
+  let store: ApprovalStore
+
+  beforeEach(() => {
+    store = new ApprovalStore()
+  })
+
+  it("starts empty", () => {
+    expect(store.size).toBe(0)
+    expect(store.isApproved("/outside/file.txt")).toBe(false)
+  })
+
+  it("approving a file adds its parent directory", () => {
+    store.approve("/outside/some/file.txt")
+    expect(store.size).toBe(1)
+  })
+
+  it("allows files in the same approved directory", () => {
+    store.approve("/outside/some/file.txt")
+    expect(store.isApproved("/outside/some/other.txt")).toBe(true)
+  })
+
+  it("allows files in subdirectories of approved directory", () => {
+    store.approve("/outside/some/file.txt")
+    expect(store.isApproved("/outside/some/deep/nested/file.txt")).toBe(true)
+  })
+
+  it("rejects files in different directories", () => {
+    store.approve("/outside/some/file.txt")
+    expect(store.isApproved("/outside/other/file.txt")).toBe(false)
+  })
+
+  it("rejects files in parent of approved directory", () => {
+    store.approve("/outside/some/file.txt")
+    expect(store.isApproved("/outside/file.txt")).toBe(false)
+  })
+
+  it("supports multiple approved directories", () => {
+    store.approve("/tmp/output/result.json")
+    store.approve("/home/user/.config/settings.json")
+    expect(store.isApproved("/tmp/output/other.json")).toBe(true)
+    expect(store.isApproved("/home/user/.config/other.json")).toBe(true)
+    expect(store.isApproved("/var/log/syslog")).toBe(false)
+    expect(store.size).toBe(2)
+  })
+
+  it("clear resets all approvals", () => {
+    store.approve("/outside/some/file.txt")
+    store.approve("/tmp/output/result.json")
+    expect(store.size).toBe(2)
+    store.clear()
+    expect(store.size).toBe(0)
+    expect(store.isApproved("/outside/some/file.txt")).toBe(false)
+  })
+})

package/tests/boundary.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect, vi } from "vitest"
+import { detectBoundary } from "../src/boundary.js"
+
+function mockPi(execResult: { stdout: string; stderr: string; code: number; killed: boolean }) {
+  return {
+    exec: vi.fn().mockResolvedValue(execResult),
+  } as any
+}
+
+function mockPiExecThrows() {
+  return {
+    exec: vi.fn().mockRejectedValue(new Error("git not found")),
+  } as any
+}
+
+describe("detectBoundary", () => {
+  it("returns git worktree root when git succeeds", async () => {
+    const pi = mockPi({
+      stdout: "/Users/test/project\n",
+      stderr: "",
+      code: 0,
+      killed: false,
+    })
+    const result = await detectBoundary(pi, "/Users/test/project/src")
+    expect(result.boundary).toBe("/Users/test/project")
+    expect(result.source).toBe("git")
+  })
+
+  it("falls back to cwd when git returns non-zero exit code", async () => {
+    const pi = mockPi({
+      stdout: "",
+      stderr: "fatal: not a git repository",
+      code: 128,
+      killed: false,
+    })
+    const result = await detectBoundary(pi, "/Users/test/not-a-repo")
+    expect(result.boundary).toBe("/Users/test/not-a-repo")
+    expect(result.source).toBe("cwd")
+  })
+
+  it("falls back to cwd when git is not available", async () => {
+    const pi = mockPiExecThrows()
+    const result = await detectBoundary(pi, "/Users/test/no-git")
+    expect(result.boundary).toBe("/Users/test/no-git")
+    expect(result.source).toBe("cwd")
+  })
+
+  it("falls back to cwd when git returns empty stdout", async () => {
+    const pi = mockPi({
+      stdout: "",
+      stderr: "",
+      code: 0,
+      killed: false,
+    })
+    const result = await detectBoundary(pi, "/Users/test/empty")
+    expect(result.boundary).toBe("/Users/test/empty")
+    expect(result.source).toBe("cwd")
+  })
+
+  it("trims whitespace from git output", async () => {
+    const pi = mockPi({
+      stdout: "  /Users/test/project  \n",
+      stderr: "",
+      code: 0,
+      killed: false,
+    })
+    const result = await detectBoundary(pi, "/Users/test/project/src")
+    expect(result.boundary).toBe("/Users/test/project")
+    expect(result.source).toBe("git")
+  })
+})

package/tests/containment.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest"
+import { isInsideBoundary } from "../src/containment.js"
+import { mkdirSync, symlinkSync, rmSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+
+const TEST_DIR = join(tmpdir(), "pi-sandbox-test-" + Date.now())
+const PROJECT = join(TEST_DIR, "project")
+const OUTSIDE = join(TEST_DIR, "outside")
+
+beforeAll(() => {
+  mkdirSync(join(PROJECT, "src", "lib"), { recursive: true })
+  mkdirSync(join(OUTSIDE, "secrets"), { recursive: true })
+  writeFileSync(join(PROJECT, "src", "index.ts"), "// test")
+  writeFileSync(join(OUTSIDE, "secrets", "key.pem"), "secret")
+  // Symlink inside project pointing outside
+  symlinkSync(OUTSIDE, join(PROJECT, "escape-link"))
+})
+
+afterAll(() => {
+  rmSync(TEST_DIR, { recursive: true, force: true })
+})
+
+describe("isInsideBoundary", () => {
+  it("allows paths inside the boundary", async () => {
+    expect(await isInsideBoundary(PROJECT, join(PROJECT, "src", "index.ts"), PROJECT)).toBe(true)
+  })
+
+  it("allows the boundary root itself", async () => {
+    expect(await isInsideBoundary(PROJECT, PROJECT, PROJECT)).toBe(true)
+  })
+
+  it("allows relative paths resolving inside", async () => {
+    expect(await isInsideBoundary(PROJECT, "./src/index.ts", PROJECT)).toBe(true)
+  })
+
+  it("allows nested subdirectories", async () => {
+    expect(await isInsideBoundary(PROJECT, join(PROJECT, "src", "lib"), PROJECT)).toBe(true)
+  })
+
+  it("rejects paths outside the boundary", async () => {
+    expect(await isInsideBoundary(PROJECT, OUTSIDE, PROJECT)).toBe(false)
+  })
+
+  it("rejects paths in sibling directories", async () => {
+    expect(await isInsideBoundary(PROJECT, join(OUTSIDE, "secrets", "key.pem"), PROJECT)).toBe(false)
+  })
+
+  it("detects symlink escapes", async () => {
+    // project/escape-link -> outside/
+    const linkTarget = join(PROJECT, "escape-link", "secrets", "key.pem")
+    expect(await isInsideBoundary(PROJECT, linkTarget, PROJECT)).toBe(false)
+  })
+
+  it("handles non-existent target paths (write to new file)", async () => {
+    // Parent exists and is inside boundary
+    const newFile = join(PROJECT, "src", "new-file.ts")
+    expect(await isInsideBoundary(PROJECT, newFile, PROJECT)).toBe(true)
+  })
+
+  it("handles non-existent target outside boundary", async () => {
+    const newFile = join(OUTSIDE, "new-dir", "file.txt")
+    expect(await isInsideBoundary(PROJECT, newFile, PROJECT)).toBe(false)
+  })
+
+  it("handles relative paths with .. that escape", async () => {
+    expect(await isInsideBoundary(PROJECT, "../../etc/passwd", PROJECT)).toBe(false)
+  })
+})

package/tests/guard.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect, beforeEach, vi } from "vitest"
+import { state } from "../src/state.js"
+import { ApprovalStore } from "../src/approvals.js"
+import { isInsideBoundary } from "../src/containment.js"
+import { mkdirSync, rmSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+
+// We test the guard logic inline since the actual handler is tightly coupled
+// to ExtensionAPI. We test the decision logic that the handler uses.
+
+const TEST_DIR = join(tmpdir(), "pi-sandbox-guard-test-" + Date.now())
+const PROJECT = join(TEST_DIR, "project")
+const OUTSIDE = join(TEST_DIR, "outside")
+
+beforeEach(() => {
+  mkdirSync(join(PROJECT, "src"), { recursive: true })
+  mkdirSync(OUTSIDE, { recursive: true })
+  writeFileSync(join(PROJECT, "src", "index.ts"), "// test")
+  writeFileSync(join(OUTSIDE, "secret.txt"), "secret")
+  state.boundary = PROJECT
+  state.approvals = new ApprovalStore()
+})
+
+import { afterAll } from "vitest"
+afterAll(() => {
+  rmSync(TEST_DIR, { recursive: true, force: true })
+})
+
+// Simulates the guard decision logic
+async function guardDecision(
+  toolName: string,
+  path: string,
+  cwd: string,
+  userApproves: boolean
+): Promise<"allow" | "block" | "ask"> {
+  const FILE_TOOLS = ["read", "write", "edit", "grep", "find", "ls"]
+  if (!FILE_TOOLS.includes(toolName)) return "allow" // not a file tool
+
+  const inside = await isInsideBoundary(state.boundary, path, cwd)
+  if (inside) return "allow"
+
+  const { resolve } = await import("node:path")
+  const absolutePath = resolve(cwd, path)
+  if (state.approvals.isApproved(absolutePath)) return "allow"
+
+  // Would prompt user — return what user would do
+  if (userApproves) {
+    state.approvals.approve(absolutePath)
+    return "allow"
+  }
+  return "block"
+}
+
+describe("guard decision logic", () => {
+  it("allows file tool calls inside boundary", async () => {
+    const result = await guardDecision("read", join(PROJECT, "src", "index.ts"), PROJECT, false)
+    expect(result).toBe("allow")
+  })
+
+  it("allows non-file tools without checking", async () => {
+    const result = await guardDecision("bash", "/etc/passwd", PROJECT, false)
+    expect(result).toBe("allow")
+  })
+
+  it("blocks outside path when user denies", async () => {
+    const result = await guardDecision("read", join(OUTSIDE, "secret.txt"), PROJECT, false)
+    expect(result).toBe("block")
+  })
+
+  it("allows outside path when user approves", async () => {
+    const result = await guardDecision("write", join(OUTSIDE, "output.txt"), PROJECT, true)
+    expect(result).toBe("allow")
+  })
+
+  it("auto-allows after previous approval in same directory", async () => {
+    // First access — user approves
+    await guardDecision("read", join(OUTSIDE, "secret.txt"), PROJECT, true)
+    // Second access — same directory, should auto-allow
+    const result = await guardDecision("read", join(OUTSIDE, "other.txt"), PROJECT, false)
+    expect(result).toBe("allow")
+  })
+
+  it("prompts for different directory even after approval", async () => {
+    const OTHER = join(TEST_DIR, "other-outside")
+    mkdirSync(OTHER, { recursive: true })
+    writeFileSync(join(OTHER, "file.txt"), "test")
+
+    await guardDecision("read", join(OUTSIDE, "secret.txt"), PROJECT, true)
+    const result = await guardDecision("read", join(OTHER, "file.txt"), PROJECT, false)
+    expect(result).toBe("block")
+  })
+
+  it("works for all file tool types", async () => {
+    for (const tool of ["read", "write", "edit", "grep", "find", "ls"]) {
+      state.approvals = new ApprovalStore() // reset
+      const result = await guardDecision(tool, join(OUTSIDE, "file.txt"), PROJECT, false)
+      expect(result).toBe("block")
+    }
+  })
+})