pi-task-tracker 0.2.5 → 0.2.7

package/README.md

@@ -16,7 +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`.
+- **Scope guard** — the writable scope equals the trackable scope: out-of-session writes follow `taskTracker.externalWrite` (default `"ask"`: confirm; `"warn"`: allow + yellow notice; `"block"`: hard deny), so nothing changes that `/rollback` could not restore. Git history protection is built in.
 - **Subagent-safe** — `.pi-subagents/` session artifacts are never recorded, listed, or committed.
 
 ## Lightweight by design (measured, not claimed)
@@ -76,7 +76,7 @@ Optional `taskTracker` key in `~/.pi/agent/settings.json` (all default to `true`
 - `readme` — maintain the `README.md` project-structure section
 - `autoCommit` — per-task commits; these are the `/rollback` checkpoints, so disabling this also disables rollback targets
 - `guard` — master switch for the built-in permission layer (default `true`). Set `false` to defer permission decisions entirely to another extension (e.g. `pi-permission-system`): no external-write checks, no git-ask prompts, no cd sandbox.
-- `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. Everything INSIDE the session directory passes by default — the only sandbox-internal intervention is the `cd` disable. 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. Git-Bash/MSYS paths (`/c/Users/...`, `/cygdrive/c/...`) are normalized before evaluation, so drive-absolute forms do not false-positive as external; `/tmp` and other non-drive names stay external (they resolve outside the session on Windows). 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` is free inside the session directory; a `cd` that would move the working directory outside it is blocked** (that is the one operation that changes pi's effective scope). No cd-tracking is performed — resolution baseline stays the session root, so a deep in-session `cd` followed by enough `../` levels to escape may over-block, which is the fail-safe direction.
+- `externalWrite` — policy for tool calls that would create/modify files OUTSIDE the session directory: `"ask"` (default, per-attempt confirmation), `"warn"` (allow + yellow UI notice, no prompt), `"block"` (hard deny — external changes cannot be tracked or rolled back), `"off"` (no enforcement; defer permission decisions to another extension). Reads stay free. Copying files FROM outside INTO the session is allowed (`cp` checks only its destination); moving/deleting external paths is checked. Everything INSIDE the session directory passes by default. Git history protection is built in: history-rewriting git (rebase/reset/amend/force-push/clean/...) prompts for confirmation, routine git passes untouched, and an external `git init`/`clone` is allowed with a heads-up that the new repo is not tracked. Git-Bash/MSYS paths (`/c/Users/...`, `/cygdrive/c/...`) are normalized before evaluation, so drive-absolute forms do not false-positive as external; `/tmp` and other non-drive names stay external (they resolve outside the session on Windows). Shell commands are analyzed statically (redirects, `rm/mv/cp/touch/...`, PowerShell equivalents; redirect targets and `-C` destinations on git segments). **`cd` is free inside the session directory; a `cd` that would move the working directory outside it follows the same policy** (ask/warn/block). No cd-tracking is performed — resolution baseline stays the session root, so a deep in-session `cd` followed by enough `../` levels to escape may over-block, which is the fail-safe direction.
 
 ## Requirements
 

package/index.ts

@@ -290,7 +290,7 @@ const GUARD_ASK_PROMPT = "pi-task-tracker external-write guard";
 async function guardExternalWriteHit(
   event: { toolName: string; input?: unknown },
   sessionCwd: string,
-  mode: "block" | "ask",
+  mode: "block" | "ask" | "warn",
   ctx?: { hasUI?: boolean; ui?: { confirm: (t: string, m: string) => Promise<boolean>; notify: (m: string, kind?: string) => void } }
 ): Promise<string | null> {
   if (!sessionCwd) return null;
@@ -313,6 +313,12 @@ async function guardExternalWriteHit(
     }
     if (hit.block) {
       const why = "External changes cannot be tracked or rolled back by pi-task-tracker.";
+      if (mode === "warn") {
+        if (ctx?.hasUI && ctx.ui) {
+          ctx.ui.notify(`pi-task-tracker: command writes to '${hit.block}' outside the session directory. ${why}`, "warning");
+        }
+        return null;
+      }
       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(
@@ -335,6 +341,12 @@ async function guardExternalWriteHit(
   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 === "warn") {
+    if (ctx?.hasUI && ctx.ui) {
+      ctx.ui.notify(`pi-task-tracker: '${toolName}' targets '${p}' outside the session directory. ${why}`, "warning");
+    }
+    return null;
+  }
   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(
@@ -599,8 +611,8 @@ interface TrackerConfig {
   /** master switch for the built-in permission layer (external-write guard,
    *  git-ask inheritance, cd disable). false = defer entirely to other extensions */
   guard: boolean;
-  /** Writes outside the session directory: "block" (default) | "ask" | "off" */
-  externalWrite: "block" | "ask" | "off";
+  /** Writes outside the session directory: "ask" (default) | "warn" (allow + yellow notice) | "block" | "off" */
+  externalWrite: "block" | "ask" | "warn" | "off";
 }
 
 function readConfig(): TrackerConfig {
@@ -615,7 +627,7 @@ function readConfig(): TrackerConfig {
       readme: t.readme !== false,
       autoCommit: t.autoCommit !== false,
       guard: t.guard !== false,
-      externalWrite: t.externalWrite === "block" || t.externalWrite === "off" ? t.externalWrite : "ask",
+      externalWrite: t.externalWrite === "block" || t.externalWrite === "off" || t.externalWrite === "warn" ? t.externalWrite : "ask",
     };
   } catch {
     return fallback;

package/package.json

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