@nimbus-dev/connectors 0.2.2 → 0.2.4

package/shared/cli-json-kit.ts

@@ -14,7 +14,13 @@
  *
  * The argument guard is the reason this is worth sharing rather than tolerating:
  * it is a security control, and a security control that exists in five
- * hand-written copies is one that can be strengthened in four of them.
+ * hand-written copies is one that can be strengthened in four of them. Every
+ * caller-supplied value that reaches a CLI's argv, in all eleven connectors
+ * that spawn one, now passes one of the argument schemas here — including in
+ * the connectors that spawn through `run-cli-json.ts` rather than
+ * {@link createCliJsonRunner}; bigquery's values never reach argv at all. And
+ * `scripts/cli-argument-guards.test.ts` fails a tool whose schema lets a value
+ * the CLI would misread through, whether or not something later refuses it.
  *
  * The `gcloud` connectors (bigquery, cloud-logging, gcp, vertex-ai) also share
  * how they hand gcloud its project and credentials: see {@link gcloudEnv} and
@@ -23,11 +29,24 @@
 
 import { z } from "zod";
 import { optionalEnv } from "./env-json-api.ts";
-import { isSafeCliArg } from "./safe-cli-arg.ts";
+import { awsCliArgProblem, azCliArgProblem, cliArgProblem } from "./safe-cli-arg.ts";
 
 /** Body-snippet length in the thrown error. The value every connector used. */
 export const DEFAULT_STDERR_SNIPPET = 400;
 
+/**
+ * A Zod string that refuses every value `problem` names a reason against, with that reason as the
+ * message — so a refused call says which rule it broke rather than listing all of them.
+ */
+function cliArgSchema(problem: (value: unknown) => string | undefined): z.ZodString {
+  return z
+    .string()
+    .min(1)
+    .refine((value) => problem(value) === undefined, {
+      error: (issue) => problem(issue.input) ?? "is not a safe CLI argument",
+    });
+}
+
 /**
  * A value passed to a CLI as an argument.
  *
@@ -35,10 +54,20 @@ export const DEFAULT_STDERR_SNIPPET = 400;
  * `-` would be read by the CLI as a flag rather than as the name it is meant to
  * be, and control characters have no legitimate place in one.
  */
-export const cliArg = z
-  .string()
-  .min(1)
-  .refine(isSafeCliArg, { message: 'must not start with "-" or contain control characters' });
+export const cliArg = cliArgSchema(cliArgProblem);
+
+/**
+ * A value passed to the `aws` CLI as an argument: {@link cliArg}, and not a value the CLI would
+ * replace by reading a file or fetching a URL (`file://`, `fileb://`, `http://`, `https://`), nor
+ * one carrying the shorthand file-load operator `@=`.
+ */
+export const awsCliArg = cliArgSchema(awsCliArgProblem);
+
+/**
+ * A value passed to the `az` CLI as an argument: {@link cliArg}, and not one `az` would replace by
+ * a file's contents — a leading `@`, or `=@` anywhere.
+ */
+export const azCliArg = cliArgSchema(azCliArgProblem);
 
 /** The spawn seam. Production passes `nimbusSpawn`; tests pass a fake. */
 export type SpawnFn = (

package/shared/consent-kit.ts

@@ -2,11 +2,9 @@ import type { McpListResult, ZodObjectSchema } from "@nimbus-dev/sdk/connector-k
 
 import { type AuditOutcome, appendAuditEntry } from "./audit-chain.ts";
 import { getConnectorMode } from "./connector-mode.ts";
+import { createWriteBudget, parseWriteBudget, WRITE_BUDGET_ENV } from "./write-budget.ts";
 import { parseWriteScope, scopeAllows } from "./write-scope.ts";
 
-/** Mutations allowed per process lifetime when NIMBUS_MCP_WRITE_BUDGET is unset. */
-const DEFAULT_BUDGET = 10;
-
 /** The subset of the SDK's `RegisteredTool` this kit needs. */
 export type ToolHandle = { disable(): void };
 
@@ -61,6 +59,19 @@ export type ConsentServer = {
   sendLoggingMessage(params: { level: "info" | "warning"; data: unknown }): Promise<void>;
 };
 
+/**
+ * What a connector with write tools constructs its `McpServer` with:
+ * `new McpServer(info, { capabilities: CONSENT_SERVER_CAPABILITIES })`.
+ *
+ * The kit tells the client about every gated outcome with `notifications/message`, and the SDK
+ * sends that only for a server that declared the MCP `logging` capability. No connector did, so
+ * each notification was dropped without a word. It must be declared at construction: that is the
+ * only moment the SDK installs its `logging/setLevel` handler, and a server that declared the
+ * capability later would refuse a client setting the level. `scripts/connector-boot.test.ts`
+ * fails a connector whose manifest declares a write and whose booted server does not declare it.
+ */
+export const CONSENT_SERVER_CAPABILITIES = { logging: {} };
+
 export type WriteToolConfig<T> = {
   /** Action type this tool performs, e.g. "repo.branch.delete". Machine-readable, not prose. */
   readonly mutates: string;
@@ -84,6 +95,11 @@ function refused(why: string): McpListResult {
   return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: why }) }] };
 }
 
+/** The message of whatever was thrown, which need not be an `Error`. */
+function messageOf(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
 /**
  * Ask the human, through the client, and report whether they said yes.
  *
@@ -172,30 +188,77 @@ export function createWriteToolRegistrar(
 
   const scope = parseWriteScope(process.env[cfg.scopeEnv], cfg.scopeKinds);
   const auditLog = process.env["NIMBUS_MCP_AUDIT_LOG"];
-  let remaining = Number(process.env["NIMBUS_MCP_WRITE_BUDGET"] ?? DEFAULT_BUDGET);
+  // Throws on a value that is not plain digits, an empty one included, as the scope parse above
+  // does on a malformed term: read with `Number()`, `abc` became NaN, which `remaining <= 0` never
+  // refused.
+  const budget = createWriteBudget(parseWriteBudget(process.env[WRITE_BUDGET_ENV]));
 
   async function record(
     tool: string,
     outcome: AuditOutcome,
     detail: Record<string, unknown>,
   ): Promise<void> {
-    // Client-visible channel: any MCP client can display or persist this.
-    await server.sendLoggingMessage({
-      level: outcome === "executed" ? "info" : "warning",
-      data: { connector: cfg.connector, tool, outcome },
-    });
-    // Durable channel: only when the operator configured a path.
-    if (auditLog !== undefined && auditLog !== "") {
-      await appendAuditEntry(auditLog, {
-        ts: new Date().toISOString(),
-        connector: cfg.connector,
-        tool,
-        outcome,
-        detail,
-      });
+    try {
+      // Durable channel first: only when the operator configured a path. An append that fails
+      // rejects, and every record before the mutation is awaited, so a write whose entry did not
+      // land never runs.
+      if (auditLog !== undefined && auditLog !== "") {
+        await appendAuditEntry(auditLog, {
+          ts: new Date().toISOString(),
+          connector: cfg.connector,
+          tool,
+          outcome,
+          detail,
+        });
+      }
+    } finally {
+      // Then the client-visible channel, told of every record attempted, one whose append failed
+      // included. It reaches the client because the connector declared the MCP `logging`
+      // capability (CONSENT_SERVER_CAPABILITIES), and a client may filter it by level. Best
+      // effort, and after the durable log: a client that has gone away mid-write must not keep the
+      // `executed` or `failed` record of a write that ran out of the log, and since the capability
+      // made this channel live, a dead pipe is where a send now fails.
+      await server
+        .sendLoggingMessage({
+          level: outcome === "executed" ? "info" : "warning",
+          data: { connector: cfg.connector, tool, outcome },
+        })
+        .catch(() => undefined);
     }
   }
 
+  /**
+   * Take one unit of budget if any is left. Spending the last unit disables every write tool and
+   * tells the client.
+   *
+   * Nothing may be awaited between the check and the decrement, which is why both are the one
+   * synchronous call `budget.take()`. Calls run concurrently (the SDK starts each request's
+   * handler as it arrives), and with an await between the two every call in flight passed the
+   * check before any of them spent: three approved calls all mutated under a budget of one.
+   */
+  function spendOne(): boolean {
+    if (!budget.take()) return false;
+    if (!budget.hasLeft()) {
+      for (const h of handles) h.disable();
+      server.sendToolListChanged();
+    }
+    return true;
+  }
+
+  /**
+   * The refusal for a spent budget, worded the same for the client at both places it is checked.
+   * The audit reason tells them apart: `budget exhausted after approval` follows an `accepted`
+   * entry, because the budget ran out while that write's prompt was open.
+   */
+  async function budgetExhausted(
+    tool: string,
+    target: { kind: string; value: string },
+    reason: "budget exhausted" | "budget exhausted after approval",
+  ): Promise<McpListResult> {
+    await record(tool, "refused", { reason, target });
+    return refused("write budget exhausted for this session");
+  }
+
   /**
    * Decide the write surface, once, at the first moment client capabilities are knowable.
    *
@@ -269,11 +332,9 @@ export function createWriteToolRegistrar(
         return refused(`out of scope: ${target.kind}:${target.value} is not in ${cfg.scopeEnv}`);
       }
 
-      // 2. BUDGET — same reasoning: a refusal that consent cannot lift comes before consent.
-      if (remaining <= 0) {
-        await record(name, "refused", { reason: "budget exhausted", target });
-        return refused("write budget exhausted for this session");
-      }
+      // 2. BUDGET — same reasoning: a refusal that consent cannot lift comes before consent. Not
+      //    the last word on the budget, though: see step 4.
+      if (!budget.hasLeft()) return budgetExhausted(name, target, "budget exhausted");
 
       // 3. CONSENT.
       await record(name, "requested", { target, params: args });
@@ -283,7 +344,13 @@ export function createWriteToolRegistrar(
       }
       await record(name, "accepted", { target });
 
-      // 4. PRE-STATE — after approval, before the mutation, so an unrecoverable action leaves a
+      // 4. SPEND — the budget checked AGAIN, and decremented in the same synchronous step: every
+      //    call in flight passed step 2 before any of them got this far, so step 2 alone cannot
+      //    hold the cap (see `spendOne`). Spent BEFORE the mutation so a throwing one still
+      //    consumes budget — otherwise a failing destructive tool could be retried without limit.
+      if (!spendOne()) return budgetExhausted(name, target, "budget exhausted after approval");
+
+      // 5. PRE-STATE — after approval, before the mutation, so an unrecoverable action leaves a
       //    record of what it destroyed. Capture failure is NOT fatal: refusing here would turn a
       //    transient read error into a blocked action the owner already approved.
       let preState: Record<string, unknown> = {};
@@ -291,29 +358,39 @@ export function createWriteToolRegistrar(
         try {
           preState = await toolCfg.capturePreState(args);
         } catch (e) {
-          preState = { captureFailed: e instanceof Error ? e.message : String(e) };
+          preState = { captureFailed: messageOf(e) };
         }
       }
 
-      // 5. MUTATE. Decrement BEFORE the call so a throwing mutation still consumes budget —
-      //    otherwise a failing destructive tool could be retried without limit.
-      remaining -= 1;
-      if (remaining <= 0) {
-        for (const h of handles) h.disable();
-        server.sendToolListChanged();
+      // 6. MUTATE.
+      let result: McpListResult;
+      try {
+        result = await handler(args);
+      } catch (e) {
+        // A tool that threw may still have changed something first. If recording the failure fails
+        // too, the tool's own error still leads what the call reports: an audit error alone reads
+        // as a write that never started, and so as one that is safe to try again.
+        try {
+          await record(name, "failed", { target, preState, error: messageOf(e) });
+        } catch (error_) {
+          throw new Error(
+            `${name} failed: ${messageOf(e)}. Recording that failure also failed: ${messageOf(error_)}`,
+            { cause: e },
+          );
+        }
+        throw e;
       }
+      // Outside the `try`: the mutation has happened, so a failure to RECORD it must not be
+      // recorded as the mutation failing, which it was when both shared one `catch`. The call still
+      // rejects, saying the write ran, so it is not taken for one that is safe to try again.
       try {
-        const result = await handler(args);
         await record(name, "executed", { target, preState });
-        return result;
       } catch (e) {
-        await record(name, "failed", {
-          target,
-          preState,
-          error: e instanceof Error ? e.message : String(e),
+        throw new Error(`${name} ran, but recording that it ran failed: ${messageOf(e)}`, {
+          cause: e,
         });
-        throw e;
       }
+      return result;
     };
 
     pending.push(() => {

package/shared/nimbus-spawn.ts

@@ -1,7 +1,100 @@
-import { spawn } from "node:child_process";
+/**
+ * nimbus-spawn — the one place this package starts a process.
+ *
+ * Every connector that reaches its service through a CLI spawns it through {@link nimbusSpawn},
+ * directly or by way of `run-cli-json.ts` and `cli-json-kit.ts`, and `scripts/spawn-chokepoint.test.ts`
+ * fails any other shipped file that imports a module able to start a process, in any import form,
+ * or refers to the `Bun` global at all. That is what makes a rule enforced here hold for every
+ * connector: today, `windows-batch-args.ts`'s refusal of an argument cmd.exe would act on, when the
+ * program may start a Windows batch file. Both implementations build the child's environment once
+ * and hand the SAME object to that check and to the spawn, so the environment that was checked is
+ * the one the child gets.
+ */
+
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { batchArgumentRefusal } from "./windows-batch-args.ts";
 
 export type SpawnResult = { code: number; stdout: string; stderr: string };
 
+/**
+ * The child's environment: `base` with `overrides` laid over it.
+ *
+ * On Windows a variable's name is case-insensitive, so an override replaces the base's variable
+ * whatever its spelling, instead of sitting beside it as a second one that the child may or may
+ * not see in its place. And the search path is spelled `PATH`, the only spelling Bun resolves a
+ * bare command through. A process started from PowerShell, cmd or Explorer has `Path`, and with it
+ * a bare `az` or `gcloud`, which are the batch files `az.cmd` and `gcloud.cmd` there, did not start
+ * at all: Bun 1.3.14 answered ENOENT, while an `.exe` such as `aws.exe` still started.
+ *
+ * Elsewhere names are case-sensitive, and the two are merged as written.
+ */
+export function childEnvironment(
+  base: Record<string, string | undefined>,
+  overrides: Record<string, string | undefined>,
+  platform: NodeJS.Platform = process.platform,
+): Record<string, string | undefined> {
+  if (platform !== "win32") {
+    return { ...base, ...overrides };
+  }
+  const byName = new Map<string, readonly [string, string | undefined]>();
+  for (const source of [base, overrides]) {
+    for (const [key, value] of Object.entries(source)) {
+      const name = key.toUpperCase();
+      byName.set(name, [name === "PATH" ? "PATH" : key, value]);
+    }
+  }
+  return Object.fromEntries(byName.values());
+}
+
+/**
+ * The child's environment for `env`, and why `command` must not be spawned with it, if it must
+ * not. Nothing is spawned for a refused command: it resolves as a failure whose stderr says so.
+ */
+function prepareSpawn(
+  command: readonly string[],
+  env: Record<string, string | undefined>,
+): { childEnv: Record<string, string | undefined>; refusal: SpawnResult | undefined } {
+  const childEnv = childEnvironment(process.env, env);
+  const refusal = batchArgumentRefusal(command, childEnv);
+  return {
+    childEnv,
+    refusal: refusal === undefined ? undefined : { code: 1, stdout: "", stderr: refusal },
+  };
+}
+
+/**
+ * Collect a child's output and resolve with it once the child closes or fails to start.
+ *
+ * Output is accumulated as raw `Buffer`s and decoded ONCE at the end. Decoding each chunk with
+ * `chunk.toString("utf8")` corrupts any multi-byte character that straddles a chunk boundary, and
+ * chunk boundaries are a function of pipe timing — so it fails intermittently, on non-ASCII data,
+ * in production.
+ */
+function collectOutput(
+  child: ChildProcessWithoutNullStreams,
+  resolveP: (result: SpawnResult) => void,
+): void {
+  const outChunks: Buffer[] = [];
+  const errChunks: Buffer[] = [];
+  child.stdout.on("data", (c: Buffer) => {
+    outChunks.push(c);
+  });
+  child.stderr.on("data", (c: Buffer) => {
+    errChunks.push(c);
+  });
+  const decode = (): { stdout: string; stderr: string } => ({
+    stdout: Buffer.concat(outChunks).toString("utf8"),
+    stderr: Buffer.concat(errChunks).toString("utf8"),
+  });
+  child.on("error", (e: Error) => {
+    const d = decode();
+    resolveP({ code: 1, stdout: d.stdout, stderr: `${d.stderr}${e.message}` });
+  });
+  child.on("close", (code: number | null) => {
+    resolveP({ code: code ?? 1, ...decode() });
+  });
+}
+
 /**
  * Node implementation. Exported so it can be tested directly: the suite runs under Bun, so
  * `nimbusSpawn` would otherwise never exercise this branch and it would ship unverified.
@@ -15,11 +108,6 @@ export type SpawnResult = { code: number; stdout: string; stderr: string };
  *    `Bun.spawn` path reads stdout uncapped, and `aws logs` / `gcloud logging` JSON routinely
  *    exceeds 1 MB, so `execFile` would be a silent-truncation regression dressed up as a
  *    portability fix.
- *
- * Output is accumulated as raw `Buffer`s and decoded ONCE at the end. Decoding each chunk with
- * `chunk.toString("utf8")` corrupts any multi-byte character that straddles a chunk boundary, and
- * chunk boundaries are a function of pipe timing — so it fails intermittently, on non-ASCII data,
- * in production.
  */
 export function spawnViaNode(
   command: readonly string[],
@@ -29,27 +117,20 @@ export function spawnViaNode(
   if (bin === undefined) {
     return Promise.resolve({ code: 1, stdout: "", stderr: "empty command" });
   }
+  const { childEnv, refusal } = prepareSpawn(command, env);
+  if (refusal !== undefined) {
+    return Promise.resolve(refusal);
+  }
   return new Promise((resolveP) => {
-    const child = spawn(bin, args, { env: { ...process.env, ...env } });
-    const outChunks: Buffer[] = [];
-    const errChunks: Buffer[] = [];
-    child.stdout.on("data", (c: Buffer) => {
-      outChunks.push(c);
-    });
-    child.stderr.on("data", (c: Buffer) => {
-      errChunks.push(c);
-    });
-    const decode = (): { stdout: string; stderr: string } => ({
-      stdout: Buffer.concat(outChunks).toString("utf8"),
-      stderr: Buffer.concat(errChunks).toString("utf8"),
-    });
-    child.on("error", (e: Error) => {
-      const d = decode();
-      resolveP({ code: 1, stdout: d.stdout, stderr: `${d.stderr}${e.message}` });
-    });
-    child.on("close", (code: number | null) => {
-      resolveP({ code: code ?? 1, ...decode() });
-    });
+    // `spawn` THROWS, rather than emitting "error", for a command it cannot start at all: an
+    // argument holding a NUL byte, or — on Node, though not in Bun's `node:child_process` — a
+    // `.cmd` or `.bat` without a shell, which Node refuses with EINVAL. Uncaught, the throw would
+    // REJECT this promise, against the contract both implementations keep.
+    try {
+      collectOutput(spawn(bin, args, { env: childEnv }), resolveP);
+    } catch (e) {
+      resolveP({ code: 1, stdout: "", stderr: e instanceof Error ? e.message : String(e) });
+    }
   });
 }
 
@@ -61,12 +142,16 @@ export async function spawnViaBun(
   if (command.length === 0) {
     return { code: 1, stdout: "", stderr: "empty command" };
   }
+  const { childEnv, refusal } = prepareSpawn(command, env);
+  if (refusal !== undefined) {
+    return refusal;
+  }
   // `Bun.spawn` THROWS synchronously when the binary does not exist, where `child_process` emits
   // an "error" event instead. Both branches must honour the same contract — resolve with a
   // non-zero code, never reject — or a caller's behaviour would depend on the runtime.
   try {
     const proc = Bun.spawn([...command], {
-      env: { ...process.env, ...env },
+      env: childEnv,
       stdout: "pipe",
       stderr: "pipe",
     });
@@ -119,6 +204,8 @@ export function selectSpawnImpl(g: unknown = globalThis): SpawnImpl {
  * routing unconditionally through Node made it spawn a real `aws` and hang the suite.
  *
  * Never rejects: a spawn failure resolves with a non-zero code, matching the previous behaviour.
+ * So does a REFUSED spawn — on Windows, an argument cmd.exe would act on, for a program that may
+ * start a batch file — whose stderr says why and that nothing was run.
  */
 export function nimbusSpawn(
   command: readonly string[],

package/shared/run-read-only-mcp-connector.ts

@@ -1,5 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CONSENT_SERVER_CAPABILITIES } from "./consent-kit.ts";
 import {
   createRegisterSimpleTool,
   createZodToolRegistrar,
@@ -41,7 +42,12 @@ export function buildReadOnlyMcpConnector(
   register: (reg: ZodToolRegistrar, server: unknown) => void,
   options?: BuildReadOnlyMcpConnectorOptions,
 ): unknown {
-  const make = options?.createServer ?? ((info) => new McpServer(info));
+  // Every server built here declares the MCP `logging` capability, since the consent kit's
+  // notifications reach a client only through it. A truly read-only connector sends no log
+  // message, so declaring it costs that connector nothing.
+  const make =
+    options?.createServer ??
+    ((info) => new McpServer(info, { capabilities: CONSENT_SERVER_CAPABILITIES }));
   const mcp = make({ name: serverName, version: "0.1.0" });
   const reg = createZodToolRegistrar(createRegisterSimpleTool(mcp));
   register(reg, mcp);

package/shared/safe-cli-arg.ts

@@ -1,40 +1,70 @@
 /**
  * Guard a tool-supplied value before it is passed as an argument to a spawned CLI
- * (`gcloud` / `aws` / `bq` / …).
+ * (`gcloud` / `aws` / `az` / `kubectl` / …).
  *
  * Spawns use an argv array (no shell), so there is no classic shell injection — but
  * a value that begins with `-` would be parsed by the CLI as a FLAG rather than a
  * positional / flag-value. This "argv flag smuggling" lets tool input inject
- * arbitrary CLI flags (e.g. a `sinkName` of `--project=attacker` or `-h`). Reject
+ * arbitrary CLI flags (e.g. a `sinkName` of `--project=attacker`, or a pod name of
+ * `--kubeconfig=<path>`, whose exec credential plugin runs a command). Reject
  * any value that is empty, over-long, starts with `-`, or contains control
  * characters.
  *
  * Resource-id charsets vary per service (sink ids are `[A-Za-z0-9_.-]`, CloudWatch
  * log-group names contain `/`, BigQuery refs contain `.`), so this is the UNIVERSAL
  * guard against flag smuggling; callers may layer a stricter per-resource regex on
- * top. Returns the value unchanged so it can be used inline:
+ * top. Two CLIs need one: `aws` and `az` read some argument values from a file
+ * instead of taking them as written — see {@link awsCliArgProblem} and
+ * {@link azCliArgProblem}. A third rule is not per value at all: an argument to a CLI
+ * that Windows runs as a batch file is checked at the spawn itself, in
+ * `windows-batch-args.ts`.
+ *
+ * Returns the value unchanged so it can be used inline:
  * `cli(["describe", assertSafeCliArg(p.id, "id")])`.
  *
  * @throws {Error} when the value is unsafe to pass as a CLI argument.
  */
 export function assertSafeCliArg(value: string, label = "argument"): string {
+  const problem = cliArgProblem(value);
+  if (problem !== undefined) {
+    throw new Error(`Invalid ${label}: ${problem}`);
+  }
+  return value;
+}
+
+/** The longest value accepted as one CLI argument. */
+const MAX_CLI_ARG_LENGTH = 1024;
+
+/**
+ * Why `value` must not be passed to a spawned CLI as one argument, or `undefined` when it may.
+ *
+ * The reason is the whole of the message a refusal carries, so it says what to change. It is the
+ * rule {@link assertSafeCliArg} throws on and {@link isSafeCliArg} tests, written once so that the
+ * two can never disagree.
+ */
+export function cliArgProblem(value: unknown): string | undefined {
   if (typeof value !== "string" || value.length === 0) {
-    throw new Error(`Invalid ${label}: must be a non-empty string`);
+    return "must be a non-empty string";
   }
-  if (value.length > 1024) {
-    throw new Error(`Invalid ${label}: exceeds 1024 characters`);
+  if (value.length > MAX_CLI_ARG_LENGTH) {
+    return `exceeds ${String(MAX_CLI_ARG_LENGTH)} characters`;
   }
   if (value.startsWith("-")) {
-    throw new Error(
-      `Invalid ${label}: must not start with "-" (argv flag smuggling is not allowed)`,
-    );
+    return 'must not start with "-" (argv flag smuggling is not allowed)';
+  }
+  if (hasControlCharacter(value)) {
+    return "must not contain control characters";
   }
+  return undefined;
+}
+
+function hasControlCharacter(value: string): boolean {
   for (let i = 0; i < value.length; i += 1) {
     if ((value.codePointAt(i) ?? 0) < 0x20) {
-      throw new Error(`Invalid ${label}: must not contain control characters`);
+      return true;
     }
   }
-  return value;
+  return false;
 }
 
 /**
@@ -43,13 +73,85 @@ export function assertSafeCliArg(value: string, label = "argument"): string {
  * schema boundary before the handler ever shells out.
  */
 export function isSafeCliArg(value: unknown): value is string {
+  return cliArgProblem(value) === undefined;
+}
+
+// ---------------------------------------------------------------------------
+// aws
+// ---------------------------------------------------------------------------
+
+/**
+ * The prefixes with which the AWS CLI REPLACES a parameter's value by what it reads from
+ * somewhere else. Matched here case-insensitively and after leading whitespace, though the CLI
+ * matches them exactly: refusing a value the CLI would have taken as written costs nothing.
+ *
+ * `file://` and `fileb://` read a local file — for nearly every parameter, not only the ones
+ * documented as taking a document; the CLI exempts a short list whose value is itself a URL — and
+ * v1 of the CLI fetches an `http://` or `https://` value too, unless `cli_follow_urlparam` is
+ * turned off. The CLI then sends what it read to AWS as the value, and an
+ * error can quote it back — AWS's own validation errors name the value they reject — so a tool
+ * argument of `file://<path>` could hand the model the contents of a file on the user's machine.
+ */
+export const AWS_CLI_LOADING_PREFIXES = ["file://", "fileb://", "http://", "https://"] as const;
+
+function awsPrefixProblem(value: string): string | undefined {
+  const head = value.trimStart().toLowerCase();
+  const prefix = AWS_CLI_LOADING_PREFIXES.find((p) => head.startsWith(p));
+  return prefix === undefined
+    ? undefined
+    : `must not start with "${prefix}" (the aws CLI would read the value from that location)`;
+}
+
+/**
+ * `@=` is the AWS CLI v2 shorthand-syntax operator that loads a file into one key of a structure
+ * parameter, as in `TemplateBody@=file://<path>`. No tool passes a structure parameter today, so
+ * this is refused for the next tool that does rather than for any value that reaches the CLI now.
+ */
+function awsShorthandProblem(value: string): string | undefined {
+  return value.includes("@=")
+    ? 'must not contain "@=" (aws shorthand syntax would read a file into the value)'
+    : undefined;
+}
+
+/**
+ * Why `value` must not be passed to the AWS CLI as one argument, or `undefined` when it may: the
+ * universal rule, then a loading prefix ({@link AWS_CLI_LOADING_PREFIXES}), then `@=`.
+ */
+export function awsCliArgProblem(value: unknown): string | undefined {
   if (typeof value !== "string") {
-    return false;
+    return cliArgProblem(value);
   }
-  try {
-    assertSafeCliArg(value);
-    return true;
-  } catch {
-    return false;
+  return cliArgProblem(value) ?? awsPrefixProblem(value) ?? awsShorthandProblem(value);
+}
+
+// ---------------------------------------------------------------------------
+// az
+// ---------------------------------------------------------------------------
+
+function azFileProblem(value: string): string | undefined {
+  if (value.startsWith("@")) {
+    return 'must not start with "@" (az would read the value from a file)';
+  }
+  if (value.includes("=@")) {
+    return 'must not contain "=@" (az would read what follows from a file)';
+  }
+  return undefined;
+}
+
+/**
+ * Why `value` must not be passed to the Azure CLI as one argument, or `undefined` when it may: the
+ * universal rule, then a leading `@`, then `=@`.
+ *
+ * Before it parses anything, `az` replaces every argument that starts with `@` by the contents of
+ * the file named after it — with `~` expanded, and `@-` read from stdin — and does the same to
+ * whatever follows the first `=` in an argument. A resource group of
+ * `@~/.azure/msal_token_cache.json` would be sent to Azure as that cache, which a "could not be
+ * found" error can quote back. An `@` anywhere else, as in an email address, is left alone by `az`
+ * and is accepted here.
+ */
+export function azCliArgProblem(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return cliArgProblem(value);
   }
+  return cliArgProblem(value) ?? azFileProblem(value);
 }