@staix/agent-hub 0.12.45 → 0.13.0

package/src/cli/output.ts

@@ -5,6 +5,7 @@ import { cells, TABLES, table, fitLine, wrap, duration, relative, plural, termin
 import { taskProgress } from "../ui/task-progress.ts";
 import { backendLabel } from "./status-lines.ts";
 import { formatReport, formatTaskReport, type Report, type TaskReport } from "../hub/report.ts";
+import type { Counter, LimitsResult, TotalResult, UsageResult } from "../hub/usage-rollup.ts";
 
 export interface DoctorCheck { section: "Tools" | "Hub" | "Config" | "Models" | "Memory"; level: "ok" | "warn" | "fail" | "unknown"; name: string; detail: string }
 export interface StatusOutput {
@@ -17,7 +18,7 @@ export interface StatusOutput {
   isolatedChecks?: { pending?: number; orphans?: string[]; unknownReceipts?: readonly string[]; maintenanceUnavailable?: boolean };
   memoryProfile?: { profile?: string; generation?: string; state?: string; agentMemVersion?: string; skippedRows?: number; error?: string };
   taskWip?: Record<string, { wip: number; wipLimit: number }>;
-  pid?: number; controlPort?: number; cwd?: string; version?: string; peers: Record<string, any>; roleInfo?: Record<string, any>; budget?: Record<string, any>; planner?: { peers?: string[]; source?: string };
+  pid?: number; controlPort?: number; cwd?: string; version?: string; peers: Record<string, any>; roleInfo?: Record<string, any>; actionPolicyInfo?: Record<string, { note: string; enforceable: boolean }>; budget?: Record<string, any>; planner?: { peers?: string[]; source?: string };
   tasks?: Record<string, number>; models?: { backends?: any[] }; permissionDefaults?: any[]; deliveryError?: string; crash?: string[];
 }
 export interface BudgetOutput { budget: Record<string, any>; gate?: number }
@@ -245,9 +246,12 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
     }
     if (p.toolsOnly) out.push(...detail(definitionOf(id)?.attach?.pullOnlyForms?.includes("tui") && p.pullOnly ? "pull-only" : "tools-only", flat(p.toolsOnly).replace(/^(?:tools-only|pull-only):\s*/, ""), columns, "attention"));
     if (p.pullOnly && definitionOf(id)?.attach?.pullOnlyForms?.includes("tui")) out.push(...detail(`${id} last read`, typeof p.lastInboxAt === "number" ? relative(p.lastInboxAt, now) : "never", columns, "muted"));
+    const actionPolicy = data.actionPolicyInfo?.[id];
+    if (actionPolicy?.note) out.push(...detail(`${id} action policy`, actionPolicy.note, columns, actionPolicy.enforceable ? "muted" : "attention"));
     if (p.permissionNote) out.push(...detail("permission", p.permissionNote, columns, "muted"));
     if (typeof p.statusNotice?.message === "string" && p.statusNotice.message) out.push(...detail("status notice", p.statusNotice.message, columns, "attention"));
     if (p.requestedModel && p.servedBy && p.requestedModel !== p.servedBy) out.push(...detail("requested model", p.requestedModel, columns));
+    if (typeof p.modelSource === "string" && p.modelSource) out.push(...detail("model source", flat(p.modelSource), columns, "muted")); // an extra Jcode instance (#685): names only, never a URL or token
     if (typeof p.importantWaitingSince === "number" && p.importantWaitingNote) out.push(...detail("important waiting", `${p.importantWaitingNote.replace(/^\d+ important messages? waiting/, "important messages waiting")}`, columns, "attention"));
     if (typeof p.oldestQueuedAt === "number") out.push(...detail(`${id} oldest queued`, relative(p.oldestQueuedAt, now), columns, "muted"));
     return out;
@@ -431,3 +435,42 @@ export function renderReport(report: Report | TaskReport, columns?: number, now
   }
   return out;
 }
+
+// ---- ahub usage (#683 U2): every number names its source; an unknown number prints `unknown`, never 0 ----------------------------------------------
+const SOURCE_NAME: Record<Counter["source"], string> = { native: "native", count: "hub count", manual: "manual", partial: "partial, at least", unknown: "unknown" };
+/** `1234 (native)`, `1234 (hub count)`, or `unknown`: a missing counter is never shown as zero. */
+export const usageNumber = (c: Counter): string => c.value === null ? "unknown" : `${c.value} (${SOURCE_NAME[c.source]})`;
+const usageCell = (c: Counter): OutputCell => c.value === null ? span("unknown", "muted") : span(usageNumber(c), "number");
+
+export function renderUsage(result: UsageResult, columns?: number): Span[][] {
+  const out = lines(`usage by ${result.by}: ${result.coverage.records} records, ${result.coverage.withUsage} with provider counters, ${result.coverage.withoutUsage} without`, columns, "muted");
+  const header = ["KEY", "TOTAL", "WITHOUT CACHE", "CACHE READ", "INPUT", "OUTPUT", "REASONING", "HUB COUNT"];
+  const row = (r: UsageResult["rows"][number]) => [span(r.pii ? `${r.key} [pii]` : r.key), usageCell(r.total), usageCell(r.totalWithoutCache), usageCell(r.cacheRead), usageCell(r.input), usageCell(r.output), usageCell(r.reasoning), usageCell(r.counted)];
+  const all = [...result.rows, ...(result.unattributed ? [result.unattributed] : [])];
+  if (!all.length) return [...out, ...lines("no usage recorded in this period", columns)];
+  return [...out, [], ...rows(header, all.map(row), columns, undefined, true),
+    ...lines("TOTAL is the provider's own total, cache reads included; WITHOUT CACHE removes them. HUB COUNT is what the hub counted itself and covers peers that report no usage record. unknown is never zero.", columns, "muted")];
+}
+
+export function renderLimits(result: LimitsResult, current: unknown, columns?: number): Span[][] {
+  const out = lines(`limit history: ${result.truncated ? `the newest ${result.shown} of ${result.total}` : `${result.total}`} events, ${result.open.length} open pause${result.open.length === 1 ? "" : "s"}`, columns, "muted");
+  if (result.truncated) out.push(...lines(`${result.omitted} older events are not shown: use --limit <n> (up to ${result.maxLimit}) for more`, columns, "attention"));
+  for (const o of result.open) out.push(...lines(`open pause: ${o.peer} ${o.window} since ${o.since}, resets ${new Date(o.resetsAt).toISOString()}`, columns, "attention"));
+  for (const o of result.endedUnknown) out.push(...lines(`pause ended, end unknown: ${o.peer} ${o.window} since ${o.since} (the hub no longer holds it, for example after ahub reset; no resume was recorded)`, columns, "muted"));
+  const windows = current && typeof current === "object" ? Object.entries(current as Record<string, { windows?: { id: string; used: number; resetsAt?: number }[] }>) : [];
+  const live = windows.flatMap(([peer, b]) => (b?.windows ?? []).map(w => [span(peer), span(w.id), span(`${Math.round(w.used * 100)}%`, "number"), span(w.resetsAt ? new Date(w.resetsAt).toISOString() : "unknown", w.resetsAt ? undefined : "muted")]));
+  if (live.length) out.push([], ...lines("current windows", columns, "strong"), ...rows(["PEER", "WINDOW", "USED", "RESETS"], live, columns, undefined, true));
+  const hist = result.history.map(h => [span(h.at), span(h.type.replace("budget_", "").replace("quota_reset", "reset")), span(h.peer), span(h.window), span(Object.entries(h.detail).map(([k, v]) => `${k} ${v}`).join(", "), "muted")]);
+  if (hist.length) out.push([], ...lines("history", columns, "strong"), ...rows(["AT", "EVENT", "PEER", "WINDOW", "DETAIL"], hist, columns, undefined, true));
+  return out;
+}
+
+export function renderTotal(result: TotalResult, columns?: number): Span[][] {
+  const out = lines(`lifetime development tokens since ${result.since ?? "the first event"}`, columns, "muted");
+  const table = result.peers.map(p => [span(p.peer), usageCell(p.tokens), usageCell(p.withoutCache), usageCell(p.cacheRead)]);
+  table.push([span("ALL PEERS", "strong"), usageCell(result.overall.tokens), usageCell(result.overall.withoutCache), usageCell(result.overall.cacheRead)]);
+  const left = (label: string, peers: string[]) => peers.length ? lines(`${label} leaves out ${peers.join(", ")} (unknown, not counted as 0): a lower bound`, columns, "attention") : [];
+  return [...out, [], ...rows(["PEER", "TOTAL", "WITHOUT CACHE", "CACHE READ"], table, columns, undefined, true),
+    ...left("ALL PEERS TOTAL", result.overall.tokens.source === "partial" ? result.unknownPeers.tokens : []), ...left("ALL PEERS CACHE READ", result.overall.cacheRead.source === "partial" ? result.unknownPeers.cacheRead : []),
+    ...lines("A peer with no provider counters (for example jcode, kimi) shows the hub's own count where one exists, otherwise unknown. The overall WITHOUT CACHE is unknown unless every peer's cache split is known.", columns, "muted")];
+}

package/src/cli/preview.ts

@@ -21,7 +21,7 @@ export function launcherPreview(tool: "claude" | "codex" | "kimi" | "pi" | "qwen
     if (mode >= 0 && args[mode + 1] !== "headless") throw new Error("extra instances require headless mode");
     if (mode < 0 && !args.includes("--headless")) args.push("--mode", "headless");
   }
-  const result = preview({ tool, args, cwd, stateDir, cliDir: import.meta.dir, unattended, config, definition,
+  const result = preview({ tool, args, cwd, stateDir, cliDir: import.meta.dir, unattended, config, definition, ...(selected.instance ? { instance: selected.instance } : {}),
     baseEnvNames: Object.keys(childEnv()).concat(["AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR"]),
     helpers: { buildLaunch: (native, argv, ctx) => buildLaunch(native, argv, { ...ctx, ...(selected.instance ? { instance: selected.instance } : {}) }), claudeObservationHooks, buildKimiLaunch, buildKimiTuiLaunch, nativeLaunchEnv, childEnv,
       startModeOf, kimiMcpPlan, jcodeCommand, jcodeTuiCommand, qwenSessionId, relayModelIds, buildPiLaunch },

package/src/cli/sdlc-release-guard.ts

@@ -0,0 +1,82 @@
+/** Literal release targets only. Parsing never executes a command or reads the repository. */
+export type ReleaseGuardRequest =
+  | { kind: "tag-push"; version: string; tag: string; sourceRef: string; remote: string }
+  | { kind: "gh-release"; version: string; tag: string; target?: string }
+  | { kind: "npm-publish" };
+export interface ReleasePushUpdate { localRef: string; localOid: string; remoteRef: string; remoteOid: string; version: string; }
+type Refusal = { ok: false; reason: string };
+export type ReleaseGuardParse = { ok: true; request: ReleaseGuardRequest } | Refusal;
+export type ReleasePushParse = { ok: true; remoteName: string; remoteUrl: string; updates: ReleasePushUpdate[]; stdin: string } | Refusal;
+const refuse = (): Refusal => ({ ok: false, reason: "release target is ambiguous, unsupported or invalid" });
+const SEMVER = /^(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?(?:[+][0-9A-Za-z.-]+)?$/;
+const oid = (value: string) => /^[0-9a-f]{40}$/.test(value);
+const zero = (value: string) => /^0{40}$/.test(value);
+const literal = (value: string) => value.length > 0 && value.length <= 4096 && !/[\s\0-\x1f\x7f$`*?\\]/.test(value);
+const ref = (value: string) => literal(value) && !value.startsWith("-") && !value.includes("..") && !value.includes("@{") && !value.includes("//") && !value.endsWith("/") && !value.endsWith(".") && !value.endsWith(".lock") && !"~^:[]()".split("").some(char => value.includes(char));
+const versionOf = (tag: string): string | undefined => tag.startsWith("v") && SEMVER.test(tag.slice(1)) ? tag.slice(1) : undefined;
+
+// Hook values are opaque Git data, not shell source. Unicode and shell-looking
+// characters are valid in refs; only Git's forbidden ref syntax is rejected.
+const hookText = (value: string) => value.length > 0 && value.length <= 4096 && !/[\p{Cc}]/u.test(value);
+const hookRef = (value: string) => hookText(value) && !/[\0-\x20\x7f]/.test(value) && !"~^:?*[\\".split("").some(char => value.includes(char)) && !value.includes("..") && !value.includes("@{") && !value.includes("//") && !value.endsWith("/") && !value.endsWith(".") && !value.split("/").some(part => !part || part.startsWith(".") || part.endsWith(".lock"));
+
+export function parseReleaseGuardArgv(argv: readonly string[]): ReleaseGuardParse {
+  if (!Array.isArray(argv) || !argv.length || argv.length > 128 || !argv.every(word => typeof word === "string" && word.length <= 4096 && !/[\0-\x1f\x7f]/.test(word)) || Buffer.byteLength(argv.join("\0")) > 16 * 1024) return refuse();
+  const [program, ...args] = argv;
+  if (program === "git" && args[0] === "push") {
+    if (args.length !== 3 || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(args[1] ?? "")) return refuse();
+    const spec = args[2]!, parts = spec.split(":");
+    if (parts.length > 2 || spec.startsWith("+")) return refuse();
+    const destination = parts.length === 2 ? parts[1]! : parts[0]!;
+    const tag = destination.startsWith("refs/tags/") ? destination.slice(10) : destination;
+    const version = versionOf(tag), sourceRef = parts[0]!;
+    if (!version || !ref(sourceRef) || parts.length === 2 && !destination.startsWith("refs/tags/")) return refuse();
+    return { ok: true, request: { kind: "tag-push", version, tag, sourceRef, remote: args[1]! } };
+  }
+  if (program === "gh" && args[0] === "release" && args[1] === "create") {
+    const tag = args[2] ?? "", version = versionOf(tag);
+    if (!version) return refuse();
+    let target: string | undefined;
+    const valued = new Set(["--title", "-t", "--notes", "-n", "--notes-file", "-F", "--notes-start-tag", "--target"]);
+    const flags = new Set(["--verify-tag", "--generate-notes", "--draft", "-d", "--prerelease", "-p", "--fail-on-no-commits"]);
+    for (let i = 3; i < args.length; i++) {
+      const flag = args[i]!;
+      if (flags.has(flag)) continue;
+      if (!valued.has(flag) || args[i + 1] === undefined) return refuse();
+      const value = args[++i]!;
+      if (flag === "--target") { if (target !== undefined || !ref(value)) return refuse(); target = value; }
+    }
+    return { ok: true, request: { kind: "gh-release", version, tag, ...(target === undefined ? {} : { target }) } };
+  }
+  if (program === "npm" && args[0] === "publish") {
+    const flags = new Set(["--provenance", "--ignore-scripts", "--dry-run"]);
+    for (let i = 1; i < args.length; i++) {
+      if (flags.has(args[i]!)) continue;
+      if (args[i] === "--access" && ["public", "restricted"].includes(args[i + 1] ?? "")) { i++; continue; }
+      if (args[i] === "--tag" && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(args[i + 1] ?? "")) { i++; continue; }
+      return refuse();
+    }
+    return { ok: true, request: { kind: "npm-publish" } };
+  }
+  return refuse();
+}
+
+/** Validate every hook row before selecting version-tag updates. Preserve the exact original input. */
+export function parseReleasePushUpdates(remoteName: string, remoteUrl: string, stdin: string): ReleasePushParse {
+  if (typeof remoteName !== "string" || typeof remoteUrl !== "string" || typeof stdin !== "string" || !hookText(remoteName) || !hookText(remoteUrl) || Buffer.byteLength(stdin) > 128 * 1024) return refuse();
+  const lines = stdin.endsWith("\n") ? stdin.slice(0, -1).split("\n") : stdin.split("\n");
+  if (stdin === "") lines.length = 0;
+  if (lines.length > 128) return refuse();
+  const updates: ReleasePushUpdate[] = [];
+  for (const line of lines) {
+    const fields = line.split(" ");
+    if (fields.length !== 4) return refuse();
+    const [localRef, localOid, remoteRef, remoteOid] = fields as [string, string, string, string];
+    if ((!hookRef(localRef) && localRef !== "(delete)") || !hookRef(remoteRef) || !remoteRef.startsWith("refs/") || !oid(localOid) || !oid(remoteOid)) return refuse();
+    if (!remoteRef.startsWith("refs/tags/v")) continue;
+    const version = versionOf(remoteRef.slice(10));
+    if (!version || zero(localOid) || localRef === "(delete)") return refuse();
+    updates.push({ localRef, localOid, remoteRef, remoteOid, version });
+  }
+  return { ok: true, remoteName, remoteUrl, updates, stdin };
+}

package/src/hub/action-class.ts

@@ -0,0 +1,362 @@
+import { basename, isAbsolute, relative, resolve } from "node:path";
+
+export const ACTION_CLASSES = ["publish", "external-write", "destroy", "install"] as const;
+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[] };
+
+/** Bound the whole input before accepting any prefix, including unsupported suffixes. */
+function segmentLimit(text: string): boolean {
+  let quote = "", count = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]!;
+    if (c === "\\" && quote !== "'") { i++; continue; }
+    if (quote) { if (quote === c) quote = ""; continue; }
+    if (c === "'" || c === '"') { quote = c; continue; }
+    if (c === "#" && (i === 0 || /[ \t\r\n;]/.test(text[i - 1]!))) {
+      while (i < text.length && text[i] !== "\n") i++;
+    }
+    if (i < text.length && ";|&\n".includes(text[i]!)) {
+      // FD duplication is an operator, not another command.
+      if (text[i] === "&" && [">", "<"].includes(text[i - 1] ?? "")) continue;
+      if (++count > 64) return false;
+      if ((c === "|" || c === "&") && text[i + 1] === c) i++;
+    }
+  }
+  return true;
+}
+
+/** Literal shell words only; unsupported syntax discards only its unfinished segment. */
+function commands(text: string): Command[] | undefined {
+  if (text.length > LIMIT || text.includes("\0") || !segmentLimit(text)) return;
+  const result: Command[] = [];
+  let words: string[] = [], outputs: string[] = [], word = "", active = false, quote = "";
+  let redirect: false | "overwrite" | "skip" = false;
+  const flush = () => {
+    if (!active) return;
+    if (redirect === "overwrite") outputs.push(word);
+    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 = []; };
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]!;
+    if (quote === "'") { if (c === "'") quote = ""; else word += c; continue; }
+    if (c === "\\") {
+      const next = text[++i];
+      if (next === undefined) return result;
+      if (quote === '"' && !['$', '`', '"', "\\", "\n"].includes(next)) word += "\\";
+      if (next !== "\n") word += next;
+      active = true; continue;
+    }
+    if (c === "$" || c === "`") return result;
+    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; }
+    if ("(){}".includes(c)) {
+      if (redirect && !active) return result;
+      finish(); continue;
+    }
+    if (c === ">" || c === "<") {
+      if (redirect && !active) return result;
+      if (redirect) flush();
+      if (c === "<" && text[i + 1] === "<") return result;
+      if (active && /^\d+$/.test(word)) { word = ""; active = false; } else flush();
+      if (text[i + 1] === "&") {
+        const duplicate = text.slice(i + 2).match(/^(?:\d+|-)(?=$|[ \t\r\n;|&(){}<>])/);
+        if (!duplicate) return result;
+        i += 1 + duplicate[0].length; continue;
+      }
+      redirect = c === "<" || text[i + 1] === ">" ? "skip" : "overwrite";
+      if (text[i + 1] === ">" || text[i + 1] === "|") i++;
+      continue;
+    }
+    if (/[ \t\r]/.test(c)) { flush(); continue; }
+    if (";|&\n".includes(c)) {
+      if (redirect && !active) return result;
+      finish();
+      if (text[i + 1] === c && (c === "|" || c === "&")) i++;
+      continue;
+    }
+    word += c; active = true;
+    if (words.length + outputs.length > 256) return result;
+  }
+  if (quote || (redirect && !active)) return result;
+  finish();
+  return result;
+}
+
+function object(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+function outside(target: string, root: string, cwd: string): boolean {
+  if (!isAbsolute(root) || !target || /[$`]/.test(target)) return false;
+  if (target.startsWith("~") || !cwd && !isAbsolute(target)) return true;
+  const rel = relative(resolve(root), resolve(cwd, target));
+  return rel === ".." || rel.startsWith("../") || isAbsolute(rel);
+}
+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));
+}
+function operands(words: string[]): string[] {
+  const end = words.indexOf("--");
+  return end < 0 ? words.filter(w => !w.startsWith("-")) : [...words.slice(0, end).filter(w => !w.startsWith("-")), ...words.slice(end + 1)];
+}
+function option(words: string[], short: string, long: string): string | undefined {
+  for (let i = 0; i < words.length; i++) {
+    const w = words[i]!;
+    if (w === "--") break;
+    if (w === short || w === long) return words[i + 1];
+    if (w.startsWith(`${long}=`)) return w.slice(long.length + 1);
+    if (w.startsWith(short) && w.length > short.length) return w.slice(short.length);
+  }
+  return;
+}
+/** Known option values are opaque. Unknown prefix options retain every plausible action head. */
+function commandHeads(words: string[], values: readonly string[], booleans: readonly string[], actions: readonly string[]): Array<{ name: string; args: string[] }> {
+  const heads: Array<{ name: string; args: string[] }> = [];
+  let uncertain = false, literal = false;
+  for (let i = 0; i < words.length; i++) {
+    const word = words[i]!;
+    if (!literal && word === "--") { literal = true; continue; }
+    if (!literal && word.startsWith("-")) {
+      if (!uncertain && ["--help", "--version", "-h", "-V"].includes(word)) return [];
+      if (values.includes(word)) { if (!uncertain) i++; continue; }
+      if (values.some(key => key.startsWith("--") ? word.startsWith(`${key}=`) : word.startsWith(key) && word.length > key.length)) continue;
+      if (!booleans.includes(word)) uncertain = true;
+      continue;
+    }
+    if (!uncertain) return [{ name: word, args: words.slice(i + 1) }];
+    if (actions.includes(word)) heads.push({ name: word, args: words.slice(i + 1) });
+  }
+  return heads;
+}
+
+/** Exclude patterns and path operands cannot impersonate clean's force/dry-run options. */
+function forcedClean(words: string[]): boolean {
+  let force = false, dry = false;
+  for (let i = 0; i < words.length; i++) {
+    const word = words[i]!;
+    if (word === "--") break;
+    if (word === "--exclude") { i++; continue; }
+    if (word.startsWith("--exclude=")) continue;
+    if (word === "--force") force = true;
+    else if (word === "--dry-run") dry = true;
+    else if (/^-[^-]/.test(word)) {
+      for (let at = 1; at < word.length; at++) {
+        const flag = word[at]!;
+        if (flag === "e") { if (at === word.length - 1) i++; break; }
+        if (flag === "f") force = true;
+        if (flag === "n") dry = true;
+      }
+    }
+  }
+  return force && !dry;
+}
+
+/** Peel only known transparent argv wrappers; no aliases or executable discovery. */
+function unwrapped(input: string[]): string[] {
+  const words = [...input];
+  for (let step = 0; step < 32; step++) {
+    while (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0] ?? "")) words.shift();
+    const name = basename(words[0] ?? "");
+    if (["!", "if", "then", "elif", "else"].includes(name)) { words.shift(); continue; }
+    if (["fi", "do", "done"].includes(name)) return [];
+    if (!["sudo", "time", "timeout", "nohup", "exec", "xargs", "nice", "env", "command"].includes(name)) return words;
+    words.shift();
+    const values: Record<string, string[]> = {
+      sudo: ["-u", "-g", "-h", "-p", "-C", "-T", "--user", "--group", "--host", "--prompt"],
+      time: ["-f", "-o", "--format", "--output"],
+      timeout: ["-s", "-k", "--signal", "--kill-after"],
+      exec: ["-a"], xargs: ["-n", "-P", "-I", "-L", "-s", "-E", "-d", "--max-args", "--max-procs", "--replace", "--delimiter"],
+      nice: ["-n", "--adjustment"], env: ["-u", "--unset"],
+    };
+    while (words[0]?.startsWith("-")) {
+      const flag = words.shift()!;
+      if (flag === "--") break;
+      if (name === "command" && (flag === "-v" || flag === "-V")) return [];
+      if ((values[name] ?? []).includes(flag)) { if (!words.length) return []; words.shift(); }
+      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 [];
+    }
+  }
+  return [];
+}
+
+/** Scan curl options once: data, headers and other option values never become options. */
+function curlWrites(input: string[]): boolean {
+  const longValues = new Set([
+    "request", "data", "data-ascii", "data-binary", "data-raw", "data-urlencode", "json", "form", "form-string", "upload-file",
+    "url-query", "header", "proxy-header", "output", "output-dir", "user-agent", "user", "proxy-user", "cookie", "cookie-jar", "referer", "url",
+    "resolve", "connect-to", "config", "cacert", "capath", "cert", "cert-type", "key", "key-type", "pass", "proxy", "preproxy",
+    "interface", "max-time", "connect-timeout", "limit-rate", "range", "request-target", "unix-socket", "abstract-unix-socket",
+    "write-out", "trace", "trace-ascii", "dump-header", "stderr", "netrc-file", "ftp-method", "ftp-port", "oauth2-bearer",
+    "proxy-cacert", "proxy-cert", "proxy-key", "socks5", "socks5-hostname", "retry", "retry-delay", "retry-max-time", "local-port",
+  ]);
+  let method: string | undefined, data = false, upload = false, get = false, head = false, uncertain = false, writeMethod = false;
+  const booleanOptions = new Set(["get", "head", "compressed", "location", "insecure", "silent", "show-error", "fail", "fail-with-body", "globoff", "verbose", "include", "remote-name", "path-as-is", "create-dirs", "progress-meter", "progress-bar", "http1.1", "http2", "http3"]);
+  // An unknown option may consume a following read-looking token. It cannot erase known write evidence.
+  const writes = () => uncertain && (data || upload || writeMethod) || (method !== undefined ? !["GET", "HEAD"].includes(method.toUpperCase()) : !head && (upload || data && !get));
+  for (let i = 0; i < input.length; i++) {
+    const arg = input[i]!;
+    if (arg === "--") break;
+    if (arg === "--next" || arg === "-:") {
+      if (writes()) return true;
+      method = undefined; data = upload = get = head = uncertain = writeMethod = false;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      const equal = arg.indexOf("=");
+      const name = arg.slice(2, equal < 0 ? undefined : equal);
+      if (name === "get" || name === "no-get") get = name === "get";
+      else if (name === "head" || name === "no-head") head = name === "head";
+      if (!longValues.has(name)) { if (!booleanOptions.has(name.replace(/^no-/, ""))) uncertain = true; continue; }
+      const value = equal < 0 ? input[++i] : arg.slice(equal + 1);
+      if (value === undefined) continue;
+      if (name === "request") { method = value; writeMethod ||= !["GET", "HEAD"].includes(value.toUpperCase()); }
+      else if (name === "upload-file") upload = true;
+      else if (name === "json" || name.startsWith("data") || name === "form" || name === "form-string") data = true;
+      continue;
+    }
+    if (!/^-[^-]/.test(arg)) continue;
+    for (let at = 1; at < arg.length; at++) {
+      const flag = arg[at]!;
+      if (flag === "G") get = true;
+      if (flag === "I") head = true;
+      // These short options consume the rest of this word, or the next whole word.
+      if (!"XdFTHoAuUbecrxEKPmCwDQztYy".includes(flag)) continue;
+      const value = arg.slice(at + 1) || input[++i];
+      if (value !== undefined) {
+        if (flag === "X") { method = value; writeMethod ||= !["GET", "HEAD"].includes(value.toUpperCase()); }
+        else if (flag === "d" || flag === "F") data = true;
+        else if (flag === "T") upload = true;
+      }
+      break;
+    }
+  }
+  return writes();
+}
+
+function sequence(parsed: Command[], root: string, initial: string[], found: Set<ActionClass>, depth = 0): void {
+  const cwd = new Set(initial);
+  for (const command of parsed) {
+    classify(command, root, [...cwd], found, depth);
+    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 (!cwd.has("") && cwd.size >= 128) cwd.delete(cwd.values().next().value!);
+      cwd.add("");
+    }
+    else if (program === "cd" && target && !target.startsWith("-") && !"$`*?[]".split("").some(c => target.includes(c))) {
+      for (const current of [...cwd]) {
+        if (cwd.size >= 128) break;
+        cwd.add(current || isAbsolute(target) ? resolve(current, target) : "");
+      }
+    }
+  }
+}
+function classify(command: Command, root: string, cwd: string[], found: Set<ActionClass>, depth = 0): void {
+  const words = unwrapped(command.words);
+  const program = basename(words.shift() ?? "");
+  if (["sh", "bash", "zsh"].includes(program) && depth < 2) {
+    const shell = [...words];
+    while (["--noprofile", "--norc"].includes(shell[0] ?? "")) shell.shift();
+    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]);
+      if (nested) sequence(nested, root, cwd, found, depth + 1);
+    }
+  }
+  if (command.outputs.some(p => cwd.some(at => outside(p, root, at)))) found.add("destroy");
+  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"]);
+    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 === "clean" && forcedClean(args)) found.add("destroy");
+      if (sub === "branch" && (flags(args, "D") || args.includes("--delete") && args.includes("--force"))) found.add("destroy");
+    }
+  }
+  if (["npm", "cargo", "pnpm", "yarn", "bun"].includes(program)) {
+    const valuesByProgram: Record<string, string[]> = {
+      npm: ["--registry", "--prefix", "-C", "--cache", "--userconfig", "--globalconfig", "--loglevel", "--workspace", "-w"],
+      pnpm: ["--registry", "--dir", "-C", "--filter", "-F", "--store-dir", "--reporter", "--loglevel"],
+      yarn: ["--registry", "--cwd", "--cache-folder", "--mutex", "--use-yarnrc", "--modules-folder", "--network-concurrency", "--network-timeout"],
+      cargo: ["--color", "--config", "--manifest-path", "--target-dir"],
+      bun: ["--registry", "--cwd", "-C", "--filter", "-F", "--env-file", "--config", "-c", "--cache-dir"],
+    };
+    const values = valuesByProgram[program]!;
+    const booleans = ["--global", "-g", "--offline", "--locked", "--frozen", "--silent", "--quiet", "-q", "--verbose", "-v"];
+    const actions = ["publish", "install", "i", "add", "global", "npm"];
+    const heads = commandHeads(words, values, booleans, actions);
+    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 (sub === "publish") found.add("publish");
+        const global = words.includes("--global") || flags(words, "g");
+        if ((program === "cargo" && sub === "install") || (["install", "i", "add"].includes(sub) && global) || (program === "yarn" && sub === "global" && args[0] === "add")) found.add("install");
+      }
+    }
+  }
+  if (program === "pipx" && words[0] === "install" || program === "brew" && ["install", "reinstall"].includes(words[0] ?? "") || ["pip", "pip3"].includes(program) && words[0] === "install" && words.includes("--user")) found.add("install");
+  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") {
+      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 (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"))) {
+    const target = option(words, "-t", "--target-directory") ?? operands(words).at(-1);
+    if (target && cwd.some(at => outside(target, root, at))) found.add("destroy");
+  }
+}
+
+/** Adds information only; an empty result always retains the native permission policy.
+ * ponytail: literal bounded shell/argv forms only; aliases, functions, expansion,
+ * interpreter programs and symlink targets need a richer observed contract.
+ * Home targets are conservatively outside without resolving a personal home.
+ * Unsupported segments retain only preceding complete commands.
+ * Literal cd retains both success/failure cwd candidates (at most 128); it may
+ * overclassify a later relative write and is not a shell control-flow proof.
+ */
+export function classifyAction(tool: string, args: unknown, executionRoot: string): ActionClass[] {
+  if (typeof tool !== "string" || tool.length > 128 || typeof executionRoot !== "string" || executionRoot.length > LIMIT) return [];
+  if (typeof args === "string") {
+    if (args.length > LIMIT) return [];
+    try { args = JSON.parse(args) as unknown; } catch { args = { command: args }; }
+  }
+  const input = object(args);
+  if (!input) return [];
+  const found = new Set<ActionClass>();
+  if (["http", "http_request", "fetch"].includes(tool.toLowerCase()) && typeof input.method === "string" && /^[A-Za-z]+$/.test(input.method) && !["GET", "HEAD"].includes(input.method.toUpperCase())) found.add("external-write");
+  const boundedArgv = (value: unknown): value is string[] => Array.isArray(value) && value.length <= 256 && value.every(w => typeof w === "string" && w.length <= LIMIT) && value.join("").length <= LIMIT;
+  const location = input.cwd ?? input.workdir;
+  const cwd = typeof location === "string" && location.startsWith("~") ? "" : typeof location === "string" && location.length <= LIMIT && !/[$`]/.test(location) ? resolve(executionRoot, location) : executionRoot;
+  if (tool.toLowerCase() === "git" && boundedArgv(input.args)) classify({ words: ["git", ...input.args], outputs: [] }, executionRoot, [cwd], found);
+  if (SHELL_TOOLS.has(tool.toLowerCase())) {
+    const raw = input.command ?? input.cmd;
+    if (typeof raw === "string") {
+      const parsed = commands(raw);
+      if (parsed) sequence(parsed, executionRoot, [cwd], found);
+    } else if (boundedArgv(raw)) {
+      classify({ words: raw, outputs: [] }, executionRoot, [cwd], found);
+    }
+  }
+  return ACTION_CLASSES.filter(value => found.has(value));
+}