pi-task-tracker 0.1.8 → 0.2.0

package/README.md

@@ -16,6 +16,7 @@ Task workflow tracking for the [pi coding agent](https://www.npmjs.com/package/@
 - **Nested-repo aware** — changes inside a sub-repository (a `.git` below your session root) are committed *there* — the innermost repo wins — and never pollute the outer repo. The outer task commit records anchors (`Nested: <repo>@<sha>`), so `/rollback` restores nested repos to their exact matching commit.
 - **Pre-existing double tracking respected** — if a file is already tracked by both an outer repo and a nested repo, changes go to the nested repo (innermost wins), pi never untracks the outer copy, and `/rollback` never lets the outer repo restore its stale copy over the inner worktree.
 - **Subdirectory start** — start pi in a subdirectory of an existing repo and no fresh `.git` is created there: all session changes (including TODO.md / README.md) are recorded in the enclosing repository, and `/rollback` restores the enclosing repo scoped to the session subtree.
+- **Scope guard** — the writable scope equals the trackable scope: out-of-session writes are blocked by default (`taskTracker.externalWrite`), so nothing can be changed that `/rollback` could not restore. Git rules are inherited from `pi-permission-system`.
 - **Subagent-safe** — `.pi-subagents/` session artifacts are never recorded, listed, or committed.
 
 ## Lightweight by design (measured, not claimed)
@@ -74,6 +75,7 @@ Optional `taskTracker` key in `~/.pi/agent/settings.json` (all default to `true`
 - `todo` — maintain `TODO.md`
 - `readme` — maintain the `README.md` project-structure section
 - `autoCommit` — per-task commits; these are the `/rollback` checkpoints, so disabling this also disables rollback targets
+- `externalWrite` — policy for tool calls that would create/modify files OUTSIDE the session directory: `"block"` (default, hard deny — external changes cannot be tracked or rolled back), `"ask"` (per-attempt confirmation), `"off"` (no enforcement; `pi-permission-system` rules still apply). Reads stay free. Copying files FROM outside INTO the session is allowed (`cp` checks only its destination); moving/deleting external paths is blocked. Git history protection is **inherited**: history-rewriting git (rebase/reset/amend/force-push/clean/...) prompts for confirmation right here, so `pi-permission-system` can be uninstalled without losing that layer; routine git passes untouched, an external `git init`/`clone` is allowed with a heads-up that the new repo is not tracked. Shell commands are analyzed statically (redirects, `rm/mv/cp/touch/...`, `cd` tracking, PowerShell equivalents); git protection is inherited from `pi-permission-system` — routine git passes untouched and history-rewriting git still prompts there; only redirect targets and `-C` destinations on git segments are checked.
 
 ## Requirements
 
@@ -95,3 +97,13 @@ Optional `taskTracker` key in `~/.pi/agent/settings.json` (all default to `true`
 ## License
 
 MIT
+
+## Overview
+
+TODO: Add project description.
+
+## Project Structure
+
+```
+pi-task-tracker/
+```

package/index.ts

@@ -106,6 +106,233 @@ function findEnclosingRepo(dir: string): string | null {
   }
 }
 
+
+// ---- External-write guard ----
+// Enforces the tracking boundary as a write boundary: pi-task-tracker can
+// only track (and therefore only roll back) the session directory, so by
+// default (config taskTracker.externalWrite="block") tool calls that would
+// create/modify files OUTSIDE it are denied. Reads stay free. Git command
+// protection is inherited from pi-permission-system's bash rules (rebase/
+// reset/amend/force-push/... ask there): this guard never inspects git
+// arguments, only redirect targets and -C destinations on git segments.
+
+const GUARD_WRITE_TOOLS = new Set(["write", "edit", "replace", "insert", "undo_last_change"]);
+const GUARD_READ_TOOLS = new Set(["read", "grep", "find", "ls", "anchor_grep", "glob"]);
+const GUARD_SHELL_WRITE_CMDS = new Set([
+  "rm", "mv", "touch", "mkdir", "rmdir", "tee", "truncate", "dd",
+  "patch", "chmod", "chmod", "chown", "sed",
+]);
+// copy-like commands only WRITE their destination (last path argument);
+// the source is a read, so `cp /external/file ./` stays allowed
+const GUARD_COPY_CMDS = new Set(["cp", "install", "ln", "rsync"]);
+// interpreters: their -c/script payload can write anywhere; if the command
+// text mentions an external absolute path we block, otherwise we cannot
+// judge script contents (documented limitation)
+const GUARD_INTERPRETERS = new Set(["python", "python3", "py", "node", "deno", "bun", "ruby", "perl", "php"]);
+// inherited verbatim from pi-permissions.jsonc (pi-permission-system):
+// git operations that DELETE or REWRITE history require user confirmation.
+const GUARD_GIT_ASK = [
+  "git rebase", "git reset", "git commit --amend", "git push --force",
+  "git push -f", "git revert", "git branch -D", "git branch -d", "git tag -d",
+  "git clean", "git stash drop", "git stash clear", "git filter-branch",
+];
+const GUARD_GIT_ASK_CACHE_TTL = 0;
+const GUARD_PS_WRITE_CMDS = new Set([
+  "set-content", "out-file", "add-content", "new-item", "remove-item",
+  "copy-item", "move-item", "clear-content", "ni", "ri", "mi", "ac", "sc", "sp",
+]);
+
+// Resolve a shell token to an absolute path; unresolvable tokens (env vars,
+// command substitution) are treated as external - conservative by design.
+function guardResolve(effCwd: string, sessionCwd: string, token: string): { abs: string; external: boolean } {
+  let t = token.replace(/^["']|["']$/g, "").trim();
+  if (!t) return { abs: effCwd, external: false };
+  if (t.startsWith("~")) return { abs: t, external: true };
+  if (/[\$`]/.test(t)) return { abs: t, external: true };
+  if (/^[A-Za-z]:[\\/]/.test(t) || t.startsWith("/")) {
+    return { abs: t, external: isExternalAbs(t, sessionCwd) };
+  }
+  const abs = path.resolve(effCwd, t);
+  return { abs, external: isExternalAbs(abs, sessionCwd) };
+}
+
+function isExternalAbs(abs: string, base: string): boolean {
+  const rel = path.relative(base, abs);
+  return rel.startsWith("..") || path.isAbsolute(rel);
+}
+
+function guardIsDevNull(t: string): boolean {
+  return /^\/dev\/null/i.test(t) || /^nul$/i.test(t) || /^\$null$/i.test(t);
+}
+
+// Analyze one shell command for writes that would land outside `sessionCwd`.
+// Returns the offending path (for the deny reason) or null.
+// Analyze one shell command. Returns { block, ask, notify } hits (any may be
+// absent). External-write analysis is best effort: redirect targets,
+// write-command arguments (copy-like: destination only), interpreter payloads
+// mentioning external absolute paths, cd tracking. Git arguments are NOT
+// analyzed (inherited protection: only history-rewriting git asks).
+function guardShellExternalWrite(cmd: string, sessionCwd: string): { block?: string; ask?: string; notify?: string } | null {
+  const segments = cmd.split(/\n|&&|\|\||;|\|/).map((s) => s.trim()).filter(Boolean);
+  let effCwd = sessionCwd;
+  const out: { block?: string; ask?: string; notify?: string } = {};
+  for (const seg of segments) {
+    const cd = seg.match(/^cd\s+(.+)$/i) || seg.match(/^sl\s+(.+)$/i) || seg.match(/^set-location\s+(.+)$/i);
+    if (cd) {
+      const r = guardResolve(effCwd, sessionCwd, cd[1]);
+      // switch to the real effective cwd even when external: only WRITE ops
+      // are analyzed below, so `cd elsewhere && cat f` still passes while
+      // `cd elsewhere && touch a.txt` is correctly judged external.
+      effCwd = r.abs;
+      continue;
+    }
+    // 2. redirects: > >> 2> 2>> &> &>> >| (not heredocs, not fd dups like 2>&1)
+    for (const m of seg.matchAll(/(?:^|[^<>&=(])(?:\d?>{1,2}|&>>?|>\|)\s*([^\s;&|]+)/g)) {
+      const tgt = m[1];
+      if (/^&?\d+$/.test(tgt) || guardIsDevNull(tgt)) continue;
+      const r = guardResolve(effCwd, sessionCwd, tgt);
+      if (r.external) out.block = r.abs;
+    }
+    const isGit = /^git(\s|$)/.test(seg);
+    // 1. inherited git protection: history-rewriting git asks (matches
+    //    pi-permissions.jsonc bash patterns; prefix match like "git rebase*")
+    if (isGit) {
+      const low = seg.toLowerCase();
+      if (GUARD_GIT_ASK.some((p) => low.startsWith(p))) {
+        out.ask = seg.slice(0, 80);
+        continue;
+      }
+      if (/^git\s+(init|clone)/.test(low)) {
+        const r = guardResolve(effCwd, sessionCwd, seg.split(/\s+/)[1] === "clone" ? (seg.match(/\s+(\S+)\s+\S+$/) || [])[1] || "." : ".");
+        if (r.external) {
+          out.notify = `git ${seg.startsWith("git clone") ? "clone" : "init"} outside the session directory (${r.abs}). pi-task-tracker does NOT track that directory; start a separate pi session there if you want it tracked.`;
+        }
+      }
+      // external -C destination on any git command
+      const c = seg.match(/\s-C\s+(\S+)/);
+      if (c) {
+        const r = guardResolve(effCwd, sessionCwd, c[1]);
+        if (r.external) out.block = r.abs;
+      }
+      continue;
+    }
+    // 3. write-ish commands: copy-like checks ONLY the destination (last path
+    //    argument) so `cp /external/file ./` stays allowed; others check all
+    const tokens = seg.split(/\s+/);
+    const head = (tokens[0] || "").toLowerCase().replace(/\.exe$/, "");
+    const headBase = head.split(/[\/]/).pop() || head;
+    const isPsWrite = GUARD_PS_WRITE_CMDS.has(headBase);
+    const isShWrite = GUARD_SHELL_WRITE_CMDS.has(headBase);
+    const isCopy = GUARD_COPY_CMDS.has(headBase);
+    const isInterp = GUARD_INTERPRETERS.has(headBase);
+    if (!isPsWrite && !isShWrite && !isCopy && !isInterp) continue;
+    if (isInterp) {
+      // interpreter: block only if the command TEXT names an external path
+      for (const m of seg.matchAll(/[A-Za-z]:[\/]\S*|\/(?:[\w.-]+\/)+[\w.-]+/g)) {
+        if (guardIsDevNull(m[0])) continue;
+        if (isExternalAbs(m[0], sessionCwd)) { out.block = m[0]; break; }
+      }
+      continue;
+    }
+    const pathArgs = [];
+    for (let k = 1; k < tokens.length; k++) {
+      if (tokens[k].startsWith("-")) continue;
+      pathArgs.push(tokens[k]);
+    }
+    const checkList = isCopy ? pathArgs.slice(-1) : pathArgs;
+    for (const t of checkList) {
+      if (/^[A-Za-z]:[\{1,2}]/.test(t) || t.startsWith("/")) { // absolute
+        if (guardIsDevNull(t)) continue;
+        if (isExternalAbs(t, sessionCwd)) out.block = t;
+      } else if (/[\$`~]/.test(t)) {
+        out.block = t; // unresolvable -> conservative
+      } else {
+        const abs = path.resolve(effCwd, t);
+        if (isExternalAbs(abs, sessionCwd)) out.block = t;
+      }
+      if (out.block) break;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+const GUARD_ASK_PROMPT = "pi-task-tracker external-write guard";
+
+// Returns null (allow), "__ask__" (ask mode, user approved), or a deny reason.
+async function guardExternalWriteHit(
+  event: { toolName: string; input?: unknown },
+  sessionCwd: string,
+  mode: "block" | "ask",
+  ctx?: { hasUI?: boolean; ui?: { confirm: (t: string, m: string) => Promise<boolean>; notify: (m: string, kind?: string) => void } }
+): Promise<string | null> {
+  if (!sessionCwd) return null;
+  const toolName = event.toolName || "";
+
+  // shell tools: static best-effort analysis (bash/powershell)
+  if (toolName === "bash" || toolName === "powershell") {
+    const cmd = (event.input as { command?: string } | undefined)?.command || "";
+    const hit = guardShellExternalWrite(cmd, sessionCwd);
+    if (!hit) return null;
+    if (hit.notify && ctx?.hasUI && ctx.ui) ctx.ui.notify(hit.notify, "info");
+    if (hit.ask) {
+      if (!ctx?.hasUI || !ctx.ui) return `pi-task-tracker guard: history-rewriting git ('${hit.ask}') requires approval but no UI is available.`;
+      const ok = await ctx.ui.confirm(
+        "pi-task-tracker git guard (inherited)",
+        `History-rewriting git command: '${hit.ask}'. This protection was inherited from pi-permission-system. Allow?`,
+      );
+      if (ok) return null;
+      return `pi-task-tracker guard: user denied '${hit.ask}'. Do not retry or bypass.`;
+    }
+    if (hit.block) {
+      const why = "External changes cannot be tracked or rolled back by pi-task-tracker.";
+      if (mode === "ask") {
+        if (!ctx?.hasUI || !ctx.ui) return `pi-task-tracker scope guard: '${hit.block}' is outside the session directory and no UI is available. ${why}`;
+        const ok = await ctx.ui.confirm(
+          "pi-task-tracker external-write guard",
+          `This command writes to '${hit.block}' outside the session directory. ${why} Allow anyway?`,
+        );
+        if (ok) return null;
+        return `pi-task-tracker scope guard: user denied external write to '${hit.block}'. Do not retry or bypass.`;
+      }
+      return `pi-task-tracker scope guard (externalWrite=block): this command writes to '${hit.block}' outside the session directory. ${why} Stay inside the session directory, or have the user adjust taskTracker.externalWrite / run it manually.`;
+    }
+    return null;
+  }
+
+  // path-bearing tools
+  const input = (event.input || {}) as Record<string, unknown>;
+  const p = typeof input.path === "string" ? input.path : typeof input.file_path === "string" ? input.file_path : "";
+  if (!p) return null;
+  const isWriteish = GUARD_WRITE_TOOLS.has(toolName);
+  if (!isWriteish && (GUARD_READ_TOOLS.has(toolName) || coveredByGuardHeuristics(toolName))) return null;
+  if (!isExternalAbs2(sessionCwd, p)) return null;
+  const why = "External changes cannot be tracked or rolled back by pi-task-tracker.";
+  if (mode === "ask") {
+    if (!ctx?.hasUI || !ctx.ui) return `pi-task-tracker scope guard: '${p}' is outside the session directory and no UI is available to approve external writes. ${why}`;
+    const ok = await ctx.ui.confirm(
+      "pi-task-tracker external-write guard",
+      `Tool '${toolName}' targets '${p}' outside the session directory. ${why} Allow anyway?`,
+    );
+    if (ok) return "__ask__";
+    return `pi-task-tracker scope guard: user denied external write to '${p}'. Do not retry or bypass.`;
+  }
+  return `pi-task-tracker scope guard (externalWrite=block): tool '${toolName}' targets '${p}' outside the session directory. ${why} Ask the user to adjust taskTracker.externalWrite or perform the change manually.`;
+}
+
+function isExternalAbs2(base: string, p: string): boolean {
+  const abs = path.isAbsolute(p) ? p : path.resolve(base, p);
+  const rel = path.relative(base, abs);
+  return rel.startsWith("..") || path.isAbsolute(rel);
+}
+
+// Mirror of pi-permission-system's path-bearing heuristics: tools it already
+// checks (or read-only ones) are left to it.
+function coveredByGuardHeuristics(toolName: string): boolean {
+  const t = toolName.trim().toLowerCase();
+  const parts = t.split(/[^a-z0-9]+/).filter(Boolean);
+  return ["read", "write", "edit", "find", "grep", "search", "list", "ls"].some((s) => t.endsWith(s) || parts.includes(s));
+}
+
 // Repos whose identity was already ensured this process (git config persists,
 // so one check per repo per pi session is enough - saves 2 spawns per repo
 // per task).
@@ -340,20 +567,25 @@ interface TrackerConfig {
   todo: boolean;
   readme: boolean;
   autoCommit: boolean;
+  /** Writes outside the session directory: "block" (default) | "ask" | "off" */
+  externalWrite: "block" | "ask" | "off";
 }
 
 function readConfig(): TrackerConfig {
+  const fallback: TrackerConfig = { todo: true, readme: true, autoCommit: true, externalWrite: "block" };
   try {
     const dir = process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
-    const raw = JSON.parse(fs.readFileSync(path.join(dir, "settings.json"), "utf-8"));
+    const file = process.env.PI_TRACKER_SETTINGS || path.join(dir, "settings.json");
+    const raw = JSON.parse(fs.readFileSync(file, "utf-8"));
     const t = raw.taskTracker && typeof raw.taskTracker === "object" ? raw.taskTracker : {};
     return {
       todo: t.todo !== false,
       readme: t.readme !== false,
       autoCommit: t.autoCommit !== false,
+      externalWrite: t.externalWrite === "ask" || t.externalWrite === "off" ? t.externalWrite : "block",
     };
   } catch {
-    return { todo: true, readme: true, autoCommit: true };
+    return fallback;
   }
 }
 
@@ -434,8 +666,17 @@ export default function (pi: ExtensionAPI) {
     fs.appendFileSync(todoPath, line, "utf-8");
   });
 
-  pi.on("tool_call", async (event) => {
-    if (!cwd) return;
+  pi.on("tool_call", async (event, ctx) => {
+    // External-write guard: keep the writable scope equal to the trackable
+    // scope. See the "External-write guard" block above for the policy.
+    if (config.externalWrite !== "off") {
+      const hit = await guardExternalWriteHit(event, cwd, config.externalWrite === "off" ? "block" : config.externalWrite, ctx);
+      if (hit) {
+        if (hit === "__ask__") return; // ask mode: user approved in guardExternalWriteHit
+        return { block: true, reason: hit };
+      }
+    }
+
 
     if (isToolCallEventType("write", event)) {
       const p = event.input.path as string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-task-tracker",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Task workflow tracking for the pi coding agent: TODO/README maintenance, per-task git auto-commits as checkpoints, and an interactive /rollback. Hashline-aware, nested-repo aware, subagent-artifact-safe.",
   "keywords": [
     "pi-package",