pi-task-tracker 0.1.9 → 0.2.1

package/README.md

@@ -75,7 +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.
+- `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. **`cd`/`Set-Location` are disabled outright** (sandbox design: pi's bash tool runs each command in a fresh child process pinned to the session directory anyway, so a `cd` can never move the session — denying it keeps the analysis simple and the writable scope exactly the trackable scope).
 
 ## Requirements
 
@@ -97,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

@@ -119,9 +119,24 @@ function findEnclosingRepo(dir: string): string | null {
 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",
+  "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",
@@ -129,16 +144,16 @@ const GUARD_PS_WRITE_CMDS = new Set([
 
 // 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 } {
+function guardResolve(sessionCwd: string, token: string): { abs: string; external: boolean } {
   let t = token.replace(/^["']|["']$/g, "").trim();
-  if (!t) return { abs: base, external: false };
+  if (!t) return { abs: sessionCwd, 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) };
+    return { abs: t, external: isExternalAbs(t, sessionCwd) };
   }
-  const abs = path.resolve(base, t);
-  return { abs, external: isExternalAbs(abs, base) };
+  const abs = path.resolve(sessionCwd, t);
+  return { abs, external: isExternalAbs(abs, sessionCwd) };
 }
 
 function isExternalAbs(abs: string, base: string): boolean {
@@ -152,60 +167,95 @@ function guardIsDevNull(t: string): boolean {
 
 // 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 {
+// 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).
+// Analyze one shell command. cd/Set-Location are DISABLED outright (sandbox
+// design: the process cwd is pinned to the session directory, which also
+// removes any need for cd-tracking in this analysis). Returns
+// { block, ask, notify } hits. External-write analysis is best effort:
+// redirect targets, write-command arguments (copy-like: destination only),
+// interpreter payloads mentioning external absolute paths. 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, 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;
+    if (/^(cd|sl|set-location)\s/i.test(seg)) {
+      out.block = "cd is disabled in this sandbox; run commands from the session directory";
+      return out;
     }
-    const isGit = /^git(\s|$)/.test(seg);
-    // 1. redirects: > >> 2> 2>> &> &>> >| (not heredocs, not fd dups like 2>&1)
+    // 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, tgt);
-      if (r.external) return r.abs;
+      const r = guardResolve(sessionCwd, tgt);
+      if (r.external) out.block = 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.
+    const isGit = /^git(\s|$)/.test(seg);
+    // 1. inherited git protection: history-rewriting git asks (matches
+    //    the old pi-permissions.jsonc bash patterns; prefix match)
     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 target = (seg.split(/\s+/).filter((x) => x && !x.startsWith("-")).pop()) || ".";
+        const r = guardResolve(sessionCwd, target);
+        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, c[1]);
-        if (r.external) return r.abs;
+        const r = guardResolve(sessionCwd, c[1]);
+        if (r.external) out.block = r.abs;
       }
       continue;
     }
-    // 3. write-ish commands: check every path-looking argument
+    // 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 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;
+    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++) {
-      const t = tokens[k];
-      if (t.startsWith("-")) continue;
-      if (/^[A-Za-z]:\{1,2}/.test(t) || t.startsWith("/")) { // absolute
+      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)) return t;
+        if (isExternalAbs(t, sessionCwd)) out.block = t;
       } else if (/[\$`~]/.test(t)) {
-        return t; // unresolvable -> conservative
+        out.block = t; // unresolvable -> conservative
       } else {
-        const abs = path.resolve(effCwd, t);
-        if (isExternalAbs(abs, sessionCwd)) return t;
+        const abs = path.resolve(sessionCwd, t);
+        if (isExternalAbs(abs, sessionCwd)) out.block = t;
       }
-      if (isShWrite && (headBase === "sed")) break; // sed: only check -i file once
+      if (out.block) break;
     }
   }
-  return null;
+  return Object.keys(out).length > 0 ? out : null;
 }
 
 const GUARD_ASK_PROMPT = "pi-task-tracker external-write guard";
@@ -215,7 +265,7 @@ async function guardExternalWriteHit(
   event: { toolName: string; input?: unknown },
   sessionCwd: string,
   mode: "block" | "ask",
-  ctx?: { hasUI?: boolean; ui?: { confirm: (t: string, m: string) => Promise<boolean> } }
+  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 || "";
@@ -223,9 +273,32 @@ async function guardExternalWriteHit(
   // 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.`;
+    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
@@ -235,7 +308,7 @@ async function guardExternalWriteHit(
   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.`;
+  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(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-task-tracker",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "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",