From 1da5793b9293cca5fca3e316bda18ed02443f2e2 Mon Sep 17 00:00:00 2001
From: gitbluf <gh+git@gitbluf.xyz>
Date: Wed, 6 May 2026 15:43:04 +0200
Subject: [PATCH 01/13] feat(hooks): add Pi coding agent integration

---
 hooks/README.md           |  10 +-
 hooks/pi/README.md        |  37 +++
 hooks/pi/rtk-awareness.md |  37 +++
 hooks/pi/rtk.ts           | 132 +++++++++
 src/hooks/constants.rs    |   9 +
 src/hooks/init.rs         | 550 +++++++++++++++++++++++++++++++++++++-
 src/main.rs               | 144 ++++++----
 7 files changed, 867 insertions(+), 52 deletions(-)
 create mode 100644 hooks/pi/README.md
 create mode 100644 hooks/pi/rtk-awareness.md
 create mode 100644 hooks/pi/rtk.ts

diff --git a/hooks/README.md b/hooks/README.md
index 6a6744281..c15d9a357 100644
--- a/hooks/README.md
+++ b/hooks/README.md
@@ -4,7 +4,7 @@
 
 **Deployed hook artifacts** — the actual files installed on user machines by `rtk init`. These are shell scripts, TypeScript plugins, and rules files that run outside the Rust binary. They are **thin delegates**: parse agent-specific JSON, call `rtk rewrite` as a subprocess, format agent-specific response. Zero filtering logic lives here.
 
-Owns: per-agent hook scripts and configuration files for 7 supported agents (Claude Code, Copilot, Cursor, Cline, Windsurf, Codex, OpenCode).
+Owns: per-agent hook scripts and configuration files for 8 supported agents (Claude Code, Copilot, Cursor, Cline, Windsurf, Codex, OpenCode, Pi).
 
 Does **not** own: hook installation/uninstallation (that's `src/hooks/init.rs`), the rewrite pattern registry (that's `discover/registry`), or integrity verification (that's `src/hooks/integrity.rs`).
 
@@ -40,6 +40,7 @@ Each agent subdirectory has its own README with hook-specific details:
 - **[`windsurf/`](windsurf/README.md)** — Rules file (prompt-level), `.windsurfrules` workspace-scoped
 - **[`codex/`](codex/README.md)** — Awareness document, `AGENTS.md` integration, `$CODEX_HOME` or `~/.codex/` location
 - **[`opencode/`](opencode/README.md)** — TypeScript plugin, `zx` library, `tool.execute.before` event, in-place mutation
+- **[`pi/`](pi/README.md)** — TypeScript extension, `tool_call` event, `isToolCallEventType` guard, in-place mutation, `~/.pi/agent/extensions/`
 
 ## Supported Agents
 
@@ -54,6 +55,7 @@ Each agent subdirectory has its own README with hook-specific details:
 | Windsurf | Custom instructions (rules file) | Prompt-level guidance | N/A |
 | Codex CLI | AGENTS.md / instructions | Prompt-level guidance | N/A |
 | OpenCode | TypeScript plugin (`tool.execute.before`) | In-place mutation | Yes |
+| Pi | TypeScript extension (`tool_call` event) | In-place mutation | Yes |
 
 ## JSON Formats by Agent
 
@@ -217,7 +219,7 @@ New integrations must follow the [Exit Code Contract](#exit-code-contract) and [
 | Tier | Mechanism | Maintenance | Examples |
 |------|-----------|-------------|----------|
 | **Full hook** | Shell script or Rust binary, intercepts commands via agent's hook API | High — must track agent API changes | Claude Code, Cursor, Copilot, Gemini |
-| **Plugin** | TypeScript/JS plugin in agent's plugin system | Medium — agent manages loading | OpenCode |
+| **Plugin** | TypeScript/JS plugin in agent's plugin system | Medium — agent manages loading | OpenCode, Pi |
 | **Rules file** | Prompt-level instructions the agent reads | Low — no code to break | Cline, Windsurf, Codex |
 
 ### Eligibility
@@ -233,3 +235,7 @@ RTK supports AI coding assistants that developers actually use day-to-day. To ad
 
 If an agent's API changes and the hook breaks, the integration should be updated promptly. If the agent becomes unmaintained or the hook can't be fixed, the integration may be deprecated with a release note.
 
+### Worked Example
+
+See [`docs/specs/pi-hook-integration.md`](../docs/specs/pi-hook-integration.md) for a complete integration SPEC — covering design, component inventory, exit-code mapping, install layout, error handling, and testing strategy. Use it as a template when speccing new agent integrations.
+
diff --git a/hooks/pi/README.md b/hooks/pi/README.md
new file mode 100644
index 000000000..ceb7dc01f
--- /dev/null
+++ b/hooks/pi/README.md
@@ -0,0 +1,37 @@
+# Pi Hooks
+
+> Part of [`hooks/`](../README.md) — see also [`src/hooks/`](../../src/hooks/README.md) for installation code
+
+## Specifics
+
+- TypeScript extension using Pi's `ExtensionAPI` (not a shell hook, no `zx` dependency)
+- Subscribes to `tool_call` event, narrows to `bash` tool via `isToolCallEventType`
+- Calls `rtk rewrite` as a subprocess; mutates `event.input.command` in-place if rewrite differs
+- Returns `{ block: true, reason }` on deny (exit code 2); all other error paths return `undefined`
+- Version guard at load time: checks `rtk >= 0.23.0`; warns and registers no-op if too old or missing
+- Installed to `.pi/extensions/rtk.ts` by `rtk init --pi` (project-local) or `~/.pi/agent/extensions/rtk.ts` by `rtk init --pi --global`
+- `rtk-awareness.md` is embedded into `AGENTS.md` by `rtk init --pi`
+
+## Testing
+
+```bash
+# Load the extension directly without installing
+pi -e ./hooks/pi/rtk.ts
+
+# Verify rewrites are active — ask the agent to run a command, then check history
+rtk gain --history   # should show rtk-prefixed commands with savings %
+
+# Test RTK_DISABLED passthrough
+RTK_DISABLED=1 pi -e ./hooks/pi/rtk.ts
+# → commands pass through unchanged; no rewrites in rtk gain --history
+
+# Test version guard — temporarily shadow rtk with a stub that prints "rtk 0.22.0"
+# → extension logs a warning at startup and registers a no-op; pi starts normally
+```
+
+## Design Notes
+
+- All filtering logic lives in `rtk rewrite` (the Rust registry), not in this file
+- Exit code 3 (ask) is treated as allow — Pi has no per-tool confirmation UI
+- No `zx` library required; uses `node:child_process` `spawn` directly
+- See [`docs/specs/pi-hook-integration.md`](../../docs/specs/pi-hook-integration.md) for the full design spec
diff --git a/hooks/pi/rtk-awareness.md b/hooks/pi/rtk-awareness.md
new file mode 100644
index 000000000..7bfe0dac6
--- /dev/null
+++ b/hooks/pi/rtk-awareness.md
@@ -0,0 +1,37 @@
+# RTK — Rust Token Killer
+
+**Usage**: Token-optimized CLI proxy. Commands are automatically rewritten
+by the RTK extension before they execute — no changes to your workflow needed.
+
+## Meta Commands
+
+```bash
+rtk gain              # Show token savings analytics
+rtk gain --history    # Show recent command savings history
+rtk proxy <cmd>       # Run raw command without filtering (bypass RTK)
+```
+
+## Verification
+
+```bash
+rtk --version         # Should show: rtk X.Y.Z
+rtk gain              # Should work (not "command not found")
+which rtk             # Verify correct binary in PATH
+```
+
+⚠️ **Name collision**: Two packages share the name `rtk`. If `rtk gain`
+fails, you may have `reachingforthejack/rtk` (Rust Type Kit) installed
+instead. See the RTK README for installation instructions.
+
+## How It Works
+
+The RTK extension intercepts every bash tool call and transparently rewrites
+commands to their token-optimized equivalents before execution:
+
+```
+git status          →  rtk git status      (~70% fewer tokens)
+cargo test          →  rtk cargo test      (~90% fewer tokens)
+npm run build       →  rtk npm run build   (~80% fewer tokens)
+```
+
+Rewrites are invisible — the LLM sees only the filtered output.
diff --git a/hooks/pi/rtk.ts b/hooks/pi/rtk.ts
new file mode 100644
index 000000000..8fec20512
--- /dev/null
+++ b/hooks/pi/rtk.ts
@@ -0,0 +1,132 @@
+// rtk-hook-version: 1
+// RTK Pi extension — rewrites bash commands to use rtk for token savings.
+// Requires: rtk >= 0.23.0 in PATH.
+//
+// This is a thin delegating extension: all rewrite logic lives in `rtk rewrite`,
+// which is the single source of truth (src/discover/registry.rs).
+// To add or change rewrite rules, edit the Rust registry — not this file.
+//
+// Exit code contract for `rtk rewrite`:
+//   0 + stdout  Rewrite found → mutate command, allow
+//   1           No RTK equivalent → pass through unchanged
+//   2           Deny rule matched → block execution
+//   3 + stdout  Ask rule matched → mutate command, allow (Pi has no confirm UI)
+
+import { spawn } from "node:child_process"
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"
+import { isToolCallEventType } from "@mariozechner/pi-coding-agent"
+
+// Run a command, return { stdout, exitCode } or null on spawn error / timeout.
+function exec(cmd: string, args: string[], timeoutMs = 2000): Promise<{ stdout: string; exitCode: number } | null> {
+  return new Promise((resolve) => {
+    let stdout = ""
+    let settled = false
+
+    const child = spawn(cmd, args, { env: process.env })
+
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true
+        child.kill()
+        resolve(null)
+      }
+    }, timeoutMs)
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString()
+    })
+
+    child.on("close", (code: number | null) => {
+      if (!settled) {
+        settled = true
+        clearTimeout(timer)
+        resolve({ stdout, exitCode: code ?? 1 })
+      }
+    })
+
+    child.on("error", () => {
+      if (!settled) {
+        settled = true
+        clearTimeout(timer)
+        resolve(null)
+      }
+    })
+  })
+}
+
+// Parse "X.Y.Z" semver, return [major, minor, patch] or null.
+function parseSemver(raw: string): [number, number, number] | null {
+  const m = raw.trim().match(/(\d+)\.(\d+)\.(\d+)/)
+  if (!m) return null
+  return [parseInt(m[1], 10), parseInt(m[2], 10), parseInt(m[3], 10)]
+}
+
+export default async function (pi: ExtensionAPI) {
+  // Load-time check: probe rtk by running --version. This confirms the binary
+  // is in PATH and gives us the version for the semver guard in one spawn.
+  const ver = await exec("rtk", ["--version"])
+  if (!ver || ver.exitCode !== 0) {
+    console.warn("[rtk] rtk binary not found in PATH — extension disabled")
+    return
+  }
+
+  // Load-time version guard: rtk rewrite was introduced in 0.23.0. Without
+  // this check the extension still degrades gracefully — exec() returns null
+  // on any subprocess failure, which falls through to pass-through behaviour.
+  // The guard exists purely to surface a clear, actionable warning
+  // ("your rtk is too old, upgrade") rather than leaving the user wondering
+  // why rewrites silently stopped working after a version rollback.
+  // stdout format: "rtk X.Y.Z"
+  const parsed = parseSemver(ver.stdout.replace(/^rtk\s+/, ""))
+  if (parsed) {
+    const [major, minor] = parsed
+    if (major === 0 && minor < 23) {
+      console.warn(`[rtk] rtk ${ver.stdout.trim()} is too old (need >= 0.23.0) — extension disabled`)
+      return
+    }
+  }
+
+  pi.on("tool_call", async (event) => {
+    // Only intercept bash tool calls.
+    if (!isToolCallEventType("bash", event)) return
+
+    const cmd = event.input.command
+    if (!cmd) return
+
+    if (cmd.startsWith("rtk ")) return
+    if (process.env.RTK_DISABLED === "1") return
+
+    // Delegate all rewrite + permission logic to the RTK.
+    const result = await exec("rtk", ["rewrite", cmd])
+    if (!result) return // spawn error or timeout — pass through
+
+    const rewritten = result.stdout.trim()
+
+    switch (result.exitCode) {
+      case 0:
+        // Rewrite found — mutate the command in-place.
+        if (rewritten && rewritten !== cmd) {
+          event.input.command = rewritten
+        }
+        return
+
+      case 1:
+        // No RTK equivalent — pass through unchanged.
+        return
+
+      case 2:
+        // Deny rule matched — block execution.
+        return { block: true, reason: `RTK: '${cmd}' is blocked — see rtk gain for details` }
+
+      case 3:
+        // Ask rule matched — rewrite and allow (Pi has no per-tool confirm UI).
+        if (rewritten && rewritten !== cmd) {
+          event.input.command = rewritten
+        }
+        return
+
+      default:
+        return
+    }
+  })
+}
diff --git a/src/hooks/constants.rs b/src/hooks/constants.rs
index 1d9f33ccd..0aa435537 100644
--- a/src/hooks/constants.rs
+++ b/src/hooks/constants.rs
@@ -21,3 +21,12 @@ pub const OPENCODE_PLUGIN_FILE: &str = "rtk.ts";
 pub const CURSOR_DIR: &str = ".cursor";
 pub const CODEX_DIR: &str = ".codex";
 pub const GEMINI_DIR: &str = ".gemini";
+
+/// Default Pi config subdirectory under $HOME
+pub const PI_DIR: &str = ".pi/agent";
+/// Subdirectory inside the Pi config dir where extensions live
+pub const PI_EXTENSIONS_SUBDIR: &str = "extensions";
+/// Filename for the installed RTK extension
+pub const PI_PLUGIN_FILE: &str = "rtk.ts";
+/// Environment variable that overrides the Pi config directory
+pub const PI_CODING_AGENT_DIR_ENV: &str = "PI_CODING_AGENT_DIR";
diff --git a/src/hooks/init.rs b/src/hooks/init.rs
index c6bd05c2b..51662a3c9 100644
--- a/src/hooks/init.rs
+++ b/src/hooks/init.rs
@@ -1,6 +1,8 @@
 //! Sets up RTK hooks so AI coding agents automatically route commands through RTK.
 
 use anyhow::{Context, Result};
+use lazy_static::lazy_static;
+use regex::Regex;
 use std::fs;
 use std::io::Write;
 use std::path::{Path, PathBuf};
@@ -12,16 +14,21 @@ use crate::hooks::constants::{
 
 use super::constants::{
     BEFORE_TOOL_KEY, CLAUDE_DIR, CLAUDE_HOOK_COMMAND, CODEX_DIR, CURSOR_HOOK_COMMAND,
-    GEMINI_HOOK_FILE, HOOKS_JSON, HOOKS_SUBDIR, PRE_TOOL_USE_KEY, REWRITE_HOOK_FILE, SETTINGS_JSON,
+    GEMINI_HOOK_FILE, HOOKS_JSON, HOOKS_SUBDIR, PI_CODING_AGENT_DIR_ENV, PI_DIR,
+    PI_EXTENSIONS_SUBDIR, PI_PLUGIN_FILE, PRE_TOOL_USE_KEY, REWRITE_HOOK_FILE, SETTINGS_JSON,
 };
 use super::integrity;
 
 // Embedded OpenCode plugin (auto-rewrite)
 const OPENCODE_PLUGIN: &str = include_str!("../../hooks/opencode/rtk.ts");
 
+// Embedded Pi extension (auto-rewrite)
+const PI_PLUGIN: &str = include_str!("../../hooks/pi/rtk.ts");
+
 // Embedded slim RTK awareness instructions
 const RTK_SLIM: &str = include_str!("../../hooks/claude/rtk-awareness.md");
 const RTK_SLIM_CODEX: &str = include_str!("../../hooks/codex/rtk-awareness.md");
+const RTK_SLIM_PI: &str = include_str!("../../hooks/pi/rtk-awareness.md");
 
 /// Template written by `rtk init` when no filters.toml exists yet.
 const FILTERS_TEMPLATE: &str = r#"# Project-local RTK filters — commit this file with your repo.
@@ -541,8 +548,15 @@ fn remove_hook_from_settings(verbose: u8) -> Result<bool> {
     Ok(removed)
 }
 
-/// Full uninstall for Claude, Gemini, Codex, or Cursor artifacts.
-pub fn uninstall(global: bool, gemini: bool, codex: bool, cursor: bool, verbose: u8) -> Result<()> {
+/// Full uninstall for Claude, Gemini, Codex, Cursor, or Pi artifacts.
+pub fn uninstall(
+    global: bool,
+    gemini: bool,
+    codex: bool,
+    cursor: bool,
+    pi: bool,
+    verbose: u8,
+) -> Result<()> {
     if codex {
         return uninstall_codex(global, verbose);
     }
@@ -565,6 +579,35 @@ pub fn uninstall(global: bool, gemini: bool, codex: bool, cursor: bool, verbose:
         return Ok(());
     }
 
+    if pi {
+        let plugin_path = pi_plugin_path_for_scope(global)?;
+        let mut removed = Vec::new();
+
+        if plugin_path.exists() {
+            fs::remove_file(&plugin_path).with_context(|| {
+                format!("Failed to remove Pi extension: {}", plugin_path.display())
+            })?;
+            if verbose > 0 {
+                eprintln!("Removed Pi extension: {}", plugin_path.display());
+            }
+            removed.push(plugin_path);
+        }
+
+        let agents_md = pi_agents_md_path_for_scope(global)?;
+        remove_pi_awareness(&agents_md, verbose).context("Failed to remove Pi awareness block")?;
+
+        if !removed.is_empty() {
+            println!("RTK uninstalled (Pi):");
+            for path in &removed {
+                println!("  - {}", path.display());
+            }
+            println!("\nRestart pi to apply changes.");
+        } else {
+            println!("RTK Pi extension was not installed (nothing to remove)");
+        }
+        return Ok(());
+    }
+
     if !global {
         anyhow::bail!("Uninstall only works with --global flag. For local projects, manually remove RTK from CLAUDE.md");
     }
@@ -1826,6 +1869,232 @@ fn resolve_opencode_dir() -> Result<PathBuf> {
     resolve_home_subdir(CONFIG_DIR).map(|p| p.join(OPENCODE_SUBDIR))
 }
 
+// ─── Pi coding agent support ──────────────────────────────────────────
+
+/// Resolve Pi config directory, honouring `PI_CODING_AGENT_DIR` override.
+fn resolve_pi_dir() -> Result<PathBuf> {
+    if let Ok(dir) = std::env::var(PI_CODING_AGENT_DIR_ENV) {
+        if !dir.is_empty() {
+            return Ok(PathBuf::from(dir));
+        }
+    }
+    resolve_home_subdir(PI_DIR)
+}
+
+/// Return the path to the installed Pi extension file.
+fn pi_plugin_path(pi_dir: &Path) -> PathBuf {
+    pi_dir.join(PI_EXTENSIONS_SUBDIR).join(PI_PLUGIN_FILE)
+}
+
+/// Return the Pi extension install path for the given scope.
+/// global=true  → `$PI_CODING_AGENT_DIR/extensions/rtk.ts`
+/// global=false → `./.pi/extensions/rtk.ts`
+fn pi_plugin_path_for_scope(global: bool) -> Result<PathBuf> {
+    if global {
+        Ok(pi_plugin_path(&resolve_pi_dir()?))
+    } else {
+        Ok(PathBuf::from(".pi")
+            .join(PI_EXTENSIONS_SUBDIR)
+            .join(PI_PLUGIN_FILE))
+    }
+}
+
+/// Return the AGENTS.md path for the given Pi install scope.
+/// global=true  → `$PI_CODING_AGENT_DIR/AGENTS.md`
+/// global=false → `./AGENTS.md`
+fn pi_agents_md_path_for_scope(global: bool) -> Result<PathBuf> {
+    if global {
+        Ok(resolve_pi_dir()?.join(AGENTS_MD))
+    } else {
+        Ok(PathBuf::from(AGENTS_MD))
+    }
+}
+
+/// Write the Pi extension file if missing or outdated. Returns true if written.
+fn ensure_pi_plugin_installed(path: &Path, verbose: u8) -> Result<bool> {
+    write_if_changed(path, PI_PLUGIN, "Pi extension", verbose)
+}
+
+/// Sentinel constants for the Pi awareness block in AGENTS.md.
+const PI_AWARENESS_START: &str = "<!-- rtk-pi-start v1 -->";
+const PI_AWARENESS_END: &str = "<!-- rtk-pi-end -->";
+
+lazy_static! {
+    /// Matches the full sentinel block including any preceding newline so
+    /// replacement leaves no double-blank gaps.
+    static ref PI_SENTINEL_RE: Regex =
+        Regex::new(r"(?s)\n?<!-- rtk-pi-start[^>]*-->.*?<!-- rtk-pi-end -->").unwrap();
+}
+
+/// Build the full sentinel-wrapped awareness block.
+fn pi_awareness_block() -> String {
+    format!(
+        "{}\n{}\n{}",
+        PI_AWARENESS_START,
+        RTK_SLIM_PI.trim(),
+        PI_AWARENESS_END
+    )
+}
+
+/// Append or update the RTK awareness block in a Pi AGENTS.md file.
+///
+/// Uses sentinel comments for idempotent install / version-bump updates:
+/// - Sentinels absent  → append block with a blank-line separator
+/// - Sentinels present, content identical → no-op
+/// - Sentinels present, content differs   → replace block in-place
+fn install_pi_awareness(agents_md_path: &Path, verbose: u8) -> Result<()> {
+    let block = pi_awareness_block();
+
+    if agents_md_path.exists() {
+        let existing = fs::read_to_string(agents_md_path)
+            .with_context(|| format!("Failed to read {}", agents_md_path.display()))?;
+
+        if existing.contains(&block) {
+            if verbose > 0 {
+                eprintln!(
+                    "Pi awareness already up to date: {}",
+                    agents_md_path.display()
+                );
+            }
+            return Ok(());
+        }
+
+        let updated = if PI_SENTINEL_RE.is_match(&existing) {
+            // Sentinels present but content differs (version bump) — replace in-place.
+            PI_SENTINEL_RE
+                .replace(&existing, format!("\n{}", block).as_str())
+                .into_owned()
+        } else {
+            // No sentinels yet — append with a blank-line separator.
+            format!("{}\n\n{}", existing.trim_end(), block)
+        };
+
+        atomic_write(agents_md_path, &updated)
+            .with_context(|| format!("Failed to write {}", agents_md_path.display()))?;
+
+        if verbose > 0 {
+            eprintln!("Updated Pi awareness: {}", agents_md_path.display());
+        }
+    } else {
+        // File absent — create it containing only the awareness block.
+        atomic_write(agents_md_path, &block)
+            .with_context(|| format!("Failed to create {}", agents_md_path.display()))?;
+
+        if verbose > 0 {
+            eprintln!("Created Pi awareness: {}", agents_md_path.display());
+        }
+    }
+
+    Ok(())
+}
+
+/// Remove the RTK awareness sentinel block from an AGENTS.md file.
+/// If the sentinels are absent this is a no-op.
+fn remove_pi_awareness(agents_md_path: &Path, verbose: u8) -> Result<()> {
+    if !agents_md_path.exists() {
+        return Ok(());
+    }
+
+    let existing = fs::read_to_string(agents_md_path)
+        .with_context(|| format!("Failed to read {}", agents_md_path.display()))?;
+
+    if !PI_SENTINEL_RE.is_match(&existing) {
+        return Ok(());
+    }
+
+    let updated = PI_SENTINEL_RE.replace(&existing, "").into_owned();
+    atomic_write(agents_md_path, updated.trim_end())
+        .with_context(|| format!("Failed to write {}", agents_md_path.display()))?;
+
+    if verbose > 0 {
+        eprintln!(
+            "Removed Pi awareness block from: {}",
+            agents_md_path.display()
+        );
+    }
+
+    Ok(())
+}
+
+/// Install the Pi extension and inject the awareness block into AGENTS.md.
+///
+/// global=true  → `$PI_CODING_AGENT_DIR/extensions/rtk.ts` + `$PI_CODING_AGENT_DIR/AGENTS.md`
+/// global=false → `.pi/extensions/rtk.ts` + `./AGENTS.md`
+///
+/// AGENTS.md injection is skipped in global mode when the Pi config directory
+/// did not previously exist (the user has not yet run `pi`). The extension is
+/// still written so the user gets immediate coverage once they do initialise Pi.
+pub fn run_pi_mode(global: bool, verbose: u8) -> Result<()> {
+    let mut should_install_awareness = true;
+
+    let plugin_path = if global {
+        let pi_dir = resolve_pi_dir()?;
+        // Capture existence *before* we create subdirectories.
+        let pi_dir_preexisting = pi_dir.exists();
+
+        let path = pi_plugin_path(&pi_dir);
+        if let Some(parent) = path.parent() {
+            fs::create_dir_all(parent).with_context(|| {
+                format!(
+                    "Failed to create Pi extensions directory: {}",
+                    parent.display()
+                )
+            })?;
+        }
+
+        if !pi_dir_preexisting {
+            should_install_awareness = false;
+        }
+
+        path
+    } else {
+        let path = pi_plugin_path_for_scope(false)?;
+        if let Some(parent) = path.parent() {
+            fs::create_dir_all(parent).with_context(|| {
+                format!(
+                    "Failed to create local Pi extensions directory: {}",
+                    parent.display()
+                )
+            })?;
+        }
+        path
+    };
+
+    let installed = ensure_pi_plugin_installed(&plugin_path, verbose)?;
+    let agents_md_path = pi_agents_md_path_for_scope(global)?;
+
+    if should_install_awareness {
+        install_pi_awareness(&agents_md_path, verbose)?;
+        print_pi_result(&plugin_path, Some(&agents_md_path), installed);
+    } else {
+        eprintln!(
+            "[rtk] Pi config directory not found ({}).\n\
+             Extension installed but skipping AGENTS.md injection.\n\
+             Create the directory or run `pi` once to initialise it.",
+            resolve_pi_dir()?.display()
+        );
+        print_pi_result(&plugin_path, None, installed);
+    }
+
+    Ok(())
+}
+
+fn print_pi_result(plugin_path: &Path, agents_md_path: Option<&Path>, installed: bool) {
+    let status = if installed {
+        "installed"
+    } else {
+        "already up to date"
+    };
+    println!("RTK Pi extension {}:", status);
+    println!("  Extension: {}", plugin_path.display());
+    if let Some(p) = agents_md_path {
+        println!("  AGENTS.md: {}", p.display());
+    }
+    println!();
+    println!("Pi will load the extension automatically on next start.");
+    println!("Verify: pi -e {} --no-session", plugin_path.display());
+}
+
 /// Return OpenCode plugin path: ~/.config/opencode/plugins/rtk.ts
 fn opencode_plugin_path(opencode_dir: &Path) -> PathBuf {
     opencode_dir.join(PLUGIN_SUBDIR).join(OPENCODE_PLUGIN_FILE)
@@ -3740,6 +4009,9 @@ mod tests {
 
     use std::sync::Mutex;
     static CLAUDE_DIR_LOCK: Mutex<()> = Mutex::new(());
+    static PI_DIR_LOCK: Mutex<()> = Mutex::new(());
+    /// Serialises all tests that mutate the process-wide working directory.
+    static CWD_LOCK: Mutex<()> = Mutex::new(());
 
     fn with_claude_dir_override<F: FnOnce(&Path)>(tmp: &TempDir, f: F) {
         let _guard = CLAUDE_DIR_LOCK.lock().unwrap_or_else(|e| e.into_inner());
@@ -3755,6 +4027,20 @@ mod tests {
         }
     }
 
+    fn with_pi_dir_override<F: FnOnce(&Path)>(tmp: &TempDir, f: F) {
+        let _guard = PI_DIR_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let pi_dir = tmp.path().join("pi_agent");
+        fs::create_dir_all(&pi_dir).unwrap();
+
+        let orig = std::env::var_os(PI_CODING_AGENT_DIR_ENV);
+        std::env::set_var(PI_CODING_AGENT_DIR_ENV, &pi_dir);
+        f(&pi_dir);
+        match orig {
+            Some(v) => std::env::set_var(PI_CODING_AGENT_DIR_ENV, v),
+            None => std::env::remove_var(PI_CODING_AGENT_DIR_ENV),
+        }
+    }
+
     #[test]
     fn test_global_default_mode_creates_artifacts() {
         let tmp = TempDir::new().unwrap();
@@ -3782,7 +4068,7 @@ mod tests {
         let tmp = TempDir::new().unwrap();
         with_claude_dir_override(&tmp, |claude_dir| {
             run_default_mode(true, PatchMode::Auto, 0, false).unwrap();
-            uninstall(true, false, false, false, 0).unwrap();
+            uninstall(true, false, false, false, false, 0).unwrap();
 
             assert!(!claude_dir.join(RTK_MD).exists(), "RTK.md must be removed");
             let settings_content =
@@ -3832,6 +4118,7 @@ mod tests {
     #[test]
     fn test_local_init_no_hook() {
         let tmp = TempDir::new().unwrap();
+        let _cwd_guard = CWD_LOCK.lock().unwrap_or_else(|e| e.into_inner());
         let cwd = std::env::current_dir().unwrap();
         std::env::set_current_dir(tmp.path()).unwrap();
 
@@ -3956,4 +4243,259 @@ mod tests {
             "RTK end marker must be removed"
         );
     }
+
+    // ─── Pi integration tests ───────────────────────────────────────────
+
+    #[test]
+    fn test_run_pi_mode_global_installs_plugin() {
+        let tmp = TempDir::new().unwrap();
+        with_pi_dir_override(&tmp, |pi_dir| {
+            run_pi_mode(true, 0).unwrap();
+
+            let plugin = pi_dir.join(PI_EXTENSIONS_SUBDIR).join(PI_PLUGIN_FILE);
+            assert!(plugin.exists(), "global Pi extension must be created");
+
+            let content = fs::read_to_string(&plugin).unwrap();
+            assert!(
+                content.contains("rtk rewrite"),
+                "extension must delegate to rtk rewrite"
+            );
+        });
+    }
+
+    #[test]
+    fn test_run_pi_mode_local_installs_plugin() {
+        let tmp = TempDir::new().unwrap();
+        let _cwd_guard = CWD_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let cwd = std::env::current_dir().unwrap();
+        std::env::set_current_dir(tmp.path()).unwrap();
+
+        let result = run_pi_mode(false, 0);
+        std::env::set_current_dir(&cwd).unwrap();
+        result.unwrap();
+
+        let plugin = tmp
+            .path()
+            .join(".pi")
+            .join(PI_EXTENSIONS_SUBDIR)
+            .join(PI_PLUGIN_FILE);
+        assert!(plugin.exists(), "local Pi extension must be created");
+    }
+
+    #[test]
+    fn test_run_pi_mode_global_injects_awareness() {
+        let tmp = TempDir::new().unwrap();
+        with_pi_dir_override(&tmp, |pi_dir| {
+            run_pi_mode(true, 0).unwrap();
+
+            let agents_md = pi_dir.join(AGENTS_MD);
+            assert!(agents_md.exists(), "AGENTS.md must be created");
+
+            let content = fs::read_to_string(&agents_md).unwrap();
+            assert!(
+                content.contains(PI_AWARENESS_START),
+                "AGENTS.md must contain sentinel start"
+            );
+            assert!(
+                content.contains(PI_AWARENESS_END),
+                "AGENTS.md must contain sentinel end"
+            );
+        });
+    }
+
+    #[test]
+    fn test_run_pi_mode_global_skips_awareness_when_dir_absent() {
+        let tmp = TempDir::new().unwrap();
+        let absent_dir = tmp.path().join("no_such_pi_dir");
+        let _guard = PI_DIR_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let orig = std::env::var_os(PI_CODING_AGENT_DIR_ENV);
+        std::env::set_var(PI_CODING_AGENT_DIR_ENV, &absent_dir);
+
+        let result = run_pi_mode(true, 0);
+
+        match orig {
+            Some(v) => std::env::set_var(PI_CODING_AGENT_DIR_ENV, v),
+            None => std::env::remove_var(PI_CODING_AGENT_DIR_ENV),
+        }
+
+        result.unwrap();
+
+        let plugin = absent_dir.join(PI_EXTENSIONS_SUBDIR).join(PI_PLUGIN_FILE);
+        assert!(
+            plugin.exists(),
+            "plugin must be written even when dir was absent"
+        );
+
+        let agents_md = absent_dir.join(AGENTS_MD);
+        assert!(
+            !agents_md.exists(),
+            "AGENTS.md must not be created when Pi dir was absent"
+        );
+    }
+
+    #[test]
+    fn test_install_pi_awareness_appends_to_existing_file() {
+        let tmp = TempDir::new().unwrap();
+        let path = tmp.path().join(AGENTS_MD);
+        fs::write(&path, "# Existing content\n").unwrap();
+
+        install_pi_awareness(&path, 0).unwrap();
+
+        let content = fs::read_to_string(&path).unwrap();
+        assert!(content.contains("# Existing content"));
+        assert!(content.contains(PI_AWARENESS_START));
+        assert!(content.contains(PI_AWARENESS_END));
+    }
+
+    #[test]
+    fn test_install_pi_awareness_idempotent() {
+        let tmp = TempDir::new().unwrap();
+        let path = tmp.path().join(AGENTS_MD);
+
+        install_pi_awareness(&path, 0).unwrap();
+        let content_after_first = fs::read_to_string(&path).unwrap();
+
+        install_pi_awareness(&path, 0).unwrap();
+        let content_after_second = fs::read_to_string(&path).unwrap();
+
+        assert_eq!(
+            content_after_first, content_after_second,
+            "second install must be a no-op"
+        );
+        assert_eq!(content_after_second.matches(PI_AWARENESS_START).count(), 1);
+    }
+
+    #[test]
+    fn test_install_pi_awareness_replaces_stale_block() {
+        let tmp = TempDir::new().unwrap();
+        let path = tmp.path().join(AGENTS_MD);
+
+        let stale =
+            format!("# Existing\n\n<!-- rtk-pi-start v0 -->\nstale content\n<!-- rtk-pi-end -->");
+        fs::write(&path, &stale).unwrap();
+
+        install_pi_awareness(&path, 0).unwrap();
+
+        let content = fs::read_to_string(&path).unwrap();
+        assert!(
+            !content.contains("stale content"),
+            "old block must be replaced"
+        );
+        assert!(
+            content.contains(PI_AWARENESS_START),
+            "new sentinel must be present"
+        );
+        assert_eq!(content.matches("<!-- rtk-pi-start").count(), 1);
+    }
+
+    #[test]
+    fn test_remove_pi_awareness_removes_block() {
+        let tmp = TempDir::new().unwrap();
+        let path = tmp.path().join(AGENTS_MD);
+        fs::write(&path, "# Existing\n").unwrap();
+
+        install_pi_awareness(&path, 0).unwrap();
+        assert!(fs::read_to_string(&path)
+            .unwrap()
+            .contains(PI_AWARENESS_START));
+
+        remove_pi_awareness(&path, 0).unwrap();
+        let content = fs::read_to_string(&path).unwrap();
+        assert!(
+            !content.contains(PI_AWARENESS_START),
+            "sentinel must be removed"
+        );
+        assert!(
+            !content.contains(PI_AWARENESS_END),
+            "sentinel end must be removed"
+        );
+    }
+
+    #[test]
+    fn test_remove_pi_awareness_noop_when_absent() {
+        let tmp = TempDir::new().unwrap();
+        let path = tmp.path().join(AGENTS_MD);
+        fs::write(&path, "# No rtk block here\n").unwrap();
+
+        remove_pi_awareness(&path, 0).unwrap();
+
+        let content = fs::read_to_string(&path).unwrap();
+        assert_eq!(content, "# No rtk block here\n", "file must be unchanged");
+    }
+
+    #[test]
+    fn test_remove_pi_awareness_noop_when_file_missing() {
+        let tmp = TempDir::new().unwrap();
+        let path = tmp.path().join(AGENTS_MD);
+        remove_pi_awareness(&path, 0).unwrap();
+    }
+
+    #[test]
+    fn test_pi_global_uninstall_removes_plugin_and_awareness() {
+        let tmp = TempDir::new().unwrap();
+        with_pi_dir_override(&tmp, |pi_dir| {
+            run_pi_mode(true, 0).unwrap();
+
+            let plugin = pi_dir.join(PI_EXTENSIONS_SUBDIR).join(PI_PLUGIN_FILE);
+            let agents_md = pi_dir.join(AGENTS_MD);
+            assert!(plugin.exists());
+            assert!(agents_md.exists());
+
+            uninstall(true, false, false, false, true, 0).unwrap();
+
+            assert!(!plugin.exists(), "plugin must be removed");
+            let content = fs::read_to_string(&agents_md).unwrap_or_default();
+            assert!(
+                !content.contains(PI_AWARENESS_START),
+                "awareness block must be removed"
+            );
+        });
+    }
+
+    #[test]
+    fn test_pi_local_uninstall_removes_plugin_and_awareness() {
+        let tmp = TempDir::new().unwrap();
+        let _cwd_guard = CWD_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let cwd = std::env::current_dir().unwrap();
+        std::env::set_current_dir(tmp.path()).unwrap();
+
+        run_pi_mode(false, 0).unwrap();
+        let result = uninstall(false, false, false, false, true, 0);
+        std::env::set_current_dir(&cwd).unwrap();
+        result.unwrap();
+
+        let plugin = tmp
+            .path()
+            .join(".pi")
+            .join(PI_EXTENSIONS_SUBDIR)
+            .join(PI_PLUGIN_FILE);
+        assert!(!plugin.exists(), "local plugin must be removed");
+
+        let agents_md = tmp.path().join(AGENTS_MD);
+        let content = fs::read_to_string(&agents_md).unwrap_or_default();
+        assert!(
+            !content.contains(PI_AWARENESS_START),
+            "local awareness block must be removed"
+        );
+    }
+
+    #[test]
+    fn test_pi_plugin_path_for_scope_global() {
+        let tmp = TempDir::new().unwrap();
+        with_pi_dir_override(&tmp, |pi_dir| {
+            let path = pi_plugin_path_for_scope(true).unwrap();
+            assert_eq!(path, pi_dir.join(PI_EXTENSIONS_SUBDIR).join(PI_PLUGIN_FILE));
+        });
+    }
+
+    #[test]
+    fn test_pi_plugin_path_for_scope_local() {
+        let path = pi_plugin_path_for_scope(false).unwrap();
+        assert_eq!(
+            path,
+            PathBuf::from(".pi")
+                .join(PI_EXTENSIONS_SUBDIR)
+                .join(PI_PLUGIN_FILE)
+        );
+    }
 }
diff --git a/src/main.rs b/src/main.rs
index ccb096ef0..131324d76 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -44,6 +44,8 @@ pub enum AgentTarget {
     Kilocode,
     /// Google Antigravity
     Antigravity,
+    /// Pi coding agent
+    Pi,
 }
 
 #[derive(Parser)]
@@ -371,6 +373,10 @@ enum Commands {
         /// Install GitHub Copilot integration (VS Code + CLI)
         #[arg(long)]
         copilot: bool,
+
+        /// Install Pi coding agent extension
+        #[arg(long)]
+        pi: bool,
     },
 
     /// Download with compact output (strips progress bars)
@@ -1754,62 +1760,108 @@ fn run_cli() -> Result<i32> {
             uninstall,
             codex,
             copilot,
+            pi,
         } => {
             if show {
                 hooks::init::show_config(codex)?;
             } else if uninstall {
                 let cursor = agent == Some(AgentTarget::Cursor);
-                hooks::init::uninstall(global, gemini, codex, cursor, cli.verbose)?;
-            } else if gemini {
-                let patch_mode = if auto_patch {
-                    hooks::init::PatchMode::Auto
-                } else if no_patch {
-                    hooks::init::PatchMode::Skip
-                } else {
-                    hooks::init::PatchMode::Ask
-                };
-                hooks::init::run_gemini(global, hook_only, patch_mode, cli.verbose)?;
-            } else if copilot {
-                hooks::init::run_copilot(cli.verbose)?;
-            } else if agent == Some(AgentTarget::Kilocode) {
-                if global {
-                    anyhow::bail!("Kilo Code is project-scoped. Use: rtk init --agent kilocode");
+                let uninstall_pi = pi || agent == Some(AgentTarget::Pi);
+                hooks::init::uninstall(global, gemini, codex, cursor, uninstall_pi, cli.verbose)?;
+            } else {
+                // Guard: --pi only composes with the default Claude/OpenCode flow.
+                // Combining it with a dedicated-agent mode silently swallows
+                // one of the two installs, so we fail loudly with clear guidance.
+                if pi && gemini {
+                    anyhow::bail!(
+                        "--pi cannot be combined with --gemini. Run them separately:\n  rtk init --pi\n  rtk init --gemini"
+                    );
                 }
-                hooks::init::run_kilocode_mode(cli.verbose)?;
-            } else if agent == Some(AgentTarget::Antigravity) {
-                if global {
+                if pi && copilot {
                     anyhow::bail!(
-                        "Antigravity is project-scoped. Use: rtk init --agent antigravity"
+                        "--pi cannot be combined with --copilot. Run them separately:\n  rtk init --pi\n  rtk init --copilot"
                     );
                 }
-                hooks::init::run_antigravity_mode(cli.verbose)?;
-            } else {
-                let install_opencode = opencode;
-                let install_claude = !opencode;
-                let install_cursor = agent == Some(AgentTarget::Cursor);
-                let install_windsurf = agent == Some(AgentTarget::Windsurf);
-                let install_cline = agent == Some(AgentTarget::Cline);
-
-                let patch_mode = if auto_patch {
-                    hooks::init::PatchMode::Auto
-                } else if no_patch {
-                    hooks::init::PatchMode::Skip
+                if pi && codex {
+                    anyhow::bail!(
+                        "--pi cannot be combined with --codex. Run them separately:\n  rtk init --pi\n  rtk init --codex"
+                    );
+                }
+                if pi && matches!(agent, Some(AgentTarget::Kilocode)) {
+                    anyhow::bail!(
+                        "--pi cannot be combined with --agent kilocode. Run them separately:\n  rtk init --pi\n  rtk init --agent kilocode"
+                    );
+                }
+                if pi && matches!(agent, Some(AgentTarget::Antigravity)) {
+                    anyhow::bail!(
+                        "--pi cannot be combined with --agent antigravity. Run them separately:\n  rtk init --pi\n  rtk init --agent antigravity"
+                    );
+                }
+
+                if gemini {
+                    let patch_mode = if auto_patch {
+                        hooks::init::PatchMode::Auto
+                    } else if no_patch {
+                        hooks::init::PatchMode::Skip
+                    } else {
+                        hooks::init::PatchMode::Ask
+                    };
+                    hooks::init::run_gemini(global, hook_only, patch_mode, cli.verbose)?;
+                } else if copilot {
+                    hooks::init::run_copilot(cli.verbose)?;
+                } else if agent == Some(AgentTarget::Pi) {
+                    // Pi-only mode: --agent pi installs Pi and nothing else.
+                    hooks::init::run_pi_mode(global, cli.verbose)?;
+                } else if agent == Some(AgentTarget::Kilocode) {
+                    if global {
+                        anyhow::bail!(
+                            "Kilo Code is project-scoped. Use: rtk init --agent kilocode"
+                        );
+                    }
+                    hooks::init::run_kilocode_mode(cli.verbose)?;
+                } else if agent == Some(AgentTarget::Antigravity) {
+                    if global {
+                        anyhow::bail!(
+                            "Antigravity is project-scoped. Use: rtk init --agent antigravity"
+                        );
+                    }
+                    hooks::init::run_antigravity_mode(cli.verbose)?;
                 } else {
-                    hooks::init::PatchMode::Ask
-                };
-                hooks::init::run(
-                    global,
-                    install_claude,
-                    install_opencode,
-                    install_cursor,
-                    install_windsurf,
-                    install_cline,
-                    claude_md,
-                    hook_only,
-                    codex,
-                    patch_mode,
-                    cli.verbose,
-                )?;
+                    let install_opencode = opencode;
+                    let install_claude = !opencode;
+                    let install_cursor = agent == Some(AgentTarget::Cursor);
+                    let install_windsurf = agent == Some(AgentTarget::Windsurf);
+                    let install_cline = agent == Some(AgentTarget::Cline);
+
+                    let patch_mode = if auto_patch {
+                        hooks::init::PatchMode::Auto
+                    } else if no_patch {
+                        hooks::init::PatchMode::Skip
+                    } else {
+                        hooks::init::PatchMode::Ask
+                    };
+
+                    // Run the main Claude/OpenCode flow first so validation
+                    // failures don't leave a partial Pi install behind.
+                    hooks::init::run(
+                        global,
+                        install_claude,
+                        install_opencode,
+                        install_cursor,
+                        install_windsurf,
+                        install_cline,
+                        claude_md,
+                        hook_only,
+                        codex,
+                        patch_mode,
+                        cli.verbose,
+                    )?;
+
+                    // --pi is additive: layer Pi extension on top of the main flow.
+                    if pi {
+                        hooks::init::run_pi_mode(global, cli.verbose)?;
+                    }
+                }
             }
             0
         }

From d6e27527ea0ac452333fb2c608c85ef29af349d6 Mon Sep 17 00:00:00 2001
From: gitbluf <git+gh@gitbluf.xyz>
Date: Wed, 6 May 2026 16:34:46 +0200
Subject: [PATCH 02/13] refactor: handling of uninstallation

---
 .../guide/getting-started/supported-agents.md | 26 +++++++++++++-
 hooks/pi/README.md                            | 21 +++++++++++
 src/hooks/README.md                           |  7 ++--
 src/hooks/init.rs                             | 36 +++++++++++--------
 4 files changed, 71 insertions(+), 19 deletions(-)

diff --git a/docs/guide/getting-started/supported-agents.md b/docs/guide/getting-started/supported-agents.md
index 4623353d5..7697778ee 100644
--- a/docs/guide/getting-started/supported-agents.md
+++ b/docs/guide/getting-started/supported-agents.md
@@ -35,6 +35,7 @@ Agent runs "cargo test"
 | Gemini CLI | Rust binary (`BeforeTool`) | Yes |
 | OpenCode | TypeScript plugin (`tool.execute.before`) | Yes |
 | OpenClaw | TypeScript plugin (`before_tool_call`) | Yes |
+| Pi | TypeScript extension (`tool_call` event) | Yes |
 | Cline / Roo Code | Rules file (prompt-level) | N/A |
 | Windsurf | Rules file (prompt-level) | N/A |
 | Codex CLI | AGENTS.md instructions | N/A |
@@ -84,6 +85,29 @@ rtk init --global --opencode
 
 Creates `~/.config/opencode/plugins/rtk.ts`. Uses the `tool.execute.before` hook.
 
+### Pi
+
+```bash
+# Project-local (default)
+rtk init --pi
+
+# Global — all projects
+rtk init --pi --global
+
+# Pi only (no Claude/OpenCode install)
+rtk init --agent pi
+rtk init --agent pi --global
+```
+
+Creates `.pi/extensions/rtk.ts` (local) or `~/.pi/agent/extensions/rtk.ts` (global) and appends an RTK awareness block to `AGENTS.md`. Pi auto-discovers extensions from both paths on startup.
+
+Uninstall:
+
+```bash
+rtk init --uninstall --pi
+rtk init --uninstall --pi --global
+```
+
 ### OpenClaw
 
 ```bash
@@ -140,7 +164,7 @@ Support is blocked on upstream `BeforeToolCallback` ([mistral-vibe#531](https://
 | **Plugin** | TypeScript/JS in agent's plugin system | Transparent — in-place mutation |
 | **Rules file** | Prompt-level instructions | Guidance only — agent is told to prefer `rtk <cmd>` |
 
-Rules file integrations (Cline, Windsurf, Codex, Kilo Code, Antigravity) rely on the model following instructions. Full hook integrations (Claude Code, Cursor, Gemini) are guaranteed — the command is rewritten before the agent sees it.
+Rules file integrations (Cline, Windsurf, Codex, Kilo Code, Antigravity) rely on the model following instructions. Full hook integrations (Claude Code, Cursor, Gemini) are guaranteed — the command is rewritten before the agent sees it. Plugin integrations (OpenCode, Pi) use in-place mutation via the agent's TypeScript extension API.
 
 ## Windows support
 
diff --git a/hooks/pi/README.md b/hooks/pi/README.md
index ceb7dc01f..defaa7b5b 100644
--- a/hooks/pi/README.md
+++ b/hooks/pi/README.md
@@ -12,6 +12,27 @@
 - Installed to `.pi/extensions/rtk.ts` by `rtk init --pi` (project-local) or `~/.pi/agent/extensions/rtk.ts` by `rtk init --pi --global`
 - `rtk-awareness.md` is embedded into `AGENTS.md` by `rtk init --pi`
 
+## Uninstall
+
+```bash
+# Remove project-local install (run from the project root)
+rtk init --uninstall --pi
+# → removes .pi/extensions/rtk.ts
+# → removes RTK awareness block from AGENTS.md (if present)
+
+# Remove global install
+rtk init --uninstall --pi --global
+# → removes ~/.pi/agent/extensions/rtk.ts
+# → removes RTK awareness block from ~/.pi/agent/AGENTS.md
+
+# Pi-only target form also works
+rtk init --uninstall --agent pi
+rtk init --uninstall --agent pi --global
+```
+
+Uninstall is idempotent — re-running when nothing is installed is a no-op.
+Both the extension file and the awareness block are reported individually when removed.
+
 ## Testing
 
 ```bash
diff --git a/src/hooks/README.md b/src/hooks/README.md
index bf947a0f1..04460722c 100644
--- a/src/hooks/README.md
+++ b/src/hooks/README.md
@@ -6,7 +6,7 @@
 
 The **lifecycle management** layer for LLM agent hooks: install, uninstall, verify integrity, audit usage, and manage trust. This component creates and maintains the hook artifacts that live in `hooks/` (root), but does **not** execute rewrite logic itself — that lives in `discover/registry`.
 
-Owns: `rtk init` installation flows (4 agents via `AgentTarget` enum + 3 special modes: Gemini, Codex, OpenCode), SHA-256 integrity verification, hook version checking, audit log analysis, `rtk rewrite` CLI entry point, and TOML filter trust management.
+Owns: `rtk init` installation flows (5 agents via `AgentTarget` enum + 3 special modes: Gemini, Codex, OpenCode), SHA-256 integrity verification, hook version checking, audit log analysis, `rtk rewrite` CLI entry point, and TOML filter trust management.
 
 Does **not** own: the deployed hook scripts themselves (that's `hooks/`), the rewrite pattern registry (that's `discover/`), or command filtering (that's `cmds/`).
 
@@ -19,10 +19,10 @@ LLM agent integration layer that installs, validates, and executes command-rewri
 
 ## Installation Modes
 
-`rtk init` supports 6 distinct installation flows:
+`rtk init` supports 8 distinct installation flows:
 
 | Mode | Command | Creates | Patches |
-|------|---------|---------|---------|
+|------|---------|---------|----------|
 | Default (global) | `rtk init -g` | Hook, SHA-256 hash, RTK.md | settings.json, CLAUDE.md |
 | Hook only | `rtk init -g --hook-only` | Hook, SHA-256 hash | settings.json |
 | Claude-MD (legacy) | `rtk init --claude-md` | 134-line RTK block | CLAUDE.md |
@@ -30,6 +30,7 @@ LLM agent integration layer that installs, validates, and executes command-rewri
 | Cline | `rtk init --agent cline` | `.clinerules` | -- |
 | Codex | `rtk init --codex` | RTK.md in `$CODEX_HOME` or `~/.codex` | AGENTS.md |
 | Cursor | `rtk init -g --agent cursor` | Cursor hook | hooks.json |
+| Pi | `rtk init --pi` | `.pi/extensions/rtk.ts` | AGENTS.md (awareness block) |
 
 
 ## Integrity Verification
diff --git a/src/hooks/init.rs b/src/hooks/init.rs
index 51662a3c9..7ee3d855b 100644
--- a/src/hooks/init.rs
+++ b/src/hooks/init.rs
@@ -581,7 +581,8 @@ pub fn uninstall(
 
     if pi {
         let plugin_path = pi_plugin_path_for_scope(global)?;
-        let mut removed = Vec::new();
+        let agents_md = pi_agents_md_path_for_scope(global)?;
+        let mut removed: Vec<String> = Vec::new();
 
         if plugin_path.exists() {
             fs::remove_file(&plugin_path).with_context(|| {
@@ -590,16 +591,19 @@ pub fn uninstall(
             if verbose > 0 {
                 eprintln!("Removed Pi extension: {}", plugin_path.display());
             }
-            removed.push(plugin_path);
+            removed.push(format!("Pi extension: {}", plugin_path.display()));
         }
 
-        let agents_md = pi_agents_md_path_for_scope(global)?;
-        remove_pi_awareness(&agents_md, verbose).context("Failed to remove Pi awareness block")?;
+        let awareness_removed = remove_pi_awareness(&agents_md, verbose)
+            .context("Failed to remove Pi awareness block")?;
+        if awareness_removed {
+            removed.push(format!("Pi awareness: {}", agents_md.display()));
+        }
 
         if !removed.is_empty() {
             println!("RTK uninstalled (Pi):");
-            for path in &removed {
-                println!("  - {}", path.display());
+            for item in &removed {
+                println!("  - {}", item);
             }
             println!("\nRestart pi to apply changes.");
         } else {
@@ -1989,17 +1993,17 @@ fn install_pi_awareness(agents_md_path: &Path, verbose: u8) -> Result<()> {
 }
 
 /// Remove the RTK awareness sentinel block from an AGENTS.md file.
-/// If the sentinels are absent this is a no-op.
-fn remove_pi_awareness(agents_md_path: &Path, verbose: u8) -> Result<()> {
+/// Returns true if a block was found and removed, false if absent or file missing.
+fn remove_pi_awareness(agents_md_path: &Path, verbose: u8) -> Result<bool> {
     if !agents_md_path.exists() {
-        return Ok(());
+        return Ok(false);
     }
 
     let existing = fs::read_to_string(agents_md_path)
         .with_context(|| format!("Failed to read {}", agents_md_path.display()))?;
 
     if !PI_SENTINEL_RE.is_match(&existing) {
-        return Ok(());
+        return Ok(false);
     }
 
     let updated = PI_SENTINEL_RE.replace(&existing, "").into_owned();
@@ -2013,7 +2017,7 @@ fn remove_pi_awareness(agents_md_path: &Path, verbose: u8) -> Result<()> {
         );
     }
 
-    Ok(())
+    Ok(true)
 }
 
 /// Install the Pi extension and inject the awareness block into AGENTS.md.
@@ -4399,7 +4403,8 @@ mod tests {
             .unwrap()
             .contains(PI_AWARENESS_START));
 
-        remove_pi_awareness(&path, 0).unwrap();
+        let removed = remove_pi_awareness(&path, 0).unwrap();
+        assert!(removed, "must report true when block was present");
         let content = fs::read_to_string(&path).unwrap();
         assert!(
             !content.contains(PI_AWARENESS_START),
@@ -4417,8 +4422,8 @@ mod tests {
         let path = tmp.path().join(AGENTS_MD);
         fs::write(&path, "# No rtk block here\n").unwrap();
 
-        remove_pi_awareness(&path, 0).unwrap();
-
+        let removed = remove_pi_awareness(&path, 0).unwrap();
+        assert!(!removed, "must report false when no block present");
         let content = fs::read_to_string(&path).unwrap();
         assert_eq!(content, "# No rtk block here\n", "file must be unchanged");
     }
@@ -4427,7 +4432,8 @@ mod tests {
     fn test_remove_pi_awareness_noop_when_file_missing() {
         let tmp = TempDir::new().unwrap();
         let path = tmp.path().join(AGENTS_MD);
-        remove_pi_awareness(&path, 0).unwrap();
+        let removed = remove_pi_awareness(&path, 0).unwrap();
+        assert!(!removed, "must report false when file missing");
     }
 
     #[test]

From 2acc0c489c1424514f81f0201bf3a8e6939f884e Mon Sep 17 00:00:00 2001
From: gitbluf <git+gh@gitbluf.xyz>
Date: Wed, 6 May 2026 16:52:00 +0200
Subject: [PATCH 03/13] test(cli): add init parse coverage for --pi, --agent
 pi, and --uninstall --pi

---
 src/hooks/constants.rs |   4 -
 src/main.rs            | 182 ++++++++++++++++++++---------------------
 2 files changed, 91 insertions(+), 95 deletions(-)

diff --git a/src/hooks/constants.rs b/src/hooks/constants.rs
index 0aa435537..cde730756 100644
--- a/src/hooks/constants.rs
+++ b/src/hooks/constants.rs
@@ -22,11 +22,7 @@ pub const CURSOR_DIR: &str = ".cursor";
 pub const CODEX_DIR: &str = ".codex";
 pub const GEMINI_DIR: &str = ".gemini";
 
-/// Default Pi config subdirectory under $HOME
 pub const PI_DIR: &str = ".pi/agent";
-/// Subdirectory inside the Pi config dir where extensions live
 pub const PI_EXTENSIONS_SUBDIR: &str = "extensions";
-/// Filename for the installed RTK extension
 pub const PI_PLUGIN_FILE: &str = "rtk.ts";
-/// Environment variable that overrides the Pi config directory
 pub const PI_CODING_AGENT_DIR_ENV: &str = "PI_CODING_AGENT_DIR";
diff --git a/src/main.rs b/src/main.rs
index 131324d76..4ce076e40 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1763,104 +1763,65 @@ fn run_cli() -> Result<i32> {
             pi,
         } => {
             if show {
-                hooks::init::show_config(codex)?;
+                hooks::init::show_config(codex)?
             } else if uninstall {
                 let cursor = agent == Some(AgentTarget::Cursor);
-                let uninstall_pi = pi || agent == Some(AgentTarget::Pi);
-                hooks::init::uninstall(global, gemini, codex, cursor, uninstall_pi, cli.verbose)?;
-            } else {
-                // Guard: --pi only composes with the default Claude/OpenCode flow.
-                // Combining it with a dedicated-agent mode silently swallows
-                // one of the two installs, so we fail loudly with clear guidance.
-                if pi && gemini {
-                    anyhow::bail!(
-                        "--pi cannot be combined with --gemini. Run them separately:\n  rtk init --pi\n  rtk init --gemini"
-                    );
-                }
-                if pi && copilot {
-                    anyhow::bail!(
-                        "--pi cannot be combined with --copilot. Run them separately:\n  rtk init --pi\n  rtk init --copilot"
-                    );
-                }
-                if pi && codex {
-                    anyhow::bail!(
-                        "--pi cannot be combined with --codex. Run them separately:\n  rtk init --pi\n  rtk init --codex"
-                    );
-                }
-                if pi && matches!(agent, Some(AgentTarget::Kilocode)) {
-                    anyhow::bail!(
-                        "--pi cannot be combined with --agent kilocode. Run them separately:\n  rtk init --pi\n  rtk init --agent kilocode"
-                    );
+                let pi = pi || agent == Some(AgentTarget::Pi);
+                hooks::init::uninstall(global, gemini, codex, cursor, pi, cli.verbose)?;
+            } else if gemini {
+                let patch_mode = if auto_patch {
+                    hooks::init::PatchMode::Auto
+                } else if no_patch {
+                    hooks::init::PatchMode::Skip
+                } else {
+                    hooks::init::PatchMode::Ask
+                };
+                hooks::init::run_gemini(global, hook_only, patch_mode, cli.verbose)?;
+            } else if copilot {
+                hooks::init::run_copilot(cli.verbose)?;
+            } else if agent == Some(AgentTarget::Pi) {
+                hooks::init::run_pi_mode(global, cli.verbose)?;
+            } else if agent == Some(AgentTarget::Kilocode) {
+                if global {
+                    anyhow::bail!("Kilo Code is project-scoped. Use: rtk init --agent kilocode");
                 }
-                if pi && matches!(agent, Some(AgentTarget::Antigravity)) {
+                hooks::init::run_kilocode_mode(cli.verbose)?;
+            } else if agent == Some(AgentTarget::Antigravity) {
+                if global {
                     anyhow::bail!(
-                        "--pi cannot be combined with --agent antigravity. Run them separately:\n  rtk init --pi\n  rtk init --agent antigravity"
+                        "Antigravity is project-scoped. Use: rtk init --agent antigravity"
                     );
                 }
-
-                if gemini {
-                    let patch_mode = if auto_patch {
-                        hooks::init::PatchMode::Auto
-                    } else if no_patch {
-                        hooks::init::PatchMode::Skip
-                    } else {
-                        hooks::init::PatchMode::Ask
-                    };
-                    hooks::init::run_gemini(global, hook_only, patch_mode, cli.verbose)?;
-                } else if copilot {
-                    hooks::init::run_copilot(cli.verbose)?;
-                } else if agent == Some(AgentTarget::Pi) {
-                    // Pi-only mode: --agent pi installs Pi and nothing else.
-                    hooks::init::run_pi_mode(global, cli.verbose)?;
-                } else if agent == Some(AgentTarget::Kilocode) {
-                    if global {
-                        anyhow::bail!(
-                            "Kilo Code is project-scoped. Use: rtk init --agent kilocode"
-                        );
-                    }
-                    hooks::init::run_kilocode_mode(cli.verbose)?;
-                } else if agent == Some(AgentTarget::Antigravity) {
-                    if global {
-                        anyhow::bail!(
-                            "Antigravity is project-scoped. Use: rtk init --agent antigravity"
-                        );
-                    }
-                    hooks::init::run_antigravity_mode(cli.verbose)?;
+                hooks::init::run_antigravity_mode(cli.verbose)?;
+            } else {
+                let install_opencode = opencode;
+                let install_claude = !opencode;
+                let install_cursor = agent == Some(AgentTarget::Cursor);
+                let install_windsurf = agent == Some(AgentTarget::Windsurf);
+                let install_cline = agent == Some(AgentTarget::Cline);
+
+                let patch_mode = if auto_patch {
+                    hooks::init::PatchMode::Auto
+                } else if no_patch {
+                    hooks::init::PatchMode::Skip
                 } else {
-                    let install_opencode = opencode;
-                    let install_claude = !opencode;
-                    let install_cursor = agent == Some(AgentTarget::Cursor);
-                    let install_windsurf = agent == Some(AgentTarget::Windsurf);
-                    let install_cline = agent == Some(AgentTarget::Cline);
-
-                    let patch_mode = if auto_patch {
-                        hooks::init::PatchMode::Auto
-                    } else if no_patch {
-                        hooks::init::PatchMode::Skip
-                    } else {
-                        hooks::init::PatchMode::Ask
-                    };
-
-                    // Run the main Claude/OpenCode flow first so validation
-                    // failures don't leave a partial Pi install behind.
-                    hooks::init::run(
-                        global,
-                        install_claude,
-                        install_opencode,
-                        install_cursor,
-                        install_windsurf,
-                        install_cline,
-                        claude_md,
-                        hook_only,
-                        codex,
-                        patch_mode,
-                        cli.verbose,
-                    )?;
-
-                    // --pi is additive: layer Pi extension on top of the main flow.
-                    if pi {
-                        hooks::init::run_pi_mode(global, cli.verbose)?;
-                    }
+                    hooks::init::PatchMode::Ask
+                };
+                hooks::init::run(
+                    global,
+                    install_claude,
+                    install_opencode,
+                    install_cursor,
+                    install_windsurf,
+                    install_cline,
+                    claude_md,
+                    hook_only,
+                    codex,
+                    patch_mode,
+                    cli.verbose,
+                )?;
+                if pi {
+                    hooks::init::run_pi_mode(global, cli.verbose)?;
                 }
             }
             0
@@ -3057,4 +3018,43 @@ mod tests {
             _ => panic!("Expected Commands::Npx for unknown tool"),
         }
     }
+
+    #[test]
+    fn test_init_pi_flag_parses() {
+        let cli = Cli::try_parse_from(["rtk", "init", "--pi"]).unwrap();
+        match cli.command {
+            Commands::Init { pi, .. } => assert!(pi, "--pi flag must be set"),
+            _ => panic!("Expected Init command"),
+        }
+    }
+
+    #[test]
+    fn test_init_agent_pi_parses() {
+        let cli = Cli::try_parse_from(["rtk", "init", "--agent", "pi"]).unwrap();
+        match cli.command {
+            Commands::Init { agent, .. } => {
+                assert_eq!(agent, Some(AgentTarget::Pi), "--agent pi must set Pi variant");
+            }
+            _ => panic!("Expected Init command"),
+        }
+    }
+
+    #[test]
+    fn test_init_uninstall_pi_parses() {
+        let cli =
+            Cli::try_parse_from(["rtk", "init", "--uninstall", "--pi", "--global"]).unwrap();
+        match cli.command {
+            Commands::Init {
+                uninstall,
+                pi,
+                global,
+                ..
+            } => {
+                assert!(uninstall);
+                assert!(pi);
+                assert!(global);
+            }
+            _ => panic!("Expected Init command"),
+        }
+    }
 }

From b2a3ad9443d6242f60b4c05265bda56b2a7e72b6 Mon Sep 17 00:00:00 2001
From: gitbluf <git+gh@gitbluf.xyz>
Date: Wed, 6 May 2026 18:44:27 +0200
Subject: [PATCH 04/13] feat: rm rtk awareness injection

---
 .../guide/getting-started/supported-agents.md |   4 +-
 hooks/pi/README.md                            |   5 +-
 hooks/pi/rtk-awareness.md                     |  37 ---
 src/hooks/README.md                           |   2 +-
 src/hooks/init.rs                             | 300 +-----------------
 src/main.rs                                   |   9 +-
 6 files changed, 22 insertions(+), 335 deletions(-)
 delete mode 100644 hooks/pi/rtk-awareness.md

diff --git a/docs/guide/getting-started/supported-agents.md b/docs/guide/getting-started/supported-agents.md
index 7697778ee..01d0551c1 100644
--- a/docs/guide/getting-started/supported-agents.md
+++ b/docs/guide/getting-started/supported-agents.md
@@ -99,7 +99,7 @@ rtk init --agent pi
 rtk init --agent pi --global
 ```
 
-Creates `.pi/extensions/rtk.ts` (local) or `~/.pi/agent/extensions/rtk.ts` (global) and appends an RTK awareness block to `AGENTS.md`. Pi auto-discovers extensions from both paths on startup.
+Creates `.pi/extensions/rtk.ts` (local) or `~/.pi/agent/extensions/rtk.ts` (global). Pi auto-discovers extensions from both paths on startup.
 
 Uninstall:
 
@@ -108,6 +108,8 @@ rtk init --uninstall --pi
 rtk init --uninstall --pi --global
 ```
 
+Removes only the installed Pi extension file.
+
 ### OpenClaw
 
 ```bash
diff --git a/hooks/pi/README.md b/hooks/pi/README.md
index defaa7b5b..ef7038f71 100644
--- a/hooks/pi/README.md
+++ b/hooks/pi/README.md
@@ -10,7 +10,6 @@
 - Returns `{ block: true, reason }` on deny (exit code 2); all other error paths return `undefined`
 - Version guard at load time: checks `rtk >= 0.23.0`; warns and registers no-op if too old or missing
 - Installed to `.pi/extensions/rtk.ts` by `rtk init --pi` (project-local) or `~/.pi/agent/extensions/rtk.ts` by `rtk init --pi --global`
-- `rtk-awareness.md` is embedded into `AGENTS.md` by `rtk init --pi`
 
 ## Uninstall
 
@@ -18,12 +17,10 @@
 # Remove project-local install (run from the project root)
 rtk init --uninstall --pi
 # → removes .pi/extensions/rtk.ts
-# → removes RTK awareness block from AGENTS.md (if present)
 
 # Remove global install
 rtk init --uninstall --pi --global
 # → removes ~/.pi/agent/extensions/rtk.ts
-# → removes RTK awareness block from ~/.pi/agent/AGENTS.md
 
 # Pi-only target form also works
 rtk init --uninstall --agent pi
@@ -31,7 +28,7 @@ rtk init --uninstall --agent pi --global
 ```
 
 Uninstall is idempotent — re-running when nothing is installed is a no-op.
-Both the extension file and the awareness block are reported individually when removed.
+Only the extension file is managed by install/uninstall.
 
 ## Testing
 
diff --git a/hooks/pi/rtk-awareness.md b/hooks/pi/rtk-awareness.md
deleted file mode 100644
index 7bfe0dac6..000000000
--- a/hooks/pi/rtk-awareness.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# RTK — Rust Token Killer
-
-**Usage**: Token-optimized CLI proxy. Commands are automatically rewritten
-by the RTK extension before they execute — no changes to your workflow needed.
-
-## Meta Commands
-
-```bash
-rtk gain              # Show token savings analytics
-rtk gain --history    # Show recent command savings history
-rtk proxy <cmd>       # Run raw command without filtering (bypass RTK)
-```
-
-## Verification
-
-```bash
-rtk --version         # Should show: rtk X.Y.Z
-rtk gain              # Should work (not "command not found")
-which rtk             # Verify correct binary in PATH
-```
-
-⚠️ **Name collision**: Two packages share the name `rtk`. If `rtk gain`
-fails, you may have `reachingforthejack/rtk` (Rust Type Kit) installed
-instead. See the RTK README for installation instructions.
-
-## How It Works
-
-The RTK extension intercepts every bash tool call and transparently rewrites
-commands to their token-optimized equivalents before execution:
-
-```
-git status          →  rtk git status      (~70% fewer tokens)
-cargo test          →  rtk cargo test      (~90% fewer tokens)
-npm run build       →  rtk npm run build   (~80% fewer tokens)
-```
-
-Rewrites are invisible — the LLM sees only the filtered output.
diff --git a/src/hooks/README.md b/src/hooks/README.md
index 04460722c..cded0d218 100644
--- a/src/hooks/README.md
+++ b/src/hooks/README.md
@@ -30,7 +30,7 @@ LLM agent integration layer that installs, validates, and executes command-rewri
 | Cline | `rtk init --agent cline` | `.clinerules` | -- |
 | Codex | `rtk init --codex` | RTK.md in `$CODEX_HOME` or `~/.codex` | AGENTS.md |
 | Cursor | `rtk init -g --agent cursor` | Cursor hook | hooks.json |
-| Pi | `rtk init --pi` | `.pi/extensions/rtk.ts` | AGENTS.md (awareness block) |
+| Pi | `rtk init --pi` | `.pi/extensions/rtk.ts` | -- |
 
 
 ## Integrity Verification
diff --git a/src/hooks/init.rs b/src/hooks/init.rs
index 7ee3d855b..8338d946c 100644
--- a/src/hooks/init.rs
+++ b/src/hooks/init.rs
@@ -1,8 +1,6 @@
 //! Sets up RTK hooks so AI coding agents automatically route commands through RTK.
 
 use anyhow::{Context, Result};
-use lazy_static::lazy_static;
-use regex::Regex;
 use std::fs;
 use std::io::Write;
 use std::path::{Path, PathBuf};
@@ -28,7 +26,6 @@ const PI_PLUGIN: &str = include_str!("../../hooks/pi/rtk.ts");
 // Embedded slim RTK awareness instructions
 const RTK_SLIM: &str = include_str!("../../hooks/claude/rtk-awareness.md");
 const RTK_SLIM_CODEX: &str = include_str!("../../hooks/codex/rtk-awareness.md");
-const RTK_SLIM_PI: &str = include_str!("../../hooks/pi/rtk-awareness.md");
 
 /// Template written by `rtk init` when no filters.toml exists yet.
 const FILTERS_TEMPLATE: &str = r#"# Project-local RTK filters — commit this file with your repo.
@@ -581,7 +578,6 @@ pub fn uninstall(
 
     if pi {
         let plugin_path = pi_plugin_path_for_scope(global)?;
-        let agents_md = pi_agents_md_path_for_scope(global)?;
         let mut removed: Vec<String> = Vec::new();
 
         if plugin_path.exists() {
@@ -594,12 +590,6 @@ pub fn uninstall(
             removed.push(format!("Pi extension: {}", plugin_path.display()));
         }
 
-        let awareness_removed = remove_pi_awareness(&agents_md, verbose)
-            .context("Failed to remove Pi awareness block")?;
-        if awareness_removed {
-            removed.push(format!("Pi awareness: {}", agents_md.display()));
-        }
-
         if !removed.is_empty() {
             println!("RTK uninstalled (Pi):");
             for item in &removed {
@@ -1903,139 +1893,18 @@ fn pi_plugin_path_for_scope(global: bool) -> Result<PathBuf> {
     }
 }
 
-/// Return the AGENTS.md path for the given Pi install scope.
-/// global=true  → `$PI_CODING_AGENT_DIR/AGENTS.md`
-/// global=false → `./AGENTS.md`
-fn pi_agents_md_path_for_scope(global: bool) -> Result<PathBuf> {
-    if global {
-        Ok(resolve_pi_dir()?.join(AGENTS_MD))
-    } else {
-        Ok(PathBuf::from(AGENTS_MD))
-    }
-}
-
 /// Write the Pi extension file if missing or outdated. Returns true if written.
 fn ensure_pi_plugin_installed(path: &Path, verbose: u8) -> Result<bool> {
     write_if_changed(path, PI_PLUGIN, "Pi extension", verbose)
 }
 
-/// Sentinel constants for the Pi awareness block in AGENTS.md.
-const PI_AWARENESS_START: &str = "<!-- rtk-pi-start v1 -->";
-const PI_AWARENESS_END: &str = "<!-- rtk-pi-end -->";
-
-lazy_static! {
-    /// Matches the full sentinel block including any preceding newline so
-    /// replacement leaves no double-blank gaps.
-    static ref PI_SENTINEL_RE: Regex =
-        Regex::new(r"(?s)\n?<!-- rtk-pi-start[^>]*-->.*?<!-- rtk-pi-end -->").unwrap();
-}
-
-/// Build the full sentinel-wrapped awareness block.
-fn pi_awareness_block() -> String {
-    format!(
-        "{}\n{}\n{}",
-        PI_AWARENESS_START,
-        RTK_SLIM_PI.trim(),
-        PI_AWARENESS_END
-    )
-}
-
-/// Append or update the RTK awareness block in a Pi AGENTS.md file.
-///
-/// Uses sentinel comments for idempotent install / version-bump updates:
-/// - Sentinels absent  → append block with a blank-line separator
-/// - Sentinels present, content identical → no-op
-/// - Sentinels present, content differs   → replace block in-place
-fn install_pi_awareness(agents_md_path: &Path, verbose: u8) -> Result<()> {
-    let block = pi_awareness_block();
-
-    if agents_md_path.exists() {
-        let existing = fs::read_to_string(agents_md_path)
-            .with_context(|| format!("Failed to read {}", agents_md_path.display()))?;
-
-        if existing.contains(&block) {
-            if verbose > 0 {
-                eprintln!(
-                    "Pi awareness already up to date: {}",
-                    agents_md_path.display()
-                );
-            }
-            return Ok(());
-        }
-
-        let updated = if PI_SENTINEL_RE.is_match(&existing) {
-            // Sentinels present but content differs (version bump) — replace in-place.
-            PI_SENTINEL_RE
-                .replace(&existing, format!("\n{}", block).as_str())
-                .into_owned()
-        } else {
-            // No sentinels yet — append with a blank-line separator.
-            format!("{}\n\n{}", existing.trim_end(), block)
-        };
-
-        atomic_write(agents_md_path, &updated)
-            .with_context(|| format!("Failed to write {}", agents_md_path.display()))?;
-
-        if verbose > 0 {
-            eprintln!("Updated Pi awareness: {}", agents_md_path.display());
-        }
-    } else {
-        // File absent — create it containing only the awareness block.
-        atomic_write(agents_md_path, &block)
-            .with_context(|| format!("Failed to create {}", agents_md_path.display()))?;
-
-        if verbose > 0 {
-            eprintln!("Created Pi awareness: {}", agents_md_path.display());
-        }
-    }
-
-    Ok(())
-}
-
-/// Remove the RTK awareness sentinel block from an AGENTS.md file.
-/// Returns true if a block was found and removed, false if absent or file missing.
-fn remove_pi_awareness(agents_md_path: &Path, verbose: u8) -> Result<bool> {
-    if !agents_md_path.exists() {
-        return Ok(false);
-    }
-
-    let existing = fs::read_to_string(agents_md_path)
-        .with_context(|| format!("Failed to read {}", agents_md_path.display()))?;
-
-    if !PI_SENTINEL_RE.is_match(&existing) {
-        return Ok(false);
-    }
-
-    let updated = PI_SENTINEL_RE.replace(&existing, "").into_owned();
-    atomic_write(agents_md_path, updated.trim_end())
-        .with_context(|| format!("Failed to write {}", agents_md_path.display()))?;
-
-    if verbose > 0 {
-        eprintln!(
-            "Removed Pi awareness block from: {}",
-            agents_md_path.display()
-        );
-    }
-
-    Ok(true)
-}
-
-/// Install the Pi extension and inject the awareness block into AGENTS.md.
+/// Install the Pi extension (hook-only; no AGENTS.md injection).
 ///
-/// global=true  → `$PI_CODING_AGENT_DIR/extensions/rtk.ts` + `$PI_CODING_AGENT_DIR/AGENTS.md`
-/// global=false → `.pi/extensions/rtk.ts` + `./AGENTS.md`
-///
-/// AGENTS.md injection is skipped in global mode when the Pi config directory
-/// did not previously exist (the user has not yet run `pi`). The extension is
-/// still written so the user gets immediate coverage once they do initialise Pi.
+/// global=true  → `$PI_CODING_AGENT_DIR/extensions/rtk.ts`
+/// global=false → `.pi/extensions/rtk.ts`
 pub fn run_pi_mode(global: bool, verbose: u8) -> Result<()> {
-    let mut should_install_awareness = true;
-
     let plugin_path = if global {
         let pi_dir = resolve_pi_dir()?;
-        // Capture existence *before* we create subdirectories.
-        let pi_dir_preexisting = pi_dir.exists();
-
         let path = pi_plugin_path(&pi_dir);
         if let Some(parent) = path.parent() {
             fs::create_dir_all(parent).with_context(|| {
@@ -2045,11 +1914,6 @@ pub fn run_pi_mode(global: bool, verbose: u8) -> Result<()> {
                 )
             })?;
         }
-
-        if !pi_dir_preexisting {
-            should_install_awareness = false;
-        }
-
         path
     } else {
         let path = pi_plugin_path_for_scope(false)?;
@@ -2065,25 +1929,12 @@ pub fn run_pi_mode(global: bool, verbose: u8) -> Result<()> {
     };
 
     let installed = ensure_pi_plugin_installed(&plugin_path, verbose)?;
-    let agents_md_path = pi_agents_md_path_for_scope(global)?;
-
-    if should_install_awareness {
-        install_pi_awareness(&agents_md_path, verbose)?;
-        print_pi_result(&plugin_path, Some(&agents_md_path), installed);
-    } else {
-        eprintln!(
-            "[rtk] Pi config directory not found ({}).\n\
-             Extension installed but skipping AGENTS.md injection.\n\
-             Create the directory or run `pi` once to initialise it.",
-            resolve_pi_dir()?.display()
-        );
-        print_pi_result(&plugin_path, None, installed);
-    }
+    print_pi_result(&plugin_path, installed);
 
     Ok(())
 }
 
-fn print_pi_result(plugin_path: &Path, agents_md_path: Option<&Path>, installed: bool) {
+fn print_pi_result(plugin_path: &Path, installed: bool) {
     let status = if installed {
         "installed"
     } else {
@@ -2091,9 +1942,6 @@ fn print_pi_result(plugin_path: &Path, agents_md_path: Option<&Path>, installed:
     };
     println!("RTK Pi extension {}:", status);
     println!("  Extension: {}", plugin_path.display());
-    if let Some(p) = agents_md_path {
-        println!("  AGENTS.md: {}", p.display());
-    }
     println!();
     println!("Pi will load the extension automatically on next start.");
     println!("Verify: pi -e {} --no-session", plugin_path.display());
@@ -4287,28 +4135,18 @@ mod tests {
     }
 
     #[test]
-    fn test_run_pi_mode_global_injects_awareness() {
+    fn test_run_pi_mode_global_does_not_create_agents_md() {
         let tmp = TempDir::new().unwrap();
         with_pi_dir_override(&tmp, |pi_dir| {
             run_pi_mode(true, 0).unwrap();
 
             let agents_md = pi_dir.join(AGENTS_MD);
-            assert!(agents_md.exists(), "AGENTS.md must be created");
-
-            let content = fs::read_to_string(&agents_md).unwrap();
-            assert!(
-                content.contains(PI_AWARENESS_START),
-                "AGENTS.md must contain sentinel start"
-            );
-            assert!(
-                content.contains(PI_AWARENESS_END),
-                "AGENTS.md must contain sentinel end"
-            );
+            assert!(!agents_md.exists(), "AGENTS.md must not be created");
         });
     }
 
     #[test]
-    fn test_run_pi_mode_global_skips_awareness_when_dir_absent() {
+    fn test_run_pi_mode_global_creates_plugin_when_dir_absent() {
         let tmp = TempDir::new().unwrap();
         let absent_dir = tmp.path().join("no_such_pi_dir");
         let _guard = PI_DIR_LOCK.lock().unwrap_or_else(|e| e.into_inner());
@@ -4331,135 +4169,26 @@ mod tests {
         );
 
         let agents_md = absent_dir.join(AGENTS_MD);
-        assert!(
-            !agents_md.exists(),
-            "AGENTS.md must not be created when Pi dir was absent"
-        );
-    }
-
-    #[test]
-    fn test_install_pi_awareness_appends_to_existing_file() {
-        let tmp = TempDir::new().unwrap();
-        let path = tmp.path().join(AGENTS_MD);
-        fs::write(&path, "# Existing content\n").unwrap();
-
-        install_pi_awareness(&path, 0).unwrap();
-
-        let content = fs::read_to_string(&path).unwrap();
-        assert!(content.contains("# Existing content"));
-        assert!(content.contains(PI_AWARENESS_START));
-        assert!(content.contains(PI_AWARENESS_END));
-    }
-
-    #[test]
-    fn test_install_pi_awareness_idempotent() {
-        let tmp = TempDir::new().unwrap();
-        let path = tmp.path().join(AGENTS_MD);
-
-        install_pi_awareness(&path, 0).unwrap();
-        let content_after_first = fs::read_to_string(&path).unwrap();
-
-        install_pi_awareness(&path, 0).unwrap();
-        let content_after_second = fs::read_to_string(&path).unwrap();
-
-        assert_eq!(
-            content_after_first, content_after_second,
-            "second install must be a no-op"
-        );
-        assert_eq!(content_after_second.matches(PI_AWARENESS_START).count(), 1);
-    }
-
-    #[test]
-    fn test_install_pi_awareness_replaces_stale_block() {
-        let tmp = TempDir::new().unwrap();
-        let path = tmp.path().join(AGENTS_MD);
-
-        let stale =
-            format!("# Existing\n\n<!-- rtk-pi-start v0 -->\nstale content\n<!-- rtk-pi-end -->");
-        fs::write(&path, &stale).unwrap();
-
-        install_pi_awareness(&path, 0).unwrap();
-
-        let content = fs::read_to_string(&path).unwrap();
-        assert!(
-            !content.contains("stale content"),
-            "old block must be replaced"
-        );
-        assert!(
-            content.contains(PI_AWARENESS_START),
-            "new sentinel must be present"
-        );
-        assert_eq!(content.matches("<!-- rtk-pi-start").count(), 1);
-    }
-
-    #[test]
-    fn test_remove_pi_awareness_removes_block() {
-        let tmp = TempDir::new().unwrap();
-        let path = tmp.path().join(AGENTS_MD);
-        fs::write(&path, "# Existing\n").unwrap();
-
-        install_pi_awareness(&path, 0).unwrap();
-        assert!(fs::read_to_string(&path)
-            .unwrap()
-            .contains(PI_AWARENESS_START));
-
-        let removed = remove_pi_awareness(&path, 0).unwrap();
-        assert!(removed, "must report true when block was present");
-        let content = fs::read_to_string(&path).unwrap();
-        assert!(
-            !content.contains(PI_AWARENESS_START),
-            "sentinel must be removed"
-        );
-        assert!(
-            !content.contains(PI_AWARENESS_END),
-            "sentinel end must be removed"
-        );
-    }
-
-    #[test]
-    fn test_remove_pi_awareness_noop_when_absent() {
-        let tmp = TempDir::new().unwrap();
-        let path = tmp.path().join(AGENTS_MD);
-        fs::write(&path, "# No rtk block here\n").unwrap();
-
-        let removed = remove_pi_awareness(&path, 0).unwrap();
-        assert!(!removed, "must report false when no block present");
-        let content = fs::read_to_string(&path).unwrap();
-        assert_eq!(content, "# No rtk block here\n", "file must be unchanged");
-    }
-
-    #[test]
-    fn test_remove_pi_awareness_noop_when_file_missing() {
-        let tmp = TempDir::new().unwrap();
-        let path = tmp.path().join(AGENTS_MD);
-        let removed = remove_pi_awareness(&path, 0).unwrap();
-        assert!(!removed, "must report false when file missing");
+        assert!(!agents_md.exists(), "AGENTS.md must not be created");
     }
 
     #[test]
-    fn test_pi_global_uninstall_removes_plugin_and_awareness() {
+    fn test_pi_global_uninstall_removes_plugin() {
         let tmp = TempDir::new().unwrap();
         with_pi_dir_override(&tmp, |pi_dir| {
             run_pi_mode(true, 0).unwrap();
 
             let plugin = pi_dir.join(PI_EXTENSIONS_SUBDIR).join(PI_PLUGIN_FILE);
-            let agents_md = pi_dir.join(AGENTS_MD);
             assert!(plugin.exists());
-            assert!(agents_md.exists());
 
             uninstall(true, false, false, false, true, 0).unwrap();
 
             assert!(!plugin.exists(), "plugin must be removed");
-            let content = fs::read_to_string(&agents_md).unwrap_or_default();
-            assert!(
-                !content.contains(PI_AWARENESS_START),
-                "awareness block must be removed"
-            );
         });
     }
 
     #[test]
-    fn test_pi_local_uninstall_removes_plugin_and_awareness() {
+    fn test_pi_local_uninstall_removes_plugin() {
         let tmp = TempDir::new().unwrap();
         let _cwd_guard = CWD_LOCK.lock().unwrap_or_else(|e| e.into_inner());
         let cwd = std::env::current_dir().unwrap();
@@ -4476,13 +4205,6 @@ mod tests {
             .join(PI_EXTENSIONS_SUBDIR)
             .join(PI_PLUGIN_FILE);
         assert!(!plugin.exists(), "local plugin must be removed");
-
-        let agents_md = tmp.path().join(AGENTS_MD);
-        let content = fs::read_to_string(&agents_md).unwrap_or_default();
-        assert!(
-            !content.contains(PI_AWARENESS_START),
-            "local awareness block must be removed"
-        );
     }
 
     #[test]
diff --git a/src/main.rs b/src/main.rs
index 4ce076e40..74736d5e5 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -3033,7 +3033,11 @@ mod tests {
         let cli = Cli::try_parse_from(["rtk", "init", "--agent", "pi"]).unwrap();
         match cli.command {
             Commands::Init { agent, .. } => {
-                assert_eq!(agent, Some(AgentTarget::Pi), "--agent pi must set Pi variant");
+                assert_eq!(
+                    agent,
+                    Some(AgentTarget::Pi),
+                    "--agent pi must set Pi variant"
+                );
             }
             _ => panic!("Expected Init command"),
         }
@@ -3041,8 +3045,7 @@ mod tests {
 
     #[test]
     fn test_init_uninstall_pi_parses() {
-        let cli =
-            Cli::try_parse_from(["rtk", "init", "--uninstall", "--pi", "--global"]).unwrap();
+        let cli = Cli::try_parse_from(["rtk", "init", "--uninstall", "--pi", "--global"]).unwrap();
         match cli.command {
             Commands::Init {
                 uninstall,

From a4caafad710dc6dd23bd26e625a22dd2306a4ce0 Mon Sep 17 00:00:00 2001
From: gitbluf <git+gh@gitbluf.xyz>
Date: Wed, 6 May 2026 18:51:39 +0200
Subject: [PATCH 05/13] chore: docs cleanup

---
 docs/guide/getting-started/supported-agents.md | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/docs/guide/getting-started/supported-agents.md b/docs/guide/getting-started/supported-agents.md
index 01d0551c1..88748a714 100644
--- a/docs/guide/getting-started/supported-agents.md
+++ b/docs/guide/getting-started/supported-agents.md
@@ -90,13 +90,8 @@ Creates `~/.config/opencode/plugins/rtk.ts`. Uses the `tool.execute.before` hook
 ```bash
 # Project-local (default)
 rtk init --pi
-
 # Global — all projects
 rtk init --pi --global
-
-# Pi only (no Claude/OpenCode install)
-rtk init --agent pi
-rtk init --agent pi --global
 ```
 
 Creates `.pi/extensions/rtk.ts` (local) or `~/.pi/agent/extensions/rtk.ts` (global). Pi auto-discovers extensions from both paths on startup.

From 2f163e3a41cbc6e46c814b80976993a73df3bea0 Mon Sep 17 00:00:00 2001
From: gitbluf <git+gh@gitbluf.xyz>
Date: Thu, 7 May 2026 20:27:51 +0200
Subject: [PATCH 06/13] fix(init): make --pi route to Pi-only mode and skip
 CLAUDE.md injection

---
 src/main.rs | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/src/main.rs b/src/main.rs
index 74736d5e5..b2148a58c 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1779,8 +1779,8 @@ fn run_cli() -> Result<i32> {
                 hooks::init::run_gemini(global, hook_only, patch_mode, cli.verbose)?;
             } else if copilot {
                 hooks::init::run_copilot(cli.verbose)?;
-            } else if agent == Some(AgentTarget::Pi) {
-                hooks::init::run_pi_mode(global, cli.verbose)?;
+            } else if pi || agent == Some(AgentTarget::Pi) {
+                hooks::init::run_pi_mode(global, cli.verbose)?
             } else if agent == Some(AgentTarget::Kilocode) {
                 if global {
                     anyhow::bail!("Kilo Code is project-scoped. Use: rtk init --agent kilocode");
@@ -1820,9 +1820,6 @@ fn run_cli() -> Result<i32> {
                     patch_mode,
                     cli.verbose,
                 )?;
-                if pi {
-                    hooks::init::run_pi_mode(global, cli.verbose)?;
-                }
             }
             0
         }

From a7cab79084c59c6146428a66c2df1318381c625e Mon Sep 17 00:00:00 2001
From: Marko Petrovic <22802784+gitbluf@users.noreply.github.com>
Date: Fri, 8 May 2026 00:32:31 +0200
Subject: [PATCH 07/13] chore: update hooks/pi/rtk.ts to reflect new package
 name

Co-authored-by: Jean du Plessis <jeandp@gmail.com>
---
 hooks/pi/rtk.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/hooks/pi/rtk.ts b/hooks/pi/rtk.ts
index 8fec20512..d0debffe5 100644
--- a/hooks/pi/rtk.ts
+++ b/hooks/pi/rtk.ts
@@ -13,8 +13,8 @@
 //   3 + stdout  Ask rule matched → mutate command, allow (Pi has no confirm UI)
 
 import { spawn } from "node:child_process"
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"
-import { isToolCallEventType } from "@mariozechner/pi-coding-agent"
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
+import { isToolCallEventType } from "@earendil-works/pi-coding-agent"
 
 // Run a command, return { stdout, exitCode } or null on spawn error / timeout.
 function exec(cmd: string, args: string[], timeoutMs = 2000): Promise<{ stdout: string; exitCode: number } | null> {

From cb1661e68d995e72bec49fb0e619fd8178f376a4 Mon Sep 17 00:00:00 2001
From: gitbluf <git+gh@gitbluf.xyz>
Date: Mon, 11 May 2026 21:46:46 +0200
Subject: [PATCH 08/13] feat(init): remove --pi flag, canonicalize Pi install
 to --agent pi chore: sync the codebase after mergew

---
 .../guide/getting-started/supported-agents.md |  9 +++--
 hooks/README.md                               | 14 ++++---
 hooks/pi/README.md                            |  8 ++--
 src/hooks/README.md                           |  2 +-
 src/hooks/init.rs                             | 37 ++++++++++---------
 src/main.rs                                   | 35 ++++++++----------
 6 files changed, 53 insertions(+), 52 deletions(-)

diff --git a/docs/guide/getting-started/supported-agents.md b/docs/guide/getting-started/supported-agents.md
index 16f30615f..b7fb920de 100644
--- a/docs/guide/getting-started/supported-agents.md
+++ b/docs/guide/getting-started/supported-agents.md
@@ -90,9 +90,10 @@ Creates `~/.config/opencode/plugins/rtk.ts`. Uses the `tool.execute.before` hook
 
 ```bash
 # Project-local (default)
-rtk init --pi
+rtk init --agent pi
+
 # Global — all projects
-rtk init --pi --global
+rtk init --agent pi --global
 ```
 
 Creates `.pi/extensions/rtk.ts` (local) or `~/.pi/agent/extensions/rtk.ts` (global). Pi auto-discovers extensions from both paths on startup.
@@ -100,8 +101,8 @@ Creates `.pi/extensions/rtk.ts` (local) or `~/.pi/agent/extensions/rtk.ts` (glob
 Uninstall:
 
 ```bash
-rtk init --uninstall --pi
-rtk init --uninstall --pi --global
+rtk init --uninstall --agent pi
+rtk init --uninstall --agent pi --global
 ```
 
 Removes only the installed Pi extension file.
diff --git a/hooks/README.md b/hooks/README.md
index 6a485dd17..55b2149dd 100644
--- a/hooks/README.md
+++ b/hooks/README.md
@@ -64,6 +64,7 @@ Each agent subdirectory has its own README with hook-specific details:
 ### Claude Code (Shell Hook)
 
 **Input** (stdin):
+
 ```json
 {
   "tool_name": "Bash",
@@ -72,6 +73,7 @@ Each agent subdirectory has its own README with hook-specific details:
 ```
 
 **Output** (stdout, when rewritten):
+
 ```json
 {
   "hookSpecificOutput": {
@@ -88,6 +90,7 @@ Each agent subdirectory has its own README with hook-specific details:
 **Input**: Same as Claude Code.
 
 **Output** (stdout, when rewritten):
+
 ```json
 {
   "permission": "allow",
@@ -100,6 +103,7 @@ Returns `{}` when no rewrite (Cursor requires JSON for all paths).
 ### Copilot CLI (Rust Binary)
 
 **Input** (stdin, camelCase, `toolArgs` is JSON-stringified):
+
 ```json
 {
   "toolName": "bash",
@@ -108,6 +112,7 @@ Returns `{}` when no rewrite (Cursor requires JSON for all paths).
 ```
 
 **Output** (no `updatedInput` support -- uses deny-with-suggestion):
+
 ```json
 {
   "permissionDecision": "deny",
@@ -118,6 +123,7 @@ Returns `{}` when no rewrite (Cursor requires JSON for all paths).
 ### VS Code Copilot Chat (Rust Binary)
 
 **Input** (stdin, snake_case):
+
 ```json
 {
   "tool_name": "Bash",
@@ -130,6 +136,7 @@ Returns `{}` when no rewrite (Cursor requires JSON for all paths).
 ### Gemini CLI (Rust Binary)
 
 **Input** (stdin):
+
 ```json
 {
   "tool_name": "run_shell_command",
@@ -138,6 +145,7 @@ Returns `{}` when no rewrite (Cursor requires JSON for all paths).
 ```
 
 **Output** (when rewritten):
+
 ```json
 {
   "decision": "allow",
@@ -152,6 +160,7 @@ Returns `{}` when no rewrite (Cursor requires JSON for all paths).
 ### OpenCode (TypeScript Plugin)
 
 Mutates `args.command` in-place via the zx library:
+
 ```typescript
 const result = await $`rtk rewrite ${command}`.quiet().nothrow()
 const rewritten = String(result.stdout).trim()
@@ -247,8 +256,3 @@ RTK supports AI coding assistants that developers actually use day-to-day. To ad
 ### Maintenance
 
 If an agent's API changes and the hook breaks, the integration should be updated promptly. If the agent becomes unmaintained or the hook can't be fixed, the integration may be deprecated with a release note.
-
-### Worked Example
-
-See [`docs/specs/pi-hook-integration.md`](../docs/specs/pi-hook-integration.md) for a complete integration SPEC — covering design, component inventory, exit-code mapping, install layout, error handling, and testing strategy. Use it as a template when speccing new agent integrations.
-
diff --git a/hooks/pi/README.md b/hooks/pi/README.md
index ef7038f71..167490936 100644
--- a/hooks/pi/README.md
+++ b/hooks/pi/README.md
@@ -9,20 +9,20 @@
 - Calls `rtk rewrite` as a subprocess; mutates `event.input.command` in-place if rewrite differs
 - Returns `{ block: true, reason }` on deny (exit code 2); all other error paths return `undefined`
 - Version guard at load time: checks `rtk >= 0.23.0`; warns and registers no-op if too old or missing
-- Installed to `.pi/extensions/rtk.ts` by `rtk init --pi` (project-local) or `~/.pi/agent/extensions/rtk.ts` by `rtk init --pi --global`
+- Installed to `.pi/extensions/rtk.ts` by `rtk init --agent pi` (project-local) or `~/.pi/agent/extensions/rtk.ts` by `rtk init --agent pi --global`
 
 ## Uninstall
 
 ```bash
 # Remove project-local install (run from the project root)
-rtk init --uninstall --pi
+rtk init --uninstall --agent pi
 # → removes .pi/extensions/rtk.ts
 
 # Remove global install
-rtk init --uninstall --pi --global
+rtk init --uninstall --agent pi --global
 # → removes ~/.pi/agent/extensions/rtk.ts
 
-# Pi-only target form also works
+# Pi-only target form
 rtk init --uninstall --agent pi
 rtk init --uninstall --agent pi --global
 ```
diff --git a/src/hooks/README.md b/src/hooks/README.md
index 3f9a17346..a0c76b76d 100644
--- a/src/hooks/README.md
+++ b/src/hooks/README.md
@@ -30,7 +30,7 @@ LLM agent integration layer that installs, validates, and executes command-rewri
 | Cline | `rtk init --agent cline` | `.clinerules` | -- |
 | Codex | `rtk init --codex` | RTK.md in `$CODEX_HOME` or `~/.codex` | AGENTS.md |
 | Cursor | `rtk init -g --agent cursor` | Cursor hook | hooks.json |
-| Pi | `rtk init --pi` | `.pi/extensions/rtk.ts` | -- |
+| Pi | `rtk init --agent pi` | `.pi/extensions/rtk.ts` | -- |
 | Hermes | `rtk init --agent hermes` | Python plugin in `~/.hermes/plugins/rtk-rewrite/` | `config.yaml` `plugins.enabled` |
 
 
diff --git a/src/hooks/init.rs b/src/hooks/init.rs
index 18c504073..94fda39db 100644
--- a/src/hooks/init.rs
+++ b/src/hooks/init.rs
@@ -13,10 +13,9 @@ use crate::hooks::constants::{
 
 use super::constants::{
     BEFORE_TOOL_KEY, CLAUDE_DIR, CLAUDE_HOOK_COMMAND, CODEX_DIR, CURSOR_HOOK_COMMAND,
-    GEMINI_HOOK_FILE, HOOKS_JSON, HOOKS_SUBDIR, PI_CODING_AGENT_DIR_ENV, PI_DIR,
-    PI_EXTENSIONS_SUBDIR, PI_PLUGIN_FILE, PRE_TOOL_USE_KEY, REWRITE_HOOK_FILE, SETTINGS_JSON,
     GEMINI_HOOK_FILE, HERMES_DIR, HERMES_PLUGINS_SUBDIR, HERMES_PLUGIN_INIT_FILE,
-    HERMES_PLUGIN_MANIFEST_FILE, HERMES_PLUGIN_NAME, HOOKS_JSON, HOOKS_SUBDIR, PRE_TOOL_USE_KEY,
+    HERMES_PLUGIN_MANIFEST_FILE, HERMES_PLUGIN_NAME, HOOKS_JSON, HOOKS_SUBDIR,
+    PI_CODING_AGENT_DIR_ENV, PI_DIR, PI_EXTENSIONS_SUBDIR, PI_PLUGIN_FILE, PRE_TOOL_USE_KEY,
     REWRITE_HOOK_FILE, SETTINGS_JSON,
 };
 use super::integrity;
@@ -612,8 +611,9 @@ pub fn uninstall(
     codex: bool,
     cursor: bool,
     pi: bool,
-    verbose: u8,
+    ctx: InitContext,
 ) -> Result<()> {
+    let InitContext { verbose, dry_run } = ctx;
     if codex {
         uninstall_codex(global, ctx)?;
         if dry_run {
@@ -2784,15 +2784,16 @@ fn pi_plugin_path_for_scope(global: bool) -> Result<PathBuf> {
 }
 
 /// Write the Pi extension file if missing or outdated. Returns true if written.
-fn ensure_pi_plugin_installed(path: &Path, verbose: u8) -> Result<bool> {
-    write_if_changed(path, PI_PLUGIN, "Pi extension", verbose)
+fn ensure_pi_plugin_installed(path: &Path, ctx: InitContext) -> Result<bool> {
+    write_if_changed(path, PI_PLUGIN, "Pi extension", ctx)
 }
 
 /// Install the Pi extension (hook-only; no AGENTS.md injection).
 ///
 /// global=true  → `$PI_CODING_AGENT_DIR/extensions/rtk.ts`
 /// global=false → `.pi/extensions/rtk.ts`
-pub fn run_pi_mode(global: bool, verbose: u8) -> Result<()> {
+pub fn run_pi_mode(global: bool, ctx: InitContext) -> Result<()> {
+    let InitContext { verbose: _, .. } = ctx;
     let plugin_path = if global {
         let pi_dir = resolve_pi_dir()?;
         let path = pi_plugin_path(&pi_dir);
@@ -2818,7 +2819,7 @@ pub fn run_pi_mode(global: bool, verbose: u8) -> Result<()> {
         path
     };
 
-    let installed = ensure_pi_plugin_installed(&plugin_path, verbose)?;
+    let installed = ensure_pi_plugin_installed(&plugin_path, ctx)?;
     print_pi_result(&plugin_path, installed);
 
     Ok(())
@@ -5526,7 +5527,7 @@ mod tests {
         let tmp = TempDir::new().unwrap();
         with_claude_dir_override(&tmp, |claude_dir| {
             run_default_mode(true, PatchMode::Auto, false, InitContext::default()).unwrap();
-            uninstall(true, false, false, false, InitContext::default()).unwrap();
+            uninstall(true, false, false, false, false, InitContext::default()).unwrap();
 
             assert!(!claude_dir.join(RTK_MD).exists(), "RTK.md must be removed");
             let settings_content =
@@ -5654,7 +5655,7 @@ mod tests {
                 dry_run: true,
                 ..Default::default()
             };
-            uninstall(true, false, false, false, dry).unwrap();
+            uninstall(true, false, false, false, false, dry).unwrap();
 
             // Files must still exist with identical content
             assert!(
@@ -5774,7 +5775,7 @@ mod tests {
     fn test_run_pi_mode_global_installs_plugin() {
         let tmp = TempDir::new().unwrap();
         with_pi_dir_override(&tmp, |pi_dir| {
-            run_pi_mode(true, 0).unwrap();
+            run_pi_mode(true, InitContext::default()).unwrap();
 
             let plugin = pi_dir.join(PI_EXTENSIONS_SUBDIR).join(PI_PLUGIN_FILE);
             assert!(plugin.exists(), "global Pi extension must be created");
@@ -5794,7 +5795,7 @@ mod tests {
         let cwd = std::env::current_dir().unwrap();
         std::env::set_current_dir(tmp.path()).unwrap();
 
-        let result = run_pi_mode(false, 0);
+        let result = run_pi_mode(false, InitContext::default());
         std::env::set_current_dir(&cwd).unwrap();
         result.unwrap();
 
@@ -5810,7 +5811,7 @@ mod tests {
     fn test_run_pi_mode_global_does_not_create_agents_md() {
         let tmp = TempDir::new().unwrap();
         with_pi_dir_override(&tmp, |pi_dir| {
-            run_pi_mode(true, 0).unwrap();
+            run_pi_mode(true, InitContext::default()).unwrap();
 
             let agents_md = pi_dir.join(AGENTS_MD);
             assert!(!agents_md.exists(), "AGENTS.md must not be created");
@@ -5825,7 +5826,7 @@ mod tests {
         let orig = std::env::var_os(PI_CODING_AGENT_DIR_ENV);
         std::env::set_var(PI_CODING_AGENT_DIR_ENV, &absent_dir);
 
-        let result = run_pi_mode(true, 0);
+        let result = run_pi_mode(true, InitContext::default());
 
         match orig {
             Some(v) => std::env::set_var(PI_CODING_AGENT_DIR_ENV, v),
@@ -5848,12 +5849,12 @@ mod tests {
     fn test_pi_global_uninstall_removes_plugin() {
         let tmp = TempDir::new().unwrap();
         with_pi_dir_override(&tmp, |pi_dir| {
-            run_pi_mode(true, 0).unwrap();
+            run_pi_mode(true, InitContext::default()).unwrap();
 
             let plugin = pi_dir.join(PI_EXTENSIONS_SUBDIR).join(PI_PLUGIN_FILE);
             assert!(plugin.exists());
 
-            uninstall(true, false, false, false, true, 0).unwrap();
+            uninstall(true, false, false, false, true, InitContext::default()).unwrap();
 
             assert!(!plugin.exists(), "plugin must be removed");
         });
@@ -5866,8 +5867,8 @@ mod tests {
         let cwd = std::env::current_dir().unwrap();
         std::env::set_current_dir(tmp.path()).unwrap();
 
-        run_pi_mode(false, 0).unwrap();
-        let result = uninstall(false, false, false, false, true, 0);
+        run_pi_mode(false, InitContext::default()).unwrap();
+        let result = uninstall(false, false, false, false, true, InitContext::default());
         std::env::set_current_dir(&cwd).unwrap();
         result.unwrap();
 
diff --git a/src/main.rs b/src/main.rs
index 5cec09efb..469eefa9f 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -376,10 +376,6 @@ enum Commands {
         /// Install GitHub Copilot integration (VS Code + CLI)
         #[arg(long)]
         copilot: bool,
-
-        /// Install Pi coding agent extension
-        #[arg(long)]
-        pi: bool,
         /// Preview changes without writing any files (combine with -v to show content)
         #[arg(long = "dry-run", conflicts_with = "show")]
         dry_run: bool,
@@ -1366,13 +1362,14 @@ fn uninstall_init_dispatch<UninstallHermes, UninstallStandard>(
 ) -> Result<()>
 where
     UninstallHermes: FnOnce(hooks::init::InitContext) -> Result<()>,
-    UninstallStandard: FnOnce(bool, bool, bool, bool, hooks::init::InitContext) -> Result<()>,
+    UninstallStandard: FnOnce(bool, bool, bool, bool, bool, hooks::init::InitContext) -> Result<()>,
 {
     if agent == Some(AgentTarget::Hermes) {
         uninstall_hermes(ctx)
     } else {
         let cursor = agent == Some(AgentTarget::Cursor);
-        uninstall_standard(global, gemini, codex, cursor, ctx)
+        let pi = agent == Some(AgentTarget::Pi);
+        uninstall_standard(global, gemini, codex, cursor, pi, ctx)
     }
 }
 
@@ -1795,7 +1792,6 @@ fn run_cli() -> Result<i32> {
             uninstall,
             codex,
             copilot,
-            pi,
             dry_run,
         } => {
             let ctx = hooks::init::InitContext {
@@ -1825,8 +1821,8 @@ fn run_cli() -> Result<i32> {
                 hooks::init::run_gemini(global, hook_only, patch_mode, ctx)?;
             } else if copilot {
                 hooks::init::run_copilot(ctx)?;
-            } else if pi || agent == Some(AgentTarget::Pi) {
-                hooks::init::run_pi_mode(global, cli.verbose)?
+            } else if agent == Some(AgentTarget::Pi) {
+                hooks::init::run_pi_mode(global, ctx)?
             } else if agent == Some(AgentTarget::Kilocode) {
                 if global {
                     anyhow::bail!("Kilo Code is project-scoped. Use: rtk init --agent kilocode");
@@ -2680,7 +2676,7 @@ mod tests {
                 assert!(ctx.dry_run);
                 Ok(())
             },
-            |_, _, _, _, _| {
+            |_, _, _, _, _, _| {
                 standard_called.set(true);
                 Ok(())
             },
@@ -3149,12 +3145,10 @@ mod tests {
     }
 
     #[test]
-    fn test_init_pi_flag_parses() {
-        let cli = Cli::try_parse_from(["rtk", "init", "--pi"]).unwrap();
-        match cli.command {
-            Commands::Init { pi, .. } => assert!(pi, "--pi flag must be set"),
-            _ => panic!("Expected Init command"),
-        }
+    fn test_init_pi_flag_rejected() {
+        // --pi has been removed; --agent pi is the canonical form
+        let result = Cli::try_parse_from(["rtk", "init", "--pi"]);
+        assert!(result.is_err(), "--pi must be rejected as unknown argument");
     }
 
     #[test]
@@ -3173,17 +3167,18 @@ mod tests {
     }
 
     #[test]
-    fn test_init_uninstall_pi_parses() {
-        let cli = Cli::try_parse_from(["rtk", "init", "--uninstall", "--pi", "--global"]).unwrap();
+    fn test_init_uninstall_agent_pi_parses() {
+        let cli = Cli::try_parse_from(["rtk", "init", "--uninstall", "--agent", "pi", "--global"])
+            .unwrap();
         match cli.command {
             Commands::Init {
                 uninstall,
-                pi,
+                agent,
                 global,
                 ..
             } => {
                 assert!(uninstall);
-                assert!(pi);
+                assert_eq!(agent, Some(AgentTarget::Pi));
                 assert!(global);
             }
             _ => panic!("Expected Init command"),

From 64ed4f85504d94ac54e481b289e11362a5f75fdd Mon Sep 17 00:00:00 2001
From: gitbluf <git+gh@gitbluf.xyz>
Date: Mon, 18 May 2026 21:10:48 +0200
Subject: [PATCH 09/13] fix(init): honor dry-run for Pi install and uninstall
 paths

---
 src/hooks/init.rs | 184 ++++++++++++++++++++++++++++++++++++++++------
 src/main.rs       |   2 +-
 2 files changed, 164 insertions(+), 22 deletions(-)

diff --git a/src/hooks/init.rs b/src/hooks/init.rs
index 94fda39db..b452a4db8 100644
--- a/src/hooks/init.rs
+++ b/src/hooks/init.rs
@@ -654,16 +654,26 @@ pub fn uninstall(
         let mut removed: Vec<String> = Vec::new();
 
         if plugin_path.exists() {
-            fs::remove_file(&plugin_path).with_context(|| {
-                format!("Failed to remove Pi extension: {}", plugin_path.display())
-            })?;
-            if verbose > 0 {
-                eprintln!("Removed Pi extension: {}", plugin_path.display());
+            if dry_run {
+                println!(
+                    "[dry-run] would remove Pi extension: {}",
+                    plugin_path.display()
+                );
+            } else {
+                // nosemgrep: filesystem-deletion -- Pi uninstall removes only the RTK-managed extension file.
+                fs::remove_file(&plugin_path).with_context(|| {
+                    format!("Failed to remove Pi extension: {}", plugin_path.display())
+                })?;
+                if verbose > 0 {
+                    eprintln!("Removed Pi extension: {}", plugin_path.display());
+                }
+                removed.push(format!("Pi extension: {}", plugin_path.display()));
             }
-            removed.push(format!("Pi extension: {}", plugin_path.display()));
         }
 
-        if !removed.is_empty() {
+        if dry_run {
+            print_dry_run_footer();
+        } else if !removed.is_empty() {
             println!("RTK uninstalled (Pi):");
             for item in &removed {
                 println!("  - {}", item);
@@ -2788,39 +2798,52 @@ fn ensure_pi_plugin_installed(path: &Path, ctx: InitContext) -> Result<bool> {
     write_if_changed(path, PI_PLUGIN, "Pi extension", ctx)
 }
 
+/// Create the Pi extensions directory, or in dry-run mode, print a message only if
+/// the directory does not yet exist (avoids reporting no-op changes).
+fn ensure_pi_extensions_dir(parent: &Path, name: &str, ctx: InitContext) -> Result<()> {
+    let InitContext { dry_run, .. } = ctx;
+    if dry_run {
+        if !parent.exists() {
+            println!("[dry-run] would create {}: {}", name, parent.display());
+        }
+    } else {
+        fs::create_dir_all(parent)
+            .with_context(|| format!("Failed to create {}: {}", name, parent.display()))?;
+    }
+    Ok(())
+}
+
 /// Install the Pi extension (hook-only; no AGENTS.md injection).
 ///
 /// global=true  → `$PI_CODING_AGENT_DIR/extensions/rtk.ts`
 /// global=false → `.pi/extensions/rtk.ts`
 pub fn run_pi_mode(global: bool, ctx: InitContext) -> Result<()> {
-    let InitContext { verbose: _, .. } = ctx;
+    let InitContext {
+        verbose: _,
+        dry_run,
+    } = ctx;
     let plugin_path = if global {
         let pi_dir = resolve_pi_dir()?;
         let path = pi_plugin_path(&pi_dir);
         if let Some(parent) = path.parent() {
-            fs::create_dir_all(parent).with_context(|| {
-                format!(
-                    "Failed to create Pi extensions directory: {}",
-                    parent.display()
-                )
-            })?;
+            ensure_pi_extensions_dir(parent, "Pi extensions directory", ctx)?;
         }
         path
     } else {
         let path = pi_plugin_path_for_scope(false)?;
         if let Some(parent) = path.parent() {
-            fs::create_dir_all(parent).with_context(|| {
-                format!(
-                    "Failed to create local Pi extensions directory: {}",
-                    parent.display()
-                )
-            })?;
+            ensure_pi_extensions_dir(parent, "local Pi extensions directory", ctx)?;
         }
         path
     };
 
     let installed = ensure_pi_plugin_installed(&plugin_path, ctx)?;
-    print_pi_result(&plugin_path, installed);
+
+    if dry_run {
+        print_dry_run_footer();
+    } else {
+        print_pi_result(&plugin_path, installed);
+    }
 
     Ok(())
 }
@@ -5899,4 +5922,123 @@ mod tests {
                 .join(PI_PLUGIN_FILE)
         );
     }
+
+    #[test]
+    fn test_run_pi_mode_global_dry_run_writes_nothing() {
+        let tmp = TempDir::new().unwrap();
+        with_pi_dir_override(&tmp, |pi_dir| {
+            run_pi_mode(
+                true,
+                InitContext {
+                    verbose: 0,
+                    dry_run: true,
+                },
+            )
+            .unwrap();
+
+            assert!(
+                !pi_dir.join(PI_EXTENSIONS_SUBDIR).exists(),
+                "dry-run must not create the Pi extensions directory"
+            );
+            assert!(
+                !pi_dir
+                    .join(PI_EXTENSIONS_SUBDIR)
+                    .join(PI_PLUGIN_FILE)
+                    .exists(),
+                "dry-run must not create the Pi extension file"
+            );
+        });
+    }
+
+    #[test]
+    fn test_run_pi_mode_local_dry_run_writes_nothing() {
+        let tmp = TempDir::new().unwrap();
+        let _cwd_guard = CWD_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let cwd = std::env::current_dir().unwrap();
+        std::env::set_current_dir(tmp.path()).unwrap();
+
+        let result = run_pi_mode(
+            false,
+            InitContext {
+                verbose: 0,
+                dry_run: true,
+            },
+        );
+        std::env::set_current_dir(&cwd).unwrap();
+        result.unwrap();
+
+        assert!(
+            !tmp.path().join(".pi").join(PI_EXTENSIONS_SUBDIR).exists(),
+            "dry-run must not create .pi/extensions/"
+        );
+    }
+
+    #[test]
+    fn test_pi_global_uninstall_dry_run_keeps_plugin() {
+        let tmp = TempDir::new().unwrap();
+        with_pi_dir_override(&tmp, |pi_dir| {
+            run_pi_mode(true, InitContext::default()).unwrap();
+            let plugin = pi_dir.join(PI_EXTENSIONS_SUBDIR).join(PI_PLUGIN_FILE);
+            assert!(
+                plugin.exists(),
+                "plugin must exist before uninstall dry-run"
+            );
+
+            uninstall(
+                true,
+                false,
+                false,
+                false,
+                true,
+                InitContext {
+                    verbose: 0,
+                    dry_run: true,
+                },
+            )
+            .unwrap();
+
+            assert!(
+                plugin.exists(),
+                "dry-run uninstall must not remove the Pi extension"
+            );
+        });
+    }
+
+    #[test]
+    fn test_pi_local_uninstall_dry_run_keeps_plugin() {
+        let tmp = TempDir::new().unwrap();
+        let _cwd_guard = CWD_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let cwd = std::env::current_dir().unwrap();
+        std::env::set_current_dir(tmp.path()).unwrap();
+
+        run_pi_mode(false, InitContext::default()).unwrap();
+        let plugin = tmp
+            .path()
+            .join(".pi")
+            .join(PI_EXTENSIONS_SUBDIR)
+            .join(PI_PLUGIN_FILE);
+        assert!(
+            plugin.exists(),
+            "plugin must exist before uninstall dry-run"
+        );
+
+        let result = uninstall(
+            false,
+            false,
+            false,
+            false,
+            true,
+            InitContext {
+                verbose: 0,
+                dry_run: true,
+            },
+        );
+        std::env::set_current_dir(&cwd).unwrap();
+        result.unwrap();
+
+        assert!(
+            plugin.exists(),
+            "dry-run uninstall must not remove the local Pi extension"
+        );
+    }
 }
diff --git a/src/main.rs b/src/main.rs
index 469eefa9f..396523e71 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1799,7 +1799,7 @@ fn run_cli() -> Result<i32> {
                 dry_run,
             };
             if show {
-                hooks::init::show_config(codex)?
+                hooks::init::show_config(codex)?;
             } else if uninstall {
                 uninstall_init_dispatch(
                     agent,

From a6844dc7efcce820560891f8831f1fab56711d2b Mon Sep 17 00:00:00 2001
From: gitbluf <git+gh@gitbluf.xyz>
Date: Thu, 21 May 2026 13:15:51 +0200
Subject: [PATCH 10/13] chore: regroup agent init tests by agent section

---
 src/hooks/init.rs | 194 +++++++++++++++++++++++-----------------------
 1 file changed, 99 insertions(+), 95 deletions(-)

diff --git a/src/hooks/init.rs b/src/hooks/init.rs
index dbe647057..3c4c84e58 100644
--- a/src/hooks/init.rs
+++ b/src/hooks/init.rs
@@ -5836,6 +5836,33 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_claude_md_mode_refuses_malformed_block() {
+        // Mirrors `test_copilot_init_refuses_malformed_block`: a malformed
+        // CLAUDE.md previously emitted a warning and exited 0, silently
+        // skipping the OpenCode plugin step. The shared `write_rtk_block`
+        // dispatcher now bails for both paths.
+        let tmp = TempDir::new().unwrap();
+        with_claude_dir_override(&tmp, |claude_dir| {
+            let claude_md = claude_dir.join(CLAUDE_MD);
+            let malformed = format!(
+                "# Existing notes\n\n{}\nincomplete RTK block\n",
+                RTK_BLOCK_START
+            );
+            fs::write(&claude_md, &malformed).unwrap();
+
+            let result = run_claude_md_mode(true, false, InitContext::default());
+
+            assert!(
+                result.is_err(),
+                "Malformed CLAUDE.md must cause a hard error, not silent skip"
+            );
+
+            let after = fs::read_to_string(&claude_md).unwrap();
+            assert_eq!(after, malformed, "File must not be modified when malformed");
+        });
+    }
+
     // ─── Pi integration tests ───────────────────────────────────────────
 
     #[test]
@@ -6015,6 +6042,78 @@ mod tests {
             !tmp.path().join(".pi").join(PI_EXTENSIONS_SUBDIR).exists(),
             "dry-run must not create .pi/extensions/"
         );
+    }
+
+    #[test]
+    fn test_pi_global_uninstall_dry_run_keeps_plugin() {
+        let tmp = TempDir::new().unwrap();
+        with_pi_dir_override(&tmp, |pi_dir| {
+            run_pi_mode(true, InitContext::default()).unwrap();
+            let plugin = pi_dir.join(PI_EXTENSIONS_SUBDIR).join(PI_PLUGIN_FILE);
+            assert!(
+                plugin.exists(),
+                "plugin must exist before uninstall dry-run"
+            );
+
+            uninstall(
+                true,
+                false,
+                false,
+                false,
+                true,
+                InitContext {
+                    verbose: 0,
+                    dry_run: true,
+                },
+            )
+            .unwrap();
+
+            assert!(
+                plugin.exists(),
+                "dry-run uninstall must not remove the Pi extension"
+            );
+        });
+    }
+
+    #[test]
+    fn test_pi_local_uninstall_dry_run_keeps_plugin() {
+        let tmp = TempDir::new().unwrap();
+        let _cwd_guard = CWD_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let cwd = std::env::current_dir().unwrap();
+        std::env::set_current_dir(tmp.path()).unwrap();
+
+        run_pi_mode(false, InitContext::default()).unwrap();
+        let plugin = tmp
+            .path()
+            .join(".pi")
+            .join(PI_EXTENSIONS_SUBDIR)
+            .join(PI_PLUGIN_FILE);
+        assert!(
+            plugin.exists(),
+            "plugin must exist before uninstall dry-run"
+        );
+
+        let result = uninstall(
+            false,
+            false,
+            false,
+            false,
+            true,
+            InitContext {
+                verbose: 0,
+                dry_run: true,
+            },
+        );
+        std::env::set_current_dir(&cwd).unwrap();
+        result.unwrap();
+
+        assert!(
+            plugin.exists(),
+            "dry-run uninstall must not remove the local Pi extension"
+        );
+    }
+
+    // ─── Copilot tests ───────────────────────────────────────────────
 
     #[test]
     fn test_copilot_init_preserves_existing_instructions() {
@@ -6192,99 +6291,4 @@ mod tests {
             hook_path.display()
         );
     }
-
-    #[test]
-    fn test_pi_global_uninstall_dry_run_keeps_plugin() {
-        let tmp = TempDir::new().unwrap();
-        with_pi_dir_override(&tmp, |pi_dir| {
-            run_pi_mode(true, InitContext::default()).unwrap();
-            let plugin = pi_dir.join(PI_EXTENSIONS_SUBDIR).join(PI_PLUGIN_FILE);
-            assert!(
-                plugin.exists(),
-                "plugin must exist before uninstall dry-run"
-            );
-
-            uninstall(
-                true,
-                false,
-                false,
-                false,
-                true,
-                InitContext {
-                    verbose: 0,
-                    dry_run: true,
-                },
-            )
-            .unwrap();
-
-            assert!(
-                plugin.exists(),
-                "dry-run uninstall must not remove the Pi extension"
-            );
-        });
-    }
-
-    #[test]
-    fn test_pi_local_uninstall_dry_run_keeps_plugin() {
-        let tmp = TempDir::new().unwrap();
-        let _cwd_guard = CWD_LOCK.lock().unwrap_or_else(|e| e.into_inner());
-        let cwd = std::env::current_dir().unwrap();
-        std::env::set_current_dir(tmp.path()).unwrap();
-
-        run_pi_mode(false, InitContext::default()).unwrap();
-        let plugin = tmp
-            .path()
-            .join(".pi")
-            .join(PI_EXTENSIONS_SUBDIR)
-            .join(PI_PLUGIN_FILE);
-        assert!(
-            plugin.exists(),
-            "plugin must exist before uninstall dry-run"
-        );
-
-        let result = uninstall(
-            false,
-            false,
-            false,
-            false,
-            true,
-            InitContext {
-                verbose: 0,
-                dry_run: true,
-            },
-        );
-        std::env::set_current_dir(&cwd).unwrap();
-        result.unwrap();
-
-        assert!(
-            plugin.exists(),
-            "dry-run uninstall must not remove the local Pi extension"
-        );
-
-
-    fn test_claude_md_mode_refuses_malformed_block() {
-        // Mirrors `test_copilot_init_refuses_malformed_block`: a malformed
-        // CLAUDE.md previously emitted a warning and exited 0, silently
-        // skipping the OpenCode plugin step. The shared `write_rtk_block`
-        // dispatcher now bails for both paths.
-        let tmp = TempDir::new().unwrap();
-        with_claude_dir_override(&tmp, |claude_dir| {
-            let claude_md = claude_dir.join(CLAUDE_MD);
-            let malformed = format!(
-                "# Existing notes\n\n{}\nincomplete RTK block\n",
-                RTK_BLOCK_START
-            );
-            fs::write(&claude_md, &malformed).unwrap();
-
-            let result = run_claude_md_mode(true, false, InitContext::default());
-
-            assert!(
-                result.is_err(),
-                "Malformed CLAUDE.md must cause a hard error, not silent skip"
-            );
-
-            let after = fs::read_to_string(&claude_md).unwrap();
-            assert_eq!(after, malformed, "File must not be modified when malformed");
-        });
-    }
 }

From 9bd6e6f3929cf320193e34a2654603afa1e9fa91 Mon Sep 17 00:00:00 2001
From: gitbluf <git+gh@gitbluf.xyz>
Date: Sat, 23 May 2026 01:36:07 +0200
Subject: [PATCH 11/13] feat: address pr suggestions

---
 hooks/pi/README.md     |  23 ++++---
 hooks/pi/rtk.ts        | 135 +++++++++++++----------------------------
 src/hooks/constants.rs |   1 +
 src/hooks/init.rs      |  81 ++++++++++++++-----------
 4 files changed, 103 insertions(+), 137 deletions(-)

diff --git a/hooks/pi/README.md b/hooks/pi/README.md
index 167490936..1f0c8e00a 100644
--- a/hooks/pi/README.md
+++ b/hooks/pi/README.md
@@ -2,12 +2,22 @@
 
 > Part of [`hooks/`](../README.md) — see also [`src/hooks/`](../../src/hooks/README.md) for installation code
 
+## Design Intent
+
+RTK's Pi extension is a **rewrite-only token optimizer**. It mutates bash commands to their
+`rtk`-prefixed equivalents, saving 60–90% context tokens.
+
+**Permission gating is intentionally out of scope.** RTK does not block, confirm, or audit
+commands — that concern belongs to a dedicated permission extension (e.g. one that gates
+`rm -rf`, `sudo`, etc.). This separation keeps RTK's hook fast, predictable, and composable
+with other Pi extensions.
+
 ## Specifics
 
 - TypeScript extension using Pi's `ExtensionAPI` (not a shell hook, no `zx` dependency)
 - Subscribes to `tool_call` event, narrows to `bash` tool via `isToolCallEventType`
-- Calls `rtk rewrite` as a subprocess; mutates `event.input.command` in-place if rewrite differs
-- Returns `{ block: true, reason }` on deny (exit code 2); all other error paths return `undefined`
+- Calls `rtk rewrite` via `pi.exec`; mutates `event.input.command` in-place if rewrite differs
+- All error paths return `undefined` (pass through); RTK never blocks execution
 - Version guard at load time: checks `rtk >= 0.23.0`; warns and registers no-op if too old or missing
 - Installed to `.pi/extensions/rtk.ts` by `rtk init --agent pi` (project-local) or `~/.pi/agent/extensions/rtk.ts` by `rtk init --agent pi --global`
 
@@ -21,10 +31,6 @@ rtk init --uninstall --agent pi
 # Remove global install
 rtk init --uninstall --agent pi --global
 # → removes ~/.pi/agent/extensions/rtk.ts
-
-# Pi-only target form
-rtk init --uninstall --agent pi
-rtk init --uninstall --agent pi --global
 ```
 
 Uninstall is idempotent — re-running when nothing is installed is a no-op.
@@ -50,6 +56,5 @@ RTK_DISABLED=1 pi -e ./hooks/pi/rtk.ts
 ## Design Notes
 
 - All filtering logic lives in `rtk rewrite` (the Rust registry), not in this file
-- Exit code 3 (ask) is treated as allow — Pi has no per-tool confirmation UI
-- No `zx` library required; uses `node:child_process` `spawn` directly
-- See [`docs/specs/pi-hook-integration.md`](../../docs/specs/pi-hook-integration.md) for the full design spec
+- Exit codes 0 and 3 both mean "rewrite and allow"; they are handled identically
+- Uses `pi.exec` for subprocess management — consistent with Pi's extension API
diff --git a/hooks/pi/rtk.ts b/hooks/pi/rtk.ts
index d0debffe5..69f59c640 100644
--- a/hooks/pi/rtk.ts
+++ b/hooks/pi/rtk.ts
@@ -1,4 +1,4 @@
-// rtk-hook-version: 1
+// rtk-hook-version: 2
 // RTK Pi extension — rewrites bash commands to use rtk for token savings.
 // Requires: rtk >= 0.23.0 in PATH.
 //
@@ -7,52 +7,16 @@
 // To add or change rewrite rules, edit the Rust registry — not this file.
 //
 // Exit code contract for `rtk rewrite`:
-//   0 + stdout  Rewrite found → mutate command, allow
+//   0 + stdout  Rewrite found → mutate command
 //   1           No RTK equivalent → pass through unchanged
-//   2           Deny rule matched → block execution
-//   3 + stdout  Ask rule matched → mutate command, allow (Pi has no confirm UI)
+//   3 + stdout  Rewrite (advisory) → mutate command
 
-import { spawn } from "node:child_process"
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
 import { isToolCallEventType } from "@earendil-works/pi-coding-agent"
 
-// Run a command, return { stdout, exitCode } or null on spawn error / timeout.
-function exec(cmd: string, args: string[], timeoutMs = 2000): Promise<{ stdout: string; exitCode: number } | null> {
-  return new Promise((resolve) => {
-    let stdout = ""
-    let settled = false
-
-    const child = spawn(cmd, args, { env: process.env })
-
-    const timer = setTimeout(() => {
-      if (!settled) {
-        settled = true
-        child.kill()
-        resolve(null)
-      }
-    }, timeoutMs)
-
-    child.stdout.on("data", (chunk: Buffer) => {
-      stdout += chunk.toString()
-    })
-
-    child.on("close", (code: number | null) => {
-      if (!settled) {
-        settled = true
-        clearTimeout(timer)
-        resolve({ stdout, exitCode: code ?? 1 })
-      }
-    })
-
-    child.on("error", () => {
-      if (!settled) {
-        settled = true
-        clearTimeout(timer)
-        resolve(null)
-      }
-    })
-  })
-}
+const REWRITE_TIMEOUT_MS = 2_000
+const MAX_REWRITE_OUTPUT_BYTES = 1024 * 1024
+const MIN_SUPPORTED_RTK_MINOR = 23
 
 // Parse "X.Y.Z" semver, return [major, minor, patch] or null.
 function parseSemver(raw: string): [number, number, number] | null {
@@ -61,72 +25,59 @@ function parseSemver(raw: string): [number, number, number] | null {
   return [parseInt(m[1], 10), parseInt(m[2], 10), parseInt(m[3], 10)]
 }
 
+// Calls `rtk rewrite`; returns the rewritten command or null (pass through).
+async function rewriteCommand(
+  pi: ExtensionAPI,
+  cmd: string,
+  signal?: AbortSignal
+): Promise<string | null> {
+  const result = await pi.exec("rtk", ["rewrite", cmd], {
+    timeout: REWRITE_TIMEOUT_MS,
+    signal,
+    maxBuffer: MAX_REWRITE_OUTPUT_BYTES,
+  })
+  if (result.killed) return null
+  if (result.code !== 0 && result.code !== 3) return null
+  return result.stdout.trim() || null
+}
+
 export default async function (pi: ExtensionAPI) {
-  // Load-time check: probe rtk by running --version. This confirms the binary
-  // is in PATH and gives us the version for the semver guard in one spawn.
-  const ver = await exec("rtk", ["--version"])
-  if (!ver || ver.exitCode !== 0) {
+  // Probe rtk version at load time; disables extension if missing or too old.
+  const ver = await pi.exec("rtk", ["--version"], { timeout: REWRITE_TIMEOUT_MS })
+  if (ver.code !== 0) {
     console.warn("[rtk] rtk binary not found in PATH — extension disabled")
     return
   }
 
-  // Load-time version guard: rtk rewrite was introduced in 0.23.0. Without
-  // this check the extension still degrades gracefully — exec() returns null
-  // on any subprocess failure, which falls through to pass-through behaviour.
-  // The guard exists purely to surface a clear, actionable warning
-  // ("your rtk is too old, upgrade") rather than leaving the user wondering
-  // why rewrites silently stopped working after a version rollback.
-  // stdout format: "rtk X.Y.Z"
+  // Warn and bail if rtk predates 0.23.0 (when `rtk rewrite` was introduced).
   const parsed = parseSemver(ver.stdout.replace(/^rtk\s+/, ""))
   if (parsed) {
     const [major, minor] = parsed
-    if (major === 0 && minor < 23) {
+    if (major === 0 && minor < MIN_SUPPORTED_RTK_MINOR) {
       console.warn(`[rtk] rtk ${ver.stdout.trim()} is too old (need >= 0.23.0) — extension disabled`)
       return
     }
   }
 
-  pi.on("tool_call", async (event) => {
-    // Only intercept bash tool calls.
-    if (!isToolCallEventType("bash", event)) return
-
-    const cmd = event.input.command
-    if (!cmd) return
-
-    if (cmd.startsWith("rtk ")) return
-    if (process.env.RTK_DISABLED === "1") return
-
-    // Delegate all rewrite + permission logic to the RTK.
-    const result = await exec("rtk", ["rewrite", cmd])
-    if (!result) return // spawn error or timeout — pass through
+  pi.on("tool_call", async (event, ctx) => {
+    try {
+      if (!isToolCallEventType("bash", event)) return
 
-    const rewritten = result.stdout.trim()
+      const cmd = event.input.command
+      if (typeof cmd !== "string" || cmd.trim() === "") return
 
-    switch (result.exitCode) {
-      case 0:
-        // Rewrite found — mutate the command in-place.
-        if (rewritten && rewritten !== cmd) {
-          event.input.command = rewritten
-        }
-        return
+      if (cmd.startsWith("rtk ")) return
+      if (process.env.RTK_DISABLED === "1") return
 
-      case 1:
-        // No RTK equivalent — pass through unchanged.
-        return
-
-      case 2:
-        // Deny rule matched — block execution.
-        return { block: true, reason: `RTK: '${cmd}' is blocked — see rtk gain for details` }
-
-      case 3:
-        // Ask rule matched — rewrite and allow (Pi has no per-tool confirm UI).
-        if (rewritten && rewritten !== cmd) {
-          event.input.command = rewritten
-        }
-        return
-
-      default:
-        return
+      // Delegate to RTK.
+      const rewritten = await rewriteCommand(pi, cmd, ctx.signal)
+      if (rewritten && rewritten !== cmd) {
+        event.input.command = rewritten
+      }
+    } catch (err) {
+      // Fail open: never block execution on an unexpected error.
+      console.warn("[rtk] unexpected error in tool_call handler; passing through command", err)
+      return
     }
   })
 }
diff --git a/src/hooks/constants.rs b/src/hooks/constants.rs
index bd1937cf6..506e88cdf 100644
--- a/src/hooks/constants.rs
+++ b/src/hooks/constants.rs
@@ -23,6 +23,7 @@ pub const CODEX_DIR: &str = ".codex";
 pub const GEMINI_DIR: &str = ".gemini";
 
 pub const PI_DIR: &str = ".pi/agent";
+pub const PI_LOCAL_DIR: &str = ".pi";
 pub const PI_EXTENSIONS_SUBDIR: &str = "extensions";
 pub const PI_PLUGIN_FILE: &str = "rtk.ts";
 pub const PI_CODING_AGENT_DIR_ENV: &str = "PI_CODING_AGENT_DIR";
diff --git a/src/hooks/init.rs b/src/hooks/init.rs
index 3c4c84e58..189f5de55 100644
--- a/src/hooks/init.rs
+++ b/src/hooks/init.rs
@@ -15,8 +15,8 @@ use super::constants::{
     BEFORE_TOOL_KEY, CLAUDE_DIR, CLAUDE_HOOK_COMMAND, CODEX_DIR, CURSOR_HOOK_COMMAND,
     GEMINI_HOOK_FILE, HERMES_DIR, HERMES_PLUGINS_SUBDIR, HERMES_PLUGIN_INIT_FILE,
     HERMES_PLUGIN_MANIFEST_FILE, HERMES_PLUGIN_NAME, HOOKS_JSON, HOOKS_SUBDIR,
-    PI_CODING_AGENT_DIR_ENV, PI_DIR, PI_EXTENSIONS_SUBDIR, PI_PLUGIN_FILE, PRE_TOOL_USE_KEY,
-    REWRITE_HOOK_FILE, SETTINGS_JSON,
+    PI_CODING_AGENT_DIR_ENV, PI_DIR, PI_EXTENSIONS_SUBDIR, PI_LOCAL_DIR, PI_PLUGIN_FILE,
+    PRE_TOOL_USE_KEY, REWRITE_HOOK_FILE, SETTINGS_JSON,
 };
 use super::integrity;
 
@@ -650,38 +650,7 @@ pub fn uninstall(
     }
 
     if pi {
-        let plugin_path = pi_plugin_path_for_scope(global)?;
-        let mut removed: Vec<String> = Vec::new();
-
-        if plugin_path.exists() {
-            if dry_run {
-                println!(
-                    "[dry-run] would remove Pi extension: {}",
-                    plugin_path.display()
-                );
-            } else {
-                // nosemgrep: filesystem-deletion -- Pi uninstall removes only the RTK-managed extension file.
-                fs::remove_file(&plugin_path).with_context(|| {
-                    format!("Failed to remove Pi extension: {}", plugin_path.display())
-                })?;
-                if verbose > 0 {
-                    eprintln!("Removed Pi extension: {}", plugin_path.display());
-                }
-                removed.push(format!("Pi extension: {}", plugin_path.display()));
-            }
-        }
-
-        if dry_run {
-            print_dry_run_footer();
-        } else if !removed.is_empty() {
-            println!("RTK uninstalled (Pi):");
-            for item in &removed {
-                println!("  - {}", item);
-            }
-            println!("\nRestart pi to apply changes.");
-        } else {
-            println!("RTK Pi extension was not installed (nothing to remove)");
-        }
+        uninstall_pi(global, ctx)?;
         return Ok(());
     }
 
@@ -2816,7 +2785,7 @@ fn pi_plugin_path_for_scope(global: bool) -> Result<PathBuf> {
     if global {
         Ok(pi_plugin_path(&resolve_pi_dir()?))
     } else {
-        Ok(PathBuf::from(".pi")
+        Ok(PathBuf::from(PI_LOCAL_DIR)
             .join(PI_EXTENSIONS_SUBDIR)
             .join(PI_PLUGIN_FILE))
     }
@@ -2842,6 +2811,46 @@ fn ensure_pi_extensions_dir(parent: &Path, name: &str, ctx: InitContext) -> Resu
     Ok(())
 }
 
+/// Uninstall Pi extension for the given scope.
+/// Mirrors `uninstall_codex` / `uninstall_hermes`: extracted from the dispatcher
+/// so it can be tested and reasoned about independently.
+fn uninstall_pi(global: bool, ctx: InitContext) -> Result<()> {
+    let InitContext { verbose, dry_run } = ctx;
+    let plugin_path = pi_plugin_path_for_scope(global)?;
+    let mut removed: Vec<String> = Vec::new();
+
+    if plugin_path.exists() {
+        if dry_run {
+            println!(
+                "[dry-run] would remove Pi extension: {}",
+                plugin_path.display()
+            );
+        } else {
+            // nosemgrep: filesystem-deletion -- Pi uninstall removes only the RTK-managed extension file.
+            fs::remove_file(&plugin_path).with_context(|| {
+                format!("Failed to remove Pi extension: {}", plugin_path.display())
+            })?;
+            if verbose > 0 {
+                eprintln!("Removed Pi extension: {}", plugin_path.display());
+            }
+            removed.push(format!("Pi extension: {}", plugin_path.display()));
+        }
+    }
+
+    if dry_run {
+        print_dry_run_footer();
+    } else if !removed.is_empty() {
+        println!("RTK uninstalled (Pi):");
+        for item in &removed {
+            println!("  - {}", item);
+        }
+        println!("\nRestart pi to apply changes.");
+    } else {
+        println!("RTK Pi extension was not installed (nothing to remove)");
+    }
+    Ok(())
+}
+
 /// Install the Pi extension (hook-only; no AGENTS.md injection).
 ///
 /// global=true  → `$PI_CODING_AGENT_DIR/extensions/rtk.ts`
@@ -5988,7 +5997,7 @@ mod tests {
         let path = pi_plugin_path_for_scope(false).unwrap();
         assert_eq!(
             path,
-            PathBuf::from(".pi")
+            PathBuf::from(PI_LOCAL_DIR)
                 .join(PI_EXTENSIONS_SUBDIR)
                 .join(PI_PLUGIN_FILE)
         );

From 8bc8b463840183bc17817dbab0546b95c659bcc0 Mon Sep 17 00:00:00 2001
From: gitbluf <git+gh@gitbluf.xyz>
Date: Sat, 23 May 2026 01:57:37 +0200
Subject: [PATCH 12/13] chore: sync with pi api

---
 hooks/pi/rtk.ts | 2 --
 1 file changed, 2 deletions(-)

diff --git a/hooks/pi/rtk.ts b/hooks/pi/rtk.ts
index 69f59c640..4c30f203b 100644
--- a/hooks/pi/rtk.ts
+++ b/hooks/pi/rtk.ts
@@ -15,7 +15,6 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
 import { isToolCallEventType } from "@earendil-works/pi-coding-agent"
 
 const REWRITE_TIMEOUT_MS = 2_000
-const MAX_REWRITE_OUTPUT_BYTES = 1024 * 1024
 const MIN_SUPPORTED_RTK_MINOR = 23
 
 // Parse "X.Y.Z" semver, return [major, minor, patch] or null.
@@ -34,7 +33,6 @@ async function rewriteCommand(
   const result = await pi.exec("rtk", ["rewrite", cmd], {
     timeout: REWRITE_TIMEOUT_MS,
     signal,
-    maxBuffer: MAX_REWRITE_OUTPUT_BYTES,
   })
   if (result.killed) return null
   if (result.code !== 0 && result.code !== 3) return null

From f6a54518bd8576d5032f232b9e19f0a5b9e7399d Mon Sep 17 00:00:00 2001
From: gitbluf <git+gh@gitbluf.xyz>
Date: Sat, 23 May 2026 01:58:47 +0200
Subject: [PATCH 13/13] chore: minor cleanup

---
 hooks/pi/rtk.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/hooks/pi/rtk.ts b/hooks/pi/rtk.ts
index 4c30f203b..32cb2b5f1 100644
--- a/hooks/pi/rtk.ts
+++ b/hooks/pi/rtk.ts
@@ -1,4 +1,3 @@
-// rtk-hook-version: 2
 // RTK Pi extension — rewrites bash commands to use rtk for token savings.
 // Requires: rtk >= 0.23.0 in PATH.
 //