pi-claude-supervisor 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this project will be documented here.
 
+## [0.8.1](https://github.com/btnalit/pi-claude-supervisor/compare/v0.8.0...v0.8.1) (2026-09-20)
+
+
+### Bug Fixes
+
+* **policy:** let a Worker keep its own memory, and make denials actionable ([605fb58](https://github.com/btnalit/pi-claude-supervisor/commit/605fb5860b38ee9023ad980b3101708cadd39fb2))
+* **policy:** make the memory write root actually reachable, and drop the cwd-identity relaxation ([8a1bfc5](https://github.com/btnalit/pi-claude-supervisor/commit/8a1bfc55f97421997b0a8c87f0b1ae9cd7c94ba9))
+* **tmux:** accept an adopted pane whose cwd path went stale but is the same directory ([207219c](https://github.com/btnalit/pi-claude-supervisor/commit/207219c1fec218d1eecf1920c5ba9a2806935a8f))
+
 ## [0.8.0](https://github.com/btnalit/pi-claude-supervisor/compare/v0.7.3...v0.8.0) (2026-09-19)
 
 

package/docs/architecture.md

@@ -424,7 +424,23 @@ stay on a blocked candidate instead of being cut short by the stop. For an adopt
 interactive session the outright stop is a release (the adapter never kills a
 session it does not own), so the Claude process keeps running unsupervised; the
 close-out exists so that a task which merely ran long still ends with a verified
-candidate instead of a silent hand-back. A record left behind by the outright
+candidate instead of a silent hand-back.
+
+A denial is a capability boundary the Worker has to route around by itself, so
+each one names a remedy it can act on: a dynamic argument says to substitute the
+literal value so the command can be read, and an outside-cwd write names the
+write roots this Worker actually holds (and nothing when it holds none). Those
+roots are what the permission policy accepts beside the task cwd: the scratchpad
+Claude reports at SessionStart, and its per-project memory directory, derived
+from the session's own `transcript_path`. The transcript path is captured from
+any hook event, since an adopted session never replays SessionStart, and it is
+untrusted input, so the shape is verified rather than trusted — it must be
+`<…>/.claude/projects/<slug>/<session>.jsonl` whose slug is the one Claude
+derives from this task's cwd, which rejects a subagent transcript and any path
+naming another project. A root is honored before it exists (Claude creates the
+memory directory on first write) and through a symlinked ancestor.
+
+A record left behind by the outright
 stop (`recoverable_failure`, so `active/interrupted`) is not a dead end either:
 `recover --extend <duration>` re-persists a deadline measured from now
 (`extendedDeadlineMs`), `--extend 0` recovers straight into the close-out, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-claude-supervisor",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "A policy-gated Pi supervisor for observing and verifying Claude Code workers.",
   "license": "MIT",
   "publishConfig": {

package/src/policy.ts

@@ -1,5 +1,5 @@
 import { lstatSync, realpathSync, statSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 
 export type PolicyDecision = "allow" | "review" | "deny";
 
@@ -26,7 +26,12 @@ export function evaluatePermission(toolName: string, input: unknown, cwd = proce
     const paths = fileToolPaths(input);
     if (paths.length === 0) return { decision: "deny", reason: `${toolName} request has no recognizable file path` };
     const violation = paths.map((path) => ({ path, classification: classifyWritePath(path, cwd, options.writeRoots) })).find((entry) => entry.classification !== undefined);
-    if (violation?.classification === "outside-cwd") return { decision: "deny", reason: `Worker cannot write outside the task working directory: ${violation.path}` };
+    if (violation?.classification === "outside-cwd") {
+      // Only name an alternative the Worker actually has: writeRoots is empty
+      // for a bridge Worker and before an adopted session's first hook event.
+      const alternatives = (options.writeRoots ?? []).length > 0 ? `; scratch work may go under ${(options.writeRoots ?? []).join(", ")}` : "";
+      return { decision: "deny", reason: `Worker cannot write outside the task working directory: ${violation.path}${alternatives}` };
+    }
     if (violation?.classification === "git-metadata") return { decision: "deny", reason: "Worker cannot write Git metadata or protected branch refs" };
     return { decision: "allow", reason: `local Claude file tool is allowed by the task policy: ${toolName}` };
   }
@@ -50,19 +55,47 @@ function fileToolPaths(input: unknown): string[] {
 
 type WritePathViolation = "outside-cwd" | "git-metadata";
 
+/**
+ * `realpath` of the deepest ancestor that exists, with the not-yet-created tail
+ * re-appended. Plain `realpathSync` throws for a directory the Worker is about
+ * to create, and the caller cannot tell that apart from a hostile path.
+ */
+function resolveExistingPath(path: string): string {
+  let current = resolve(path);
+  const missing: string[] = [];
+  for (;;) {
+    try { return join(realpathSync(current), ...[...missing].reverse()); }
+    catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT" && code !== "ENOTDIR") return resolve(path);
+      const parent = dirname(current);
+      if (parent === current) return resolve(path);
+      missing.push(basename(current));
+      current = parent;
+    }
+  }
+}
+
 function classifyWritePath(value: string, cwd: string, writeRoots: readonly string[] = []): WritePathViolation | undefined {
   if (value.replaceAll("\\", "/").split("/").some((segment) => segment.toLowerCase() === ".git")) return "git-metadata";
   // A path inside an extra write root (Claude's own scratchpad) is judged
   // against that root instead of the cwd, with the same symlink/metadata rules.
   for (const root of writeRoots) {
     if (!isAbsolute(root) || !isAbsolute(value)) continue;
-    const rel = relative(root, value);
+    // Resolve both sides before comparing: a write root reached through a
+    // symlinked ancestor (a dotfile-managed ~/.claude, /var on macOS) would
+    // otherwise be judged outside itself. The final component stays unresolved
+    // so the per-segment symlink and `.git` checks below still see it.
+    const resolvedRoot = resolveExistingPath(root);
+    const resolvedValue = join(resolveExistingPath(dirname(value)), basename(value));
+    const rel = relative(resolvedRoot, resolvedValue);
     if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) continue;
-    return classifyWritePath(value, root);
+    return classifyWritePath(resolvedValue, resolvedRoot);
   }
-  let root: string;
-  try { root = realpathSync(cwd); }
-  catch { return "git-metadata"; }
+  // A write root need not exist yet: Claude creates its memory directory on
+  // the first write, and failing closed there denied the very write the
+  // outside-cwd message points at.
+  const root = resolveExistingPath(cwd);
   const raw = value.replaceAll("\\", "/");
   const canonicalRoot = root.replaceAll("\\", "/").replace(/\/+$/u, "") || "/";
   let components: string[];
@@ -212,7 +245,7 @@ function evaluateRepositoryBoundary(tokens: readonly ShellToken[], canonical: st
   // Dynamic text in an ordinary local command (`for f in …; echo "$f"`) or in
   // another statement (`npm test; echo "exit $?"`) is Claude's own business.
   if ((hasDynamicArgument && hasDynamicCommandName(tokens)) || segmentsOf(tokens).some((segment) => hasDynamicSensitiveArgument(segment))) {
-    return { decision: "deny", reason: "a repository, package, network or shell command with a dynamic argument cannot be capability-checked" };
+    return { decision: "deny", reason: "a repository, package, network or shell command with a dynamic argument cannot be capability-checked; substitute the literal value for the shell variable so the command can be read, or use the Write/Edit tools when the intent is to change a file" };
   }
   if (/\bgit\b[\s\S]*\b(?:push|merge(?!-)|send-pack|receive-pack|update-ref)\b/iu.test(canonical)
     || /\bgit-(?:send|receive|upload)-pack\b/iu.test(canonical)

package/src/worker/tmux-adapter.ts

@@ -3,7 +3,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { constants as fsConstants, lstatSync, readdirSync, unlinkSync } from "node:fs";
 import { access, chmod, lstat, mkdir, open, readdir, readFile, realpath, rm, rmdir, stat, truncate, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { delimiter, dirname, isAbsolute, join } from "node:path";
+import { basename, delimiter, dirname, isAbsolute, join } from "node:path";
 import type {
   PermissionDecision,
   WorkerAdapter,
@@ -1344,6 +1344,11 @@ export class TmuxWorkerAdapter implements WorkerAdapter {
     if (expected?.pid !== undefined && pane.pid !== expected.pid) throw new Error("tmux pane pid changed; refusing identity-unverified handoff");
     if (pane.dead) throw new Error("cannot adopt a dead tmux pane");
     record.handle.pid = pane.pid;
+    // Compared as reported, not by inode identity: the hook relay routes events
+    // by the SHA-256 of realpath(cwd), so a pane whose cwd merely *resolves* to
+    // the same directory under a different spelling would be adopted and then
+    // never deliver a single hook event -- an unsupervised Worker that looks
+    // supervised. A mismatch means the pane cannot be governed, so it is refused.
     const currentPath = await this.#run(record, ["display-message", "-p", "-t", record.target, "#{pane_current_path}"]);
     if (currentPath.stdout.trim() !== cwd) throw new Error(`tmux session cwd mismatch: expected ${cwd}, got ${currentPath.stdout.trim()}`);
     const command = (await this.#run(record, ["display-message", "-p", "-t", record.target, "#{pane_current_command}"])).stdout.trim();
@@ -1989,12 +1994,16 @@ export class TmuxWorkerAdapter implements WorkerAdapter {
     }
     record.lastOutputAt = new Date().toISOString();
     const event = request.event;
+    // Every hook event carries `transcript_path`, and an adopted session never
+    // replays SessionStart, so capture it here rather than only at startup:
+    // it is what locates Claude's own per-project memory directory below.
+    if (!record.transcriptPath && isSafeAbsolutePath(event.transcript_path)) record.transcriptPath = event.transcript_path;
     switch (event.hook_event_name) {
       case "SessionStart": {
         record.claudeSessionId ??= event.session_id;
         record.handle.sessionId = event.session_id;
-        if (event.transcript_path) record.transcriptPath = event.transcript_path;
-        if (typeof event.scratchpad_dir === "string" && isAbsolute(event.scratchpad_dir) && !event.scratchpad_dir.includes("\0")) record.scratchpadDir = event.scratchpad_dir;
+        if (isSafeAbsolutePath(event.transcript_path)) record.transcriptPath = event.transcript_path;
+        if (isSafeAbsolutePath(event.scratchpad_dir)) record.scratchpadDir = event.scratchpad_dir;
         record.sessionStartReceived = true;
         return {};
       }
@@ -2068,6 +2077,7 @@ export class TmuxWorkerAdapter implements WorkerAdapter {
     // itself away in respondPermission and hang the relay.
     record.permissionResponses.delete(requestId);
     const toolUseId = event.tool_use_id ?? requestId;
+    const writeRoots = writeRootsOf(record);
     this.#emit(record, {
       type: "permission_request",
       handle: record.handle,
@@ -2078,7 +2088,7 @@ export class TmuxWorkerAdapter implements WorkerAdapter {
         input: event.tool_input,
         raw: event as unknown as Record<string, unknown>,
         phase,
-        ...(record.scratchpadDir ? { writeRoots: [record.scratchpadDir] } : {}),
+        ...(writeRoots.length > 0 ? { writeRoots } : {}),
       },
     });
     return new Promise<HookRelayReply>((resolve) => {
@@ -2151,6 +2161,44 @@ function bridgeEnvironment(env: NodeJS.ProcessEnv, cwd: string, command: string,
   return result;
 }
 
+/** Same shape the decision-session registry requires of an untrusted absolute path. */
+function isSafeAbsolutePath(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= 4_096
+    && isAbsolute(value) && String(redactSensitiveText(value)) === value;
+}
+
+/**
+ * Claude's per-project memory directory for this task, or undefined when the
+ * reported transcript path is not this project's session transcript.
+ *
+ * `transcript_path` is untrusted hook input, so the shape is checked rather
+ * than trusted: it must be `<…>/.claude/projects/<slug>/<session>.jsonl` whose
+ * `<slug>` is the one Claude derives from this task's cwd. That rejects a
+ * subagent transcript (`<slug>/<session>/subagents/agent-*.jsonl`, which would
+ * otherwise freeze a bogus root) and any path naming another project, a home
+ * directory, or somewhere inside the repository.
+ */
+export function memoryRootFor(transcriptPath: string | undefined, cwd: string): string | undefined {
+  if (!transcriptPath || !cwd) return undefined;
+  const sessionDir = dirname(transcriptPath);
+  const projectsDir = dirname(sessionDir);
+  if (basename(projectsDir) !== "projects" || basename(dirname(projectsDir)) !== ".claude") return undefined;
+  if (basename(sessionDir) !== cwd.replaceAll("/", "-")) return undefined;
+  return join(sessionDir, "memory");
+}
+
+/**
+ * The directories outside the task cwd that the Worker may still write: its own
+ * per-session scratchpad, and Claude's per-project memory directory.
+ */
+export function writeRootsOf(record: { scratchpadDir?: string; transcriptPath?: string; handle?: { cwd: string } }): string[] {
+  const roots: string[] = [];
+  if (record.scratchpadDir) roots.push(record.scratchpadDir);
+  const memory = memoryRootFor(record.transcriptPath, record.handle?.cwd ?? "");
+  if (memory) roots.push(memory);
+  return roots;
+}
+
 export function attachCommand(handle: Pick<WorkerHandle, "tmuxSocket" | "sessionName">): string {
   const target = shellQuote(handle.sessionName ?? "");
   return handle.tmuxSocket ? `tmux -S ${shellQuote(handle.tmuxSocket)} attach -t ${target}` : `tmux attach -t ${target}`;