@hasna/hooks 0.11.6 → 0.12.0

package/hooks/hook-signed-link-guard/src/classify.ts

@@ -0,0 +1,1280 @@
+/**
+ * Command classification for the signed-link guard.
+ *
+ * THE CLASS. Composite GitHub content — pull request, issue, release and
+ * discussion bodies, comments, reviews, commit messages and check-run details —
+ * carries third-party signed action links: URLs with a signature parameter, a
+ * multi-week expiry and no revoke path. A tool result is persisted in the agent
+ * transcript, so a printed link is an exposed capability. This module decides,
+ * before a shell command runs, whether any `gh` invocation in it would print
+ * such content, so the harness can refuse it with SIGNED_LINK_REFUSAL.
+ *
+ * Command position is honoured through the existing parser (`lexCommand`,
+ * `commandWordIndex` from hook-trash-guard): only a `gh` word in command
+ * position — after assignments, keywords and wrappers such as `env`, `sudo`,
+ * `timeout`, `command`, `exec` — is a `gh` invocation. `echo gh pr view` is
+ * text, and so is `node x.js gh pr view`. The classifier also follows the
+ * places a command can hide:
+ *   - pipelines, `&&`, `||`, `;`, newlines, subshells and `{ …; }` groups;
+ *   - `$( … )` and backtick substitutions, including inside double quotes and
+ *     unquoted here-documents (here-document bodies inside `$( )` are data);
+ *   - `sh|bash|zsh|… -c <string>` (also when the string is built from a
+ *     `$(cat <<EOF …)` or `$(echo …)` substitution), `eval`, `env -S`,
+ *     `su|runuser|script|flock -c`, `ssh <host> <command>` and `watch`;
+ *   - text a shell reads as its script: here-documents and here-strings fed to
+ *     a shell, `echo … | bash`, `cat <<EOF | sh`, `source <(…)`, `. /dev/stdin`;
+ *   - `xargs … gh …` (a read whose arguments come from stdin fails closed) and
+ *     `find … -exec gh … ;`;
+ *   - known runners that pass a bare `gh` word on (`secrets exec … -- gh`,
+ *     `op run -- gh`, `unbuffer gh`, …) and a command word built by expansion
+ *     whose name cannot be read (`$GH pr view …`).
+ *
+ * `GH_DEBUG` (and gh's legacy `DEBUG`) makes gh log HTTP traffic, response
+ * bodies included, whatever `--jq` or `--silent` print. Under it only reads
+ * that FETCH nothing composite pass.
+ *
+ * Anything the classifier cannot read with confidence inside a `gh` read of
+ * those objects (an expanded endpoint, field list or query, an unknown `gh`
+ * command that may be an alias, an unterminated command) fails closed.
+ */
+
+import { commandWordIndex, envSplitCommandText, heredocMarkerAt, lexCommand, scanParenAt, skipHeredocBodies, type Word } from "../../hook-trash-guard/src/hook";
+import { jqProjectionIsScalar } from "./jq";
+
+/** The exact refusal reason, fixed by the engineering decision for this class. */
+export const SIGNED_LINK_REFUSAL =
+  "composite output withheld: signed-link shape; use bounded scalar projections per class disposition 799310";
+
+export type SignedLinkRule =
+  | "view-human"
+  | "view-comments"
+  | "json-composite"
+  | "checks-human"
+  | "checks-json"
+  | "api-rest"
+  | "api-graphql"
+  | "composite-other"
+  | "debug-traffic"
+  | "unclassifiable";
+
+export type SignedLinkVerdict = { refused: false } | { refused: true; rule: SignedLinkRule };
+
+const ALLOW: SignedLinkVerdict = { refused: false };
+const refused = (rule: SignedLinkRule): SignedLinkVerdict => ({ refused: true, rule });
+
+/* ------------------------------------------------------------------ */
+/* JSON field classes                                                  */
+/* ------------------------------------------------------------------ */
+
+/**
+ * `--json` fields that are safe to print, per command family. Everything else
+ * — every current composite field and any field a future gh adds — is refused
+ * unless a `--jq` projection provably prints only bounded scalars.
+ *
+ * Admitted: numbers, booleans, timestamps, enums, refs and object ids; identity
+ * objects (login, name, id); the object's own title; the object's own canonical
+ * GitHub URL (generated by GitHub from owner, repository and number, with no
+ * query string, so it cannot carry a signature parameter); file paths (the same
+ * information `gh pr diff` prints); reaction counts; and labels (a label
+ * description is a repository setting capped at 100 characters, too short for
+ * the signed-link shape).
+ *
+ * Refused, with the reason:
+ *   body                        free text authored by users and apps
+ *   comments, reviews,          comment and review bodies
+ *   latestReviews
+ *   statusCheckRollup           check details URLs, target URLs and descriptions
+ *   commits                     commit messages (autofix commits are app-authored)
+ *   autoMergeRequest            commit headline and body text
+ *   closingIssuesReferences,    other objects' titles and URLs
+ *   closedByPullRequestsReferences, blockedBy, blocking, parent, subIssues
+ *   milestone, projectCards,    free-text descriptions and titles with no length cap
+ *   projectItems, issueType, category
+ *   assets                      uploader-authored labels and names
+ */
+const PR_FIELDS = new Set([
+  "additions", "assignees", "author", "baseRefName", "baseRefOid", "changedFiles", "closed", "closedAt",
+  "createdAt", "deletions", "files", "fullDatabaseId", "headRefName", "headRefOid", "headRepository",
+  "headRepositoryOwner", "id", "isCrossRepository", "isDraft", "labels", "maintainerCanModify", "mergeCommit",
+  "mergeStateStatus", "mergeable", "mergedAt", "mergedBy", "number", "potentialMergeCommit", "reactionGroups",
+  "reviewDecision", "reviewRequests", "state", "title", "updatedAt", "url",
+]);
+const ISSUE_FIELDS = new Set([
+  "assignees", "author", "closed", "closedAt", "createdAt", "id", "isPinned", "labels", "number",
+  "reactionGroups", "state", "stateReason", "subIssuesSummary", "title", "updatedAt", "url",
+]);
+const RELEASE_FIELDS = new Set([
+  "apiUrl", "author", "createdAt", "databaseId", "id", "isDraft", "isImmutable", "isLatest", "isPrerelease", "name",
+  "publishedAt", "tagName", "tarballUrl", "targetCommitish", "uploadUrl", "url", "zipballUrl",
+]);
+const DISCUSSION_FIELDS = new Set([
+  "answerChosenAt", "answerChosenBy", "answered", "author", "closed", "closedAt", "createdAt", "id", "labels",
+  "locked", "number", "reactionGroups", "state", "stateReason", "title", "updatedAt", "url",
+]);
+const SEARCH_ISSUE_FIELDS = new Set([
+  "assignees", "author", "authorAssociation", "closedAt", "commentsCount", "createdAt", "id", "isDraft", "isLocked",
+  "isPullRequest", "labels", "number", "repository", "state", "title", "updatedAt", "url",
+]);
+const SEARCH_COMMIT_FIELDS = new Set(["author", "committer", "id", "parents", "repository", "sha", "url"]);
+/** `link` and `description` are app-authored and carry the signed link itself. */
+const CHECK_FIELDS = new Set(["bucket", "completedAt", "event", "name", "startedAt", "state", "workflow"]);
+
+/* ------------------------------------------------------------------ */
+/* Shell words                                                         */
+/* ------------------------------------------------------------------ */
+
+export interface ShellWord {
+  /** The word after quote removal. Expansions are kept as written. */
+  value: string;
+  /** True when the value depends on an expansion (`$x`, `$( )`, backticks, globs, brace lists). */
+  opaque: boolean;
+  /** Raw source text. */
+  raw: string;
+}
+
+/**
+ * An unquoted brace list (`{a,b}`) or sequence (`{1..3}`), which the shell
+ * expands into several words. One linear pass over the raw word.
+ */
+function hasBraceExpansion(raw: string): boolean {
+  const open: Array<{ list: boolean }> = [];
+  for (let i = 0; i < raw.length; i++) {
+    const c = raw[i];
+    if (c === "\\") { i++; continue; }
+    if (c === "'") { const end = raw.indexOf("'", i + 1); if (end < 0) return false; i = end; continue; }
+    if (c === '"') {
+      i++;
+      while (i < raw.length && raw[i] !== '"') i += raw[i] === "\\" ? 2 : 1;
+      continue;
+    }
+    if (c === "{") { open.push({ list: false }); continue; }
+    if (open.length === 0) continue;
+    if (c === "," || (c === "." && raw[i + 1] === ".")) open[open.length - 1].list = true;
+    else if (c === "}" && open.pop()!.list) return true;
+  }
+  return false;
+}
+
+/**
+ * Decode one shell word the way the shell would for its literal parts.
+ * Single quotes are literal; double quotes keep `$`, backticks and `\`-escapes
+ * of `$ \` " \\` and newline only; an unquoted backslash escapes any character.
+ */
+export function shellWord(raw: string): ShellWord {
+  let value = "";
+  let opaque = false;
+  let i = 0;
+  const expansionAt = (at: number) => raw[at] === "`" || (raw[at] === "$" && /[A-Za-z_{(@*#?$!0-9-]/.test(raw[at + 1] ?? ""));
+  while (i < raw.length) {
+    const ch = raw[i];
+    if (ch === "\\") { value += raw[i + 1] ?? ""; i += 2; continue; }
+    if (ch === "$" && raw[i + 1] === "'") { opaque = true; value += ch; i++; continue; }
+    if (ch === "'") {
+      const end = raw.indexOf("'", i + 1);
+      if (end < 0) { opaque = true; value += raw.slice(i + 1); break; }
+      value += raw.slice(i + 1, end);
+      i = end + 1;
+      continue;
+    }
+    if (ch === '"') {
+      i++;
+      while (i < raw.length && raw[i] !== '"') {
+        if (raw[i] === "\\" && /[$`"\\\n]/.test(raw[i + 1] ?? "")) { value += raw[i + 1]; i += 2; continue; }
+        if (expansionAt(i)) opaque = true;
+        value += raw[i];
+        i++;
+      }
+      if (i >= raw.length) opaque = true;
+      i++;
+      continue;
+    }
+    if (expansionAt(i) || ch === "*" || ch === "?" || ch === "[") opaque = true;
+    value += ch;
+    i++;
+  }
+  if (!opaque && raw.includes("{") && hasBraceExpansion(raw)) opaque = true;
+  return { value, opaque, raw };
+}
+
+const base = (value: string) => value.slice(value.lastIndexOf("/") + 1);
+
+/**
+ * Bodies of every command substitution in `text` — `$( … )` and backticks.
+ * In `word` mode (shell source) single quotes hide substitutions and double
+ * quotes do not; in `heredoc` mode (an unquoted here-document body) quotes are
+ * plain characters. `complete` is false when a substitution does not end.
+ */
+export function substitutions(text: string, mode: "word" | "heredoc" = "word"): { bodies: string[]; complete: boolean } {
+  const bodies: string[] = [];
+  let inDouble = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "\\") { i++; continue; }
+    if (mode === "word" && ch === "'" && !inDouble) {
+      const end = text.indexOf("'", i + 1);
+      if (end < 0) return { bodies, complete: false };
+      i = end;
+      continue;
+    }
+    if (mode === "word" && ch === '"') { inDouble = !inDouble; continue; }
+    if (ch === "`") {
+      let j = i + 1;
+      while (j < text.length && text[j] !== "`") j += text[j] === "\\" ? 2 : 1;
+      if (j >= text.length) return { bodies, complete: false };
+      bodies.push(text.slice(i + 1, j));
+      i = j;
+      continue;
+    }
+    if (ch === "$" && text[i + 1] === "(") {
+      const end = scanParenAt(text, i + 1);
+      if (end < 0) return { bodies, complete: false };
+      bodies.push(text.slice(i + 2, end - 1));
+      i = end - 1;
+    }
+  }
+  return { bodies, complete: true };
+}
+
+/* ------------------------------------------------------------------ */
+/* Flag parsing (pflag-compatible, per command)                        */
+/* ------------------------------------------------------------------ */
+
+interface FlagSpec {
+  /** Flags that take a value, long (`--json`) and short (`-q`) spellings. */
+  values: string[];
+}
+
+interface Flag { name: string; value?: ShellWord; missing?: boolean; inline?: boolean }
+
+interface ParsedFlags {
+  /** Every flag occurrence in order, with its value when it takes one. */
+  flags: Flag[];
+  positionals: ShellWord[];
+}
+
+/**
+ * Parse arguments the way gh's flag library does: `--name=value`, `--name
+ * value`, `-x value`, `-xvalue`, `-x=value`, boolean clusters (`-cw`) and
+ * `--` ending options. Unknown flags are booleans; gh refuses them before
+ * printing data. A boolean given inline (`--web=false`) keeps its value.
+ */
+function parseFlags(args: ShellWord[], spec: FlagSpec): ParsedFlags {
+  const takesValue = new Set(spec.values);
+  const out: ParsedFlags = { flags: [], positionals: [] };
+  const inlineValue = (text: string, word: ShellWord): ShellWord => ({ value: text, opaque: word.opaque, raw: word.raw });
+  for (let i = 0; i < args.length; i++) {
+    const word = args[i];
+    const text = word.value;
+    if (text === "--") { out.positionals.push(...args.slice(i + 1)); break; }
+    if (text.startsWith("--") && text.length > 2) {
+      const eq = text.indexOf("=");
+      const name = eq >= 0 ? text.slice(0, eq) : text;
+      if (eq >= 0) out.flags.push({ name, value: inlineValue(text.slice(eq + 1), word), inline: true });
+      else if (takesValue.has(name)) {
+        const value = args[i + 1];
+        out.flags.push(value ? { name, value } : { name, missing: true });
+        i++;
+      } else out.flags.push({ name });
+      continue;
+    }
+    if (text.startsWith("-") && text.length > 1) {
+      for (let at = 1; at < text.length; at++) {
+        const name = "-" + text[at];
+        const rest = text.slice(at + 1);
+        if (rest.startsWith("=")) {
+          out.flags.push({ name, value: inlineValue(rest.slice(1), word), inline: true });
+          break;
+        }
+        if (!takesValue.has(name)) { out.flags.push({ name }); continue; }
+        if (rest) out.flags.push({ name, value: inlineValue(rest, word), inline: true });
+        else {
+          const value = args[i + 1];
+          out.flags.push(value ? { name, value } : { name, missing: true });
+          i++;
+        }
+        break;
+      }
+      continue;
+    }
+    out.positionals.push(word);
+  }
+  return out;
+}
+
+/**
+ * Whether a boolean flag ends up set: its last occurrence wins, `--web` and
+ * `--web=true` set it, `--web=false` (and pflag's other false spellings)
+ * clear it. A value that cannot be read (an expansion) counts as not set, so
+ * it never unlocks an allow shortcut.
+ */
+function flagOn(parsed: ParsedFlags, ...names: string[]): boolean {
+  let on = false;
+  for (const flag of parsed.flags) {
+    if (!names.includes(flag.name)) continue;
+    if (!flag.inline) { on = true; continue; }
+    const value = flag.value!;
+    on = !value.opaque && ["1", "t", "T", "TRUE", "true", "True"].includes(value.value);
+  }
+  return on;
+}
+
+const valuesOf = (parsed: ParsedFlags, ...names: string[]) => parsed.flags.filter((flag) => names.includes(flag.name));
+
+const COMMON_VALUES = ["-R", "--repo", "-q", "--jq", "-t", "--template", "--json"];
+const SPECS: Record<string, FlagSpec> = {
+  "pr view": { values: COMMON_VALUES },
+  "issue view": { values: COMMON_VALUES },
+  "release view": { values: COMMON_VALUES },
+  "discussion view": { values: [...COMMON_VALUES, "--after", "-L", "--limit", "--order"] },
+  "pr list": { values: [...COMMON_VALUES, "--app", "-a", "--assignee", "-A", "--author", "-B", "--base", "-H", "--head", "-l", "--label", "-L", "--limit", "-S", "--search", "-s", "--state"] },
+  "issue list": { values: [...COMMON_VALUES, "--app", "-a", "--assignee", "-A", "--author", "-l", "--label", "-L", "--limit", "--mention", "-m", "--milestone", "-S", "--search", "-s", "--state"] },
+  "discussion list": { values: [...COMMON_VALUES, "--after", "-A", "--author", "-c", "--category", "-l", "--label", "-L", "--limit", "--order", "-S", "--search", "--sort", "-s", "--state"] },
+  "release list": { values: [...COMMON_VALUES, "-L", "--limit", "-O", "--order"] },
+  "pr status": { values: COMMON_VALUES },
+  "issue status": { values: COMMON_VALUES },
+  "pr checks": { values: [...COMMON_VALUES, "-i", "--interval"] },
+  "pr diff": { values: ["-R", "--repo"] },
+  search: { values: [...COMMON_VALUES, "--app", "--assignee", "--author", "--author-date", "--author-email", "--author-name", "--base", "--checks", "--closed", "--commenter", "--committer", "--committer-date", "--committer-email", "--committer-name", "--created", "--hash", "--head", "--interactions", "--involves", "--label", "--language", "--limit", "-L", "--match", "--mentions", "--merged-at", "--milestone", "--no-assignee", "--no-label", "--no-milestone", "--no-project", "--order", "--owner", "--parent", "--project", "--reactions", "--review", "--review-requested", "--reviewed-by", "--sort", "--state", "--team-mentions", "--tree", "--updated", "--visibility", "--extension", "--filename", "--size", "--forks", "--good-first-issue", "--help-wanted-issues", "--number-topics", "--stars", "--topic", "--followers", "--include-forks", "--license"] },
+  "project item-list": { values: ["--format", "-L", "--limit", "--owner", "-q", "--jq", "-t", "--template", "--query", "--field", "--field-id"] },
+  api: { values: ["-X", "--method", "-H", "--header", "-f", "--raw-field", "-F", "--field", "-q", "--jq", "-t", "--template", "-p", "--preview", "--input", "--hostname", "--cache"] },
+  group: { values: ["-R", "--repo"] },
+};
+
+/* ------------------------------------------------------------------ */
+/* gh classification                                                   */
+/* ------------------------------------------------------------------ */
+
+interface Context {
+  depth: number;
+  /** `xargs` without a replacement string appends stdin words to the command. */
+  appendsArgs: boolean;
+  /** `GH_DEBUG` (or gh's legacy `DEBUG`) is set: gh logs HTTP traffic, bodies included. */
+  debug: boolean;
+}
+
+/** Top-level gh commands (2.98) that never print the composite objects of this class. */
+const SAFE_TOP = new Set([
+  "auth", "browse", "codespace", "cs", "gist", "org", "repo", "skill", "cache", "run", "workflow", "co",
+  "agent-task", "alias", "attestation", "completion", "config", "copilot", "extension", "ext", "extensions",
+  "gpg-key", "label", "licenses", "preview", "ruleset", "secret", "ssh-key", "variable", "help", "version",
+  "accessibility", "actions", "environment", "exit-codes", "formatting", "mintty", "reference", "telemetry",
+]);
+/** gh commands that read the objects of this class; an unreadable read of one fails closed. */
+const READ_TOP = new Set(["pr", "issue", "release", "discussion", "search", "project", "api", "status"]);
+const PR_WRITES = new Set(["create", "new", "checkout", "co", "close", "comment", "edit", "lock", "merge", "ready", "reopen", "revert", "review", "unlock", "update-branch"]);
+const ISSUE_WRITES = new Set(["create", "new", "close", "comment", "delete", "develop", "edit", "lock", "pin", "reopen", "transfer", "unlock", "unpin"]);
+const RELEASE_WRITES = new Set(["create", "new", "delete", "delete-asset", "download", "edit", "upload", "verify", "verify-asset"]);
+const DISCUSSION_WRITES = new Set(["create", "new", "close", "comment", "delete", "edit", "lock", "reopen", "unlock", "answer", "unanswer"]);
+
+function jsonFields(parsed: ParsedFlags, ctx: Context): { present: boolean; opaque: boolean; fields: string[] } {
+  const occurrences = valuesOf(parsed, "--json");
+  const fields: string[] = [];
+  let opaque = false;
+  for (const occurrence of occurrences) {
+    if (occurrence.missing) { if (ctx.appendsArgs) opaque = true; continue; }
+    if (!occurrence.value) continue;
+    if (occurrence.value.opaque) opaque = true;
+    fields.push(...occurrence.value.value.split(",").map((field) => field.trim()).filter(Boolean));
+  }
+  return { present: occurrences.length > 0, opaque, fields };
+}
+
+/** A `--jq` projection that provably prints only bounded scalars, with nothing else printed beside it. */
+function jqRescues(parsed: ParsedFlags, rootScalars?: ReadonlySet<string>): boolean {
+  if (flagOn(parsed, "--verbose") || valuesOf(parsed, "-t", "--template").length > 0) return false;
+  const jq = valuesOf(parsed, "-q", "--jq");
+  return jq.length > 0 && jq.every((flag) => flag.value !== undefined && !flag.value.opaque && jqProjectionIsScalar(flag.value.value, { rootScalars }));
+}
+
+/**
+ * The `--json` field set decides; a composite field is admitted only when a
+ * `--jq` projection provably prints bounded scalars. Under GH_DEBUG the
+ * projection does not help (gh logs the whole response), so only an
+ * allowlisted field set passes.
+ */
+function checkFields(parsed: ParsedFlags, allowed: ReadonlySet<string>, ctx: Context, rule: SignedLinkRule): SignedLinkVerdict {
+  const json = jsonFields(parsed, ctx);
+  if (json.opaque) return refused("unclassifiable");
+  if (json.fields.every((field) => allowed.has(field))) return ALLOW;
+  if (ctx.debug) return refused("debug-traffic");
+  return jqRescues(parsed) ? ALLOW : refused(rule);
+}
+
+/** `view` commands: the human view prints the body; `--comments` prints comments. */
+function classifyView(args: ShellWord[], spec: string, fields: ReadonlySet<string>, ctx: Context, commentsFlag: boolean): SignedLinkVerdict {
+  const parsed = parseFlags(args, SPECS[spec]);
+  if (flagOn(parsed, "-h", "--help")) return ALLOW;
+  if (flagOn(parsed, "-w", "--web")) return ctx.debug ? refused("debug-traffic") : ALLOW;
+  if (commentsFlag && flagOn(parsed, "-c", "--comments")) return refused("view-comments");
+  if (!jsonFields(parsed, ctx).present) return refused(ctx.debug ? "debug-traffic" : "view-human");
+  return checkFields(parsed, fields, ctx, "json-composite");
+}
+
+/** `list`/`status`/`search` commands: the table prints no bodies; `--json` is checked. */
+function classifyList(args: ShellWord[], spec: string, fields: ReadonlySet<string>, ctx: Context): SignedLinkVerdict {
+  const parsed = parseFlags(args, SPECS[spec]);
+  if (flagOn(parsed, "-h", "--help")) return ALLOW;
+  if (ctx.debug && (flagOn(parsed, "-w", "--web") || !jsonFields(parsed, ctx).present)) return refused("debug-traffic");
+  if (flagOn(parsed, "-w", "--web")) return ALLOW;
+  return checkFields(parsed, fields, ctx, "json-composite");
+}
+
+/**
+ * `gh pr checks`: the table prints check links. With `--json` only scalar
+ * fields pass. gh's checks query always fetches `detailsUrl`, so under
+ * GH_DEBUG every form is refused.
+ */
+function classifyChecks(args: ShellWord[], ctx: Context): SignedLinkVerdict {
+  const parsed = parseFlags(args, SPECS["pr checks"]);
+  if (flagOn(parsed, "-h", "--help")) return ALLOW;
+  if (ctx.debug) return refused("debug-traffic");
+  if (flagOn(parsed, "-w", "--web")) return ALLOW;
+  if (!jsonFields(parsed, ctx).present) return refused("checks-human");
+  return checkFields(parsed, CHECK_FIELDS, ctx, "checks-json");
+}
+
+/** Split a gh group invocation into its subcommand and the remaining words. */
+function subcommand(args: ShellWord[]): { sub?: ShellWord; rest: ShellWord[] } {
+  const takesValue = new Set(SPECS.group.values);
+  for (let i = 0; i < args.length; i++) {
+    const text = args[i].value;
+    if (text === "--") return { sub: args[i + 1], rest: args.slice(i + 2) };
+    if (!text.startsWith("-") || text === "-") return { sub: args[i], rest: [...args.slice(0, i), ...args.slice(i + 1)] };
+    if (takesValue.has(text)) i++;
+  }
+  return { rest: args };
+}
+
+function classifyGroup(group: string, args: ShellWord[], ctx: Context): SignedLinkVerdict {
+  const { sub, rest } = subcommand(args);
+  // `xargs gh pr` supplies the subcommand (and its flags) from stdin.
+  if (!sub) return ctx.appendsArgs ? refused("unclassifiable") : ALLOW;
+  if (sub.opaque) return refused("unclassifiable");
+  const name = sub.value;
+  const writes = group === "pr" ? PR_WRITES : group === "issue" ? ISSUE_WRITES : group === "release" ? RELEASE_WRITES : group === "discussion" ? DISCUSSION_WRITES : new Set<string>();
+  if (writes.has(name)) {
+    // A write prints no composite content, but gh fetches the object first;
+    // under GH_DEBUG that fetch is logged.
+    return ctx.debug ? refused("debug-traffic") : ALLOW;
+  }
+  // A read whose arguments are appended from stdin can gain `--json body`,
+  // `--comments` or `--patch`: it cannot be classified.
+  if (ctx.appendsArgs && !(group === "project" && name !== "item-list")) return refused("unclassifiable");
+  switch (group) {
+    case "pr":
+      if (name === "view") return classifyView(rest, "pr view", PR_FIELDS, ctx, true);
+      if (name === "list" || name === "ls") return classifyList(rest, "pr list", PR_FIELDS, ctx);
+      if (name === "status") return classifyList(rest, "pr status", PR_FIELDS, ctx);
+      if (name === "checks") return classifyChecks(rest, ctx);
+      if (name === "diff") {
+        // `--patch` prints each commit's full message, the same content as the refused `commits` field.
+        const parsed = parseFlags(rest, SPECS["pr diff"]);
+        if (flagOn(parsed, "-h", "--help")) return ALLOW;
+        if (ctx.debug) return refused("debug-traffic");
+        return flagOn(parsed, "--patch") ? refused("composite-other") : ALLOW;
+      }
+      return refused("unclassifiable");
+    case "issue":
+      if (name === "view") return classifyView(rest, "issue view", ISSUE_FIELDS, ctx, true);
+      if (name === "list" || name === "ls") return classifyList(rest, "issue list", ISSUE_FIELDS, ctx);
+      if (name === "status") return classifyList(rest, "issue status", ISSUE_FIELDS, ctx);
+      return refused("unclassifiable");
+    case "release":
+      if (name === "view") return classifyView(rest, "release view", RELEASE_FIELDS, ctx, false);
+      if (name === "list" || name === "ls") return classifyList(rest, "release list", RELEASE_FIELDS, ctx);
+      return refused("unclassifiable");
+    case "discussion":
+      if (name === "view") return classifyView(rest, "discussion view", DISCUSSION_FIELDS, ctx, true);
+      if (name === "list" || name === "ls") return classifyList(rest, "discussion list", DISCUSSION_FIELDS, ctx);
+      return refused("unclassifiable");
+    case "search":
+      if (name === "prs" || name === "issues") return classifyList(rest, "search", SEARCH_ISSUE_FIELDS, ctx);
+      if (name === "commits") return classifyList(rest, "search", SEARCH_COMMIT_FIELDS, ctx);
+      if (name === "code" || name === "repos") return ctx.debug ? refused("debug-traffic") : ALLOW;
+      return refused("unclassifiable");
+    case "project": {
+      if (ctx.debug) return refused("debug-traffic");
+      if (name !== "item-list") return ALLOW;
+      // JSON items embed the underlying issue and pull request content.
+      const parsed = parseFlags(rest, SPECS["project item-list"]);
+      if (flagOn(parsed, "-h", "--help")) return ALLOW;
+      const format = valuesOf(parsed, "--format");
+      if (format.some((flag) => !flag.value || flag.value.opaque)) return refused("unclassifiable");
+      if (format.every((flag) => flag.value!.value !== "json")) return ALLOW;
+      return jqRescues(parsed) ? ALLOW : refused("composite-other");
+    }
+  }
+  return refused("unclassifiable");
+}
+
+/* ------------------------------------------------------------------ */
+/* gh api                                                              */
+/* ------------------------------------------------------------------ */
+
+/**
+ * REST families whose responses contain bodies, comments, reviews, commit
+ * messages, check runs and suites, statuses (target URLs and descriptions),
+ * events, deployment payloads or issue and pull request objects. Matched on
+ * the path after `repos/<owner>/<repo>` (or `repositories/<id>`).
+ */
+const REPO_FAMILIES = new Set([
+  "pulls", "issues", "commits", "check-runs", "check-suites", "statuses", "comments", "releases",
+  "compare", "events", "discussions", "deployments", "milestones",
+]);
+
+/**
+ * `download`: the response is repository data (workflow logs, artifact and
+ * source archives) served through a redirect to a short-lived signed storage
+ * URL. gh follows the redirect without printing it, so the download passes;
+ * `--verbose` and GH_DEBUG print the redirect, so under them it is refused.
+ */
+export type EndpointClass = "sensitive" | "graphql" | "download" | "other" | "unclassifiable";
+
+export interface Endpoint {
+  kind: EndpointClass;
+  /** Normalized, lower-cased path segments (empty when unreadable). */
+  segments: string[];
+}
+
+/**
+ * Normalize a gh api endpoint the way the request reaches GitHub: strip the
+ * API origin (`https://api.github.com/`, GHES `/api/v3/`), the query and
+ * fragment, percent-decode each segment, drop empty and `.` segments and
+ * resolve `..`. Any other absolute URL (a github.com web page, a raw
+ * `.patch`) is not an API path and cannot be classified.
+ */
+function normalizeEndpoint(word: ShellWord): { segments: string[]; opaque: boolean[] } | null {
+  let path = word.value.trim();
+  const absolute = /^https?:\/\/([^/]+)(\/.*)?$/i.exec(path);
+  if (absolute) {
+    const host = absolute[1].toLowerCase();
+    const rest = absolute[2] ?? "/";
+    if (host === "api.github.com" || /^api\./.test(host)) path = rest;
+    else if (/^\/api\/v3(?:\/|$)/i.test(rest)) path = rest.replace(/^\/api\/v3/i, "");
+    else if (/^\/api\/graphql(?:[/?#]|$)/i.test(rest)) path = "graphql";
+    else return null;
+  }
+  path = path.replace(/[?#].*$/, "");
+  const out: string[] = [];
+  const opaque: boolean[] = [];
+  for (const piece of path.split("/")) {
+    let decoded: string;
+    try { decoded = decodeURIComponent(piece); } catch { return null; }
+    for (const segment of decoded.split("/")) {
+      if (segment === "" || segment === ".") continue;
+      if (segment === "..") { out.pop(); opaque.pop(); continue; }
+      out.push(segment.toLowerCase());
+      opaque.push(word.opaque && /[$`]/.test(segment) || /[*?[]/.test(segment) || hasBraceExpansion(segment));
+    }
+  }
+  return { segments: out, opaque };
+}
+
+/** Classify a gh api endpoint path. */
+export function classifyEndpoint(word: ShellWord): Endpoint {
+  const normalized = normalizeEndpoint(word);
+  if (!normalized) return { kind: "unclassifiable", segments: [] };
+  const { segments: s, opaque } = normalized;
+  const endpoint = (kind: EndpointClass): Endpoint => ({ kind, segments: s });
+  if (s.length === 1 && s[0] === "graphql") return endpoint("graphql");
+  if (s.length === 0) return endpoint(word.opaque ? "unclassifiable" : "other");
+  if (opaque[0]) return endpoint("unclassifiable");
+  let rest: string[] | undefined;
+  let restOpaque: boolean[] = [];
+  if (s[0] === "repos") { rest = s.slice(3); restOpaque = opaque.slice(3); }
+  else if (s[0] === "repositories") { rest = s.slice(2); restOpaque = opaque.slice(2); }
+  if (rest) {
+    const headOpaque = s[0] === "repos" ? opaque.slice(1, 3) : opaque.slice(1, 2);
+    if (headOpaque.some(Boolean)) {
+      // An expanded owner/repo may itself contain slashes: classify from the
+      // first literal family keyword after the expansion, or fail closed.
+      const first = opaque.findIndex(Boolean);
+      const at = s.findIndex((segment, index) => index > first && !opaque[index] && REPO_KEYWORDS.has(segment));
+      return endpoint(at < 0 ? "unclassifiable" : classifyRepoPath(s.slice(at), opaque.slice(at)));
+    }
+    return endpoint(classifyRepoPath(rest, restOpaque));
+  }
+  const top = s[0];
+  if (top === "issues") return endpoint("sensitive");
+  if (top === "user" && s[1] === "issues") return endpoint("sensitive");
+  if (top === "orgs" && s[2] === "issues") return endpoint("sensitive");
+  if (top === "search") return endpoint(s[1] === "issues" || s[1] === "commits" ? "sensitive" : s[1] !== undefined && opaque[1] ? "unclassifiable" : "other");
+  if (top === "events" || top === "networks") return endpoint("sensitive");
+  if ((top === "users" || top === "orgs") && s.slice(2).some((segment) => segment === "events" || segment === "received_events" || segment === "discussions")) return endpoint("sensitive");
+  if ((top === "users" || top === "orgs") && s[2] === "projectsv2" && s[4] === "items") return endpoint("sensitive");
+  if ((top === "orgs" && s[2] === "hooks" && s[4] === "deliveries" && s[5] !== undefined) || (top === "app" && s[1] === "hook" && s[2] === "deliveries" && s[3] !== undefined)) return endpoint("sensitive");
+  if (top === "teams" && s.includes("discussions")) return endpoint("sensitive");
+  if (top === "projects" && s.includes("cards")) return endpoint("sensitive");
+  if (opaque.some(Boolean)) return endpoint(s.some((segment) => segment === "events" || segment === "discussions" || segment === "issues") ? "sensitive" : "unclassifiable");
+  return endpoint("other");
+}
+
+/** Path words that start a repository sub-resource the guard classifies. */
+const REPO_KEYWORDS = new Set([...REPO_FAMILIES, "branches", "git", "actions", "hooks", "zipball", "tarball"]);
+
+/** Classify the path after `repos/<owner>/<repo>`. */
+function classifyRepoPath(rest: string[], restOpaque: boolean[]): EndpointClass {
+  const [family, second] = rest;
+  if (family === undefined) return "other";
+  if (restOpaque[0]) return "unclassifiable";
+  if (family === "issues" && /^\d+$/.test(second ?? "") && rest[2] === "labels") return "other";
+  if (REPO_FAMILIES.has(family)) return "sensitive";
+  if (family === "branches") {
+    // A single branch carries its head commit, message included; the list and
+    // protection and rename endpoints do not. Branch names may contain `/`.
+    if (rest.length === 1 || rest.slice(1).some((segment) => segment === "protection") || rest[rest.length - 1] === "rename") return "other";
+    return restOpaque.slice(1).some(Boolean) ? "unclassifiable" : "sensitive";
+  }
+  if (family === "git") return second === undefined || second === "commits" || second === "tags" ? "sensitive" : restOpaque[1] ? "unclassifiable" : "other";
+  if (family === "actions") {
+    if (second === undefined) return "sensitive";
+    if (restOpaque[1]) return "unclassifiable";
+    if (second === "runs" || second === "jobs") {
+      // Workflow logs are the repository's own step output, the same text
+      // `gh run view --log` prints; they are not the composite class.
+      if (rest[rest.length - 1] === "logs" && rest.length >= 4 && !restOpaque.some(Boolean)) return "download";
+      return "sensitive";
+    }
+    if (second === "workflows" && rest[3] === "runs") return "sensitive";
+    if (second === "artifacts" && rest.length === 4) return "download";
+    return "other";
+  }
+  if (family === "hooks" && rest[2] === "deliveries" && rest[3] !== undefined) return "sensitive";
+  if (family === "zipball" || family === "tarball") return "download";
+  return "other";
+}
+
+/**
+ * Writes whose documented response is empty or scalar-only (GitHub REST
+ * OpenAPI description 1.1.4): deleting a comment, reaction, release, run,
+ * deployment or milestone (204); re-running, cancelling or approving a run or
+ * job (201/202, empty body); merging a pull request (`sha`, `merged` and a
+ * GitHub status `message` such as "Pull Request successfully merged" — the
+ * merge commit message is request input, never echoed); updating a branch
+ * (`message`, `url`); locking an issue (204); and adding, setting or removing
+ * issue labels (the label list; label descriptions are capped at 100
+ * characters). Writes that echo the whole issue or pull request (PATCH of an
+ * issue, review or comment) stay refused unless `--silent` or a scalar `--jq`.
+ */
+function writeIsScalar(method: string, s: string[]): boolean {
+  if (s[0] !== "repos" || s.length < 5) return false;
+  const r = s.slice(3);
+  const num = (at: number) => /^\d+$/.test(r[at] ?? "");
+  const is = (...parts: Array<string | number>) => r.length === parts.length && parts.every((part, at) => typeof part === "number" ? num(at) : r[at] === part);
+  if (method === "DELETE") {
+    return is("issues", "comments", 0) || is("pulls", "comments", 0) || is("comments", 0)
+      || is("issues", "comments", 0, "reactions", 0) || is("pulls", "comments", 0, "reactions", 0) || is("issues", 0, "reactions", 0)
+      || is("issues", 0, "labels") || (r.length === 4 && r[0] === "issues" && num(1) && r[2] === "labels")
+      || is("releases", 0) || is("releases", "assets", 0) || is("actions", "runs", 0) || is("actions", "runs", 0, "logs")
+      || is("deployments", 0) || is("milestones", 0) || is("issues", 0, "lock");
+  }
+  if (method === "POST") {
+    return (r.length === 4 && r[0] === "actions" && r[1] === "runs" && num(2) && ["rerun", "rerun-failed-jobs", "cancel", "force-cancel", "approve"].includes(r[3]))
+      || is("actions", "jobs", 0, "rerun") || is("issues", 0, "labels");
+  }
+  if (method === "PUT") return is("pulls", 0, "merge") || is("pulls", 0, "update-branch") || is("issues", 0, "labels") || is("issues", 0, "lock");
+  if (method === "GET") return is("pulls", 0, "merge");
+  return false;
+}
+
+/** Top-level fields that are plain counts on a single pull request or issue object. */
+function rootScalarsFor(s: string[]): ReadonlySet<string> | undefined {
+  if (s[0] !== "repos" || s.length !== 5 || !/^\d+$/.test(s[4])) return undefined;
+  if (s[3] === "pulls") return new Set(["commits", "comments", "review_comments"]);
+  if (s[3] === "issues") return new Set(["comments"]);
+  return undefined;
+}
+
+/**
+ * GraphQL selections that carry free text or URLs: bodies, comments, reviews,
+ * commit messages and the auto-merge commit text, check and annotation text,
+ * deployment payloads, descriptions, notes and diffs, and every URL-valued
+ * field (`url`, `*Url`, `*URL`) and HTML rendering. A check run's or status
+ * context's `title` is app-authored too, so `title` is refused beneath one.
+ */
+const GRAPHQL_SENSITIVE = new Set([
+  "body", "bodyText", "bodyHTML", "bodyUrl", "bodyResourcePath", "comments", "reviews", "latestReviews",
+  "latestOpinionatedReviews", "reviewThreads", "url", "permalink", "summary", "text", "description", "message",
+  "messageBody", "messageHeadline", "commitBody", "commitHeadline", "annotations", "rawDetails", "note", "diff",
+  "readme", "payload",
+]);
+const CHECK_SCOPES = new Set([
+  "checkRuns", "checkRun", "checkSuites", "checkSuite", "contexts", "statusCheckRollup", "annotations",
+  "CheckRun", "CheckSuite", "StatusContext", "CheckAnnotation", "latestStatus", "status", "statuses",
+]);
+
+type GqlToken = { kind: "name" | "punct"; text: string };
+
+/** Tokenize a GraphQL document: strings, block strings and `#` comments are skipped in one left-to-right pass. */
+function graphqlTokens(query: string): GqlToken[] | null {
+  const out: GqlToken[] = [];
+  let i = 0;
+  while (i < query.length) {
+    const c = query[i];
+    if (/[\s,]/.test(c)) { i++; continue; }
+    if (c === "#") { const end = query.indexOf("\n", i); i = end < 0 ? query.length : end + 1; continue; }
+    if (query.startsWith('"""', i)) {
+      let j = i + 3;
+      for (;;) {
+        const end = query.indexOf('"""', j);
+        if (end < 0) return null;
+        if (query[end - 1] === "\\") { j = end + 3; continue; }
+        i = end + 3;
+        break;
+      }
+      continue;
+    }
+    if (c === '"') {
+      let j = i + 1;
+      while (j < query.length && query[j] !== '"' && query[j] !== "\n") j += query[j] === "\\" ? 2 : 1;
+      if (query[j] !== '"') return null;
+      i = j + 1;
+      continue;
+    }
+    const name = /^[_A-Za-z][_0-9A-Za-z]*/.exec(query.slice(i, i + 256));
+    if (name) { out.push({ kind: "name", text: name[0] }); i += name[0].length; continue; }
+    const number = /^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(query.slice(i, i + 64));
+    if (number) { i += number[0].length; continue; }
+    if (query.startsWith("...", i)) { out.push({ kind: "punct", text: "..." }); i += 3; continue; }
+    if ("{}()[]:!$@=|&".includes(c)) { out.push({ kind: "punct", text: c }); i++; continue; }
+    return null;
+  }
+  return out;
+}
+
+/**
+ * Whether a GraphQL document selects a sensitive field. Argument lists,
+ * variable definitions, strings and comments are not selections. The
+ * enclosing field names and type conditions are tracked so a check run's
+ * `title` is refused while a pull request's is not. An unreadable document
+ * counts as sensitive.
+ */
+export function graphqlIsSensitive(query: string): boolean {
+  const tokens = graphqlTokens(query);
+  if (!tokens) return true;
+  const scopes: string[] = [];
+  let lastOwner = "";
+  let parenDepth = 0;
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t.kind === "punct") {
+      if (t.text === "(") parenDepth++;
+      else if (t.text === ")") { parenDepth--; if (parenDepth < 0) return true; }
+      else if (parenDepth === 0 && t.text === "{") { scopes.push(lastOwner); lastOwner = ""; }
+      else if (parenDepth === 0 && t.text === "}") { if (scopes.pop() === undefined) return true; lastOwner = ""; }
+      continue;
+    }
+    if (parenDepth > 0) continue;
+    const prev = tokens[i - 1];
+    if (prev?.kind === "punct" && (prev.text === "@" || prev.text === "$")) continue;
+    if (tokens[i + 1]?.kind === "punct" && tokens[i + 1].text === ":") continue; // an alias
+    if (t.text === "on" && prev?.kind === "punct" && prev.text === "...") continue;
+    if (prev?.kind === "name" && prev.text === "on") { lastOwner = t.text; continue; } // a type condition
+    if (scopes.length === 0) { lastOwner = t.text; continue; } // operation or fragment header
+    if (GRAPHQL_SENSITIVE.has(t.text) || /(?:Url|URL|HTML|Html)$/.test(t.text)) return true;
+    if (t.text === "title" && scopes.some((scope) => CHECK_SCOPES.has(scope))) return true;
+    lastOwner = t.text;
+  }
+  return parenDepth !== 0 || scopes.length !== 0;
+}
+
+function classifyApi(args: ShellWord[], ctx: Context): SignedLinkVerdict {
+  const parsed = parseFlags(args, SPECS.api);
+  if (flagOn(parsed, "-h", "--help")) return ALLOW;
+  const endpointWord = parsed.positionals[0];
+  if (!endpointWord) return ctx.appendsArgs ? refused("unclassifiable") : ALLOW;
+  const endpoint = classifyEndpoint(endpointWord);
+  const methodFlags = valuesOf(parsed, "-X", "--method");
+  const lastMethod = methodFlags[methodFlags.length - 1];
+  const bodyFlags = valuesOf(parsed, "-f", "--raw-field", "-F", "--field", "--input");
+  const method = lastMethod ? (lastMethod.value && !lastMethod.value.opaque ? lastMethod.value.value.toUpperCase() : "?") : bodyFlags.length > 0 ? "POST" : "GET";
+  const scalarWrite = writeIsScalar(method, endpoint.segments);
+
+  // What the request FETCHES: GH_DEBUG and --verbose print the raw response
+  // whatever --jq or --silent select.
+  let fetchVerdict: SignedLinkVerdict = ALLOW;
+  if (endpoint.kind === "unclassifiable") fetchVerdict = refused("unclassifiable");
+  else if (endpoint.kind === "sensitive" && !scalarWrite) fetchVerdict = refused("api-rest");
+  else if (endpoint.kind === "graphql") fetchVerdict = classifyGraphqlQuery(parsed);
+  const traffic = ctx.debug || flagOn(parsed, "--verbose");
+  if (traffic) {
+    if (endpoint.kind === "download" && !fetchVerdict.refused) fetchVerdict = refused("api-rest");
+    if (fetchVerdict.refused) return ctx.debug ? refused("debug-traffic") : fetchVerdict;
+    return ALLOW;
+  }
+  if (ctx.appendsArgs && endpoint.kind !== "other" && endpoint.kind !== "download") return refused("unclassifiable");
+  if (!fetchVerdict.refused || flagOn(parsed, "--silent")) return ALLOW;
+  // The projection proof is about what is printed, so it holds for any endpoint.
+  if (jqRescues(parsed, rootScalarsFor(endpoint.segments))) return ALLOW;
+  return fetchVerdict;
+}
+
+/** GraphQL: the query arrives as a `query=` field, or from a file or stdin. */
+function classifyGraphqlQuery(parsed: ParsedFlags): SignedLinkVerdict {
+  if (valuesOf(parsed, "--input").length > 0) return refused("unclassifiable");
+  const fields = valuesOf(parsed, "-f", "--raw-field", "-F", "--field");
+  const queries = fields.filter((flag) => flag.value && /^query=/.test(flag.value.value));
+  if (queries.length === 0 || fields.some((flag) => !flag.value)) return refused("unclassifiable");
+  for (const flag of queries) {
+    const text = flag.value!.value.slice("query=".length);
+    const fromFile = (flag.name === "-F" || flag.name === "--field") && text.startsWith("@");
+    if (fromFile || flag.value!.opaque) return refused("unclassifiable");
+    if (graphqlIsSensitive(text)) return refused("api-graphql");
+  }
+  return ALLOW;
+}
+
+/** Classify the words after a `gh` command word. */
+export function classifyGh(args: ShellWord[], ctx: Context): SignedLinkVerdict {
+  let i = 0;
+  while (i < args.length && args[i].value.startsWith("-") && !args[i].opaque) {
+    if (["--help", "-h", "--version"].includes(args[i].value)) return ALLOW;
+    i++;
+  }
+  // `xargs gh` supplies the whole command from stdin.
+  if (i >= args.length) return ctx.appendsArgs ? refused("unclassifiable") : ALLOW;
+  const top = args[i];
+  const rest = args.slice(i + 1);
+  if (top.opaque) return refused("unclassifiable");
+  switch (top.value) {
+    case "pr":
+    case "issue":
+    case "release":
+    case "discussion":
+    case "search":
+    case "project":
+      return classifyGroup(top.value, rest, ctx);
+    case "api":
+      return classifyApi(rest, ctx);
+    case "status":
+      // The dashboard prints excerpts of recent comments and mentions.
+      return rest.length > 0 && rest.every((word) => word.value === "-h" || word.value === "--help") ? ALLOW : refused("composite-other");
+    case "help":
+    case "version":
+      return ALLOW;
+    case "cs":
+    case "codespace": {
+      // `gh codespace ssh … -- <command>` runs the command remotely and prints its output here.
+      const separator = rest.findIndex((word) => word.value === "--");
+      if (rest.some((word) => word.value === "ssh") && separator >= 0 && separator + 1 < rest.length) {
+        const verdict = classifyCommand(rest.slice(separator + 1).map((word) => word.value).join(" "), ctx.depth + 1, ctx.debug);
+        if (verdict.refused) return verdict;
+      }
+      break;
+    }
+  }
+  if (!SAFE_TOP.has(top.value)) return refused("unclassifiable"); // may be a user alias for a read
+  if (ctx.debug) return refused("debug-traffic");
+  return ALLOW;
+}
+
+/* ------------------------------------------------------------------ */
+/* Shell traversal                                                     */
+/* ------------------------------------------------------------------ */
+
+const SHELLS = new Set(["sh", "bash", "zsh", "dash", "ksh", "ash", "mksh", "fish"]);
+/** Commands that treat their `-c` value as a command string. */
+const DASH_C_RUNNERS = new Set(["su", "runuser", "script", "flock"]);
+/**
+ * Runners that execute the command given in their arguments. Only these (and
+ * the wrappers command position already skips: env, sudo, doas, nice, ionice,
+ * stdbuf, time, timeout, nohup, setsid, command, builtin, exec) pass a bare
+ * `gh` word on as a command; any other program's `gh` argument is data.
+ */
+const RUNNERS = new Set([
+  "secrets", "op", "unbuffer", "caffeinate", "chronic", "strace", "ltrace", "firejail", "bwrap", "nsenter",
+  "unshare", "chroot", "sg", "retry", "parallel", "doppler", "aws-vault", "dotenv", "direnv", "faketime",
+  "taskset", "numactl", "cgexec", "systemd-run", "docker", "podman", "kubectl", "mise", "asdf", "rtx", "devbox",
+  "gosu", "su-exec", "setpriv", "pkexec", "with-contenv", "uv", "poetry", "pipenv", "npx", "bunx", "pnpm", "yarn",
+  "nix", "nix-shell", "infisical", "chamber", "envchain", "dotenvx", "teller", "vault", "chrt", "coproc", "prlimit",
+  "ionice", "cpulimit", "trickle", "proxychains", "proxychains4", "torsocks", "tsocks", "catchsegv", "valgrind",
+]);
+/** Package runners whose `x`/`exec`/`dlx` subcommand runs the named program. */
+const PACKAGE_EXEC = new Map([["bun", ["x", "exec"]], ["npm", ["exec", "x"]], ["deno", ["run"]]]);
+const XARGS_VALUES = new Set(["-I", "-L", "-l", "-n", "-P", "-s", "-d", "-E", "-e", "-a", "--arg-file", "--delimiter", "--max-args", "--max-lines", "--max-procs", "--max-chars", "--replace", "--eof", "--process-slot-var"]);
+const SSH_VALUES = new Set(["-b", "-c", "-D", "-E", "-e", "-F", "-I", "-i", "-J", "-L", "-l", "-m", "-O", "-o", "-p", "-Q", "-R", "-S", "-W", "-w"]);
+const GH_MENTION = /(?:^|[^A-Za-z0-9_.-])gh(?:$|[^A-Za-z0-9_.-])/;
+const ASSIGNMENT = /^([A-Za-z_][A-Za-z0-9_]*)=([\s\S]*)$/;
+
+const MAX_DEPTH = 6;
+
+/** gh's own rule (`utils.IsDebugEnabled`): GH_DEBUG wins when set; legacy DEBUG counts for 1/true/yes/api. */
+function debugFromAssignments(words: ShellWord[], inherited: boolean): boolean {
+  let ghDebug: ShellWord | undefined;
+  let legacy: ShellWord | undefined;
+  for (const word of words) {
+    const match = ASSIGNMENT.exec(word.value);
+    if (!match) continue;
+    const value = { ...word, value: match[2] };
+    if (match[1] === "GH_DEBUG") ghDebug = value;
+    else if (match[1] === "DEBUG") legacy = value;
+  }
+  if (ghDebug) return ghDebug.opaque || !["", "0", "false", "no"].includes(ghDebug.value);
+  if (legacy && (legacy.opaque || ["1", "true", "yes", "api"].includes(legacy.value))) return true;
+  return inherited;
+}
+
+interface Segment { words: Word[]; redirects: Set<number>; sepBefore: string }
+
+/** lexCommand segments with the separator text before each (`|`, `&&`, `;`, `<(`, …). */
+function segmentsOf(text: string): { segments: Segment[]; trustworthy: boolean } {
+  const lexed = lexCommand(text);
+  let last = 0;
+  const segments = lexed.segments.map((segment) => {
+    const first = segment.words[0];
+    const sepBefore = text.slice(last, first.start);
+    last = segment.words[segment.words.length - 1].end;
+    return { words: segment.words, redirects: segment.redirects, sepBefore };
+  });
+  return { segments, trustworthy: lexed.trustworthy };
+}
+
+const isPipe = (separator: string) => /(?:^|[^|])\|&?$/.test(separator.trim());
+
+/** A shell whose script is its stdin: no `-c` and no script operand (`-s` and `-` allowed). */
+function shellReadsStdin(verb: string, args: ShellWord[]): boolean {
+  if (!SHELLS.has(verb)) return false;
+  if (dashCValue(args)) return false;
+  for (let i = 0; i < args.length; i++) {
+    const text = args[i].value;
+    if (text === "--") return i + 1 >= args.length;
+    if (text === "-" || text === "-s") return true;
+    if (/^[-+][A-Za-z]*[oO]$/.test(text)) { i++; continue; }
+    if (!text.startsWith("-") && !text.startsWith("+")) return false;
+  }
+  return true;
+}
+
+/**
+ * The literal text a simple command prints, when it can be read: `echo …`,
+ * `printf <format> …` (with `%s` filled in) and `cat <<EOF … EOF`. Anything
+ * else — a file, a network download, a variable — is null.
+ */
+function literalOutput(text: string): string | null {
+  const { segments } = segmentsOf(text.trim());
+  if (segments.length !== 1) return null;
+  const segment = segments[0];
+  const index = commandWordIndex(segment);
+  if (index < 0) return null;
+  const verb = base(shellWord(segment.words[index].text).value);
+  const args = segment.words.slice(index + 1).filter((_, at) => !segment.redirects.has(at + index + 1)).map((word) => shellWord(word.text));
+  if (verb === "echo") return args.filter((word, at) => !(at === 0 && /^-[neE]+$/.test(word.value))).map((word) => word.value).join(" ");
+  if (verb === "printf") {
+    const [format, ...values] = args.filter((word) => word.value !== "--");
+    if (!format) return null;
+    let next = 0;
+    return format.value.replace(/\\n/g, "\n").replace(/%s/g, () => values[next++]?.value ?? "") + (next < values.length ? " " + values.slice(next).map((word) => word.value).join(" ") : "");
+  }
+  if (verb === "cat") {
+    const at = text.indexOf("<<");
+    if (at < 0) return null;
+    const marker = heredocMarkerAt(text, at);
+    const newline = text.indexOf("\n", at);
+    if (!marker || newline < 0) return null;
+    const end = skipHeredocBodies(text, newline, [marker]);
+    if (end < 0) return null;
+    const body = text.slice(newline + 1, end);
+    return body.slice(0, body.lastIndexOf(marker.delimiter)).replace(/\n$/, "");
+  }
+  return null;
+}
+
+/** Classify the literal output of each substitution in `raw`, as the script a shell or eval would run. */
+function scriptsFromSubstitutions(raw: string, depth: number, ctx: Context): SignedLinkVerdict {
+  for (const body of substitutions(raw).bodies) {
+    const script = literalOutput(body);
+    if (script === null) continue;
+    const verdict = classifyCommand(script, depth + 1, ctx.debug);
+    if (verdict.refused) return verdict;
+  }
+  return ALLOW;
+}
+
+/** Classify a complete shell command string. */
+export function classifyCommand(command: string, depth = 0, inheritedDebug = false): SignedLinkVerdict {
+  if (typeof command !== "string" || !command.trim()) return ALLOW;
+  if (depth > MAX_DEPTH) return GH_MENTION.test(command) ? refused("unclassifiable") : ALLOW;
+  const { segments, trustworthy } = segmentsOf(command);
+  // A command the parser cannot follow to its end cannot be proven free of a gh read.
+  if (!trustworthy) return GH_MENTION.test(command) ? refused("unclassifiable") : ALLOW;
+  let debug = inheritedDebug;
+  const next = (text: string) => classifyCommand(text, depth + 1, debug);
+
+  for (const heredoc of heredocs(command)) {
+    // A shell (or ssh) runs the body; an unquoted delimiter runs its substitutions.
+    if (heredoc.runsBody) {
+      const verdict = next(heredoc.body);
+      if (verdict.refused) return verdict;
+    }
+    if (!heredoc.quoted) {
+      const found = substitutions(heredoc.body, "heredoc");
+      if (!found.complete && GH_MENTION.test(heredoc.body)) return refused("unclassifiable");
+      for (const body of found.bodies) {
+        const verdict = next(body);
+        if (verdict.refused) return verdict;
+      }
+    }
+  }
+
+  for (let at = 0; at < segments.length; at++) {
+    const segment = segments[at];
+    // Command substitutions run wherever they appear, whatever the command is.
+    for (const word of segment.words) {
+      const found = substitutions(word.text);
+      if (!found.complete && GH_MENTION.test(word.text)) return refused("unclassifiable");
+      for (const body of found.bodies) {
+        const verdict = next(body);
+        if (verdict.refused) return verdict;
+      }
+    }
+    const index = commandWordIndex(segment);
+    const words = segment.words.map((word, position) => ({ word: shellWord(word.text), redirect: segment.redirects.has(position) }));
+    const prefix = words.slice(0, index < 0 ? words.length : index).map((entry) => entry.word);
+    // `export GH_DEBUG=api`, a bare assignment or `declare -x` sticks for the rest of the command.
+    const statement = index >= 0 ? base(words[index].word.value) : "";
+    if (index < 0 || ["export", "declare", "typeset", "readonly", "local"].includes(statement)) {
+      debug = debugFromAssignments([...prefix, ...words.slice(index + 1).map((entry) => entry.word)], debug);
+      if (index < 0) continue;
+    }
+    const segmentDebug = debugFromAssignments(prefix, debug);
+    const operands = words.slice(index + 1).filter((entry) => !entry.redirect).map((entry) => entry.word);
+    const redirects = words.slice(index + 1).filter((entry) => entry.redirect).map((entry) => entry.word);
+    const verbWord = words[index].word;
+    const verb = base(verbWord.value);
+    const ctx: Context = { depth, appendsArgs: false, debug: segmentDebug };
+    // `function name { cmd …; }`: the body's first command follows the name.
+    if (index > 0 && words[index - 1].word.value === "function") {
+      const body = operands.filter((word) => !["{", "()", "(", ")"].includes(word.value));
+      const verdict = runArgv(body, ctx);
+      if (verdict.refused) return verdict;
+      continue;
+    }
+
+    // Literal text piped into a shell that reads its script from stdin.
+    if (at > 0 && isPipe(segment.sepBefore) && shellReadsStdin(verb, operands)) {
+      const producer = segments[at - 1];
+      const text = segmentText(command, producer);
+      const script = text === null ? null : literalOutput(text);
+      if (script !== null) {
+        const verdict = classifyCommand(script, depth + 1, segmentDebug);
+        if (verdict.refused) return verdict;
+      }
+    }
+    // `source <(…)`, `. <(…)`, `bash <(…)`: the process substitution's output is the script.
+    const following = segments[at + 1];
+    if (following && /<\(\s*$/.test(following.sepBefore) && (SHELLS.has(verb) || verb === "source" || verb === ".")) {
+      const open = following.words[0].start - following.sepBefore.length + following.sepBefore.lastIndexOf("(");
+      const end = scanParenAt(command, open);
+      const script = end < 0 ? null : literalOutput(command.slice(open + 1, end - 1));
+      if (script !== null) {
+        const verdict = classifyCommand(script, depth + 1, segmentDebug);
+        if (verdict.refused) return verdict;
+      }
+    }
+
+    const verdict = classifyInvocation(verb, verbWord, operands, redirects, segment.words.slice(0, index + 1), ctx);
+    if (verdict.refused) return verdict;
+  }
+  return ALLOW;
+}
+
+/** The source text of one segment, from its first word to its last. */
+function segmentText(command: string, segment: Segment): string | null {
+  const first = segment.words[0];
+  const last = segment.words[segment.words.length - 1];
+  return first && last ? command.slice(first.start, last.end) : null;
+}
+
+/** Literal basename of a command word, or undefined when the name itself is built by an expansion. */
+function literalBasename(word: ShellWord): string | undefined {
+  const name = base(word.value);
+  return /[$`]/.test(name) || name === "" ? undefined : name;
+}
+
+function classifyInvocation(verb: string, verbWord: ShellWord, args: ShellWord[], redirects: ShellWord[], prefix: Word[], ctx: Context): SignedLinkVerdict {
+  const depth = ctx.depth;
+  const next = (text: string) => classifyCommand(text, depth + 1, ctx.debug);
+  if (verbWord.opaque) {
+    const name = literalBasename(verbWord);
+    if (name === undefined) {
+      // A command word whose name is an expansion (`$GH`, `"$(command -v gh)"`)
+      // may be gh: refuse what gh would refuse, including an unreadable read.
+      const top = args.find((word) => !word.value.startsWith("-"));
+      const verdict = classifyGh(args, ctx);
+      if (!verdict.refused) return ALLOW;
+      return verdict.rule !== "unclassifiable" || (top !== undefined && !top.opaque && READ_TOP.has(top.value)) ? verdict : ALLOW;
+    }
+    verb = name;
+  }
+  if (verb === "gh") return classifyGh(args, ctx);
+  if (SHELLS.has(verb)) {
+    const script = dashCValue(args);
+    if (script) {
+      const verdict = next(script.value);
+      if (verdict.refused || !script.opaque) return verdict;
+      // `bash -c "$(cat <<EOF …)"`: the substitution's literal output is the script.
+      return scriptsFromSubstitutions(script.raw, depth, ctx);
+    }
+    // No -c: the shell reads its script from a file or stdin; follow here-strings.
+    for (const word of redirects) {
+      const verdict = next(word.value);
+      if (verdict.refused) return verdict;
+      if (word.opaque) {
+        const fromSubstitution = scriptsFromSubstitutions(word.raw, depth, ctx);
+        if (fromSubstitution.refused) return fromSubstitution;
+      }
+    }
+    return ALLOW;
+  }
+  if (DASH_C_RUNNERS.has(verb)) {
+    const at = args.findIndex((word) => word.value === "-c" || word.value === "--command" || /^-[A-Za-z]*c$/.test(word.value));
+    const script = at >= 0 ? args[at + 1] : undefined;
+    return script ? next(script.value) : bareGh(args, ctx);
+  }
+  if (verb === "eval" || verb === "watch") {
+    let words = args;
+    if (verb === "watch") {
+      // watch's options come first; `-n`/`--interval` and `-q`/`--equexit` take a value.
+      let i = 0;
+      while (i < args.length && args[i].value.startsWith("-")) {
+        if (args[i].value === "--") { i++; break; }
+        if (["-n", "--interval", "-q", "--equexit"].includes(args[i].value)) i++;
+        i++;
+      }
+      words = args.slice(i);
+    }
+    const verdict = next(words.map((word) => word.value).join(" "));
+    if (verdict.refused) return verdict;
+    for (const word of words) {
+      const fromSubstitution = scriptsFromSubstitutions(word.raw, depth, ctx);
+      if (fromSubstitution.refused) return fromSubstitution;
+    }
+    return ALLOW;
+  }
+  if (verb === "env") {
+    // commandWordIndex stops on env only for -S/--split-string.
+    return next(envSplitCommandText([...prefix.map((word) => shellWord(word.text).value), ...args.map((word) => word.value)]));
+  }
+  if (verb === "ssh") {
+    let i = 0;
+    for (; i < args.length; i++) {
+      const text = args[i].value;
+      if (!text.startsWith("-")) break;
+      if (SSH_VALUES.has(text)) i++;
+    }
+    const remoteWords = args.slice(i + 1);
+    if (remoteWords[0]?.value === "--") remoteWords.shift();
+    const remote = remoteWords.map((word) => word.value).join(" ");
+    return remote ? next(remote) : ALLOW;
+  }
+  if (verb === "xargs") {
+    let i = 0;
+    let replace = false;
+    for (; i < args.length; i++) {
+      const text = args[i].value;
+      if (text === "--") { i++; break; }
+      if (!text.startsWith("-")) break;
+      if (/^-I|^-i|^--replace/.test(text)) replace = true;
+      if (XARGS_VALUES.has(text)) i++;
+    }
+    return runArgv(args.slice(i), { depth, appendsArgs: !replace, debug: ctx.debug });
+  }
+  if (verb === "find") {
+    for (let i = 0; i < args.length; i++) {
+      if (!["-exec", "-execdir", "-ok", "-okdir"].includes(args[i].value)) continue;
+      let end = i + 1;
+      while (end < args.length && args[end].value !== ";" && args[end].value !== "+") end++;
+      const verdict = runArgv(args.slice(i + 1, end), ctx);
+      if (verdict.refused) return verdict;
+      i = end;
+    }
+    return ALLOW;
+  }
+  if (RUNNERS.has(verb)) return bareGh(args, ctx);
+  if (PACKAGE_EXEC.get(verb)?.includes(args[0]?.value ?? "")) return bareGh(args.slice(1), ctx);
+  return ALLOW;
+}
+
+/** An argv vector run as a command (xargs, find -exec). */
+function runArgv(argv: ShellWord[], ctx: Context): SignedLinkVerdict {
+  if (argv.length === 0) return ALLOW;
+  const verb = base(argv[0].value);
+  if (verb === "gh") return classifyGh(argv.slice(1), ctx);
+  if (SHELLS.has(verb)) {
+    const script = dashCValue(argv.slice(1));
+    return script ? classifyCommand(script.value, ctx.depth + 1, ctx.debug) : ALLOW;
+  }
+  return classifyInvocation(verb, argv[0], argv.slice(1), [], [], ctx);
+}
+
+/** A known runner that passes a bare `gh` word on as a command. */
+function bareGh(args: ShellWord[], ctx: Context): SignedLinkVerdict {
+  const at = args.findIndex((word) => !word.opaque && base(word.value) === "gh" && (word.value === "gh" || word.value.includes("/")));
+  return at >= 0 ? classifyGh(args.slice(at + 1), ctx) : ALLOW;
+}
+
+/** The command string given to `-c` (also inside a short-option cluster such as `-lc`). */
+function dashCValue(args: ShellWord[]): ShellWord | undefined {
+  for (let i = 0; i < args.length; i++) {
+    const text = args[i].value;
+    if (text === "--") return undefined;
+    if (!text.startsWith("-") && !text.startsWith("+")) return undefined;
+    if (text === "-c" || (/^-[A-Za-z]+$/.test(text) && text.includes("c"))) {
+      return args.slice(i + 1).find((word) => !word.value.startsWith("-") || word.value === "-");
+    }
+    // `-o option` / `-O shopt`, also at the end of a cluster such as `-euo pipefail`.
+    if (/^[-+][A-Za-z]*[oO]$/.test(text)) i++;
+  }
+  return undefined;
+}
+
+/**
+ * Top-level here-documents, with whether the body runs as a script and
+ * whether its delimiter is quoted (a quoted body is literal). The body runs
+ * when the command that owns the operator is a shell reading stdin, `ssh`,
+ * or `source`/`.` of `/dev/stdin`, or when that command is `cat` piped
+ * straight into a shell reading stdin. A here-document feeding any other
+ * command is data.
+ */
+function heredocs(command: string): Array<{ body: string; runsBody: boolean; quoted: boolean }> {
+  const found: Array<{ body: string; runsBody: boolean; quoted: boolean }> = [];
+  let from = 0;
+  for (;;) {
+    const at = command.indexOf("<<", from);
+    if (at < 0) break;
+    from = at + 2;
+    if (command[at + 2] === "<" || (at > 0 && command[at - 1] === "<")) { from = at + 3; continue; }
+    const marker = heredocMarkerAt(command, at);
+    if (!marker) continue;
+    const lineStart = command.lastIndexOf("\n", at) + 1;
+    const lineEnd = command.indexOf("\n", at);
+    if (lineEnd < 0) continue;
+    const end = skipHeredocBodies(command, lineEnd, [marker]);
+    const bodyText = end < 0 ? command.slice(lineEnd + 1) : command.slice(lineEnd + 1, end);
+    const body = end < 0 ? bodyText : bodyText.slice(0, Math.max(0, bodyText.lastIndexOf(marker.delimiter))).replace(/\n$/, "");
+    const line = command.slice(lineStart, at) + " HEREDOC_OPERATOR " + command.slice(marker.end, lineEnd);
+    found.push({ body, runsBody: heredocRunsBody(line), quoted: marker.quoted });
+  }
+  return found;
+}
+
+function heredocRunsBody(line: string): boolean {
+  const { segments } = segmentsOf(line);
+  const owner = segments.findIndex((segment) => segment.words.some((word) => word.text === "HEREDOC_OPERATOR"));
+  if (owner < 0) return false;
+  const describe = (segment: Segment) => {
+    const index = commandWordIndex(segment);
+    if (index < 0) return { verb: "", args: [] as ShellWord[] };
+    const args = segment.words.slice(index + 1).filter((word) => word.text !== "HEREDOC_OPERATOR").map((word) => shellWord(word.text));
+    return { verb: base(shellWord(segment.words[index].text).value), args };
+  };
+  const { verb, args } = describe(segments[owner]);
+  if (verb === "ssh" || shellReadsStdin(verb, args)) return true;
+  if ((verb === "source" || verb === ".") && ["/dev/stdin", "/dev/fd/0", "/proc/self/fd/0"].includes(args[0]?.value ?? "")) return true;
+  const consumer = segments[owner + 1];
+  if (verb === "cat" && consumer && isPipe(consumer.sepBefore)) {
+    const next = describe(consumer);
+    return next.verb === "ssh" || shellReadsStdin(next.verb, next.args);
+  }
+  return false;
+}