feat(pi): Add Pi coding agent integration

.loom/audit/20260521-pi-extension-audit.md

@@ -0,0 +1,84 @@
+# Pi Extension Integration Audit
+
+ID: audit:20260521-pi-extension-audit
+Type: Audit
+Status: recorded
+Created: 2026-05-21
+Updated: 2026-05-21
+Audited: 2026-05-21
+Target: ticket:20260521-pi-extension
+
+## Summary
+
+A bounded Ralph review audited the RTK Pi extension integration, acceptance evidence, install behavior, fail-open behavior, and docs. The final follow-up audit found no material findings within scope and gave a `clear` verdict, with residual risk limited to lack of live Pi `tool_call` end-to-end observation and the need to reload/restart Pi.
+
+## Target
+
+The target was `ticket:20260521-pi-extension` and the current uncommitted diff in `/Users/crlough/Code/personal/rtk` adding first-class Pi support:
+
+- `hooks/pi/rtk.ts`
+- `hooks/pi/README.md`
+- `src/main.rs`
+- `src/hooks/init.rs`
+- `src/hooks/constants.rs`
+- `README.md`
+- `docs/guide/getting-started/supported-agents.md`
+- `hooks/README.md`
+- `src/hooks/README.md`
+- `.loom/tickets/20260521-pi-extension.md`
+- `.loom/evidence/20260521-pi-extension-validation.md`
+
+## Audit Scope And Lenses
+
+The final Ralph review challenged the current final state after prior audit follow-up fixes. Lenses used:
+
+- acceptance and scope: whether `ACC-001` through `ACC-004` are supported now;
+- evidence exactness and freshness;
+- implementation quality and fail-open behavior;
+- security/trust boundary;
+- docs and follow-through.
+
+Out of scope: live Pi UI/runtime end-to-end execution, every RTK rewrite pattern, and upstream Pi API changes after the audited documentation/source state.
+
+## Context And Evidence Reviewed
+
+- Ralph review run: headless Pi review launched from `ticket:20260521-pi-extension` and `evidence:20260521-pi-extension-validation`, with read-only scope and explicit lenses.
+- `git status --short`, `git diff --stat`, and current untracked `hooks/pi/*` - current source state under review.
+- `hooks/pi/rtk.ts` - Pi extension implementation and fail-open behavior.
+- `hooks/pi/README.md` - Pi integration installation and failure-behavior docs.
+- `src/main.rs`, `src/hooks/init.rs`, `src/hooks/constants.rs` - CLI dispatch, install/uninstall path, path resolution, and tests.
+- `README.md`, `docs/guide/getting-started/supported-agents.md`, `hooks/README.md`, `src/hooks/README.md` - public and internal docs.
+- `/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/README.md` and `docs/extensions.md` - Pi extension location and `tool_call` mutation behavior.
+- `/Users/crlough/.pi/agent/extensions/rtk.ts` - installed current-user extension; Ralph reported it exists and matches `hooks/pi/rtk.ts` by `cmp`/SHA-256.
+- `evidence:20260521-pi-extension-validation` - records `cargo fmt --all --check`, `cargo clippy --all-targets`, `cargo test --all`, isolated install, and current-user install/match observations.
+
+## Findings
+
+None - no material findings within audited scope.
+
+The Ralph review specifically rechecked the prior blockers and reported them resolved:
+
+- installed current-user Pi extension now exists and matches the repo artifact;
+- fail-open overclaim is resolved by subprocess-level fallback plus top-level `try/catch` around the `tool_call` handler;
+- Rust quality gate evidence now includes `cargo fmt --all --check`, `cargo clippy --all-targets`, and `cargo test --all`.
+
+## Verdict
+
+`clear` - within the audited scope, the Pi extension integration satisfies `ACC-001` through `ACC-004`, and the final review did not identify material blockers. This verdict does not itself close or accept the ticket; it supports the ticket owner making a closure/acceptance decision from the ticket, evidence, and audit records.
+
+## Required Follow-up
+
+No material audit follow-up is required before ticket closure.
+
+Ticket closure should still state the live-runtime limitation explicitly: the installed extension requires Pi restart or `/reload` before it is active in a running session.
+
+## Residual Risk
+
+- No actual Pi end-to-end `tool_call` execution was observed; validation is source inspection plus helper/install checks.
+- Pi must restart or run `/reload` before the installed extension is active in a running session.
+- Extension behavior depends on the local `rtk` binary found on Pi's PATH and Pi's documented extension API remaining compatible.
+
+## Related Records
+
+- `ticket:20260521-pi-extension` - owns acceptance, finding disposition, and closure state.
+- `evidence:20260521-pi-extension-validation` - records the validation observations consumed by this audit.

.loom/evidence/20260521-pi-extension-validation.md

@@ -0,0 +1,86 @@
+# Pi Extension Validation
+
+ID: evidence:20260521-pi-extension-validation
+Type: Evidence Dossier
+Status: recorded
+Created: 2026-05-21
+Updated: 2026-05-21
+Observed: 2026-05-21
+
+## Summary
+
+Validation observations for `ticket:20260521-pi-extension`: the Pi extension artifact was installed for the current user, the rewrite helper behavior handles RTK's exit-3 rewrite output, documentation/source references for Pi support are present, a Rust toolchain was installed, formatting/clippy/tests pass, and the new `rtk init --agent pi` path installs the extension into both isolated and current-user Pi config directories.
+
+## Observations
+
+- Observation: The current user's Pi extension file exists and matches the repo artifact at install time.
+  - Procedure/source: Ran `mkdir -p "$HOME/.pi/agent/extensions" && cp hooks/pi/rtk.ts "$HOME/.pi/agent/extensions/rtk.ts" && cmp -s hooks/pi/rtk.ts "$HOME/.pi/agent/extensions/rtk.ts" && ls -l "$HOME/.pi/agent/extensions/rtk.ts"` from `/Users/crlough/Code/personal/rtk`.
+  - Actual result: `cmp` exited successfully and `ls` showed `/Users/crlough/.pi/agent/extensions/rtk.ts` with size `1728` bytes.
+
+- Observation: Existing installed RTK can rewrite `git status`, returning the rewritten command on stdout with exit code `3`.
+  - Procedure/source: Ran `rtk rewrite "git status"; printf 'exit=%s\n' "$?"`.
+  - Actual result: stdout contained `rtk git status` and `exit=3`.
+
+- Observation: The Pi extension's Node rewrite-helper behavior returns the rewrite despite RTK exit code `3`.
+  - Procedure/source: Ran a Node snippet matching `hooks/pi/rtk.ts`'s `execFile("rtk", ["rewrite", command])` catch path for `git status`.
+  - Actual result: stdout was `rtk git status`.
+
+- Observation: Source and docs contain Pi integration references.
+  - Procedure/source: Ran `rg -n "Pi|--agent pi|hooks/pi|PI_CODING_AGENT_DIR|rtk.ts" README.md docs/guide/getting-started/supported-agents.md hooks/README.md src/hooks/README.md src/main.rs src/hooks/init.rs src/hooks/constants.rs hooks/pi`.
+  - Actual result: matches were found in the new Pi artifact/docs and in `src/main.rs`, `src/hooks/init.rs`, and `src/hooks/constants.rs`.
+
+- Observation: Rust formatter/tests initially could not run in this environment.
+  - Procedure/source: Ran `cargo fmt` and checked for Rust toolchain commands.
+  - Actual result: `/bin/bash: cargo: command not found`; `which cargo || which rustc || ls ~/.cargo/bin` produced no toolchain path.
+
+- Observation: Rust toolchain is now installed.
+  - Procedure/source: Confirmed Xcode Command Line Tools were present, ran the rustup installer, then added missing components with `rustup component add rustfmt clippy`.
+  - Actual result: `rustc 1.95.0 (59807616e 2026-04-14)`, `cargo 1.95.0 (f2d3ce0bd 2026-03-21)`, `rustfmt 1.9.0-stable (59807616e1 2026-04-14)`, and `clippy 0.1.95 (59807616e1 2026-04-14)` are available after sourcing `$HOME/.cargo/env`.
+
+- Observation: Rust formatting is clean after applying formatter output.
+  - Procedure/source: Ran `cargo fmt --all`, then `cargo fmt --all --check` from `/Users/crlough/Code/personal/rtk`.
+  - Actual result: `cargo fmt --all --check` exited `0` with no output.
+
+- Observation: Full Rust clippy gate passes.
+  - Procedure/source: Ran `cargo clippy --all-targets` from `/Users/crlough/Code/personal/rtk`.
+  - Actual result: `clippy_exit=0`; tail output included `Finished dev profile [unoptimized + debuginfo] target(s) in 0.41s`.
+
+- Observation: Full Rust test suite passes.
+  - Procedure/source: Ran `cargo test --all` from `/Users/crlough/Code/personal/rtk`.
+  - Actual result: `test_all_exit=0`; tail output included `test result: ok. 1919 passed; 0 failed; 6 ignored; 0 measured; 0 filtered out; finished in 1.74s`.
+
+- Observation: The implemented `rtk init --agent pi` install path writes the extension into an isolated Pi config directory and the installed file matches the repo artifact.
+  - Procedure/source: Ran `TMP_PI_DIR=$(mktemp -d); PI_CODING_AGENT_DIR="$TMP_PI_DIR" cargo run --quiet -- init --agent pi; cmp -s hooks/pi/rtk.ts "$TMP_PI_DIR/extensions/rtk.ts"; ls -l "$TMP_PI_DIR/extensions/rtk.ts"; PI_CODING_AGENT_DIR="$TMP_PI_DIR" cargo run --quiet -- init --agent pi`.
+  - Actual result: `cargo run` reported `Pi extension installed`; `cmp` exited successfully; `ls` showed `$TMP_PI_DIR/extensions/rtk.ts` with size `1728` bytes; second run completed successfully.
+
+- Observation: The implemented `rtk init --agent pi` install path was run for the current user after audit follow-up, and the installed file matches the repo artifact.
+  - Procedure/source: Ran `cargo run --quiet -- init --agent pi; cmp -s hooks/pi/rtk.ts /Users/crlough/.pi/agent/extensions/rtk.ts; ls -l /Users/crlough/.pi/agent/extensions/rtk.ts`.
+  - Actual result: `cargo run` reported `Pi extension installed`; `cmp` exited successfully; `ls` showed `/Users/crlough/.pi/agent/extensions/rtk.ts` with size `1958` bytes.
+
+## Artifacts
+
+- `hooks/pi/rtk.ts` - repo Pi extension artifact installed for the current user.
+- `/Users/crlough/.pi/agent/extensions/rtk.ts` - installed Pi extension file, matching `hooks/pi/rtk.ts` at observation time.
+- Command excerpt: `rtk rewrite "git status"` produced `rtk git status` with exit code `3`, which the extension catch path handles.
+- Command excerpt: `cargo fmt --all --check` exited `0` with no output.
+- Command excerpt: `cargo clippy --all-targets` exited `0`.
+- Command excerpt: `cargo test --all` ended with `test result: ok. 1919 passed; 0 failed; 6 ignored; 0 measured; 0 filtered out; finished in 1.74s`.
+- Command excerpt: isolated `PI_CODING_AGENT_DIR="$TMP_PI_DIR" cargo run --quiet -- init --agent pi` wrote `$TMP_PI_DIR/extensions/rtk.ts`, and `cmp -s hooks/pi/rtk.ts "$TMP_PI_DIR/extensions/rtk.ts"` succeeded.
+- Command excerpt: current-user `cargo run --quiet -- init --agent pi` wrote `/Users/crlough/.pi/agent/extensions/rtk.ts`, and `cmp -s hooks/pi/rtk.ts /Users/crlough/.pi/agent/extensions/rtk.ts` succeeded.
+
+## What This Shows
+
+- `ticket:20260521-pi-extension#ACC-001` - supports - the extension artifact targets Pi `bash` tool calls and the observed helper logic rewrites `git status` through `rtk rewrite`, including RTK's exit-code-3 path; full Rust tests also pass after adding the integration code.
+- `ticket:20260521-pi-extension#ACC-002` - supports - source inspection, Rust tests, formatting, and an isolated `PI_CODING_AGENT_DIR` `cargo run -- init --agent pi` install confirmed the path writes the expected extension file and handles a repeat run.
+- `ticket:20260521-pi-extension#ACC-003` - supports - README, supported-agent guide, hook docs, and Pi README all contain Pi install/behavior documentation.
+- `ticket:20260521-pi-extension#ACC-004` - supports - the extension is installed at `/Users/crlough/.pi/agent/extensions/rtk.ts` and matched the repo artifact when copied.
+
+## What This Does Not Show
+
+- Does not prove Pi has reloaded the extension in the currently running session; restart Pi or run `/reload` to activate the installed file.
+- Does not exercise an actual Pi `tool_call` event end-to-end; it only verifies the installed artifact and rewrite helper behavior.
+- Does not prove behavior for every RTK rewrite pattern or every shell edge case.
+
+## Related Records
+
+- `ticket:20260521-pi-extension` - owns the executable work and acceptance criteria this dossier supports.

.loom/tickets/20260521-pi-extension.md

@@ -0,0 +1,65 @@
+# Add Pi Extension Integration
+
+ID: ticket:20260521-pi-extension
+Type: Ticket
+Status: closed
+Created: 2026-05-21
+Updated: 2026-05-21
+Risk: medium - adds a new agent integration path and writes into the user's Pi config, but the runtime extension is narrow, fail-open, and locally verifiable.
+
+## Summary
+
+Add first-class RTK support for Pi by shipping a Pi extension that intercepts Pi `bash` tool calls, delegates rewrite decisions to `rtk rewrite`, and mutates the command before execution when RTK has a compact equivalent. The single closure claim is: RTK can install a Pi extension with `rtk init --agent pi`, and the installed extension rewrites Pi bash commands through the existing RTK rewrite registry without blocking command execution when RTK is unavailable or rewrite fails.
+
+## Related Records
+
+- `README.md` - public quick-start and supported-agent table must mention Pi.
+- `docs/guide/getting-started/supported-agents.md` - durable user-facing supported-agent guide must include Pi install behavior.
+- `hooks/README.md` - hook/plugin architecture record must describe the Pi extension and fail-open behavior.
+- `/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/README.md` - Pi extension locations and capabilities; Pi auto-discovers `~/.pi/agent/extensions/*.ts`.
+- `/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/docs/extensions.md` - Pi `tool_call` handlers can mutate built-in `bash` tool input before execution.
+
+## Scope
+
+May change RTK source, docs, and hook artifacts needed for a Pi integration:
+
+- add a `hooks/pi/` TypeScript extension artifact and README;
+- add `--agent pi` CLI dispatch and installation logic that writes the extension under the Pi agent config directory;
+- update supported-agent documentation and tests;
+- install the extension for the current user after implementation.
+
+Must not change RTK command filtering behavior, the rewrite registry semantics, Pi itself, or unrelated agent integrations. The extension must be a thin delegate to `rtk rewrite`, fail open on missing binary/errors/timeouts, and only mutate Pi `bash` tool calls.
+
+Evidence posture: compile/test the touched Rust installation logic where practical, inspect installed extension location, and smoke-test the extension's rewrite helper behavior by invoking `rtk rewrite` or running the install path. Review posture: separate audit would add limited value for this local integration slice if tests and inspection cover dispatch, install path, docs, and fail-open extension behavior.
+
+## Acceptance
+
+- ACC-001: The repo contains a Pi extension artifact that Pi can load from its extension directory, and it rewrites only `bash` tool commands by calling `rtk rewrite` while failing open on errors.
+  - Evidence: source inspection plus a lightweight test or type/format-compatible implementation review.
+  - Audit: verify no unrelated tool mutation and no blocking behavior on rewrite failure.
+
+- ACC-002: `rtk init --agent pi` installs the Pi extension idempotently into the Pi agent config directory, respecting `PI_CODING_AGENT_DIR` when set and dry-run behavior when requested.
+  - Evidence: Rust tests for path resolution/install/idempotence/dry-run or an equivalent command run in an isolated config directory.
+  - Audit: inspect that install writes only the expected extension path.
+
+- ACC-003: User-facing docs list Pi as a supported plugin integration and show the install command.
+  - Evidence: grep/read updated README and supported-agent docs.
+  - Audit: docs match implemented command and behavior.
+
+- ACC-004: The Pi extension is installed for the current user.
+  - Evidence: installed `~/.pi/agent/extensions/rtk.ts` exists and matches the repo artifact or install output reports it.
+  - Audit: note if Pi must be restarted/reloaded for activation.
+
+## Current State
+
+Closed. Implementation, local install, Rust validation, and audit are complete. The repo now contains a Pi TypeScript extension artifact, `--agent pi` CLI/install dispatch, docs, and Rust tests/source coverage for the install path. The extension is installed at `/Users/crlough/.pi/agent/extensions/rtk.ts` and matched the repo artifact after the final source install. Validation evidence is recorded in `evidence:20260521-pi-extension-validation`: Rust toolchain installed, `cargo fmt --all --check` passes, `cargo clippy --all-targets` passes, `cargo test --all` passes, isolated `PI_CODING_AGENT_DIR` install works, and current-user install works. Audit `audit:20260521-pi-extension-audit` returned `clear` with no material findings. Residual risk: no live Pi end-to-end `tool_call` execution was observed, and the user must restart Pi or run `/reload` for the installed extension to activate.
+
+## Journal
+
+- 2026-05-21: Created ticket with Status `open` from the operator request to add and install RTK Pi support.
+- 2026-05-21: Set Status to `active`; current session is executing the bounded Ralph implementation slice in the main rtk worktree.
+- 2026-05-21: Added Pi extension artifact, CLI install/uninstall dispatch, docs, and tests/source support; manually installed the extension to `/Users/crlough/.pi/agent/extensions/rtk.ts` because the currently installed `rtk` binary predates `--agent pi`.
+- 2026-05-21: Recorded validation dossier `evidence:20260521-pi-extension-validation`. `cargo fmt` and Rust tests were not run because no Rust toolchain was available in this environment. Set Status to `review` pending Rust-toolchain verification or external review.
+- 2026-05-21: Installed Rust with rustup after confirming Xcode Command Line Tools were present. Added `rustfmt` and `clippy` components. Ran `cargo fmt`, `cargo fmt --check` (pass), `cargo test` (pass: 1919 passed, 0 failed, 6 ignored), and isolated `PI_CODING_AGENT_DIR` `cargo run -- init --agent pi` with matching installed extension output. Updated `evidence:20260521-pi-extension-validation` with the results.
+- 2026-05-21: Ran a bounded Ralph audit pass. Initial findings identified stale current-user install evidence, a fail-open overclaim, and missing clippy/`--all` quality-gate evidence. Fixed the extension with a top-level handler `try/catch`, reinstalled for current user with `cargo run -- init --agent pi`, ran `cargo fmt --all --check`, `cargo clippy --all-targets`, and `cargo test --all`, and updated evidence.
+- 2026-05-21: Ran final bounded Ralph audit follow-up and recorded `audit:20260521-pi-extension-audit`; verdict `clear`, no material findings within audited scope. Closed ticket with residual risk limited to no live Pi end-to-end `tool_call` observation and requiring Pi restart or `/reload` for activation.