@agentproto/driver-agent-cli 2.0.1 → 2.2.0

package/dist/{chunk-H43KNN32.mjs → chunk-TFB4QYOT.mjs}

@@ -5,8 +5,9 @@ import { spawn } from 'child_process';
 import { existsSync, readFileSync, mkdirSync, writeFileSync, rmSync, rmdirSync, mkdtempSync } from 'fs';
 import { createInterface } from 'readline';
 import { join } from 'path';
-import { randomUUID } from 'crypto';
 import { tmpdir, homedir } from 'os';
+import { loadAdapterSpawnSandboxConfig, resolveCommandSandbox } from '@agentproto/command-sandbox';
+import { randomUUID } from 'crypto';
 import { createDoctype } from '@agentproto/define-doctype';
 
 /**
@@ -151,10 +152,27 @@ var authSchema = z.object({
   }).strict().optional()
 }).strict();
 var authSubscriptionSchema = z.object({
-  setEnv: z.string().min(1),
+  setEnv: z.string().min(1).optional(),
+  external: z.boolean().optional(),
   conflictEnv: z.array(z.string()).optional(),
   unsetEnvAdd: z.array(z.string()).optional()
-}).strict();
+}).strict().superRefine((v, ctx) => {
+  if (v.external) {
+    if (v.setEnv !== void 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "authSubscription.external: true must NOT declare setEnv \u2014 an external (file-based) subscription injects no bearer; the CLI reads its own login file.",
+        path: ["setEnv"]
+      });
+    }
+  } else if (v.setEnv === void 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "authSubscription requires setEnv unless external: true (the bearer must be injected into some env var).",
+      path: ["setEnv"]
+    });
+  }
+});
 var sessionSchema = z.object({
   mode: z.enum(["ephemeral", "persistent", "resumable"]).default("ephemeral"),
   idle_timeout_ms: z.number().int().min(1e3).default(6e5),
@@ -185,8 +203,7 @@ var modelsSchema = z.object({
   // How a model is selected at session start: "config" (ACP
   // set_config_option, default) | "command" (a `/model <id>` control turn,
   // for agents like hermes that ignore the ACP session model config) |
-  // "arg" (a CLI argument composed into bin_args at spawn, for agents
-  // like codex-acp that take their model as `-c model="<id>"`).
+  // "arg" (a CLI argument composed into bin_args at spawn).
   apply: z.enum(["config", "command", "arg"]).optional(),
   // Argv template for apply:"arg" — {model} interpolates the requested
   // model id. See AgentCliModels.bin_args_template.
@@ -200,6 +217,13 @@ var capabilitiesSchema = z.object({
   multimodal: z.boolean().optional(),
   resumable: z.boolean().optional(),
   bidirectional: z.boolean().optional(),
+  /**
+   * Adapter has a verified native CLI resume into a real terminal/TUI
+   * session (e.g. `claude --resume <id>` or `hermes --resume <id> --tui`).
+   * When true, the host MAY restart this adapter via its native resume argv
+   * as a PTY session. Distinct from ACP-level `resumable`.
+   */
+  nativeTerminalResume: z.boolean().optional(),
   /**
    * Adapter can ingest a filesystem path that the host UI just placed
    * on disk (host-side drag-drop into a terminal pastes the path
@@ -300,7 +324,7 @@ var printConfigSchema = z.object({
     flag: z.string(),
     kind: z.enum(["value", "boolean"])
   }).strict().optional(),
-  event_schema: z.enum(["claude-stream-json", "mastra-jsonl"]).optional()
+  event_schema: z.enum(["claude-stream-json", "mastra-jsonl", "antigravity-stream-json"]).optional()
 }).strict().optional();
 var agentCliFrontmatterSchema = z.object({
   name: z.string().min(1).max(80),
@@ -321,6 +345,26 @@ var agentCliFrontmatterSchema = z.object({
   // keep this generic doctype decoupled from @agentproto/model-catalog).
   provider: z.string().min(1).optional(),
   authSubscription: authSubscriptionSchema.optional(),
+  // How this adapter receives a GATEWAY-routed bearer credential — see the
+  // doc on AgentCliDefinition.gatewayAuth. Distinct from a gateway preset's
+  // `keyEnv` (the providers-store lookup key) and from
+  // authSubscription.setEnv (this adapter's own native bearer).
+  gatewayAuth: z.object({
+    setEnv: z.string().min(1)
+  }).strict().optional(),
+  // Auth-derivation axis (DECISION 3): true when the adapter's api-key auth
+  // is derived from the requested model rather than a fixed `provider`
+  // (e.g. `pi`, `opencode`, `mastracode`). When set, the runtime resolver
+  // allows `"api-key"` mode on the model-derived direct endpoint and
+  // includes it in eligibility manifests for by-model routers. DISTINCT
+  // from `routeSelection` (the UI-facing route-choice axis).
+  modelDerivedApiKey: z.boolean().optional(),
+  // UI-facing route-choice axis (AIP-45 launch-menu drill-down, WP1).
+  // Absent ⇒ "free" (route is an independent choice); "derived-from-model"
+  // means the endpoint falls out of the model id's vendor prefix. DISTINCT
+  // from `modelDerivedApiKey` (the auth-derivation axis) — see the field
+  // doc on AgentCliDefinition.routeSelection.
+  routeSelection: z.enum(["free", "derived-from-model"]).optional(),
   authEnforce: z.enum(["always", "when-configured"]).optional(),
   sandbox: z.union([z.string(), z.record(z.string(), z.unknown())]),
   runner: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
@@ -539,6 +583,69 @@ function toFileBasedMcpServers(servers) {
   }
   return out;
 }
+function defaultToolchainWritePaths() {
+  const home = homedir();
+  return [
+    join(home, "Library", "pnpm", ".tools"),
+    // macOS pnpm self-managed toolchain
+    join(home, ".local", "share", "pnpm"),
+    // Linux pnpm self-managed toolchain
+    join(home, ".npm"),
+    // npm cache — self-update / global installs
+    join(home, ".claude", "session-env")
+    // claude-code's own Bash-tool session bookkeeping
+  ];
+}
+function defaultToolchainReadPaths() {
+  const home = homedir();
+  return [
+    join(home, ".npmrc"),
+    join(home, "Library", "Preferences", "pnpm", "rc"),
+    join(home, ".gitconfig"),
+    // git's own global config (credential.helper, user.*, …)
+    join(home, ".config", "git"),
+    // XDG git config fallback
+    join(home, ".config", "gh"),
+    // gh's config.yml + hosts.yml
+    join(home, "Library", "Keychains")
+    // macOS Keychain DB — git/gh credential retrieval (read-only; see doc above)
+  ];
+}
+async function wrapAgentCliSpawn(bin, args, opts) {
+  const cfg = await loadAdapterSpawnSandboxConfig(opts.cwd);
+  const mode = opts.mode ?? cfg.mode;
+  if (mode === void 0) return [bin, args];
+  if (mode === "off") {
+    console.error(
+      `[agent-cli] \u26A0 spawning '${opts.label}' UNCONFINED \u2014 no OS-level sandbox is active (commandSandbox mode is "off").`
+    );
+    return [bin, args];
+  }
+  const backend = resolveCommandSandbox();
+  if (!backend) {
+    throw new Error(
+      `agent-cli '${opts.label}': commandSandbox mode="${mode}" is configured but no sandbox backend is available on ${process.platform} (macOS needs sandbox-exec, Linux needs bwrap installed). Refusing to spawn unconfined \u2014 pass commandSandbox: "off" to explicitly accept unconfined execution, or install the missing backend.`
+    );
+  }
+  const policy = {
+    workspace: opts.cwd,
+    extraReadPaths: [
+      ...defaultToolchainReadPaths(),
+      ...cfg.extraReadPaths,
+      ...opts.extraReadPaths ?? []
+    ],
+    extraWritePaths: [
+      ...defaultToolchainWritePaths(),
+      ...cfg.extraWritePaths,
+      ...opts.extraWritePaths ?? []
+    ],
+    network: mode === "strict" || cfg.network === "deny" ? "deny" : "allow"
+  };
+  const wrapped = backend.wrap([bin, ...args], policy);
+  return [wrapped[0] ?? bin, wrapped.slice(1)];
+}
+
+// src/protocol/print-arm.ts
 var DEFAULT_OUTPUT = ["--output-format", "stream-json"];
 var DEFAULT_PRE_PROMPT = ["--no-interactive"];
 var DEFAULT_RESUME = { flag: "--resume", kind: "value" };
@@ -572,7 +679,13 @@ function createPrintSession(opts) {
       } else {
         args.push(prompt);
       }
-      const child = spawn(opts.bin, args, {
+      const [execBin, execArgs] = await wrapAgentCliSpawn(opts.bin, args, {
+        mode: opts.commandSandbox,
+        cwd: opts.cwd,
+        ...opts.extraWritePaths ? { extraWritePaths: opts.extraWritePaths } : {},
+        label: "print-arm"
+      });
+      const child = spawn(execBin, execArgs, {
         cwd: opts.cwd,
         env: opts.env,
         stdio: ["ignore", "pipe", "pipe"]
@@ -607,7 +720,11 @@ function createPrintSession(opts) {
           if (csid) capturedSessionId = csid;
           const sid = capturedSessionId || sessionId || "";
           const mapped = mapEvent(evt, sid, stderrLines, eventSchema, mastraState);
-          if (mapped) queue.push(mapped);
+          if (Array.isArray(mapped)) {
+            for (const m of mapped) queue.push(m);
+          } else if (mapped) {
+            queue.push(mapped);
+          }
         });
         rl.once("close", () => queue.end());
         for await (const mapped of queue) {
@@ -616,7 +733,7 @@ function createPrintSession(opts) {
         const exitCode = await waitForExit(child);
         if (capturedSessionId) sessionId = capturedSessionId;
         if (exitCode !== 0 && exitCode !== null) {
-          const binLabel = eventSchema === "mastra-jsonl" ? "mastracode" : "claude";
+          const binLabel = eventSchema === "mastra-jsonl" ? "mastracode" : eventSchema === "antigravity-stream-json" ? "agy" : "claude";
           const errEvt = {
             kind: "error",
             error: {
@@ -751,6 +868,16 @@ function captureSessionId(evt, schema) {
       if (evt.type === "result" && typeof evt.session_id === "string" && evt.session_id)
         return evt.session_id;
       return null;
+    case "antigravity-stream-json": {
+      if (evt.event === "init" && typeof evt.conversation_id === "string" && evt.conversation_id)
+        return evt.conversation_id;
+      if (evt.event === "result") {
+        const r = evt.result;
+        if (typeof r?.conversation_id === "string" && r.conversation_id)
+          return r.conversation_id;
+      }
+      return null;
+    }
     case "mastra-jsonl":
       if (evt.type === "result" && typeof evt.threadId === "string" && evt.threadId)
         return evt.threadId;
@@ -761,6 +888,8 @@ function mapEvent(evt, sessionId, stderrLines, schema, mastraState) {
   switch (schema) {
     case "claude-stream-json":
       return mapClaudeEvent(evt, sessionId, stderrLines);
+    case "antigravity-stream-json":
+      return mapAntigravityEvent(evt, sessionId, stderrLines);
     case "mastra-jsonl": {
       if (!mastraState) {
         return mapClaudeEvent(evt, sessionId, stderrLines);
@@ -815,6 +944,93 @@ function mapClaudeEvent(evt, sessionId, stderrLines) {
       return null;
   }
 }
+function mapAntigravityEvent(evt, sessionId, stderrLines) {
+  switch (evt.event) {
+    case "step_update": {
+      const su = evt.step_update;
+      if (!su) return null;
+      const stepType = su.step_type;
+      if (stepType === "agent_response" && typeof su.text_delta === "string" && su.text_delta) {
+        return { kind: "text-delta", sessionId, text: su.text_delta };
+      }
+      if (stepType === "tool" && su.state === "DONE") {
+        const ti = su.tool_info;
+        const toolName = typeof su.tool_name === "string" && su.tool_name ? su.tool_name : typeof ti?.name === "string" && ti.name ? ti.name : "?";
+        const toolCallId = typeof su.step_index === "number" ? `step-${su.step_index}` : "";
+        const err = ti?.error;
+        const call = {
+          kind: "tool-call",
+          sessionId,
+          toolCallId,
+          toolName,
+          arguments: ti?.parameters ?? {}
+        };
+        const result = {
+          kind: "tool-result",
+          sessionId,
+          toolCallId,
+          result: err ? typeof err.message === "string" ? err.message : err : ti?.output ?? null,
+          isError: !!err
+        };
+        return [call, result];
+      }
+      return null;
+    }
+    case "result": {
+      const r = evt.result;
+      if (!r) return null;
+      const status = typeof r.status === "string" ? r.status : "";
+      const out = [];
+      const usage = mapAntigravityUsage(r.usage, sessionId);
+      if (usage) out.push(usage);
+      if (status === "ERROR" || status === "INVALID") {
+        out.push({
+          kind: "error",
+          sessionId,
+          error: {
+            message: typeof r.error === "string" && r.error ? r.error : `agy run ended with status ${status || "ERROR"}`,
+            ...stderrLines.length ? { data: { stderr: stderrLines.join("\n") } } : {}
+          }
+        });
+      } else {
+        out.push({
+          kind: "turn-end",
+          sessionId,
+          reason: mapAntigravityStatus(status)
+        });
+      }
+      return out.length ? out : null;
+    }
+    // init and any unknown event carry no host-facing StreamEvent.
+    default:
+      return null;
+  }
+}
+function mapAntigravityStatus(raw) {
+  switch (raw) {
+    case "CANCELED":
+    case "INTERRUPTED":
+      return "cancelled";
+    // SUCCESS, WAITING, RUNNING (or anything else non-error): the turn ended.
+    default:
+      return "completed";
+  }
+}
+function mapAntigravityUsage(usage, sessionId) {
+  if (usage === null || typeof usage !== "object") return null;
+  const u = usage;
+  const tokensIn = typeof u.input_tokens === "number" ? u.input_tokens : void 0;
+  const tokensOut = typeof u.output_tokens === "number" ? u.output_tokens : void 0;
+  if (tokensIn === void 0 && tokensOut === void 0) return null;
+  return {
+    kind: "usage_update",
+    sessionId,
+    size: 0,
+    used: 0,
+    ...tokensIn !== void 0 ? { tokensIn } : {},
+    ...tokensOut !== void 0 ? { tokensOut } : {}
+  };
+}
 function createMastraMapperState() {
   return { lastTextLength: 0 };
 }
@@ -1262,6 +1478,102 @@ function interpolateEnv(env, value) {
   }
   return out;
 }
+function createArmSessionControls(arm, definition) {
+  const modelApply = definition.models?.apply ?? "config";
+  return {
+    // Capability read-surface (SPEC §3.9/§3.4a) — snapshotted once
+    // `arm.connect()` has resolved. Not live-updated by a later
+    // `setModel`/`setSessionMode` call.
+    availableConfigOptions: arm.availableConfigOptions ?? [],
+    availableModes: arm.availableModes ?? [],
+    currentModeId: arm.currentModeId,
+    /**
+     * Mid-session model switch — the runtime counterpart to the
+     * spawn-time model apply. Dispatches on the same
+     * `definition.models.apply` strategy so a live switch behaves
+     * exactly like the spawn-time apply would have, just against an
+     * already-running session.
+     */
+    async setModel(modelId) {
+      if (modelApply === "arg") {
+        return { applied: false, reason: "requires-restart" };
+      }
+      if (modelApply === "command") {
+        return applyModelCommand(arm, modelId);
+      }
+      if (!arm.setConfigOption) {
+        return { applied: false, reason: "not-supported" };
+      }
+      const result = await arm.setConfigOption("model", modelId);
+      return result.applied ? { applied: true, model: modelId } : { applied: false, ...result.reason ? { reason: result.reason } : {} };
+    },
+    /**
+     * Mid-session posture switch — the native-mode counterpart to
+     * `setModel`, wired directly to the arm's `setSessionMode` (only the
+     * ACP arm implements it).
+     */
+    async setSessionMode(modeId) {
+      if (!arm.setSessionMode) {
+        return { applied: false, reason: "not-supported" };
+      }
+      const result = await arm.setSessionMode(modeId);
+      return result.applied ? { applied: true, modeId } : { applied: false, ...result.reason ? { reason: result.reason } : {} };
+    },
+    /**
+     * Mid-session effort switch — the effort-axis counterpart to
+     * `setModel`'s `"config"` strategy, wired to the same
+     * `arm.setConfigOption` surface with `configId:"effort"`. Best-effort:
+     * an effort label the current model rejects resolves
+     * `{applied:false, reason}` (SPEC risk R7).
+     */
+    async setEffort(effort) {
+      if (!arm.setConfigOption) {
+        return { applied: false, reason: "not-supported" };
+      }
+      const result = await arm.setConfigOption("effort", effort);
+      return result.applied ? { applied: true, effort } : { applied: false, ...result.reason ? { reason: result.reason } : {} };
+    }
+  };
+}
+async function applyModelCommand(arm, modelId) {
+  const turnId = randomUUID();
+  let acked = false;
+  try {
+    for await (const evt of promptTurn(arm, turnId, {
+      type: "text",
+      text: `/model ${modelId}`
+    })) {
+      if (/switch|model\s+set|now using/i.test(JSON.stringify(evt))) acked = true;
+    }
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    console.warn(
+      `[agent-cli] /model ${modelId} control turn failed (continuing on default):`,
+      err instanceof Error ? err.message : err
+    );
+    return { applied: false, reason };
+  }
+  if (!acked) {
+    const reason = "no switch acknowledgement \u2014 agent may be on its default model";
+    console.warn(`[agent-cli] /model ${modelId}: ${reason}`);
+    return { applied: false, reason };
+  }
+  return { applied: true, model: modelId };
+}
+async function* promptTurn(arm, turnId, message) {
+  await arm.send(turnId, message);
+  const stderrTail = arm._stderrTail;
+  for await (const evt of arm.events()) {
+    if (evt.kind === "error" && typeof stderrTail === "function") {
+      const tail = stderrTail();
+      if (tail) {
+        const existing = evt.error.data ?? {};
+        evt.error.data = { ...existing, stderr: tail };
+      }
+    }
+    yield evt;
+  }
+}
 var defineAgentCli = createDoctype(
   {
     aip: 45,
@@ -1311,21 +1623,11 @@ function createAgentCliRuntime(definition) {
     definition,
     async start(opts) {
       const cwd = opts?.cwd ?? process.cwd();
-      const cliEnv = {
-        ...filterStringEnv(process.env),
-        ...opts?.env ?? {}
-      };
-      const codexAuthMode = definition.id === "codex" ? detectCodexAuthMode(cliEnv, opts?.auth) : void 0;
-      const skipModelArg = definition.id === "codex" && codexAuthMode !== "api-key";
-      const composed = composeSpawn(definition, opts?.config, {
-        skipModelArg
-      });
-      const requestedModel = opts?.config?.options?.model;
-      if (skipModelArg && typeof requestedModel === "string") {
-        console.warn(
-          `[agent-cli] codex: skipped model override "${requestedModel}" for ChatGPT-account auth; using Codex's default model.`
-        );
-      }
+      const contextMode = opts?.contextProfile ? (definition.modes ?? []).find(
+        (mode) => mode.id === opts.contextProfile && mode.kind === "context"
+      ) : void 0;
+      const config = opts?.config?.mode || !contextMode ? opts?.config : { ...opts?.config, mode: contextMode.id };
+      const composed = composeSpawn(definition, config);
       const env = {
         ...filterStringEnv(process.env),
         ...composed.env
@@ -1334,36 +1636,48 @@ function createAgentCliRuntime(definition) {
       const authSpec = opts?.auth;
       const hasGatewayAuthToken = "ANTHROPIC_AUTH_TOKEN" in composed.env;
       const hasGatewayBaseUrl = "ANTHROPIC_BASE_URL" in composed.env;
-      const engageAuth = !!authSpec && !hasGatewayAuthToken && !hasGatewayBaseUrl && (authSpec.enforce === "always" || authSpec.explicit === true);
+      const resolverCoupledGateway = authSpec?.baseUrl !== void 0;
+      const engageAuth = !!authSpec && !hasGatewayAuthToken && (resolverCoupledGateway || !hasGatewayBaseUrl) && (authSpec.enforce === "always" || authSpec.explicit === true);
       if (authSpec && engageAuth) {
         for (const key of authSpec.unsetEnv) {
           if (!(key in composed.env)) delete env[key];
         }
-        if (!authSpec.credential) {
-          const slug = definition.id;
-          const providerLabel = definition.provider ?? "<provider>";
-          const configBlock = `{"defaults":{"adapters":{"${slug}":{"auth":{"mode":"api-key"}}}}} in ~/.agentproto/config.json`;
-          const storeHint = authSpec.ignoredApiKeyInStore ? ` (providers.json already has a stored key for ${providerLabel} \u2014 ignored until that block exists)` : "";
-          const supportsSub = !!definition.authSubscription;
-          const message = authSpec.neitherConfigured && supportsSub ? `agent-cli '${slug}': no billing auth. Subscription \u2192 \`claude setup-token\`. Api-key \u2192 \`agentproto auth provider set ${providerLabel} sk-\u2026\`${storeHint}. Add ${configBlock}. Never inherited from the shell.` : authSpec.mode === "subscription" ? `agent-cli '${slug}': run \`claude setup-token\` and configure the result \u2014 bills the Max/Pro subscription, not API credits. Never inherited from the shell.` : `agent-cli '${slug}': run \`agentproto auth provider set ${providerLabel} sk-\u2026\`${storeHint}, then add ${configBlock}. Never inherited from the shell.`;
-          throw new RuntimeConfigError("missing_auth_credential", "opts.auth.credential", message);
+        if (!authSpec.externalCredential) {
+          if (!authSpec.credential) {
+            const slug = definition.id;
+            const providerLabel = definition.provider ?? "<provider>";
+            const configBlock = `{"defaults":{"adapters":{"${slug}":{"auth":{"mode":"api-key"}}}}} in ~/.agentproto/config.json`;
+            const storeHint = authSpec.ignoredApiKeyInStore ? ` (providers.json already has a stored key for ${providerLabel} \u2014 ignored until that block exists)` : "";
+            const supportsSub = !!definition.authSubscription;
+            const message = authSpec.neitherConfigured && supportsSub ? `agent-cli '${slug}': no billing auth. Subscription \u2192 \`claude setup-token\`. Api-key \u2192 \`agentproto auth provider set ${providerLabel} sk-\u2026\`${storeHint}. Add ${configBlock}. Never inherited from the shell.` : authSpec.mode === "subscription" ? `agent-cli '${slug}': run \`claude setup-token\` and configure the result \u2014 bills the Max/Pro subscription, not API credits. Never inherited from the shell.` : `agent-cli '${slug}': run \`agentproto auth provider set ${providerLabel} sk-\u2026\`${storeHint}, then add ${configBlock}. Never inherited from the shell.`;
+            throw new RuntimeConfigError("missing_auth_credential", "opts.auth.credential", message);
+          }
+          env[authSpec.setEnv] = authSpec.credential;
         }
-        env[authSpec.setEnv] = authSpec.credential;
       }
       Object.assign(env, opts?.env ?? {});
       const permissionMode = resolveClaudeCodePermissionMode(
         definition,
-        opts?.config?.mode
+        opts?.posture,
+        config?.mode
       );
-      if (permissionMode) {
-        const configDir = mkdtempSync(
+      const isolateClaudeCodeConfig = definition.id === "claude-code";
+      let claudeConfigDir;
+      if (isolateClaudeCodeConfig) {
+        claudeConfigDir = mkdtempSync(
           join(tmpdir(), "agentproto-claude-config-")
         );
         writeFileSync(
-          join(configDir, "settings.json"),
-          JSON.stringify({ permissions: { defaultMode: permissionMode } })
+          join(claudeConfigDir, ".claude.json"),
+          JSON.stringify({ mcpServers: {} })
         );
-        env.CLAUDE_CONFIG_DIR = configDir;
+        if (permissionMode) {
+          writeFileSync(
+            join(claudeConfigDir, "settings.json"),
+            JSON.stringify({ permissions: { defaultMode: permissionMode } })
+          );
+        }
+        env.CLAUDE_CONFIG_DIR = claudeConfigDir;
       }
       if (definition.protocol === "print") {
         return createPrintSession({
@@ -1373,13 +1687,25 @@ function createAgentCliRuntime(definition) {
           env,
           ...opts?.resumeSessionId ? { resumeSessionId: opts.resumeSessionId } : {},
           ...opts?.mcpServers ? { mcpServers: opts.mcpServers } : {},
-          printConfig: definition.print
+          printConfig: definition.print,
+          commandSandbox: opts?.commandSandbox,
+          ...claudeConfigDir ? { extraWritePaths: [claudeConfigDir] } : {}
         });
       }
       let child;
       const stderrBuf = [];
       if (definition.protocol !== "proprietary") {
-        child = spawn(definition.bin, composed.binArgs, {
+        const [execBin, execArgs] = await wrapAgentCliSpawn(
+          definition.bin,
+          composed.binArgs,
+          {
+            mode: opts?.commandSandbox,
+            cwd,
+            ...claudeConfigDir ? { extraWritePaths: [claudeConfigDir] } : {},
+            label: definition.id
+          }
+        );
+        child = spawn(execBin, execArgs, {
           cwd,
           env,
           stdio: ["pipe", "pipe", "pipe"],
@@ -1399,7 +1725,7 @@ function createAgentCliRuntime(definition) {
         definition,
         child,
         cwd,
-        opts?.config?.mode,
+        config?.mode,
         opts?.permissionHold ?? false
       );
       arm._stderrTail = () => stderrBuf.join("\n");
@@ -1409,11 +1735,11 @@ function createAgentCliRuntime(definition) {
           once: true
         });
       }
-      const optModel = opts?.config?.options?.model;
-      const optEffort = opts?.config?.options?.effort;
+      const optModel = config?.options?.model;
+      const optEffort = config?.options?.effort;
       const modelApply = definition.models?.apply ?? "config";
       const configModel = optModel && modelApply === "config" ? String(optModel) : void 0;
-      const requestedModeId = opts?.config?.mode;
+      const requestedModeId = config?.mode;
       const requestedModeDecl = requestedModeId ? (definition.modes ?? []).find((m) => m.id === requestedModeId) : void 0;
       const configMode = requestedModeDecl?.apply === "config" ? requestedModeId : void 0;
       const turnIdleTimeoutMs = opts?.turnIdleTimeoutMs ?? definition.session?.turn_idle_timeout_ms;
@@ -1438,15 +1764,11 @@ function createAgentCliRuntime(definition) {
       return {
         sessionId,
         pid: child?.pid,
-        // Capability read-surface (SPEC §3.9/§3.4a) — snapshotted once
-        // `arm.connect()` above has resolved, so an ACP arm's captured
-        // `newSession`/`loadSession` response is already populated. Arms
-        // that don't model this (print, proprietary) leave the getters
-        // undefined, defaulted here to the same empty/absent shape their
-        // `setModel`-style counterparts use for "not supported".
-        availableConfigOptions: arm.availableConfigOptions ?? [],
-        availableModes: arm.availableModes ?? [],
-        currentModeId: arm.currentModeId,
+        // Live model/mode/effort switches + the capability read-surface,
+        // all pure arm delegation — shared with every host that builds
+        // its own session over another transport. See session-controls.ts.
+        // Snapshotted after `arm.connect()` above resolved.
+        ...createArmSessionControls(arm, definition),
         send(message) {
           const turnId = randomUUID();
           currentTurnId = turnId;
@@ -1485,58 +1807,6 @@ function createAgentCliRuntime(definition) {
             return arm.respondPermission(requestId, resolution);
           }
         } : {},
-        /**
-         * Mid-session model switch — the runtime counterpart to the
-         * spawn-time `modelApply` handling above. Dispatches on the same
-         * `definition.models.apply` strategy so a live switch behaves
-         * exactly like the spawn-time apply would have, just against an
-         * already-running session. See {@link SetModelResult} for the
-         * reason vocabulary; this never throws and never tears down the
-         * session on a rejected switch.
-         */
-        async setModel(modelId) {
-          if (modelApply === "arg") {
-            return { applied: false, reason: "requires-restart" };
-          }
-          if (modelApply === "command") {
-            return applyModelCommand(arm, modelId);
-          }
-          if (!arm.setConfigOption) {
-            return { applied: false, reason: "not-supported" };
-          }
-          const result = await arm.setConfigOption("model", modelId);
-          return result.applied ? { applied: true, model: modelId } : { applied: false, ...result.reason ? { reason: result.reason } : {} };
-        },
-        /**
-         * Mid-session posture switch — the native-mode counterpart to
-         * `setModel`, wired directly to the arm's `setSessionMode` (only
-         * the ACP arm implements it). See {@link SetSessionModeResult} for
-         * the reason vocabulary; this never throws and never tears down
-         * the session on a rejected switch.
-         */
-        async setSessionMode(modeId) {
-          if (!arm.setSessionMode) {
-            return { applied: false, reason: "not-supported" };
-          }
-          const result = await arm.setSessionMode(modeId);
-          return result.applied ? { applied: true, modeId } : { applied: false, ...result.reason ? { reason: result.reason } : {} };
-        },
-        /**
-         * Mid-session effort switch — the effort-axis counterpart to
-         * `setModel`'s `"config"` strategy, wired to the same
-         * `arm.setConfigOption` surface with `configId:"effort"` (only the
-         * ACP arm implements it). Best-effort and non-fatal: an effort label
-         * the current model rejects resolves `{applied:false, reason}` (SPEC
-         * risk R7), never thrown and never tearing down the session. See
-         * {@link SetEffortResult} for the reason vocabulary.
-         */
-        async setEffort(effort) {
-          if (!arm.setConfigOption) {
-            return { applied: false, reason: "not-supported" };
-          }
-          const result = await arm.setConfigOption("effort", effort);
-          return result.applied ? { applied: true, effort } : { applied: false, ...result.reason ? { reason: result.reason } : {} };
-        },
         async close() {
           await arm.close();
           if (child && !child.killed) child.kill("SIGTERM");
@@ -1545,45 +1815,6 @@ function createAgentCliRuntime(definition) {
     }
   };
 }
-async function applyModelCommand(arm, modelId) {
-  const turnId = randomUUID();
-  let acked = false;
-  try {
-    for await (const evt of promptTurn(arm, turnId, {
-      type: "text",
-      text: `/model ${modelId}`
-    })) {
-      if (/switch|model\s+set|now using/i.test(JSON.stringify(evt))) acked = true;
-    }
-  } catch (err) {
-    const reason = err instanceof Error ? err.message : String(err);
-    console.warn(
-      `[agent-cli] /model ${modelId} control turn failed (continuing on default):`,
-      err instanceof Error ? err.message : err
-    );
-    return { applied: false, reason };
-  }
-  if (!acked) {
-    const reason = "no switch acknowledgement \u2014 agent may be on its default model";
-    console.warn(`[agent-cli] /model ${modelId}: ${reason}`);
-    return { applied: false, reason };
-  }
-  return { applied: true, model: modelId };
-}
-async function* promptTurn(arm, turnId, message) {
-  await arm.send(turnId, message);
-  const stderrTail = arm._stderrTail;
-  for await (const evt of arm.events()) {
-    if (evt.kind === "error" && typeof stderrTail === "function") {
-      const tail = stderrTail();
-      if (tail) {
-        const existing = evt.error.data ?? {};
-        evt.error.data = { ...existing, stderr: tail };
-      }
-    }
-    yield evt;
-  }
-}
 async function buildProtocolArm(def, child, cwd, requestedMode, permissionHold) {
   switch (def.protocol) {
     case "acp":
@@ -1610,8 +1841,18 @@ async function buildProtocolArm(def, child, cwd, requestedMode, permissionHold)
       throw new Error("createAgentCliRuntime: print arm bypasses buildProtocolArm");
   }
 }
-function resolveClaudeCodePermissionMode(definition, configMode) {
-  if (definition.id !== "claude-code" || !configMode) return void 0;
+function resolveClaudeCodePermissionMode(definition, posture, configMode) {
+  if (definition.id !== "claude-code") return void 0;
+  const canonicalPermissionMode = {
+    plan: "plan",
+    "read-only": "plan",
+    "accept-edits": "acceptEdits",
+    bypass: "bypassPermissions"
+  };
+  if (posture && canonicalPermissionMode[posture]) {
+    return canonicalPermissionMode[posture];
+  }
+  if (!configMode) return void 0;
   const mode = (definition.modes ?? []).find((m) => m.id === configMode);
   const args = mode?.bin_args_append ?? [];
   const flagIndex = args.indexOf("--permission-mode");
@@ -1625,22 +1866,7 @@ function filterStringEnv(env) {
   }
   return out;
 }
-function detectCodexAuthMode(env, authSpec) {
-  if (authSpec?.credential && (authSpec.explicit === true || authSpec.enforce === "always")) {
-    return authSpec.mode === "api-key" ? "api-key" : "chatgpt";
-  }
-  if (env.OPENAI_API_KEY || env.CODEX_API_KEY) return "api-key";
-  const authPath = join(homedir(), ".codex", "auth.json");
-  try {
-    const parsed = JSON.parse(readFileSync(authPath, "utf8"));
-    if (parsed.auth_mode === "api-key" || parsed.auth_mode === "chatgpt") {
-      return parsed.auth_mode;
-    }
-  } catch {
-  }
-  return "chatgpt";
-}
 
-export { LEGACY_GATEWAY_MODE_IDS, LEGACY_POSTURE_MODE_IDS, RuntimeConfigError, agentCliFrontmatterSchema, autoAllowPermissionHandler, composeSpawn, createAcpProtocolArm, createAgentCliRuntime, createMastraMapperState, createPrintSession, createProprietaryProtocolArm, defineAgentCli, inferLegacyModeKind, isLegacyExtractedModeId, mapMastraEvent, planModePermissionHandler, resolveContinuationStrategy, runtimeConfigSchema, toFileBasedMcpServers };
-//# sourceMappingURL=chunk-H43KNN32.mjs.map
-//# sourceMappingURL=chunk-H43KNN32.mjs.map
+export { LEGACY_GATEWAY_MODE_IDS, LEGACY_POSTURE_MODE_IDS, RuntimeConfigError, agentCliFrontmatterSchema, applyModelCommand, autoAllowPermissionHandler, composeSpawn, createAcpProtocolArm, createAgentCliRuntime, createArmSessionControls, createMastraMapperState, createPrintSession, createProprietaryProtocolArm, defineAgentCli, inferLegacyModeKind, isLegacyExtractedModeId, mapMastraEvent, planModePermissionHandler, promptTurn, resolveContinuationStrategy, runtimeConfigSchema, toFileBasedMcpServers };
+//# sourceMappingURL=chunk-TFB4QYOT.mjs.map
+//# sourceMappingURL=chunk-TFB4QYOT.mjs.map