pi-claude-supervisor 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented here.
 
+## [0.7.1](https://github.com/btnalit/pi-claude-supervisor/compare/v0.7.0...v0.7.1) (2026-09-17)
+
+
+### Bug Fixes
+
+* **policy:** judge heredoc bodies by their consumer and separate statements on newlines ([ac69208](https://github.com/btnalit/pi-claude-supervisor/commit/ac692083d824b05b7665c2864aad9478f7b367a4))
+* **policy:** stop vetoing ordinary shell and scratchpad writes on the Worker's behalf ([eb72c8f](https://github.com/btnalit/pi-claude-supervisor/commit/eb72c8f267f77f4097f20c325c4087c925be5803))
+
 ## [0.7.0](https://github.com/btnalit/pi-claude-supervisor/compare/v0.6.0...v0.7.0) (2026-09-17)
 
 

package/README.cn.md

@@ -171,7 +171,13 @@ stream-json` 的方式运行 Claude,完全没有终端界面;一旦设置
 - 无论策略或权限模式如何,始终拒绝:远程 push、合并/PR 进 `main` 或 integration
   分支、其他远程 CLI 变更、`.git` 元数据写入,以及对受保护分支的破坏性改写
   (`reset`、`update-ref`、`symbolic-ref`,或带删除/移动/强制标志的 `branch`)。
-  除此之外的一切都按配置的策略处理。
+  策略看不透的 shell 参数(`$VAR`、`$(…)`、通配符)只在可能触及这条边界的命令上
+  被尽力拦截——git、gh、npm/pnpm/yarn、curl/wget/ssh、嵌套的 `claude`,以及
+  `eval`、`sh -c`、`xargs`、`find -exec` 之类的解释器/执行器。带引号分隔符的
+  heredoc 正文按其消费者判断:交给 shell 就是命令,交给 `cat > file` 或
+  `git commit -m` 就是数据。除此之外的一切(`for f in …; do echo "$f"`、
+  `rm -rf ./dist`、写入 Claude 自己的 scratchpad)都按配置的策略处理——由
+  Claude 自己的权限模式决定,和你亲自运行 Claude 时一样。
 - `autonomy.permissionAuthority`(`policy` | `hybrid` 默认 |
   `decision-worker`)决定谁来回答权限请求——headless 模式下是每一个请求,交互式
   tmux 模式下只是那些 Claude 本来会弹窗问你的请求:`hybrid` 会让策略独自回答

package/README.md

@@ -203,7 +203,14 @@ Supervisor being able to see it, or when you don't need to attach.
   merge/PR into `main` or an integration branch, other remote CLI mutations,
   `.git` metadata writes, and destructive rewrites of protected branches
   (`reset`, `update-ref`, `symbolic-ref`, or a delete/move/force `branch`).
-  Everything else follows the configured policy.
+  A shell argument the policy cannot see through (`$VAR`, `$(…)`, a glob)
+  is vetoed, best-effort, only on the commands where it could reach that
+  boundary — git, gh, npm/pnpm/yarn, curl/wget/ssh, a nested `claude`, or an
+  interpreter/runner such as `eval`, `sh -c`, `xargs`, `find -exec`. A quoted
+  heredoc body is judged by its consumer: a shell runs it, `cat > file` or
+  `git commit -m` stores it. Everything else (`for f in …; do echo "$f"`,
+  `rm -rf ./dist`, a Write to Claude's own scratchpad) follows the configured
+  policy — Claude's own permission mode governs it, as when you run Claude.
 - `autonomy.permissionAuthority` (`policy` | `hybrid` default |
   `decision-worker`) controls who answers a permission request — every
   request in headless mode, and in interactive tmux mode only those Claude

package/docs/implementation-review.md

@@ -21,8 +21,12 @@ custom/nested descendants are trusted rather than denied by a nested-process gua
 ## Findings addressed in this pass
 
 - Policy now evaluates every shell argument as well as the executable and argv
-  together; dynamic arguments are denied because their capability cannot be checked,
-  including Claude permission-bypass flags.
+  together. A dynamic argument (`$VAR`, `$(…)`, a glob) is denied on the commands
+  where it could reach the boundary — repository, package, network, nested
+  `claude`, interpreters and runners, or a dynamic command name — as a best-effort
+  veto; elsewhere it is ordinary shell that Claude's own permission mode governs.
+  Quoted heredoc bodies are evaluated according to their consumer (a shell runs
+  them, a data sink stores them, anything else keeps them visible to the checks).
 - Automatic startup pins a secure resolved Claude executable identity and rejects
   explicit paths, persists that identity for recovery, and rechecks the exact startup
   HEAD through the built-in adapter's final `preSpawnCheck` immediately before spawn.

package/package.json

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

package/src/hooks/types.ts

@@ -24,6 +24,8 @@ export interface ClaudeHookEvent {
   permission_mode?: string;
   /** SessionStart */
   source?: string;
+  /** SessionStart: Claude Code's per-session scratchpad directory (outside the cwd). */
+  scratchpad_dir?: string;
   /** SessionEnd */
   reason?: string;
   /** UserPromptSubmit */

package/src/policy.ts

@@ -15,12 +15,17 @@ export interface PolicyResult {
  * allowed; only the explicit unattended interaction and repository/remote
  * authority boundaries below remain special-cased.
  */
-export function evaluatePermission(toolName: string, input: unknown, cwd = process.cwd()): PolicyResult {
+export interface PermissionPolicyOptions {
+  /** Extra directories the Worker may write to (Claude's per-session scratchpad); each must be an absolute path. */
+  writeRoots?: readonly string[];
+}
+
+export function evaluatePermission(toolName: string, input: unknown, cwd = process.cwd(), options: PermissionPolicyOptions = {}): PolicyResult {
   if (toolName === "AskUserQuestion") return { decision: "deny", reason: "interactive questions are converted to ordinary Worker text" };
   if (toolName === "Edit" || toolName === "Write" || toolName === "NotebookEdit") {
     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) })).find((entry) => entry.classification !== undefined);
+    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 === "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}` };
@@ -30,7 +35,9 @@ export function evaluatePermission(toolName: string, input: unknown, cwd = proce
     ? (input as { command: string }).command
     : "";
   if (!command) return { decision: "deny", reason: "Bash request has no recognizable command" };
-  return evaluateCommand("bash", ["-lc", command]);
+  // Lex the command itself: wrapping it as a literal `bash -lc` argument would
+  // hide its structure (heredoc bodies, dynamic words) from the token checks.
+  return evaluateCommand(command);
 }
 
 function fileToolPaths(input: unknown): string[] {
@@ -43,8 +50,16 @@ function fileToolPaths(input: unknown): string[] {
 
 type WritePathViolation = "outside-cwd" | "git-metadata";
 
-function classifyWritePath(value: string, cwd: string): WritePathViolation | undefined {
+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);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) continue;
+    return classifyWritePath(value, root);
+  }
   let root: string;
   try { root = realpathSync(cwd); }
   catch { return "git-metadata"; }
@@ -93,12 +108,18 @@ function classifyWritePath(value: string, cwd: string): WritePathViolation | und
 }
 
 const deniedPatterns = [
-  /\b(?:npm|pnpm|yarn)\b[\s\S]*\bpublish\b/iu,
+  // `publish` must be the subcommand; a later argument that merely contains the
+  // word (scripts/publish-package.mjs) is not a publication.
+  /\b(?:npm|pnpm|yarn)\b(?:\s+-\S+)*\s+publish\b/iu,
   /\b(?:curl|wget)\b[\s\S]*(?:-X\s*(?:POST|PUT|PATCH|DELETE)|--request(?:=|\s+)(?:POST|PUT|PATCH|DELETE)|--method(?:=|\s+)(?:POST|PUT|PATCH|DELETE)|(?:^|\s)(?:-d|--data(?:[-a-z]*)(?:=|\s+)|--post-data(?:=|\s+)|--body-data(?:=|\s+)))[\s\S]*https?:\/\/(?:api\.)?(?:github|gitlab|bitbucket|registry\.npmjs)\b/iu,
-  /(?:\$\{?[^\s`}]+\}?|`[^`]*`|\$\([^)]*\))[\s\S]*\b(?:push|merge|publish)\b|\b(?:push|merge|publish)\b[\s\S]*(?:\$\{?[^\s`}]+\}?|`[^`]*`|\$\([^)]*\))/iu,
+  // A repository/package command with a dynamic argument cannot be
+  // capability-checked (`git $ACTION origin main`); dynamic text elsewhere in a
+  // command is ordinary shell and is not a boundary concern.
+  /\b(?:git|gh|glab|hub|npm|pnpm|yarn)\b[^|;&\n]*(?:\$\{?[^\s`}]+\}?|`[^`]*`|\$\([^)]*\))/iu,
   /--(?:allow-)?dangerously-skip-permissions\b/iu,
   /--permission-mode\s+(?:bypasspermissions|dontask)\b/iu,
-  /\brm\s+-rf\s+\//iu,
+  // Only the filesystem root itself; `rm -rf /abs/path/dist` is ordinary local work.
+  /\brm\s+(?:-\S+\s+)*\/+(?:\*|\s|$)/iu,
   /\bmkfs(?:\.|\s)/iu,
   /\bdd\s+if=/iu,
   /:\(\)\s*\{\s*:\|/u,
@@ -109,9 +130,34 @@ interface ShellToken {
   value: string;
   operator: boolean;
   dynamic: boolean;
+  /** A quoted heredoc body: literal text whose meaning depends on the command that consumes it. */
+  data?: boolean;
 }
 
 const protectedBranches = new Set(["main", "master", "trunk", "integration", "develop"]);
+/**
+ * Commands whose dynamic arguments could carry a boundary-crossing action or
+ * execute arbitrary expanded text: the repository, package, network and
+ * nested-worker surfaces, plus interpreters, runners and the catastrophe guards.
+ */
+const DYNAMIC_SENSITIVE_COMMANDS = new Set([
+  "git", "gh", "glab", "hub", "npm", "pnpm", "yarn", "npx", "curl", "wget", "ssh", "scp", "rsync", "sftp", "claude",
+  "eval", "exec", "source", "sh", "bash", "zsh", "dash", "ksh", "fish", "xargs", "env", "sudo", "su", "doas",
+  "timeout", "time", "nice", "nohup", "command", "builtin", "watch", "setsid", "strace", "ltrace", "stdbuf", "flock",
+  "unshare", "nsenter", "chroot", "script", "parallel", "expect", "ionice", "chrt", "taskset", "crontab", "at", "batch",
+  "systemd-run", "dd", "mkfs", "shred",
+]);
+/** `find` runs its `-exec`/`-ok` argv and so joins the sensitive set when one is present. */
+const FIND_EXEC_ACTIONS = new Set(["-exec", "-execdir", "-ok", "-okdir"]);
+/** Commands that only store or display their input; a quoted heredoc fed to one never executes. */
+const DATA_SINK_COMMANDS = new Set([
+  "cat", "tee", "head", "tail", "grep", "rg", "wc", "sort", "uniq", "cut", "tr", "diff", "less", "more", "base64",
+  "md5sum", "sha1sum", "sha256sum", "jq", "column", "fold", "paste", "comm", "cmp", "od", "hexdump", "xxd", "nl", "tac", "rev",
+  "echo", "printf",
+]);
+const SHELL_NAMES = new Set(["sh", "bash", "dash", "zsh", "fish", "ksh"]);
+/** Shell words after which the next word is again in command position. */
+const COMMAND_POSITION_KEYWORDS = new Set(["if", "then", "elif", "else", "while", "until", "do", "!", "(", "{", "time", "exec", "command", "builtin", "nohup", "sudo", "doas"]);
 /** Rewriting a protected ref's identity directly; `checkout`/`switch`/`restore`/`worktree` are read-only uses of a branch name and are not included. */
 const protectedBranchRewriteOperations = new Set(["reset", "update-ref", "symbolic-ref"]);
 /** `branch` only rewrites or deletes a protected branch when combined with one of these flags. */
@@ -164,8 +210,14 @@ function evaluateRepositoryBoundary(tokens: readonly ShellToken[], canonical: st
   const hasForcedBranchCreate = (lower.includes("checkout") && rawValues.includes("-B"))
     || (lower.includes("switch") && (rawValues.includes("-C") || rawValues.includes("--force-create")));
 
-  if (hasDynamicArgument) {
-    return { decision: "deny", reason: "dynamic shell arguments cannot be capability-checked safely" };
+  // An argument the lexer cannot see through matters only where it could reach
+  // the boundary: a repository, package, network or remote-shell command, or an
+  // interpreter that would execute the expanded text. Dynamic text in an
+  // ordinary local command (`for f in …; echo "$f"`) is Claude's own business.
+  const dynamicSensitive = lower.some((value) => DYNAMIC_SENSITIVE_COMMANDS.has(value.split(/[\\/]/u).at(-1) ?? value))
+    || (lower.some((value) => (value.split(/[\\/]/u).at(-1) ?? value) === "find") && lower.some((value) => FIND_EXEC_ACTIONS.has(value)));
+  if (hasDynamicArgument && (hasGit || hasGhRemote || hasPackagePublication || dynamicSensitive || hasDynamicCommandName(tokens))) {
+    return { decision: "deny", reason: "a repository, package, network or shell command with a dynamic argument cannot be capability-checked" };
   }
   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)
@@ -198,14 +250,34 @@ function evaluateRepositoryBoundary(tokens: readonly ShellToken[], canonical: st
   return undefined;
 }
 
+/** A dynamic word in command position (`$CMD …`, `; $CMD`, `do . $file`) could name anything. */
+function hasDynamicCommandName(tokens: readonly ShellToken[]): boolean {
+  let commandPosition = true;
+  for (const token of tokens) {
+    if (token.operator) {
+      commandPosition = SEGMENT_SPLIT_OPERATORS.has(token.value);
+      continue;
+    }
+    if (!commandPosition) continue;
+    // `VAR=value cmd` keeps the following word in command position; the value itself is data.
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/u.test(token.value)) continue;
+    if (token.dynamic) return true;
+    const word = token.value.toLowerCase().replace(/^\(+/u, "") || "(";
+    if (word === "." || word === "source") return true;
+    if (COMMAND_POSITION_KEYWORDS.has(word)) continue;
+    commandPosition = false;
+  }
+  return false;
+}
+
 function nestedShellCommands(lower: readonly string[], values: readonly string[]): string[] {
   const nested: string[] = [];
-  const shellNames = new Set(["sh", "bash", "dash", "zsh", "fish", "ksh"]);
   for (let index = 0; index < lower.length; index += 1) {
     const executable = lower[index]!.split(/[\\/]/u).at(-1);
-    if (executable && shellNames.has(executable)) {
+    if (executable && SHELL_NAMES.has(executable)) {
       for (let option = index + 1; option < lower.length; option += 1) {
-        if (["-c", "--command"].includes(lower[option]!)) {
+        // `-c`, `--command`, or a combined short option such as `-lc` / `-ec`.
+        if (lower[option] === "--command" || /^-[a-z]*c[a-z]*$/u.test(lower[option]!)) {
           const command = values.slice(option + 1).join(" ").trim();
           if (command) nested.push(command);
           break;
@@ -228,7 +300,14 @@ function evaluateCommandInternal(command: string, depth: number): PolicyResult {
   return evaluateTokens(lexical.tokens, depth);
 }
 
-function evaluateTokens(tokens: readonly ShellToken[], depth: number): PolicyResult {
+function evaluateTokens(rawTokens: readonly ShellToken[], depth: number): PolicyResult {
+  const { tokens, embedded } = resolveDataTokens(rawTokens);
+  if (depth < 4) {
+    for (const body of embedded) {
+      const nestedResult = evaluateCommandInternal(body, depth + 1);
+      if (nestedResult.decision === "deny") return nestedResult;
+    }
+  }
   const canonical = tokens.map((token) => token.value).join(" ").trim();
   if (!canonical) return { decision: "deny", reason: "empty command" };
   const boundary = evaluateRepositoryBoundary(tokens, canonical, depth);
@@ -244,31 +323,137 @@ function evaluateTokens(tokens: readonly ShellToken[], depth: number): PolicyRes
       || /\bgit\b[\s\S]*\bbranch\b[\s\S]*(?:^|\s)(?:-d|-m|-f|--force|--delete|--move)\b[\s\S]*\b(?:main|master|trunk|integration|develop)\b/iu.test(canonical)) {
       return { decision: "deny", reason: "Worker cannot rewrite or delete a protected integration branch" };
     }
-    if (/\b(?:npm|pnpm|yarn)\b[\s\S]*\bpublish\b/iu.test(canonical)) {
+    if (/\b(?:npm|pnpm|yarn)\b(?:\s+-\S+)*\s+publish\b/iu.test(canonical)) {
       return { decision: "deny", reason: "package publication belongs to the protected release workflow" };
     }
+    if (/\b(?:git|gh|glab|hub|npm|pnpm|yarn)\b[^|;&\n]*(?:\$\{?[^\s`}]+\}?|`[^`]*`|\$\([^)]*\))/iu.test(canonical)) {
+      return { decision: "deny", reason: "a repository or package command with a dynamic argument cannot be capability-checked" };
+    }
     return { decision: "deny", reason: "command matches a prohibited destructive pattern" };
   }
   return { decision: "allow", reason: "command is allowed for unattended local development" };
 }
 
+/**
+ * A quoted heredoc body means whatever its consumer makes of it. Fed to a shell
+ * (`bash <<'EOF'`, `cat <<'EOF' | sh`, `eval "$(cat <<'EOF' …)"`) it is a
+ * command and is evaluated as one; fed to a pure data sink (`cat > file`,
+ * `git commit -m`) it is text the boundary never needs to see; fed to anything
+ * else it stays in the command as literal words for the pattern checks.
+ */
+function resolveDataTokens(tokens: readonly ShellToken[]): { tokens: ShellToken[]; embedded: string[] } {
+  if (!tokens.some((token) => token.data)) return { tokens: [...tokens], embedded: [] };
+  const segments: { tokens: ShellToken[]; joiner?: string }[] = [{ tokens: [] }];
+  for (const token of tokens) {
+    if (token.operator && SEGMENT_SPLIT_OPERATORS.has(token.value)) {
+      segments.at(-1)!.joiner = token.value;
+      segments.push({ tokens: [] });
+      continue;
+    }
+    segments.at(-1)!.tokens.push(token);
+  }
+  const commandOf = (segment: readonly ShellToken[]): { name: string; words: string[] } | undefined => {
+    let afterRedirect = false;
+    let name: string | undefined;
+    const words: string[] = [];
+    for (const token of segment) {
+      if (token.operator) { afterRedirect = [">", ">>", "<", "<<", "<<<"].includes(token.value); continue; }
+      const skip = afterRedirect;
+      afterRedirect = false;
+      if (skip || token.data) continue;
+      const word = token.value.toLowerCase();
+      if (name === undefined) {
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/u.test(token.value) || COMMAND_POSITION_KEYWORDS.has(word)) continue;
+        name = word.replace(/^\(+/u, "").split(/[\\/]/u).at(-1) ?? word;
+      }
+      words.push(word);
+    }
+    return name === undefined ? undefined : { name, words };
+  };
+  const resolved: ShellToken[] = [];
+  const embedded: string[] = [];
+  segments.forEach((segment, index) => {
+    const bodies = segment.tokens.filter((token) => token.data);
+    if (bodies.length === 0) {
+      resolved.push(...segment.tokens, ...(segment.joiner ? [{ value: segment.joiner, operator: true, dynamic: false }] : []));
+      return;
+    }
+    const consumers: { name: string; words: string[] }[] = [];
+    for (let cursor = index; cursor < segments.length; cursor += 1) {
+      const command = commandOf(segments[cursor]!.tokens);
+      if (command) consumers.push(command);
+      if (segments[cursor]!.joiner !== "|") break;
+    }
+    const shellConsumer = consumers.some((consumer) => SHELL_NAMES.has(consumer.name) || consumer.name === "eval" || consumer.name === "source" || consumer.name === ".");
+    const sinkOnly = consumers.length > 0 && consumers.every((consumer) => DATA_SINK_COMMANDS.has(consumer.name) || (consumer.name === "git" && consumer.words.includes("commit")));
+    if (shellConsumer) embedded.push(...bodies.map((token) => token.value));
+    const kept = shellConsumer || sinkOnly ? segment.tokens.filter((token) => !token.data) : segment.tokens.map((token) => ({ ...token, data: false }));
+    resolved.push(...kept, ...(segment.joiner ? [{ value: segment.joiner, operator: true, dynamic: false }] : []));
+  });
+  return { tokens: resolved, embedded };
+}
+
+/**
+ * `$(cat <<'EOF' … EOF\n)` inside double quotes: Claude Code's commit-message
+ * idiom. With a quoted delimiter nothing in the body expands or runs, so the
+ * whole substitution is literal data.
+ */
+const LITERAL_CAT_HEREDOC = /^\$\(\s*cat\s+<<-?\s*(['"])([^'"\s]+)\1[ \t]*\n(?:([\s\S]*?)\n)?[ \t]*\2[ \t]*\n?\s*\)/u;
+
 function lexShell(input: string): { tokens: ShellToken[]; error?: string } {
   const tokens: ShellToken[] = [];
   let value = "";
   let dynamic = false;
   let started = false;
+  let tokenQuoted = false;
+  let tokenData = false;
   let quote: "single" | "double" | undefined;
+  // Heredocs: the word after `<<` names the delimiter; the body starts on the
+  // next line and ends at a line equal to it. A quoted delimiter makes the body
+  // pure data, which the boundary never needs to see.
+  let expectDelimiter: { stripTabs: boolean } | undefined;
+  const pendingHeredocs: { delimiter: string; quoted: boolean; stripTabs: boolean }[] = [];
   const flush = (): void => {
     if (!started) return;
-    tokens.push({ value, operator: false, dynamic });
+    // A bare `[`, `[[`, `]`, `]]`, `{` or `}` is shell syntax, not an expansion.
+    if (/^[[\]{}]+$/u.test(value)) dynamic = false;
+    if (expectDelimiter) {
+      pendingHeredocs.push({ delimiter: value, quoted: tokenQuoted, stripTabs: expectDelimiter.stripTabs });
+      expectDelimiter = undefined;
+      dynamic = false;
+    }
+    tokens.push({ value, operator: false, dynamic, ...(tokenData ? { data: true } : {}) });
     value = "";
     dynamic = false;
     started = false;
+    tokenQuoted = false;
+    tokenData = false;
   };
   const pushOperator = (operator: string): void => {
     flush();
     tokens.push({ value: operator, operator: true, dynamic: false });
   };
+  /** Consume the heredoc bodies that start after the newline at `newlineIndex`; returns the index to resume lexing at. */
+  const consumeHeredocs = (newlineIndex: number): number => {
+    let position = newlineIndex + 1;
+    for (const heredoc of pendingHeredocs.splice(0)) {
+      const bodyLines: string[] = [];
+      let terminated = false;
+      while (position <= input.length) {
+        const lineEnd = input.indexOf("\n", position);
+        const line = input.slice(position, lineEnd === -1 ? input.length : lineEnd);
+        position = lineEnd === -1 ? input.length + 1 : lineEnd + 1;
+        if ((heredoc.stripTabs ? line.replace(/^\t+/u, "") : line) === heredoc.delimiter) { terminated = true; break; }
+        bodyLines.push(line);
+      }
+      const body = bodyLines.join("\n");
+      // A quoted delimiter suppresses expansion: the body is data for its
+      // consumer. An unquoted one expands, so the body is an ordinary argument.
+      tokens.push(heredoc.quoted ? { value: body, operator: false, dynamic: false, data: true } : { value: body, operator: false, dynamic: /[$`]/u.test(body) });
+      if (!terminated) break;
+    }
+    return Math.min(position, input.length);
+  };
   for (let index = 0; index < input.length; index += 1) {
     const character = input[index]!;
     const next = input[index + 1];
@@ -282,18 +467,39 @@ function lexShell(input: string): { tokens: ShellToken[]; error?: string } {
       if (character === '"') quote = undefined;
       else if (character === "\\" && next === "\n") index += 1;
       else if (character === "\\" && next !== undefined && /[\\"$`]/u.test(next)) { value += next; index += 1; }
-      else { value += character; if (character === "$" || character === "`") dynamic = true; }
+      else if (character === "$") {
+        const literal = LITERAL_CAT_HEREDOC.exec(input.slice(index));
+        if (literal) { value += literal[3] ?? ""; tokenData = true; index += literal[0].length - 1; }
+        else { value += character; dynamic = true; }
+      }
+      else { value += character; if (character === "`") dynamic = true; }
       started = true;
       continue;
     }
-    if (character === "'") { quote = "single"; started = true; continue; }
-    if (character === '"') { quote = "double"; started = true; continue; }
+    if (character === "'") { quote = "single"; started = true; tokenQuoted = true; continue; }
+    if (character === '"') { quote = "double"; started = true; tokenQuoted = true; continue; }
     if (character === "\\") {
       if (next === "\n") index += 1;
       else if (next !== undefined) { value += next; index += 1; }
       started = true;
       continue;
     }
+    // A comment runs to the end of the line.
+    if (character === "#" && !started) {
+      const lineEnd = input.indexOf("\n", index);
+      index = (lineEnd === -1 ? input.length : lineEnd) - 1;
+      continue;
+    }
+    // A newline ends the statement. Any pending heredoc bodies belong to the
+    // statement just lexed, so they are emitted before the separator.
+    if (character === "\n") {
+      flush();
+      expectDelimiter = undefined;
+      if (pendingHeredocs.length > 0) index = consumeHeredocs(index) - 1;
+      const last = tokens.at(-1);
+      if (last && !(last.operator && SEGMENT_SPLIT_OPERATORS.has(last.value))) pushOperator(";");
+      continue;
+    }
     if (/\s/u.test(character)) { flush(); continue; }
     if (character === "$" || character === "`") { dynamic = true; value += character; started = true; continue; }
     // Brace, tilde and pathname expansion can change command names, targets or
@@ -301,7 +507,16 @@ function lexShell(input: string): { tokens: ShellToken[]; error?: string } {
     // dynamic rather than attempting to model Bash's expansion order.
     if ("*?[]{}~".includes(character)) { dynamic = true; value += character; started = true; continue; }
     if (";&|<>".includes(character)) {
-      const operator = next && ((character === "&" && next === "&") || (character === "|" && next === "|") || (character === ">" && next === ">") || (character === "<" && next === "<"))
+      if (character === "<" && next === "<") {
+        const third = input[index + 2];
+        if (third === "<") { pushOperator("<<<"); index += 2; continue; }
+        const stripTabs = third === "-";
+        pushOperator("<<");
+        expectDelimiter = { stripTabs };
+        index += stripTabs ? 2 : 1;
+        continue;
+      }
+      const operator = next && ((character === "&" && next === "&") || (character === "|" && next === "|") || (character === ">" && next === ">"))
         ? `${character}${next}`
         : character;
       pushOperator(operator);
@@ -360,8 +575,8 @@ const FIND_WRITE_ACTIONS = new Set(["-delete", "-exec", "-execdir", "-ok", "-okd
  * escalation, destructive git operations and any write outside the task cwd
  * are never routine; the Decision Worker judges those.
  */
-export function isRoutinePermission(toolName: string, input: unknown, cwd: string): boolean {
-  const policyResult = evaluatePermission(toolName, input, cwd);
+export function isRoutinePermission(toolName: string, input: unknown, cwd: string, options: PermissionPolicyOptions = {}): boolean {
+  const policyResult = evaluatePermission(toolName, input, cwd, options);
   if (policyResult.decision === "deny") return false;
   if (toolName === "Edit" || toolName === "Write" || toolName === "NotebookEdit") return true;
   if (toolName === "Read" || toolName === "Glob" || toolName === "Grep" || toolName === "LS" || toolName === "TodoWrite") return true;

package/src/supervisor.ts

@@ -651,7 +651,7 @@ export class Supervisor {
             this.#pendingPermissions.delete(event.request.requestId);
             skipDecisionNotify = true;
           } else {
-            const policy = evaluatePermission(event.request.toolName, event.request.input, task.cwd);
+            const policy = evaluatePermission(event.request.toolName, event.request.input, task.cwd, { writeRoots: event.request.writeRoots });
             if (policy.decision === "deny") {
               if (this.#adapter.respondPermission) {
                 await this.#adapter.respondPermission(handle, event.request.requestId, event.request.toolUseId, {
@@ -682,9 +682,9 @@ export class Supervisor {
           skipDecisionNotify = true;
         } else if (this.#automation && !this.#humanRequired) {
           const authority = task.spec.autonomy.permissionAuthority;
-          const policy = evaluatePermission(event.request.toolName, event.request.input, task.cwd);
+          const policy = evaluatePermission(event.request.toolName, event.request.input, task.cwd, { writeRoots: event.request.writeRoots });
           const answerLocally = authority === "policy"
-            || (authority === "hybrid" && (policy.decision === "deny" || isRoutinePermission(event.request.toolName, event.request.input, task.cwd)));
+            || (authority === "hybrid" && (policy.decision === "deny" || isRoutinePermission(event.request.toolName, event.request.input, task.cwd, { writeRoots: event.request.writeRoots })));
           if (answerLocally && this.#adapter.respondPermission) {
             const behavior: "allow" | "deny" = policy.decision === "deny" ? "deny" : "allow";
             await this.#adapter.respondPermission(handle, event.request.requestId, event.request.toolUseId, {
@@ -865,7 +865,7 @@ export class Supervisor {
         // checked before the generic policy-deny reason, or the Decision
         // Worker's chosen answer would never reach Claude.
         const isAskUserQuestionAnswer = event.request.toolName === "AskUserQuestion" && action.action === "deny_permission";
-        const policy = evaluatePermission(event.request.toolName, event.request.input, task.cwd);
+        const policy = evaluatePermission(event.request.toolName, event.request.input, task.cwd, { writeRoots: event.request.writeRoots });
         const behavior = policy.decision === "deny" ? "deny" : action.action === "allow_permission" ? "allow" : "deny";
         const message = behavior !== "deny"
           ? undefined
@@ -1042,7 +1042,7 @@ export class Supervisor {
       const request = requestId ? this.#pendingPermissions.get(requestId) : [...this.#pendingPermissions.values()].at(-1);
       if (!request) throw new Error("no pending permission request");
       if (this.#humanRequired && this.#humanGate !== "permission") throw new Error("automatic decisions are held by a separate human gate; use resume-auto explicitly");
-      const policy = evaluatePermission(request.toolName, request.input, task.cwd);
+      const policy = evaluatePermission(request.toolName, request.input, task.cwd, { writeRoots: request.writeRoots });
       if (policy.decision === "deny" && behavior === "allow") throw new Error(`permission denied by policy: ${policy.reason}`);
       await this.#adapter.respondPermission(handle, request.requestId, request.toolUseId, { behavior: policy.decision === "deny" ? "deny" : behavior }, behavior === "allow" ? request.input : undefined);
       this.#pendingPermissions.delete(request.requestId);

package/src/types.ts

@@ -25,6 +25,12 @@ export interface WorkerPermissionRequest {
    * prompt to a human. Bridge/JSONL requests have no phase.
    */
   phase?: "pre" | "prompt";
+  /**
+   * Directories outside the task cwd that the Worker may write to for this
+   * session — today Claude Code's own per-session scratchpad, reported by its
+   * SessionStart hook. Never a repository or a home directory.
+   */
+  writeRoots?: string[];
 }
 
 export type WorkerEvent =

package/src/worker/tmux-adapter.ts

@@ -120,6 +120,8 @@ interface TmuxRecord {
   hookUnsubscribe?: () => Promise<void>;
   claudeSessionId?: string;
   transcriptPath?: string;
+  /** Claude Code's per-session scratchpad directory (from SessionStart); an extra write root for the policy. */
+  scratchpadDir?: string;
   /** Primary readiness signal for interactive startup: SessionStart observed. */
   sessionStartReceived: boolean;
   /** Messages the adapter itself pasted, awaiting UserPromptSubmit acknowledgement. */
@@ -1990,6 +1992,7 @@ export class TmuxWorkerAdapter implements WorkerAdapter {
         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;
         record.sessionStartReceived = true;
         return {};
       }
@@ -2069,6 +2072,7 @@ export class TmuxWorkerAdapter implements WorkerAdapter {
         input: event.tool_input,
         raw: event as unknown as Record<string, unknown>,
         phase,
+        ...(record.scratchpadDir ? { writeRoots: [record.scratchpadDir] } : {}),
       },
     });
     return new Promise<HookRelayReply>((resolve) => {