@staix/agent-hub 0.14.0 → 0.16.0

package/src/cli/terminal-recovery.ts

@@ -328,7 +328,7 @@ export function recordPath(stateDir: string): string {
   return join(stateDir, RECORD_FILE);
 }
 
-/** Extra terminal ownership is supported only for the native proxy transport; other I2 extras stay headless. */
+/** Resolve declared terminal roots without treating a launch candidate as daemon ownership proof. */
 function executionRoot(peer: string, projectRoot: string, captured?: string): string {
   const builtin = definitionOf(peer);
   if (builtin?.session.launchRecord) return projectRoot;
@@ -336,11 +336,6 @@ function executionRoot(peer: string, projectRoot: string, captured?: string): st
   const definition = catalog.definitionOf(peer, declarations);
   if (!definition?.session.launchRecord) throw new Error(`${peer}: no managed terminal recovery adapter`);
   if (!declarations?.[peer] || definition.transport !== "codex-appserver" && definition.transport !== "claude-channel") throw new Error(`${peer}: extra instance has no managed terminal support`);
-  // #450 I3: a Claude instance reviews or plans in the canonical checkout; it never owns an execution worktree.
-  if (definition.transport === "claude-channel") {
-    if (captured !== undefined && captured !== projectRoot) throw new Error(`${peer}: recorded execution root changed; manual recovery required`);
-    return projectRoot;
-  }
   const expected = resolveInstanceExecutionCwd(projectRoot, peer, declarations, effectiveInstanceRoles(peer, declarations, roles, catalog), catalog);
   if (captured !== undefined && captured !== expected) throw new Error(`${peer}: declared execution worktree changed; manual recovery required`);
   return expected;

package/src/hub/action-class.ts

@@ -5,7 +5,8 @@ export type ActionClass = typeof ACTION_CLASSES[number];
 
 const SHELL_TOOLS = new Set(["bash", "shell", "shell_command", "exec_command", "run_shell_command"]);
 const LIMIT = 16_384;
-type Command = { words: string[]; outputs: string[] };
+/** `nested`: the commands of each substitution in the segment (`$(...)`, a backtick). They run in a subshell, so their `cd` never moves the outer cwd. */
+type Command = { words: string[]; outputs: string[]; nested?: Command[][] };
 
 /** Bound the whole input before accepting any prefix, including unsupported suffixes. */
 function segmentLimit(text: string): boolean {
@@ -28,8 +29,79 @@ function segmentLimit(text: string): boolean {
   return true;
 }
 
-/** Literal shell words only; unsupported syntax discards only its unfinished segment. */
-function commands(text: string): Command[] | undefined {
+/**
+ * An expansion (`$VAR`, `${...}`, `$(...)`, a backtick) stands in a word as this one character. The input itself may not contain it
+ * (`commands` refuses a NUL), so a word has it only where the hub put it: the word's value is unknown (#762).
+ */
+const OPAQUE = "\0";
+const opaque = (word: string | undefined): boolean => word !== undefined && word.includes(OPAQUE);
+
+/** The index after the bracket that closes `text[at]` (`(` or `{`), quotes and nested expansions respected, or -1 when it never closes. */
+function matching(text: string, at: number, nest = 0): number {
+  if (nest > 16) return -1;
+  const open = text[at]!, close = open === "(" ? ")" : "}";
+  let depth = 0;
+  for (let i = at; i < text.length; i++) {
+    const c = text[i]!;
+    if (c === "\\") { i++; continue; }
+    if (c === "'") { const end = text.indexOf("'", i + 1); if (end < 0) return -1; i = end; continue; }
+    if (c === "`") { const end = text.indexOf("`", i + 1); if (end < 0) return -1; i = end; continue; }
+    if (c === '"') {
+      for (i++; i < text.length && text[i] !== '"'; i++) {
+        if (text[i] === "\\") i++;
+        else if (text[i] === "$" && (text[i + 1] === "(" || text[i + 1] === "{")) { const end = matching(text, i + 1, nest + 1); if (end < 0) return -1; i = end - 1; }
+      }
+      if (i >= text.length) return -1;
+      continue;
+    }
+    if (c === "$" && (text[i + 1] === "(" || text[i + 1] === "{") && i + 1 !== at) { const end = matching(text, i + 1, nest + 1); if (end < 0) return -1; i = end - 1; continue; }
+    if (c === open) depth++;
+    else if (c === close && --depth === 0) return i + 1;
+  }
+  return -1;
+}
+
+/**
+ * The expansion that starts at `text[at]` (a `$` or a backtick): where it ends, the command texts it runs (`inners`: `$(...)` and a backtick
+ * run their text; `${...}` runs only the substitutions nested in its parameter text, never the text itself), and `drop` for a `$"` that only
+ * opens a quote. Undefined for a `$` that is a literal dollar. An expansion that never closes ends at the end of the text.
+ */
+function expansion(text: string, at: number, quoted: boolean, nest = 0): { end: number; inners: string[]; drop?: true } | undefined {
+  if (text[at] === "`") {
+    for (let i = at + 1; i < text.length; i++) {
+      if (text[i] === "\\") { i++; continue; }
+      if (text[i] === "`") return { end: i + 1, inners: [text.slice(at + 1, i)] };
+    }
+    return { end: text.length, inners: [] };
+  }
+  const next = text[at + 1];
+  if (next === "(") {
+    const end = matching(text, at + 1);
+    return end < 0 ? { end: text.length, inners: [] } : { end, inners: [text.slice(at + 2, end - 1)] };
+  }
+  if (next === "{") {                                       // parameter text is data: only the substitutions inside it run
+    const end = matching(text, at + 1);
+    const body = end < 0 ? text.slice(at + 2) : text.slice(at + 2, end - 1), inners: string[] = [];
+    for (let i = 0; i < body.length && nest < 4; i++) {
+      if (body[i] === "\\") { i++; continue; }
+      if (body[i] !== "$" && body[i] !== "`") continue;
+      const inner = expansion(body, i, false, nest + 1);
+      if (inner) { inners.push(...inner.inners); i = inner.end - 1; }
+    }
+    return { end: end < 0 ? text.length : end, inners };
+  }
+  if (next === "'") {                                       // $'...': ANSI-C quoting, whose escapes build the word
+    for (let i = at + 2; i < text.length; i++) { if (text[i] === "\\") i++; else if (text[i] === "'") return { end: i + 1, inners: [] }; }
+    return { end: text.length, inners: [] };
+  }
+  if (next === '"') return quoted ? undefined : { end: at + 1, inners: [], drop: true };
+  if (next !== undefined && /[A-Za-z_]/.test(next)) { let end = at + 2; while (end < text.length && /[A-Za-z0-9_]/.test(text[end]!)) end++; return { end, inners: [] }; }
+  if (next !== undefined && /[0-9@*#?$!-]/.test(next)) return { end: at + 2, inners: [] };
+  return undefined;
+}
+
+/** Shell words, literal where they can be read. An expansion becomes an opaque word and the commands it runs are read too; unsupported syntax discards only its unfinished segment. */
+function commands(text: string, nest = 0): Command[] | undefined {
   if (text.length > LIMIT || text.includes("\0") || !segmentLimit(text)) return;
   const result: Command[] = [];
   let words: string[] = [], outputs: string[] = [], word = "", active = false, quote = "";
@@ -40,7 +112,8 @@ function commands(text: string): Command[] | undefined {
     else if (!redirect) words.push(word);
     word = ""; active = false; redirect = false;
   };
-  const finish = () => { flush(); if (words.length || outputs.length) result.push({ words, outputs }); words = []; outputs = []; };
+  let nested: Command[][] = [];
+  const finish = () => { flush(); if (words.length || outputs.length || nested.length) result.push({ words, outputs, ...(nested.length ? { nested } : {}) }); words = []; outputs = []; nested = []; };
   for (let i = 0; i < text.length; i++) {
     const c = text[i]!;
     if (quote === "'") { if (c === "'") quote = ""; else word += c; continue; }
@@ -51,7 +124,13 @@ function commands(text: string): Command[] | undefined {
       if (next !== "\n") word += next;
       active = true; continue;
     }
-    if (c === "$" || c === "`") return result;
+    if (c === "$" || c === "`") {
+      const found = expansion(text, i, quote === '"');
+      if (!found) { word += c; active = true; continue; }         // a lone `$` is a literal dollar
+      if (nest < 4) for (const text of found.inners) { const inner = commands(text, nest + 1); if (inner?.length) nested.push(inner); }
+      if (!found.drop) { word += OPAQUE; active = true; }
+      i = found.end - 1; continue;
+    }
     if (quote) { if (c === quote) quote = ""; else word += c; continue; }
     if (c === "'" || c === '"') { quote = c; active = true; continue; }
     if (c === "#" && !active) { while (i < text.length && text[i] !== "\n") i++; finish(); continue; }
@@ -97,6 +176,14 @@ function outside(target: string, root: string, cwd: string): boolean {
   const rel = relative(resolve(root), resolve(cwd, target));
   return rel === ".." || rel.startsWith("../") || isAbsolute(rel);
 }
+/**
+ * A word that starts with an expansion may expand to a dash word (`$OPTS` as `-rf`), so a class that depends on a flag counts it as that flag
+ * (#762). Only the words before `--` can be options. A word that merely has an expansion later (`build/$X`, `--name=$X`) cannot start one.
+ */
+function mayBeFlag(words: readonly string[]): boolean {
+  const end = words.indexOf("--");
+  return words.slice(0, end < 0 ? undefined : end).some(w => w.startsWith(OPAQUE));
+}
 function flags(words: string[], letter: string): boolean {
   const end = words.indexOf("--");
   return words.slice(0, end < 0 ? undefined : end).some(w => /^-[^-]/.test(w) && w.slice(1).includes(letter));
@@ -130,7 +217,7 @@ function commandHeads(words: string[], values: readonly string[], booleans: read
       continue;
     }
     if (!uncertain) return [{ name: word, args: words.slice(i + 1) }];
-    if (actions.includes(word)) heads.push({ name: word, args: words.slice(i + 1) });
+    if (actions.includes(word) || opaque(word)) heads.push({ name: word, args: words.slice(i + 1) });
   }
   return heads;
 }
@@ -153,6 +240,7 @@ function forcedClean(words: string[]): boolean {
         if (flag === "n") dry = true;
       }
     }
+    else if (word.startsWith(OPAQUE)) force = true;   // an expansion may be `-f`; a literal dry run still wins (#762)
   }
   return force && !dry;
 }
@@ -182,12 +270,110 @@ function unwrapped(input: string[]): string[] {
       else if (flag.startsWith("--") && !flag.includes("=") && !["--ignore-environment", "--foreground", "--preserve-status", "--no-run-if-empty", "--verbose"].includes(flag)) return [];
     }
     if (name === "timeout") {
-      if (!/^\d+(?:\.\d+)?[smhd]?$/.test(words.shift() ?? "")) return [];
+      const duration = words.shift() ?? "";
+      if (!/^\d+(?:\.\d+)?[smhd]?$/.test(duration) && !opaque(duration)) return [];
     }
   }
   return [];
 }
 
+/**
+ * Whether every definition of a GraphQL document is a read: a `query` (or shorthand `{...}`) or a `fragment`. Strings and comments are skipped, so
+ * a keyword inside one counts for nothing. A `mutation`, a `subscription`, any other top-level word, unbalanced text or no operation is false:
+ * unknown is never a read.
+ */
+function graphqlQueryOnly(text: string): boolean {
+  const skipString = (at: number): number => {              // `at` is the opening quote; the index after the string, or -1 when it never ends
+    // A block string ends at its first `"""`: GraphQL's escaped `\"""` ends it later, so a lexer that ends early only turns a read into a write (the strict direction).
+    if (text.startsWith('"""', at)) { const end = text.indexOf('"""', at + 3); return end < 0 ? -1 : end + 3; }
+    // GraphQL's line terminators are LF, CR and CRLF, and none may appear in a single-line string: ending early is the strict direction.
+    for (let i = at + 1; i < text.length; i++) { if (text[i] === "\\") { i++; if (text[i] === "\n" || text[i] === "\r") return -1; } else if (text[i] === '"') return i + 1; else if (text[i] === "\n" || text[i] === "\r") return -1; }
+    return -1;
+  };
+  const skipComment = (at: number): number => { let i = at; while (i < text.length && text[i] !== "\n" && text[i] !== "\r") i++; return i; };   // a comment ends at LF or CR (so also CRLF), never later than GraphQL ends it
+  const closers: Record<string, string> = { "{": "}", "(": ")", "[": "]" };
+  const skipBlock = (at: number): number => {             // `at` is an opening bracket; the index after its matching close, or -1
+    const close = closers[text[at]!]!;
+    for (let i = at + 1; i < text.length; i++) {
+      const c = text[i]!;
+      if (c === '"') { const end = skipString(i); if (end < 0) return -1; i = end - 1; }
+      else if (c === "#") i = skipComment(i) - 1;
+      else if (c in closers) { const end = skipBlock(i); if (end < 0) return -1; i = end - 1; }
+      else if (c === "}" || c === ")" || c === "]") return c === close ? i + 1 : -1;
+    }
+    return -1;
+  };
+  let start = true, operations = 0;                          // `start`: the next token begins a top-level definition
+  for (let i = 0; i < text.length;) {
+    const c = text[i]!;
+    if (/[\s,\uFEFF]/.test(c)) { i++; continue; }
+    if (c === "#") { i = skipComment(i); continue; }
+    if (c === "{") { const end = skipBlock(i); if (end < 0) return false; if (start) operations++; i = end; start = true; continue; }   // shorthand query, or the body that ends a definition
+    if (c === "(") { if (start) return false; const end = skipBlock(i); if (end < 0) return false; i = end; continue; }
+    const name = /^[A-Za-z_][A-Za-z0-9_]*/.exec(text.slice(i, i + 256))?.[0];
+    if (name) {
+      if (start) { if (name === "query") operations++; else if (name !== "fragment") return false; start = false; }
+      i += name.length; continue;
+    }
+    if (!start && (c === "@" || c === ":")) { i++; continue; }   // a directive, or `fragment X on Y`; nothing else is read at the top level
+    return false;
+  }
+  return start && operations > 0;
+}
+
+/**
+ * `gh api graphql` with fields (#756): undefined when the call does not name the graphql endpoint, true only for ONE literal `query` field whose
+ * every operation is a read. A query from a file or stdin (`@file`, `--input`), a second `query` field, an option this does not know,
+ * another positional and every unparsable document are false: the caller keeps them external-write.
+ */
+function ghGraphqlRead(words: string[]): boolean | undefined {
+  const rest = words.slice(1);                                   // `words` is `api ...`
+  if (!rest.includes("graphql")) return undefined;
+  const fieldOptions = ["-f", "-F", "--field", "--raw-field"];
+  const valued = ["-H", "--header", "--hostname", "-q", "--jq", "-t", "--template", "--cache", "-p", "--preview", "-X", "--method"];
+  const booleans = ["--paginate", "--slurp", "--silent", "-i", "--include", "--verbose"];
+  const positional: string[] = [], queries: string[] = [];
+  for (let i = 0; i < rest.length; i++) {
+    const word = rest[i]!;
+    if (word === "--" || !word.startsWith("-")) { positional.push(word); continue; }
+    let field: string | undefined;
+    if (fieldOptions.includes(word)) { field = rest[++i]; if (field === undefined) return false; }
+    else if (word.startsWith("--field=") || word.startsWith("--raw-field=")) field = word.slice(word.indexOf("=") + 1);
+    else if (/^-[fF][^=]/.test(word)) field = word.slice(2);
+    else if (valued.includes(word)) { if (++i >= rest.length) return false; }
+    else if (valued.some(key => key.startsWith("--") ? word.startsWith(`${key}=`) : /^-[HqtpX]./.test(word) && word.startsWith(key))) continue;
+    else if (!booleans.includes(word)) return false;
+    if (field !== undefined) {
+      const eq = field.indexOf("=");
+      if (eq < 0) return false;
+      if (field.slice(0, eq) === "query") queries.push(field.slice(eq + 1));
+    }
+  }
+  const method = option(rest, "-X", "--method");
+  if (method !== undefined && method.toUpperCase() !== "POST") return false;
+  const [query] = queries;
+  if (queries.some(opaque)) return false;                                 // an expansion can close a brace or add an operation: unknown is never a read
+  if (positional.length !== 1 || positional[0] !== "graphql" || queries.length !== 1 || query === undefined || query.startsWith("@")) return false;
+  return graphqlQueryOnly(query);
+}
+
+/**
+ * `gh api` with a word the hub cannot read where an option may stand (#762): an option name with an expansion in it, or a later operand that
+ * starts with one (`gh api repos/o/r $FLAGS`, which can hold `-X POST`). The endpoint (the first operand) and the values of the known valued
+ * options are data. Method, field and query values are judged by the ordinary rules, where an unknown method is never GET.
+ */
+function ghApiDynamic(words: string[]): boolean {
+  const valued = ["-H", "--header", "--hostname", "-q", "--jq", "-t", "--template", "--cache", "-p", "--preview", "-X", "--method", "-f", "-F", "--field", "--raw-field", "--input"];
+  let operands = 0;
+  for (let i = 1; i < words.length; i++) {
+    const word = words[i]!;
+    if (word === "--") return words.slice(i + 1).some((w, n) => opaque(w) && operands + n > 0);
+    if (word.startsWith("-")) { if (opaque(word)) return true; if (valued.includes(word)) i++; continue; }
+    if (operands++ > 0 && word.startsWith(OPAQUE)) return true;
+  }
+  return false;
+}
+
 /** Scan curl options once: data, headers and other option values never become options. */
 function curlWrites(input: string[]): boolean {
   const longValues = new Set([
@@ -249,7 +435,7 @@ function sequence(parsed: Command[], root: string, initial: string[], found: Set
     const [program, ...args] = unwrapped(command.words);
     const target = args[0] === "--" ? args[1] : args[0];
     // Retain both outcomes: cd may fail, or be in a pipeline/conditional branch.
-    if (program === "cd" && (!target || target.startsWith("~"))) {
+    if (program === "cd" && (!target || target.startsWith("~") || opaque(target))) {   // an unknown directory is an unknown cwd
       if (!cwd.has("") && cwd.size >= 128) cwd.delete(cwd.values().next().value!);
       cwd.add("");
     }
@@ -262,6 +448,7 @@ function sequence(parsed: Command[], root: string, initial: string[], found: Set
   }
 }
 function classify(command: Command, root: string, cwd: string[], found: Set<ActionClass>, depth = 0): void {
+  for (const group of command.nested ?? []) sequence(group, root, cwd, found, depth);   // a substitution's own cwd state; only its classes come back
   const words = unwrapped(command.words);
   const program = basename(words.shift() ?? "");
   if (["sh", "bash", "zsh"].includes(program) && depth < 2) {
@@ -270,7 +457,7 @@ function classify(command: Command, root: string, cwd: string[], found: Set<Acti
     const mode = shell.shift();
     if (mode && /^-[A-Za-z]*c[A-Za-z]*$/.test(mode)) {
       if (shell[0] === "--") shell.shift();
-      const nested = shell[0] === undefined ? undefined : commands(shell[0]);
+      const nested = shell[0] === undefined ? undefined : commands(shell[0].replaceAll(OPAQUE, "$_"));
       if (nested) sequence(nested, root, cwd, found, depth + 1);
     }
   }
@@ -278,11 +465,12 @@ function classify(command: Command, root: string, cwd: string[], found: Set<Acti
   if (program === "git") {
     const heads = commandHeads(words, ["-C", "-c", "--git-dir", "--work-tree", "--namespace", "--config-env"],
       ["-P", "-p", "--no-pager", "--paginate", "--literal-pathspecs", "--bare", "--no-optional-locks", "--no-replace-objects"], ["push", "reset", "clean", "branch"]);
+    if (heads.some(head => opaque(head.name))) { found.add("publish"); found.add("destroy"); }   // `git $CMD`: the strictest classes git reaches (#762)
     for (const { name: sub, args } of heads) {
       if (sub === "push") found.add("publish");
-      if (sub === "reset" && args.some(w => w === "--hard" || w.startsWith("--hard="))) found.add("destroy");
+      if (sub === "reset" && (args.some(w => w === "--hard" || w.startsWith("--hard=")) || mayBeFlag(args))) found.add("destroy");
       if (sub === "clean" && forcedClean(args)) found.add("destroy");
-      if (sub === "branch" && (flags(args, "D") || args.includes("--delete") && args.includes("--force"))) found.add("destroy");
+      if (sub === "branch" && (flags(args, "D") || args.includes("--delete") && args.includes("--force") || mayBeFlag(args))) found.add("destroy");
     }
   }
   if (["npm", "cargo", "pnpm", "yarn", "bun"].includes(program)) {
@@ -300,8 +488,9 @@ function classify(command: Command, root: string, cwd: string[], found: Set<Acti
     for (const head of heads) {
       const candidates = program === "yarn" && head.name === "npm" ? commandHeads(head.args, values, booleans, actions) : [head];
       for (const { name: sub, args } of candidates) {
+        if (opaque(sub) && program !== "bun") { found.add("publish"); found.add("install"); }   // `npm $CMD`; bun runs a file by default, so its expansion is no subcommand (#762)
         if (sub === "publish") found.add("publish");
-        const global = words.includes("--global") || flags(words, "g");
+        const global = words.includes("--global") || flags(words, "g") || mayBeFlag(words);
         if ((program === "cargo" && sub === "install") || (["install", "i", "add"].includes(sub) && global) || (program === "yarn" && sub === "global" && args[0] === "add")) found.add("install");
       }
     }
@@ -310,20 +499,25 @@ function classify(command: Command, root: string, cwd: string[], found: Set<Acti
   if (program === "gh") {
     if (words[0] === "release" && ["create", "upload", "edit", "delete"].includes(words[1] ?? "")) found.add("publish");
     if (["issue", "pr", "gist"].includes(words[0] ?? "") && ["create", "comment", "edit", "close", "reopen", "merge", "review", "delete"].includes(words[1] ?? "")) found.add("external-write");
-    if (words[0] === "api") {
+    if (opaque(words[0])) { found.add("publish"); found.add("external-write"); }   // `gh $GROUP ...`: the strictest classes gh reaches (#762)
+    else if (opaque(words[1]) && ["release"].includes(words[0] ?? "")) found.add("publish");
+    else if (opaque(words[1]) && ["issue", "pr", "gist", "run", "workflow", "repo", "secret", "variable", "label"].includes(words[0] ?? "")) found.add("external-write");
+    if (words[0] === "repo" && ["delete", "archive", "edit"].includes(words[1] ?? "") || ["secret", "variable"].includes(words[0] ?? "") && ["set", "delete"].includes(words[1] ?? "") || words[0] === "label" && ["create", "edit", "delete"].includes(words[1] ?? "")) found.add("external-write");
+    if (words[0] === "run" && ["rerun", "cancel", "delete"].includes(words[1] ?? "") || words[0] === "workflow" && ["run", "enable", "disable"].includes(words[1] ?? "")) found.add("external-write");
+    if (words[0] === "api" && ghGraphqlRead(words) !== true) {   // a GraphQL document of queries only is a read (#756); everything else keeps the REST rule
       const method = option(words, "-X", "--method");
       const field = words.some(w => w === "-f" || w === "-F" || w.startsWith("-f") || w.startsWith("-F") || w === "--input" || w.startsWith("--input=") || w.startsWith("--field") || w.startsWith("--raw-field"));
-      if (method ? !["GET", "HEAD"].includes(method.toUpperCase()) : field) found.add("external-write");
+      if (method ? !["GET", "HEAD"].includes(method.toUpperCase()) : field || ghApiDynamic(words)) found.add("external-write");
     }
   }
   if (program === "curl" && curlWrites(words)) found.add("external-write");
   if (["http", "https"].includes(program) && words.some(w => /^(?:POST|PUT|PATCH|DELETE|OPTIONS|TRACE|CONNECT)$/.test(w))) found.add("external-write");
   if (["mail", "mailx", "sendmail"].includes(program) && operands(words).length > 0) found.add("external-write");
   if (["slack", "telegram", "discord"].includes(program) && words.some(w => ["send", "post", "chat.postMessage"].includes(w))) found.add("external-write");
-  if (program === "rm" && (flags(words, "r") || flags(words, "R") || words.includes("--recursive")) && operands(words).some(p => cwd.some(at => outside(p, root, at)))) found.add("destroy");
-  if (["cp", "mv"].includes(program) && (flags(words, "f") || words.includes("--force"))) {
+  if (program === "rm" && (flags(words, "r") || flags(words, "R") || words.includes("--recursive") || operands(words).length > 1 && mayBeFlag(words)) && operands(words).some(p => opaque(p) /* an expansion may hold `..` or an absolute path (#762) */ || cwd.some(at => outside(p, root, at)))) found.add("destroy");
+  if (["cp", "mv"].includes(program) && (flags(words, "f") || words.includes("--force") || words.length > 2 && mayBeFlag(words.slice(0, -1)))) {   // with two words the first cannot be a flag: `cp -f x` has no target
     const target = option(words, "-t", "--target-directory") ?? operands(words).at(-1);
-    if (target && cwd.some(at => outside(target, root, at))) found.add("destroy");
+    if (target && (opaque(target) || cwd.some(at => outside(target, root, at)))) found.add("destroy");
   }
 }
 

package/src/hub/action-enforce.ts

@@ -0,0 +1,90 @@
+import { ACTION_CLASSES, classifyAction, type ActionClass } from "./action-class.ts";
+import { actionApprovalView, actionPolicyConfig, type ActionBudgets, type ActionPolicyConfig } from "./action-policy.ts";
+import type { ActionGateVerdict } from "../adapters/acp.ts";
+
+/**
+ * Where the always-ask policy (#636) meets the two surfaces that see a tool call before it runs: the Claude PreToolUse hook and ACP
+ * `session/request_permission`. The classifier (`action-class.ts`) and the budget ledger (`action-policy.ts`) decide; this file only
+ * connects them, and only ever adds an approval: an empty result keeps the native permission policy.
+ */
+
+/** One native tool call as an adapter saw it: every name it is known by, the ACP tool kind when reported, and its arguments. */
+export interface ActionCall { names: readonly string[]; kind?: string; input: unknown }
+
+/** The classes of one call. ACP names a shell call `execute` by kind whatever its tool is called, so that kind is also read as a shell. */
+export function classifyCall(call: ActionCall, root: string): ActionClass[] {
+  const names = new Set(call.names.filter(name => typeof name === "string" && name.length > 0));
+  if (call.kind === "execute") names.add("bash");
+  const found = new Set<ActionClass>();
+  for (const name of names) for (const key of classifyAction(name, call.input, root)) found.add(key);
+  return ACTION_CLASSES.filter(key => found.has(key));
+}
+
+/**
+ * The classes the Claude PreToolUse hook must `ask` about, in every permission mode. The budget never relaxes it: Claude's own dialog
+ * cannot carry a class-budget choice, so every classed Claude call asks (a count of zero approved calls, always). A handle-less request
+ * selects the classes without touching any session ledger.
+ */
+export function claudeActionClasses(budgets: ActionBudgets, tool: string, input: unknown, root: string): ActionClass[] {
+  const classes = classifyAction(tool, input, root);
+  if (!classes.length) return [];
+  const decision = budgets.request(undefined, classes);
+  return decision.kind === "ask" ? decision.classes : [];
+}
+
+/** The command line an approval shows: the shell command when there is one, else the arguments. Bounded by the caller's screen. */
+export function commandText(input: unknown): string {
+  let value: unknown = input;
+  if (typeof input === "string") { try { value = JSON.parse(input) as unknown; } catch { return input; } }
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const record = value as Record<string, unknown>, command = record.command ?? record.cmd;
+    if (typeof command === "string") return command;
+    if (Array.isArray(command) && command.every(word => typeof word === "string")) return (command as string[]).join(" ");
+    if (Array.isArray(record.args) && record.args.every(word => typeof word === "string")) return ["git", ...(record.args as string[])].join(" ");
+  }
+  try { return JSON.stringify(value) ?? ""; } catch { return ""; }
+}
+
+export interface ActionGatePorts<T> {
+  budgets: ActionBudgets;
+  policy(): ActionPolicyConfig | undefined;
+  /** The peer's execution root: a delete outside it is classed. */
+  root(peer: string): string;
+  /** The task the peer is working on, for the approval line. */
+  task(peer: string): T | undefined;
+  /** The task's public view (`Tasks.publicView`): the only way a task title reaches an approval. */
+  publicView(task: T): Record<string, unknown>;
+  /** A private turn or an open PII task: the command is withheld. */
+  isPrivate(peer: string): boolean;
+  /** The PII screen for text (`Tasks.nameable`). */
+  nameable(text: string): boolean;
+}
+
+/**
+ * The ACP gate of one peer. It returns a verdict only when a person must be asked: a classed call with no session budget left. A call
+ * within an approved class budget, and every unclassed call, return undefined and follow the permission mode as before (the budget
+ * spends here, once per request).
+ */
+export function actionGate<T>(ports: ActionGatePorts<T>, peer: string): (call: ActionCall, session: string, onPremToolTitle?: string) => ActionGateVerdict | undefined {
+  return (call, session, onPremToolTitle) => {
+    const classes = classifyCall(call, ports.root(peer));
+    if (!classes.length) return undefined;
+    const decision = ports.budgets.request(ports.budgets.bindSession(peer, session), classes);
+    if (decision.kind !== "ask") return undefined; // native, or within an approved class budget
+    // Only the host's local/Pi permit callback supplies this full title. Match the exact executed tool form before bypassing public redaction.
+    const input = call.input && typeof call.input === "object" && !Array.isArray(call.input) ? call.input as Record<string, unknown> : undefined;
+    const expected = call.names.includes("bash") && typeof input?.command === "string" ? `bash: ${input.command}`
+      : call.names.includes("git") && Array.isArray(input?.args) && input.args.every(word => typeof word === "string") ? `git ${input.args.join(" ")}` : undefined;
+    const complete = expected !== undefined && expected === onPremToolTitle;
+    const view = onPremToolTitle === undefined ? actionApprovalView(decision.classes, commandText(call.input), ports.task(peer), {
+      publicView: task => ports.publicView(task), private: ports.isPrivate(peer), commandView: command => ports.nameable(command) ? command : undefined })
+      : { title: `Action approval (${decision.classes.join(", ")})\n${complete ? onPremToolTitle : "[complete command unavailable]"}`, complete };
+    const { title } = view;
+    if (!view.complete) return { title, denyOnly: true };
+    const challenge = decision.challenge, limits = actionPolicyConfig(ports.policy()).budgets;
+    // A budget of one is this call alone: the ordinary allow already says that, so no second choice is offered for it.
+    if (!challenge || !decision.classes.some(key => limits[key] > 1)) return { title };
+    return { title, budget: { label: decision.classes.map(key => `${key} x${limits[key]}`).join(", "), approve: () => ports.budgets.approve(challenge) } };
+  };
+}

package/src/hub/action-policy.ts

@@ -5,8 +5,7 @@ export interface ActionPolicyConfig { enabled: boolean; always_ask: ActionClass[
 const DEFAULT_BUDGETS: Record<ActionClass, number> = { publish: 1, destroy: 3, "external-write": 5, install: 2 };
 /** Defaults are host policy; overrides belong only in untracked config.local.json.
  * ponytail: startup adopts that local policy without a retained person confirmation.
- * Before adapter enforcement (#312/#313), bind weakened startup policy to person
- * confirmation or surface it as attention; slice 1 never enforces these grants.
+ * Status surfaces every weakening as attention; upgrade: retain a person-bound startup confirmation.
  */
 export function actionPolicyConfig(value?: unknown): ActionPolicyConfig {
   const fail = (): never => { throw new Error("action_policy: expected enabled, always_ask and class budgets (integers 0..1000)"); };
@@ -31,24 +30,25 @@ export function actionPolicyConfig(value?: unknown): ActionPolicyConfig {
 export interface ActionSessionBudget { readonly peer: string; readonly session: string }
 export interface ActionChallenge { readonly classes: readonly ActionClass[] }
 export type ActionDecision = { kind: "native" } | { kind: "ask"; classes: ActionClass[]; challenge?: ActionChallenge } | { kind: "budget"; classes: ActionClass[] };
-interface Session { handle: ActionSessionBudget; policy: string; remaining: Record<ActionClass, number> }
+/** `grants` counts the class-budget approvals of this session and policy: a challenge remembers it, so a later approval can tell that another one landed first. */
+interface Session { handle: ActionSessionBudget; policy: string; remaining: Record<ActionClass, number>; grants: Record<ActionClass, number> }
 const empty = (): Record<ActionClass, number> => ({ publish: 0, destroy: 0, "external-write": 0, install: 0 });
 /** Host-only ledger: session ids and policy come from current runtime ports, never a tool argument. */
 export class ActionBudgets {
   private sessions = new Map<string, Session>();
-  private challenges = new WeakMap<ActionChallenge, { handle: ActionSessionBudget; policy: string; classes: ActionClass[] }>();
+  private challenges = new WeakMap<ActionChallenge, { handle: ActionSessionBudget; policy: string; classes: ActionClass[]; grants: Record<ActionClass, number> }>();
   constructor(private readonly config: () => ActionPolicyConfig | undefined, private readonly currentSession: (peer: string) => string | undefined) {}
   bindSession(peer: string, session: string): ActionSessionBudget | undefined {
     if (!session || this.currentSession(peer) !== session) return undefined;
     const previous = this.sessions.get(peer);
     if (previous?.handle.session === session) return previous.handle;
     const handle = Object.freeze({ peer, session });
-    this.sessions.set(peer, { handle, policy: "", remaining: empty() });
+    this.sessions.set(peer, { handle, policy: "", remaining: empty(), grants: empty() });
     return handle;
   }
   revoke(peer: string): void { this.sessions.delete(peer); }
   policyChanged(): void {
-    for (const state of this.sessions.values()) { state.policy = ""; state.remaining = empty(); }
+    for (const state of this.sessions.values()) { state.policy = ""; state.remaining = empty(); state.grants = empty(); }
     this.challenges = new WeakMap();
   }
   private current(handle: ActionSessionBudget | undefined): Session | undefined {
@@ -56,7 +56,7 @@ export class ActionBudgets {
     const state = this.sessions.get(handle.peer);
     if (state?.handle !== handle || this.currentSession(handle.peer) !== handle.session) return undefined;
     const policy = JSON.stringify(actionPolicyConfig(this.config()));
-    if (state.policy !== policy) { state.policy = policy; state.remaining = empty(); }
+    if (state.policy !== policy) { state.policy = policy; state.remaining = empty(); state.grants = empty(); }
     return state;
   }
   private selected(actions: readonly ActionClass[]): ActionClass[] {
@@ -70,37 +70,60 @@ export class ActionBudgets {
     if (!state) return { kind: "ask", classes };
     if (classes.some(key => state.remaining[key] <= 0)) {
       const challenge = Object.freeze({ classes: Object.freeze([...classes]) });
-      this.challenges.set(challenge, { handle: state.handle, policy: state.policy, classes: [...classes] });
+      this.challenges.set(challenge, { handle: state.handle, policy: state.policy, classes: [...classes], grants: { ...state.grants } });
       return { kind: "ask", classes, challenge };
     }
     for (const key of classes) state.remaining[key]--;
     return { kind: "budget", classes };
   }
-  /** Explicit class-budget approval only, never an ordinary allow_once; this invocation consumes slot one. */
+  /**
+   * Explicit class-budget approval only, never an ordinary allow_once; this invocation consumes slot one. Requests run concurrently, so
+   * two challenges can be issued while a class is spent: the first approval opens the allowance (budget minus this call), and an approval of
+   * a challenge issued before it is a later call inside that allowance, which consumes one slot instead of opening another. With no slot
+   * left it is refused (the person asks again and sees a fresh challenge), so N approved calls is the most any budget lets through.
+   * Every class is checked before any is spent: a refusal changes nothing.
+   */
   approve(challenge: ActionChallenge | undefined): boolean {
     if (!challenge) return false;
     const grant = this.challenges.get(challenge); this.challenges.delete(challenge);
     if (!grant) return false;
     const state = this.current(grant.handle), config = actionPolicyConfig(this.config());
     if (!state || state.policy !== grant.policy) return false;
-    for (const key of grant.classes) state.remaining[key] = Math.max(0, config.budgets[key] - 1);
+    const late = (key: ActionClass) => state.grants[key] !== grant.grants[key];
+    if (grant.classes.some(key => late(key) && state.remaining[key] <= 0)) return false;
+    for (const key of grant.classes) {
+      state.remaining[key] = late(key) ? state.remaining[key] - 1 : Math.max(0, config.budgets[key] - 1);
+      state.grants[key]++;
+    }
     return true;
   }
   /** Read-only projection: no session is created, rebound or reset by a status poll. */
-  status(peer: string, enforced: boolean) {
+  status(peer: string, enforced: boolean, reason = "adapter integration pending") {
     const config = actionPolicyConfig(this.config()), state = this.sessions.get(peer);
     const bound = !!state && this.currentSession(peer) === state.handle.session && state.policy === JSON.stringify(config);
+    const weakened = !config.enabled || ACTION_CLASSES.some(key => !config.always_ask.includes(key) || config.budgets[key] > DEFAULT_BUDGETS[key]);
+    const attention = weakened ? "; attention: machine-local policy weakens defaults; no retained startup confirmation" : "";
     return { enabled: config.enabled, alwaysAsk: [...config.always_ask], limits: { ...config.budgets }, remaining: bound ? { ...state.remaining } : empty(), sessionBound: bound,
-      enforceable: enforced, note: !enforced ? `always-ask not enforceable: adapter integration pending${config.enabled ? "" : "; policy disabled"}` : config.enabled ? "always-ask active" : "always-ask disabled" };
+      enforceable: enforced, note: (!enforced ? `always-ask not enforceable: ${reason}${config.enabled ? "" : "; policy disabled"}` : config.enabled ? "always-ask active" : "always-ask disabled") + attention };
   }
 }
 
-/** Adapter integrations must pass the host's publicView and current command/private-turn screens. */
-export function actionApprovalText<T>(classes: readonly ActionClass[], command: string, task: T | undefined,
-  ports: { publicView(task: T): Record<string, unknown>; private: boolean; commandView(command: string): string | undefined }): string {
+type ActionApprovalPorts<T> = { publicView(task: T): Record<string, unknown>; private: boolean; commandView(command: string): string | undefined };
+
+/** Public/native presentation: incomplete command views grant no approval, not even once. */
+export function actionApprovalView<T>(classes: readonly ActionClass[], command: string, task: T | undefined,
+  ports: ActionApprovalPorts<T>): { title: string; complete: boolean } {
   const view = task === undefined ? undefined : ports.publicView(task);
   const title = typeof view?.title === "string" ? sanitize(view.title).replace(/[\p{Cc}\p{Cf}]/gu, " ").slice(0, 160) : undefined;
   const shown = ports.private ? undefined : ports.commandView(command);
-  const line = shown === undefined ? "[private command withheld]" : sanitize(shown).replace(/[\p{Cc}\p{Cf}]/gu, " ").slice(0, 512);
-  return `Action approval (${ACTION_CLASSES.filter(key => classes.includes(key)).join(", ")})${title ? `; task ${title}` : ""}: ${line}`;
+  const full = shown === undefined ? undefined : Array.from(sanitize(shown).replace(/[\p{Cc}\p{Cf}]/gu, " "));
+  const marker = ` [cut, ${full?.length ?? 0} chars]`;
+  const line = full === undefined ? "[private command withheld]" : full.length > 512 ? full.slice(0, 512 - marker.length).join("") + marker : full.join("");
+  return { title: `Action approval (${ACTION_CLASSES.filter(key => classes.includes(key)).join(", ")})${title ? `; task ${title}` : ""}: ${line}`,
+    complete: shown === command && full !== undefined && full.length <= 512 && full.join("") === command };
+}
+
+/** Adapter integrations must pass the host's publicView and current command/private-turn screens. */
+export function actionApprovalText<T>(classes: readonly ActionClass[], command: string, task: T | undefined, ports: ActionApprovalPorts<T>): string {
+  return actionApprovalView(classes, command, task, ports).title;
 }

package/src/hub/ask.ts

@@ -104,7 +104,7 @@ export async function gather(question: string, d: AskDeps): Promise<{ evidence:
     return { id: `task #${t.id}`, kind: "task", text: `[${t.class}] ${t.state}, owner ${t.owner ?? "none"}, reviewer ${t.reviewer ?? "none"}: ${text}`.slice(0, ITEM_CHARS) };
   });
 
-  // A question that carries PII is not sent to the memory worker, whose observer is a cloud model.
+  // A PII question never queries the shared memory view; local storage does not relax the hub privacy fence.
   const memoryRows = d.memory && !piiQuestion ? related(d.memory, d.project, question, 2).catch(() => []) : Promise.resolve([]);
   // The log carries message bodies and is written by agents too: a line with PII in it is treated like a PII task row.
   const matching = thisRunsLog(d.logFile).filter((l) => hit(l) > 0).slice(-12);
@@ -119,12 +119,24 @@ export async function gather(question: string, d: AskDeps): Promise<{ evidence:
   try { native = piiQuestion ? [] : (d.native?.(keys) ?? []).map((r) => ({ id: r.id, kind: "memory" as const, text: r.text.slice(0, ITEM_CHARS) })); } catch { /* fail-open */ }
   const memory: Evidence[] = (await memoryRows)
     .filter((r) => !r.title.startsWith(ASK_NOTE_TITLE))
-    .map((r) => ({ id: `#${r.id}`, kind: "memory" as const, text: `${r.time} ${r.type} ${r.title}`.slice(0, ITEM_CHARS) }));
+    .map((r) => ({ id: typeof r.id === "string" ? r.id : `#${r.id}`, kind: "memory" as const, text: `${r.time} ${r.type} ${r.title}`.slice(0, ITEM_CHARS) }));
 
+  // Native briefs keep short ids; the client supplies full ids for the same rows. Resolve only a unique
+  // prefix before dedupe/budget accounting. An ambiguous short id stays separate: it identifies neither full row.
+  const fullMemoryIds = new Map<string, Set<string>>();
+  for (const row of [...native, ...memory]) if (/^mem:[0-9a-f]{32}$/.test(row.id)) {
+    const prefix = row.id.slice(0, 12), ids = fullMemoryIds.get(prefix) ?? new Set<string>();
+    ids.add(row.id); fullMemoryIds.set(prefix, ids);
+  }
+  const memoryId = (row: Evidence): string => {
+    const full = row.kind === "memory" && /^mem:[0-9a-f]{8}$/.test(row.id) ? fullMemoryIds.get(row.id) : undefined;
+    return full?.size === 1 ? full.values().next().value! : row.id;
+  };
   // Every item is capped, so one long row cannot empty the list; what does not fit is skipped, not everything after it.
   const evidence: Evidence[] = [];
   let size = 0;
-  for (const e of [...taskRows, ...native, ...memory, ...logRows]) {
+  for (const row of [...taskRows, ...native, ...memory, ...logRows]) {
+    const e = { ...row, id: memoryId(row) };
     if (evidence.some((x) => x.id === e.id)) continue;
     if (size + e.text.length + e.id.length > EVIDENCE_CHARS) continue;
     size += e.text.length + e.id.length;
@@ -133,7 +145,7 @@ export async function gather(question: string, d: AskDeps): Promise<{ evidence:
   return { evidence, pii: piiQuestion || piiShown, onCampus: campus };
 }
 
-const ID = /^(task #\d+|#\d+|mem:[0-9a-f]{8}|log \d\d-\d\d \d\d:\d\d:\d\d\.\d{3})$/;
+const ID = /^(task #\d+|#\d+|mem:(?:[0-9a-f]{8}|[0-9a-f]{32})|log \d\d-\d\d \d\d:\d\d:\d\d\.\d{3})$/;
 
 /** Every id the answer cites, grouped brackets included: `[#1, #2, task #3]`. */
 export function citedIds(answer: string): string[] {