pi-task-tracker 0.1.7 → 0.1.9

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. 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
 
@@ -85,6 +87,7 @@ Optional `taskTracker` key in `~/.pi/agent/settings.json` (all default to `true`
 
 - Rollback granularity is per **task** (agent turn-set), not per message. If you need message-level time travel including your own manual edits, a snapshot-based extension is a better fit — at the cost of full-worktree scans every turn.
 - Files created by shell commands inside a nested repo that was never touched via write/edit during the session are not captured.
+- **Out-of-scope by design** — files outside the session directory (and outside its owning repo) are neither recorded nor rolled back: no new commits in *their* repos, no worktree changes. `/rollback` only ever touches the session's own repo scope, so sibling projects are safe even when the agent writes there via absolute paths — but such changes have no checkpoint.
 - An embedded (unregistered) sub-repo shows as `?? dir/` in the outer `git status` — that's standard git behavior; this extension never stages it.
 
 ## 本简介（中文）

package/index.ts

@@ -106,6 +106,162 @@ 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", "cp", "touch", "mkdir", "rmdir", "tee", "truncate", "dd", "ln",
+  "install", "patch", "chmod", "chown", "sed",
+]);
+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(base: string, token: string): { abs: string; external: boolean } {
+  let t = token.replace(/^["']|["']$/g, "").trim();
+  if (!t) return { abs: base, 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, base) };
+  }
+  const abs = path.resolve(base, t);
+  return { abs, external: isExternalAbs(abs, base) };
+}
+
+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.
+function guardShellExternalWrite(cmd: string, sessionCwd: string): string | null {
+  const segments = cmd.split(/\n|&&|\|\||;|\|/).map((s) => s.trim()).filter(Boolean);
+  let effCwd = sessionCwd;
+  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, 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;
+    }
+    const isGit = /^git(\s|$)/.test(seg);
+    // 1. 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, tgt);
+      if (r.external) return r.abs;
+    }
+    // 2. git segments: arguments are left to pi-permission-system's rules;
+    //    only an external -C destination counts as an external write risk.
+    if (isGit) {
+      const c = seg.match(/\s-C\s+(\S+)/);
+      if (c) {
+        const r = guardResolve(effCwd, c[1]);
+        if (r.external) return r.abs;
+      }
+      continue;
+    }
+    // 3. write-ish commands: check every path-looking argument
+    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);
+    if (!isPsWrite && !isShWrite) continue;
+    for (let k = 1; k < tokens.length; k++) {
+      const t = tokens[k];
+      if (t.startsWith("-")) continue;
+      if (/^[A-Za-z]:\{1,2}/.test(t) || t.startsWith("/")) { // absolute
+        if (guardIsDevNull(t)) continue;
+        if (isExternalAbs(t, sessionCwd)) return t;
+      } else if (/[\$`~]/.test(t)) {
+        return t; // unresolvable -> conservative
+      } else {
+        const abs = path.resolve(effCwd, t);
+        if (isExternalAbs(abs, sessionCwd)) return t;
+      }
+      if (isShWrite && (headBase === "sed")) break; // sed: only check -i file once
+    }
+  }
+  return 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> } }
+): 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 bad = guardShellExternalWrite(cmd, sessionCwd);
+    if (!bad) return null;
+    return `pi-task-tracker scope guard (externalWrite=${mode}): this command writes to '${bad}' outside the session directory. External changes cannot be tracked or rolled back. Stay inside the session directory, or have the user adjust taskTracker.externalWrite / run it manually.`;
+  }
+
+  // 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 +496,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 +595,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.7",
+  "version": "0.1.9",
   "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",