@agentex/agent 0.0.24 → 0.0.26

package/src/providers/claude/attach.ts

@@ -0,0 +1,147 @@
+import { stat } from "node:fs/promises";
+import type {
+  AttachOptions,
+  CatchUpOptions,
+  CatchUpYield,
+  FoundTranscript,
+  LastTurnStatus,
+  SessionAttachment,
+  SessionContext,
+  SessionRecord,
+} from "../../types.js";
+import {
+  assertSessionRecord,
+  createSessionRecord,
+  MalformedSessionRecordError,
+} from "../../sessions/record.js";
+import { getRuntimeHomeEnvVar } from "../../utils/runtime-homes.js";
+import { claudeSessionCodec } from "./codec.js";
+import {
+  findClaudeTranscriptBySessionId,
+  getClaudeTranscriptPath,
+  peekClaudeTranscript,
+  readClaudeTranscript,
+} from "./transcript.js";
+// Heavy-on-heavy is fine: this whole module loads lazily via
+// `claudeProvider.attachSession`, behind the same dynamic-import boundary as
+// `session.ts` itself (spec §5.3 / §9.6).
+import { createClaudeSession } from "./session.js";
+
+async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Home-dir override derived from `opts.env` (same var the transcript helpers honor). */
+function homeOverride(opts?: AttachOptions): string | undefined {
+  const key = getRuntimeHomeEnvVar("claude");
+  return key ? opts?.env?.[key] : undefined;
+}
+
+/**
+ * Locate a Claude transcript with an optional home override — mirrors
+ * `claudeTranscriptOps.find` (cwd fast-path, then session-id scan) but threads
+ * `claudeHome` through so `AttachOptions.env` is honored without mutating
+ * `process.env`.
+ */
+async function locate(
+  sessionId: string,
+  cwd: string | null,
+  claudeHome: string | undefined,
+): Promise<FoundTranscript | null> {
+  if (cwd) {
+    const loc = await getClaudeTranscriptPath({
+      sessionId,
+      cwd,
+      ...(claudeHome ? { claudeHome } : {}),
+    });
+    if (await pathExists(loc.filePath)) {
+      return { filePath: loc.filePath, cwd: loc.canonicalCwd };
+    }
+    // cwd was wrong (session launched in a different worktree) → fall through.
+  }
+  const found = await findClaudeTranscriptBySessionId({
+    sessionId,
+    ...(claudeHome ? { claudeHome } : {}),
+  });
+  return found ? { filePath: found.filePath, cwd: found.cwd } : null;
+}
+
+const EMPTY: AsyncIterable<CatchUpYield> = {
+  async *[Symbol.asyncIterator]() {
+    /* no transcript → nothing to replay */
+  },
+};
+
+/**
+ * Read-only reattachment to a durable Claude session. Composition of existing
+ * primitives (codec + transcript ops + `createClaudeSession` resume) — spawns
+ * nothing; `resume` is the one and only live-continuation path.
+ */
+export async function attachClaudeSession(
+  record: SessionRecord,
+  opts?: AttachOptions,
+): Promise<SessionAttachment> {
+  assertSessionRecord(record);
+
+  // 1. Normalize params through the codec.
+  const params = claudeSessionCodec.deserialize(record.params);
+  if (!params) {
+    throw new MalformedSessionRecordError(
+      "claude session record params carry no usable sessionId",
+      "params",
+    );
+  }
+  const sessionId = params["sessionId"] as string;
+  const cwd =
+    (typeof params["cwd"] === "string" ? (params["cwd"] as string) : null) ?? record.cwd ?? null;
+
+  const normalized = createSessionRecord({
+    providerType: "claude",
+    params,
+    cwd,
+    displayId: claudeSessionCodec.getDisplayId?.(params) ?? null,
+  });
+
+  // 2. Locate the transcript (honoring opts.env home override).
+  const transcript = await locate(sessionId, cwd, homeOverride(opts));
+
+  // 3. Classify how the last persisted turn ended.
+  let lastTurn: LastTurnStatus = "unknown";
+  if (transcript) {
+    const { lastEvent } = await peekClaudeTranscript(transcript.filePath);
+    if (lastEvent === null) lastTurn = "unknown";
+    else if (lastEvent.type === "result") lastTurn = "completed";
+    else lastTurn = "interrupted";
+  }
+
+  return {
+    record: normalized,
+    transcript,
+    lastTurn,
+    // 4. Replay normalized events with checkpointable offsets.
+    catchUp(catchOpts?: CatchUpOptions): AsyncIterable<CatchUpYield> {
+      if (!transcript) return EMPTY;
+      const filePath = transcript.filePath;
+      return {
+        async *[Symbol.asyncIterator]() {
+          for await (const { event, offset } of readClaudeTranscript({
+            filePath,
+            ...(catchOpts?.fromOffset !== undefined ? { fromOffset: catchOpts.fromOffset } : {}),
+            ...(catchOpts?.sinceEventId !== undefined ? { sinceEventId: catchOpts.sinceEventId } : {}),
+          })) {
+            yield { event, offset, eventId: event.eventId };
+          }
+        },
+      };
+    },
+    // 5. Continue live — exactly `createSession` with the record's params.
+    resume(ctx?: SessionContext) {
+      return createClaudeSession({ ...ctx, sessionParams: params });
+    },
+  };
+}

package/src/providers/claude/codec.ts

@@ -0,0 +1,43 @@
+import type { SessionCodec } from "../../types.js";
+
+function readNonEmptyString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function parseAsObject(raw: unknown): Record<string, unknown> | null {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+  return raw as Record<string, unknown>;
+}
+
+export const claudeSessionCodec: SessionCodec = {
+  deserialize(raw: unknown): Record<string, unknown> | null {
+    const obj = parseAsObject(raw);
+    if (!obj) return null;
+    const sessionId = readNonEmptyString(obj["sessionId"]) ?? readNonEmptyString(obj["session_id"]);
+    if (!sessionId) return null;
+    const cwd =
+      readNonEmptyString(obj["cwd"]) ??
+      readNonEmptyString(obj["workdir"]) ??
+      readNonEmptyString(obj["folder"]);
+    return {
+      sessionId,
+      ...(cwd ? { cwd } : {}),
+    };
+  },
+
+  serialize(params: Record<string, unknown> | null): Record<string, unknown> | null {
+    if (!params) return null;
+    const sessionId = readNonEmptyString(params["sessionId"]) ?? readNonEmptyString(params["session_id"]);
+    if (!sessionId) return null;
+    const cwd = readNonEmptyString(params["cwd"]);
+    return {
+      sessionId,
+      ...(cwd ? { cwd } : {}),
+    };
+  },
+
+  getDisplayId(params: Record<string, unknown> | null): string | null {
+    if (!params) return null;
+    return readNonEmptyString(params["sessionId"]) ?? readNonEmptyString(params["session_id"]);
+  },
+};

package/src/providers/claude/execute.ts

@@ -0,0 +1,300 @@
+import * as path from "node:path";
+import type { ExecutionContext, ExecutionResult } from "../../types.js";
+import { findBinary } from "../../utils/binary.js";
+import { buildEnv, ensurePathInEnv } from "../../utils/env.js";
+import { translateEndpoint } from "../../utils/endpoint.js";
+import { runChildProcess, deriveErrorCode } from "../../utils/process.js";
+import { detectAuth } from "../../utils/auth.js";
+import { buildSkillsDir, cleanupSkillsDir } from "../../utils/skills.js";
+import { claudeFeatureArgs, cleanupMcpConfig, stageMcpConfig } from "./mcp.js";
+import { createToolNameTracker } from "../../utils/tool-names.js";
+import { uuidv7 } from "../../utils/uuid.js";
+import { prepareWorkspace } from "../../utils/workspace.js";
+import type { PreparedWorkspace } from "../../utils/workspace.js";
+import { parseClaudeStreamJson, parseStreamLine, isClaudeUnknownSessionError, isClaudeAuthRequired, CLAUDE_LOGIN_COMMAND, type PartialStreamContext } from "./parse.js";
+
+export async function executeClaudeProvider(ctx: ExecutionContext): Promise<ExecutionResult> {
+  const runId = ctx.runId ?? uuidv7();
+  let cwd = ctx.cwd ?? process.cwd();
+  const config = ctx.config ?? {};
+  const rawModel = ctx.model ?? config.model;
+  const startedAt = new Date().toISOString();
+
+  // 1. Resolve binary
+  ctx.onLifecycle?.({ phase: "preparing", step: "binary" });
+  let resolvedBinary;
+  try {
+    resolvedBinary = await findBinary("claude", config.command);
+  } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : "Binary not found";
+    ctx.onLifecycle?.({ phase: "error", message: errorMessage });
+    return {
+      runId,
+      exitCode: null,
+      signal: null,
+      status: "failed" as const,
+      startedAt,
+      completedAt: new Date().toISOString(),
+      durationMs: Date.now() - new Date(startedAt).getTime(),
+      errorMessage,
+      errorCode: "binary_not_found",
+      costUsd: null,
+      model: null,
+      summary: null,
+      sessionParams: null,
+      sessionDisplayId: null,
+      clearSession: false,
+      billingType: null,
+    };
+  }
+
+  // 2. Workspace isolation
+  let workspace: PreparedWorkspace | undefined;
+  if (config.workspace) {
+    ctx.onLifecycle?.({ phase: "preparing", step: "workspace" });
+    workspace = await prepareWorkspace(cwd, config.workspace);
+    cwd = workspace.cwd;
+  }
+
+  // 3. Build env & detect auth/billing
+  ctx.onLifecycle?.({ phase: "preparing", step: "auth" });
+  const env = buildEnv(ctx.env);
+  ensurePathInEnv(env);
+  // Custom endpoint (BYOK / gateway / alt model) — env-only for claude. `unset`
+  // clears ambient Anthropic creds that would otherwise leak to a custom baseUrl.
+  const endpointTx = translateEndpoint("claude", config.endpoint);
+  Object.assign(env, endpointTx.env);
+  for (const key of endpointTx.unset) delete env[key];
+  const auth = detectAuth("claude", env);
+  // Any explicit endpoint auth or a custom base URL is external/BYOK billing,
+  // not the local subscription (detectAuth only recognizes ANTHROPIC_API_KEY).
+  const usesCustomEndpoint = !!(
+    config.endpoint?.baseUrl || config.endpoint?.authToken || config.endpoint?.apiKey
+  );
+  const billingType = usesCustomEndpoint ? "api" : auth.billingType;
+  // Skip Bedrock model-id remapping for a custom endpoint: ambient AWS creds
+  // make detectAuth return a Bedrock resolveModelId that would otherwise rewrite
+  // `--model` into a Bedrock id and send it to the wrong place.
+  const model = !usesCustomEndpoint && rawModel && auth.resolveModelId
+    ? auth.resolveModelId(rawModel)
+    : rawModel;
+
+  // 3. Build skills dir
+  ctx.onLifecycle?.({ phase: "preparing", step: "skills" });
+  let skillsDir: string | null = null;
+  if (config.skillDirs && config.skillDirs.length > 0) {
+    try {
+      skillsDir = await buildSkillsDir(config.skillDirs, "claude");
+    } catch {
+      // Skill injection failure is non-fatal
+    }
+  }
+
+  // 3.5 Stage MCP config — attached via `--mcp-config <file>` (mode 0600),
+  // never argv: http server headers can carry bearer tokens and argv is
+  // world-readable via `ps`.
+  let mcpConfigPath: string | null = null;
+  if (config.mcpServers && config.mcpServers.length > 0) {
+    mcpConfigPath = await stageMcpConfig(config.mcpServers);
+  }
+
+  // 4. Build args
+  const buildArgs = (resumeSessionId: string | null): string[] => {
+    const args = [...resolvedBinary.prefixArgs, "--print", "-", "--output-format", "stream-json", "--verbose"];
+    if (resumeSessionId) args.push("--resume", resumeSessionId);
+    // planMode and skipPermissions are mutually exclusive — planMode wins.
+    if (config.planMode) {
+      args.push("--permission-mode", "plan");
+    } else if (config.skipPermissions) {
+      args.push("--dangerously-skip-permissions");
+    }
+    if (model) args.push("--model", model);
+    if (config.effort) args.push("--effort", config.effort);
+    if (config.maxTurns && config.maxTurns > 0) args.push("--max-turns", String(config.maxTurns));
+    if (config.instructionsFile) args.push("--append-system-prompt-file", config.instructionsFile);
+    if (skillsDir) args.push("--add-dir", skillsDir);
+    args.push(...claudeFeatureArgs(config, mcpConfigPath));
+    // extraArgs stay LAST so hosts can override any generated flag.
+    if (config.extraArgs) args.push(...config.extraArgs);
+    return args;
+  };
+
+  // 5. Determine session resume
+  const sessionParams = ctx.sessionParams ?? null;
+  const sessionId = (() => {
+    if (!sessionParams) return null;
+    const id = sessionParams["sessionId"] as string | undefined ?? sessionParams["session_id"] as string | undefined;
+    if (!id || typeof id !== "string") return null;
+    const sessionCwd = sessionParams["cwd"] as string | undefined;
+    if (sessionCwd && path.resolve(sessionCwd) !== path.resolve(cwd)) return null;
+    return id;
+  })();
+
+  // 6. Run attempt
+  const runAttempt = async (resumeSessionId: string | null) => {
+    const args = buildArgs(resumeSessionId);
+
+    // stdout line buffer for real-time event parsing
+    let lineBuffer = "";
+    // Correlates tool_call → tool_result so emitted tool_result events carry
+    // toolName. One tracker per attempt (a retry restarts the stream).
+    const trackToolName = createToolNameTracker();
+    // Tracks the owning message id across --include-partial-messages stream
+    // lines so deltas reconcile with their consolidated assistant event.
+    const partialCtx: PartialStreamContext = { messageId: null };
+
+    ctx.onLifecycle?.({ phase: "spawning" });
+    const proc = await runChildProcess({
+      runId,
+      command: resolvedBinary.bin,
+      args,
+      cwd,
+      env,
+      stdin: ctx.prompt,
+      timeoutSec: config.timeoutSec,
+      graceSec: config.graceSec,
+      onStart: (pid) => {
+        ctx.onLifecycle?.({ phase: "running", pid });
+        ctx.onStart?.(pid);
+      },
+      signal: ctx.signal,
+      onOutput: async (stream, chunk) => {
+        // Forward raw output
+        if (ctx.onOutput) {
+          try { await ctx.onOutput(stream, chunk); } catch { /* swallow */ }
+        }
+
+        // Parse stdout lines for stream events
+        if (stream === "stdout" && ctx.onEvent) {
+          lineBuffer += chunk;
+          const lines = lineBuffer.split("\n");
+          // Keep the last (possibly incomplete) line in the buffer
+          lineBuffer = lines.pop() ?? "";
+          for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed) continue;
+            for (const event of parseStreamLine(trimmed, partialCtx)) {
+              try { await ctx.onEvent(trackToolName(event)); } catch { /* swallow */ }
+            }
+          }
+        }
+      },
+    });
+
+    // Parse remaining buffer
+    if (lineBuffer.trim() && ctx.onEvent) {
+      for (const event of parseStreamLine(lineBuffer.trim())) {
+        try { await ctx.onEvent(trackToolName(event)); } catch { /* swallow */ }
+      }
+    }
+
+    return proc;
+  };
+
+  try {
+    // 7. Initial attempt
+    let proc = await runAttempt(sessionId);
+    let clearSession = false;
+
+    // 8. Check for unknown session — retry once
+    if (
+      sessionId &&
+      !proc.timedOut &&
+      (proc.exitCode ?? 0) !== 0 &&
+      isClaudeUnknownSessionError(proc.stdout, proc.stderr)
+    ) {
+      proc = await runAttempt(null);
+      clearSession = true;
+    }
+
+    // 9. Parse result
+    const parsed = parseClaudeStreamJson(proc.stdout);
+    const processErrorCode = deriveErrorCode(proc);
+
+    // Determine error code: process-level errors take precedence, then provider-specific.
+    // parsed.errorCode already covers `auth_required` when the structured
+    // signal (api_error_status 401/403 or documented auth text) fired in
+    // parseClaudeStreamJson. The regex fallback below catches edge cases
+    // where the CLI bailed before emitting a result event at all (binary
+    // failure, stderr-only error from a wrapper).
+    let errorCode = processErrorCode;
+    if (!errorCode && parsed.errorCode) {
+      errorCode = parsed.errorCode;
+    }
+    if (!errorCode && isClaudeAuthRequired(proc.stdout, proc.stderr)) {
+      errorCode = "auth_required";
+    }
+
+    const errorMessage = (() => {
+      if (proc.timedOut) return `Timed out after ${config.timeoutSec ?? 0}s`;
+      if (errorCode === "auth_required") {
+        // Prefer the provider's user-facing string when we captured it,
+        // so callers can show "OAuth token has expired" rather than a
+        // generic banner. Fall back to a recovery hint otherwise.
+        return parsed.summary
+          ? `${parsed.summary} (run \`${CLAUDE_LOGIN_COMMAND}\`)`
+          : `Claude requires authentication. Run \`${CLAUDE_LOGIN_COMMAND}\`.`;
+      }
+      if ((proc.exitCode ?? 0) !== 0 && !parsed.summary) {
+        const stderrLine = proc.stderr.split(/\r?\n/).map((l) => l.trim()).find(Boolean);
+        return stderrLine ?? `Claude exited with code ${proc.exitCode ?? -1}`;
+      }
+      if (parsed.isError) return parsed.summary;
+      return null;
+    })();
+
+    const resolvedSessionId = parsed.sessionId;
+    const resultSessionParams = resolvedSessionId
+      ? { sessionId: resolvedSessionId, cwd }
+      : null;
+
+    const completedAt = new Date().toISOString();
+    const resolvedModel = parsed.model ?? model ?? null;
+    const status = proc.aborted ? "aborted" as const
+      : proc.timedOut ? "timeout" as const
+      : (errorCode || errorMessage) ? "failed" as const
+      : "completed" as const;
+
+    if (status === "completed") {
+      ctx.onLifecycle?.({ phase: "completed" });
+    } else if (status === "aborted") {
+      ctx.onLifecycle?.({ phase: "cancelled" });
+    } else {
+      ctx.onLifecycle?.({ phase: "error", message: errorMessage ?? "Unknown error" });
+    }
+
+    return {
+      runId,
+      exitCode: proc.exitCode,
+      signal: proc.signal ?? null,
+      status,
+      startedAt,
+      completedAt,
+      durationMs: new Date(completedAt).getTime() - new Date(startedAt).getTime(),
+      errorMessage,
+      errorCode,
+      usage: parsed.modelUsage ?? undefined,
+      costUsd: parsed.costUsd,
+      model: resolvedModel,
+      summary: parsed.summary,
+      sessionParams: resultSessionParams,
+      sessionDisplayId: resolvedSessionId,
+      clearSession,
+      billingType,
+      stopReason: parsed.stopReason,
+      terminalReason: parsed.terminalReason,
+      numTurns: parsed.numTurns,
+      durationApiMs: parsed.durationApiMs,
+      permissionDenials: parsed.permissionDenials ?? undefined,
+      rateLimits: parsed.rateLimits.length > 0 ? parsed.rateLimits : undefined,
+      raw: parsed.finalEvent,
+      workspace,
+    };
+  } finally {
+    // 10. Clean up staged dirs/files
+    if (skillsDir) {
+      await cleanupSkillsDir(skillsDir);
+    }
+    await cleanupMcpConfig(mcpConfigPath);
+  }
+}

package/src/providers/claude/goal-capability.ts

@@ -0,0 +1,21 @@
+import type { GoalCapability } from "../../types.js";
+
+/**
+ * Claude enforces goals natively via a Stop-hook + fast-model sentinel (the
+ * `/goal` command). Binary met/not-met, self-clearing on completion.
+ *
+ * `statuses` describes the NATIVE producible set. A Claude session that falls to
+ * the emulation engine (a custom `sentinel`, or `enforce:"emulate"`) can also
+ * produce `blocked` (`blockedReason:"max_iterations"`) — see GoalController.
+ *
+ * Lives in its own leaf module (not `session.ts`) so `index.ts` can read the
+ * static `capabilities.goals` field without pulling the heavy session machinery
+ * into the module graph (spec §5.1).
+ */
+export const claudeGoalCapability: GoalCapability = {
+  mechanism: "sentinel",
+  enforced: true,
+  statuses: ["active", "met", "cleared"],
+  clears: "both",
+  telemetry: false,
+};

package/src/providers/claude/index.ts

@@ -0,0 +1,72 @@
+import type { ProviderModule, SessionContext, AgentSession, QuotaContext, QuotaStatus } from "../../types.js";
+import { detectAuth, resolveAuthForProvider } from "../../utils/auth.js";
+import { claudeSessionCodec } from "./codec.js";
+import { buildEnv, ensurePathInEnv } from "../../utils/env.js";
+import { claudeTranscriptOps } from "./transcript.js";
+import { claudeGoalCapability } from "./goal-capability.js";
+
+async function checkQuota(ctx: QuotaContext): Promise<QuotaStatus> {
+  const env = buildEnv(ctx.env);
+  ensurePathInEnv(env);
+  const auth = detectAuth("claude", env);
+  return {
+    available: auth.method !== "subscription" || !!env["ANTHROPIC_API_KEY"],
+    billingType: auth.billingType,
+    detail: { method: auth.method, region: auth.region },
+  };
+}
+
+export const claudeProvider: ProviderModule = {
+  type: "claude",
+  capabilities: {
+    sessions: true,
+    modelDiscovery: false,
+    quotaProbing: true,
+    mcp: true,
+    skills: true,
+    skillInventory: "provider-init",
+    skillInvocation: "native-slash",
+    instructions: true,
+    workspace: true,
+    planMode: true,
+    concurrentSend: true,
+    cancelQueuedMessage: true,
+    stopTask: true,
+    modes: false,
+    goals: claudeGoalCapability,
+    durableSessions: true,
+  },
+  // Heavy machinery (execute.ts, session.ts, attach.ts) loads lazily on first
+  // use — every ProviderModule method is already async, so this is invisible to
+  // callers.
+  execute: async (ctx) => (await import("./execute.js")).executeClaudeProvider(ctx),
+  createSession: async (ctx: SessionContext): Promise<AgentSession> =>
+    (await import("./session.js")).createClaudeSession(ctx),
+  resolveAuth: (ctx) => resolveAuthForProvider("claude", ctx),
+  sessionCodec: claudeSessionCodec,
+  checkQuota,
+  transcript: claudeTranscriptOps,
+  attachSession: async (record, opts) =>
+    (await import("./attach.js")).attachClaudeSession(record, opts),
+};
+
+export {
+  getClaudeTranscriptPath,
+  findClaudeTranscriptBySessionId,
+  readClaudeTranscript,
+  peekClaudeTranscript,
+  claudeTranscriptOps,
+  sanitizeProjectPath,
+  resolveClaudeHome,
+  canonicalizeCwd,
+  MAX_SANITIZED_LENGTH,
+} from "./transcript.js";
+export type {
+  GetClaudeTranscriptPathOptions,
+  ClaudeTranscriptLocation,
+  FindClaudeTranscriptOptions,
+  FoundClaudeTranscript,
+  ReadClaudeTranscriptOptions,
+  ClaudeTranscriptYield,
+  ClaudePeekResult,
+} from "./transcript.js";

package/src/providers/claude/mcp.ts

@@ -0,0 +1,82 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { McpServerConfig, ProviderConfig } from "../../types.js";
+
+/**
+ * Map agentex `McpServerConfig[]` into Claude's `--mcp-config` JSON shape:
+ * `{ "mcpServers": { "<name>": { … } } }`.
+ *
+ * stdio servers (the default arm) keep `command`/`args`/`env`; http/sse servers
+ * carry `url` (+ optional `headers`).
+ */
+export function buildMcpConfigJson(servers: McpServerConfig[]): {
+  mcpServers: Record<string, Record<string, unknown>>;
+} {
+  const mcpServers: Record<string, Record<string, unknown>> = {};
+  for (const s of servers) {
+    if ("url" in s) {
+      mcpServers[s.name] = {
+        type: s.type,
+        url: s.url,
+        ...(s.headers ? { headers: s.headers } : {}),
+      };
+    } else {
+      mcpServers[s.name] = {
+        type: "stdio",
+        command: s.command,
+        ...(s.args ? { args: s.args } : {}),
+        ...(s.env ? { env: s.env } : {}),
+      };
+    }
+  }
+  return { mcpServers };
+}
+
+/**
+ * Stage the MCP config as a JSON file (mode 0600) in a fresh `agentex-mcp-*`
+ * temp dir and return the file path. HTTP server `headers` can carry bearer
+ * tokens, so the config never goes through argv — argv is world-readable via
+ * `ps`. Clean up with {@link cleanupMcpConfig} when the run/session ends.
+ */
+export async function stageMcpConfig(servers: McpServerConfig[]): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "agentex-mcp-"));
+  const file = path.join(dir, "mcp-config.json");
+  await fs.writeFile(file, JSON.stringify(buildMcpConfigJson(servers), null, 2), {
+    mode: 0o600,
+  });
+  return file;
+}
+
+/** Remove a staged MCP config (and its temp dir). Idempotent; null-safe. */
+export async function cleanupMcpConfig(filePath: string | null): Promise<void> {
+  if (!filePath) return;
+  try {
+    await fs.rm(path.dirname(filePath), { recursive: true, force: true });
+  } catch {
+    /* already gone */
+  }
+}
+
+/**
+ * The argv tail for Claude's MCP + tool-filtering + partial-message features.
+ * Shared by the execute and session arg builders so both stay in lockstep, and
+ * exported so tests can snapshot the exact argv. Callers append
+ * `config.extraArgs` AFTER this (the host-override invariant).
+ */
+export function claudeFeatureArgs(config: ProviderConfig, mcpConfigPath: string | null): string[] {
+  const args: string[] = [];
+  if (mcpConfigPath) args.push("--mcp-config", mcpConfigPath);
+  // Strict works with or without an attached config: strict + no config means
+  // "no MCP at all", which embedding hosts use to block ambient .mcp.json /
+  // user-scope servers from leaking into a product-controlled session.
+  if (config.strictMcpConfig) args.push("--strict-mcp-config");
+  if (config.allowedTools && config.allowedTools.length > 0) {
+    args.push("--allowed-tools", config.allowedTools.join(","));
+  }
+  if (config.disallowedTools && config.disallowedTools.length > 0) {
+    args.push("--disallowed-tools", config.disallowedTools.join(","));
+  }
+  if (config.includePartialMessages) args.push("--include-partial-messages");
+  return args;
+}