agent-relay-runner 0.67.1 → 0.68.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.67.1",
+  "version": "0.68.1",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.43"
+    "agent-relay-sdk": "0.2.44"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.67.1",
+  "version": "0.68.1",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapter.ts

@@ -191,6 +191,17 @@ export function profileAllowsRelayFeature(config: RunnerSpawnConfig, feature: ke
   return config.agentProfile?.relay?.[feature] !== false;
 }
 
+// #552 — the strictest base. Beyond the isolated provider home that every
+// non-host base already gets (fresh CLAUDE_CONFIG_DIR / CODEX_HOME, which drops
+// the GLOBAL instruction + host MCP/hooks/plugins cascade), "vanilla" actively
+// suppresses every remaining host customization channel at launch, including the
+// REPO CLAUDE.md/AGENTS.md cascade that lives in the cwd and so survives home
+// isolation. Claude: `--setting-sources "user"` (the --safe-mode pivot — safe-mode
+// blocked even explicit provisioning). Codex: `project_doc_max_bytes=0`.
+export function profileIsVanillaBase(config: Pick<RunnerSpawnConfig, "agentProfile">): boolean {
+  return config.agentProfile?.base === "vanilla";
+}
+
 export const RELAY_CONTEXT = `[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. If Relay MCP tools are available, prefer relay_reply, relay_get_message, relay_get_thread, relay_send_message, relay_upload_artifact, relay_attach_artifact, relay_agent_status, relay_find_agents, relay_compact_and_resume, relay_recall, relay_spawn_agent, and relay_shutdown_agent. You never need to know or pass your own agent id — relay fills it from your token; use relay_whoami only if you need to reason about yourself. relay_compact_and_resume is for clean-seam self-resume after a context advisory: pass workingState and optional ruledOut; Relay owns the objective envelope. relay_recall searches your own archived pre-compaction segments by keyword when a discarded detail is needed. relay_spawn_targets / relay_spawn_agent / relay_shutdown_agent only appear if your profile grants spawning (a live-children quota); when present, call relay_spawn_targets FIRST for the live host/provider/model matrix + your quota, then stand up long-living child agents and shut down your own — find them later with relay_find_agents spawnedBy:me. CLI fallback: agent-relay /reply <messageId> --stdin < response.md; if a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. For command details, run: agent-relay /guide`;
 
 // #306 — deliver the FULL message body by default. Only a pathological body beyond this

package/src/adapters/claude.ts

@@ -10,7 +10,7 @@ import { profileAllowsRelayFeature, type ManagedProcess, type ProviderAdapter, t
 import { collectClaudeSessionEvents } from "./claude-transcript";
 import type { SessionEvent } from "../session-insights";
 import { prepareClaudeProfileHome, profileUsesHostProviderGlobals } from "../profile-home";
-import { relayMcpClaudeConfigArg } from "../relay-mcp";
+import { assembleLaunch, materializeLaunchAssembly, sessionStatusLineSettingsArgs } from "../launch-assembly";
 import { claudeProviderMessageText } from "./claude-delivery";
 import { buildRateLimitProviderState, parseClaudeRateLimitPane } from "../rate-limit";
 
@@ -219,10 +219,18 @@ export class ClaudeAdapter implements ProviderAdapter {
   }
 
   buildSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig): SpawnArgs {
-    const profileHome = prepareClaudeProfileHome(config);
-    const pluginRoot = resolve(import.meta.dir, "../../plugins/claude");
+    // Create + bootstrap + auth-link the isolated config home (no-op for host base) so the
+    // assembler's materialize step has somewhere to write the provisioned skills/plugins.
+    prepareClaudeProfileHome(config);
     const defaultArgs = profileUsesHostProviderGlobals(config) ? providerConfig.defaultArgs : [];
-    const pluginDirs = profileAllowsRelayFeature(config, "plugins") ? [...new Set([pluginRoot, ...providerConfig.pluginDirs])] : [];
+    // #557 — ONE assembler owns the provisioning/vanilla/instruction launch surface
+    // (--setting-sources, --plugin-dir, --mcp-config, status-line, --append-system-prompt);
+    // profile-projection describes the SAME assembled result, so report == launch. The
+    // adapter only adds the bits the assembler does not own: claude-rig command resolution,
+    // headless permission flags, --model, and the positional prompt. materializeLaunchAssembly
+    // writes the provisioned skills/plugins the assembled args point at.
+    const assembled = assembleLaunch("claude", config, providerConfig);
+    materializeLaunchAssembly("claude", config);
     const isClaudeRig = /claude-rig/.test(providerConfig.command);
     // Isolated profiles run their own CLAUDE_CONFIG_DIR and must never route through
     // claude-rig — claude-rig resolves host rig config (and a bare `claude-rig` with no
@@ -238,10 +246,7 @@ export class ClaudeAdapter implements ProviderAdapter {
       : [...defaultArgs, ...config.providerArgs];
     const args = [
       ...rigPrefix,
-      ...pluginDirs.flatMap((dir) => ["--plugin-dir", dir]),
-      ...(profileAllowsRelayFeature(config, "mcp") ? relayMcpClaudeConfigArg(config.relayUrl, config.relayMcpEndpoint) : []),
-      ...(profileAllowsRelayFeature(config, "statusLine") ? sessionStatusLineSettingsArgs(defaultArgs, config.providerArgs) : []),
-      ...(config.systemPromptAppend ? ["--append-system-prompt", config.systemPromptAppend] : []),
+      ...assembled.args,
       ...providerArgs,
     ];
     if (config.model) args.push("--model", config.model);
@@ -256,7 +261,8 @@ export class ClaudeAdapter implements ProviderAdapter {
       cwd: config.cwd,
       env: {
         ...config.env,
-        ...(profileHome ? { CLAUDE_CONFIG_DIR: profileHome.path } : {}),
+        // #557 — the assembler owns the isolated config-home env (CLAUDE_CONFIG_DIR).
+        ...assembled.env,
         // Plain `claude` (isolated profiles) runs its own CLAUDE_CONFIG_DIR and never
         // routes through claude-rig, so it never inherits the host's long-lived
         // CLAUDE_CODE_OAUTH_TOKEN. Without it, claude falls back to the (often stale)
@@ -431,23 +437,9 @@ export function claudeShutdownGraceMs(timeoutMs: number): number {
   return Math.min(timeoutMs, 10_000);
 }
 
-export function sessionStatusLineSettingsArgs(...argLists: string[][]): string[] {
-  if (argLists.some(hasSettingsArg)) return [];
-  return ["--settings", JSON.stringify({
-    statusLine: {
-      type: "command",
-      command: "agent-relay context-probe --wrap",
-      refreshInterval: 30,
-    },
-    // Force readable thinking text for managed sessions so the session-mirror can
-    // surface reasoning in the dashboard. With showThinkingSummaries:false the API
-    // redacts thinking to a signature-only stub (empty text), leaving the transcript
-    // tail nothing to mirror. --settings merges per-key, so this overrides only this
-    // key for managed sessions — a host rig default of false still governs the
-    // operator's own interactive TUI sessions.
-    showThinkingSummaries: true,
-  })];
-}
+// #557 — sessionStatusLineSettingsArgs now lives in ../launch-assembly (the single
+// launch-arg home); re-exported so existing ./claude consumers + tests keep their path.
+export { sessionStatusLineSettingsArgs };
 
 export function claudeLaunchArgs(defaultArgs: string[], providerArgs: string[], approvalMode?: string): string[] {
   const stripToolArgs = approvalMode === "read-only";
@@ -489,9 +481,6 @@ function stripClaudePermissionArgs(args: string[], stripToolArgs = false): strin
   return result;
 }
 
-function hasSettingsArg(args: string[]): boolean {
-  return args.some((arg) => arg === "--settings" || arg.startsWith("--settings="));
-}
 
 export function tmuxSessionName(prefix: string, instanceId: string, label?: string): string {
   if (label) return `${prefix}-${sanitizeFsName(label, { replacement: "-", collapse: false, lowercase: true })}`;

package/src/adapters/codex.ts

@@ -6,7 +6,8 @@ import { isRecord, stringValue } from "agent-relay-sdk";
 import { isPidAlive, killPid, processTreePids, processTreePidsFromTable, waitForPidsExit } from "agent-relay-sdk/process-utils";
 import { profileAllowsRelayFeature, providerMessageText, RELAY_CONTEXT, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderSessionEvent, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
 import { workspaceDepsNoteFromEnv } from "../relay-instructions";
-import { relayMcpCodexConfigArgs, tomlString } from "../relay-mcp";
+import { tomlString } from "../relay-mcp";
+import { assembleLaunch, bundledCodexSkillDirs, bundledSkillConfigArgs, materializeLaunchAssembly } from "../launch-assembly";
 import { logger } from "../logger";
 import type { SessionEvent } from "../session-insights";
 
@@ -345,17 +346,24 @@ export class CodexAdapter implements ProviderAdapter {
 
   buildSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig): SpawnArgs {
     const appServerUrl = String(config.appServerUrl || process.env.CODEX_APP_SERVER_URL || `ws://127.0.0.1:${config.controlPort + 1000}`);
-    const profileHome = prepareCodexProfileHome(config);
+    // Create + bootstrap the isolated CODEX_HOME (no-op for host base) so the assembler's
+    // materialize step has somewhere to write the provisioned skills.
+    prepareCodexProfileHome(config);
     const defaultArgs = profileUsesHostProviderGlobals(config) ? providerConfig.defaultArgs : [];
+    // #557 — ONE assembler owns the provisioning/vanilla surface (skills.config, relay +
+    // provisioned -c mcp_servers.*, project_doc_max_bytes); profile-projection describes the
+    // SAME assembled result, so report == launch. The adapter only adds core launch config the
+    // assembler does not own: app-server wiring, model/approval/tool-output, managed flags, --listen.
+    const assembled = assembleLaunch("codex", config, providerConfig);
+    materializeLaunchAssembly("codex", config);
     const args = isCodexCliCommand(providerConfig.command)
       ? [
         "app-server",
         ...codexAppServerConfigArgs(defaultArgs, config.providerArgs),
         ...codexModelConfigArgs(config.model, config.effort),
         ...codexApprovalConfigArgs(config.approvalMode),
-        ...(profileAllowsRelayFeature(config, "skills") ? bundledSkillConfigArgs() : []),
-        ...(profileAllowsRelayFeature(config, "mcp") ? relayMcpCodexConfigArgs(config.relayUrl, config.relayMcpEndpoint) : []),
         ...codexToolOutputTokenLimitConfigArgs(config),
+        ...assembled.args,
         ...codexManagedConfigArgs(),
         "--listen",
         appServerUrl,
@@ -367,7 +375,8 @@ export class CodexAdapter implements ProviderAdapter {
       cwd: config.cwd,
       env: {
         ...config.env,
-        ...(profileHome ? { CODEX_HOME: profileHome.path } : {}),
+        // #557 — the assembler owns the isolated config-home env (CODEX_HOME).
+        ...assembled.env,
         CODEX_APP_SERVER_URL: appServerUrl,
         AGENT_RELAY_PROVIDER: "codex",
       },
@@ -1166,24 +1175,10 @@ function isAgentRelayCodexShim(path: string): boolean {
   return path.includes("/.agent-relay/codex/bin/codex");
 }
 
-export function bundledCodexSkillDirs(baseDir = resolve(import.meta.dir, "../../plugins/codex/skills")): string[] {
-  if (!existsSync(baseDir)) return [];
-  return readdirSync(baseDir, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory() && existsSync(join(baseDir, entry.name, "SKILL.md")))
-    .map((entry) => join(baseDir, entry.name))
-    .sort();
-}
-
-export function bundledSkillConfigArgs(skillDirs = bundledCodexSkillDirs()): string[] {
-  if (skillDirs.length === 0) return [];
-  const skillsConfig = skillDirs
-    .map((dir) => `{path=${tomlString(dir)},enabled=true}`)
-    .join(",");
-  return ["-c", `skills.config=[${skillsConfig}]`];
-}
-
-// tomlString now lives in ../relay-mcp (shared with the relay MCP injection args);
-// re-exported here so existing codex.ts consumers/tests keep their import path.
+// #557 — bundledCodexSkillDirs + bundledSkillConfigArgs now live in ../launch-assembly
+// (the single launch-arg home, shared with the assembler); re-exported so existing
+// codex.ts consumers + tests keep their import path. tomlString likewise from ../relay-mcp.
+export { bundledCodexSkillDirs, bundledSkillConfigArgs };
 export { tomlString };
 
 export function codexAppServerConfigArgs(...argLists: string[][]): string[] {

package/src/launch-assembly.ts

@@ -0,0 +1,303 @@
+import { existsSync, readdirSync } from "node:fs";
+import { resolve, join } from "node:path";
+import type { AgentProfile, AgentProfileBase, SpawnProvider } from "agent-relay-sdk";
+import {
+  profileAllowsRelayFeature,
+  profileIsVanillaBase,
+  type ProviderConfig,
+  type RunnerSpawnConfig,
+} from "./adapter";
+import { profileUsesHostProviderGlobals, providerHomePathFor } from "./profile-home";
+import {
+  materializeResolvedAssets,
+  resolveClaudeProvisionedPlugins,
+  resolveClaudeProvisionedSkills,
+  resolveCodexProvisionedSkills,
+  profileProvisioning,
+} from "./provisioning";
+import {
+  claudeMcpLaunchArgs,
+  codexProvisionedMcpArgs,
+  relayMcpCodexConfigArgs,
+  tomlString,
+  RELAY_MCP_SERVER_NAME,
+} from "./relay-mcp";
+
+// #557 — THE single launch-assembly contract. Given a resolved AgentProfile (+ its
+// spawn-time ResolvedProvisioning), `assembleLaunch` produces ONE provider-neutral
+// description of the launch: the relay-provisioned skills/plugins/MCP, the bundled relay
+// surface, the instruction-source disposition, and `base:"vanilla"` as the zero-host
+// floor. Both adapters' buildSpawnArgs splice `assembled.args`/`assembled.env`, and
+// profile-projection describes `assembled` directly — so projection and reality come
+// from one source and cannot drift.
+//
+// `assembleLaunch` is PURE (it reads the filesystem to decide which declared dirs
+// resolve, but writes nothing). `materializeLaunchAssembly` performs the disk writes the
+// description implies, driven by the SAME resolvers — so what's written equals what's
+// reported equals what's launched.
+
+export interface AssembledAsset {
+  name: string;
+  /** Materialized/in-place dir feeding the launch (e.g. a --plugin-dir or skills.config path). */
+  dir: string;
+}
+
+export type AssembledInstructionDisposition = "allow" | "suppressed" | "isolated" | "unsupported";
+
+export interface AssembledInstructions {
+  /** Repo CLAUDE.md/AGENTS.md cascade: "allow" left available, "suppressed" by the
+   *  vanilla launch mechanism, "unsupported" requested-but-not-enforced (non-vanilla isolated). */
+  repo: AssembledInstructionDisposition;
+  /** Host/global provider instructions: "allow", "isolated" (dropped by the isolated home), or "unsupported". */
+  global: AssembledInstructionDisposition;
+  /** A composed systemPromptAppend block (project preamble + profile system/append +
+   *  caller context, composed relay-side by composeSpawnInstructions) flows into this launch. */
+  systemPromptAppend: boolean;
+  // ── #559 SEAM ──────────────────────────────────────────────────────────────────
+  // Scoped {profile|user} memory does not exist yet (#559 generalizes Projects' anchor
+  // to project|profile|user). When it lands, the assembled instruction world becomes
+  // "instructions + provisioned assets + scoped knowledge": the relay-side composer
+  // (composeSpawnInstructions) gains a profile/user-scoped preamble beside the existing
+  // project preamble, and THIS field reports which scopes contributed. Until then it is
+  // always "none" — a thin add for #559, not a refactor.
+  scopedKnowledge: "none";
+}
+
+export interface AssembledMcp {
+  /** The identity-bearing relay HTTP MCP endpoint is injected. */
+  relayEndpoint: boolean;
+  /** Only the assembled servers may load (Claude --strict-mcp-config) — the vanilla floor. */
+  strict: boolean;
+  /** Relay-provisioned server names (excludes the relay endpoint itself). */
+  servers: string[];
+}
+
+export interface AssembledLaunch {
+  provider: SpawnProvider;
+  /** The resolved profile this launch was assembled from; undefined for a profile-less
+   *  (legacy default) spawn, which behaves as host base with relay features default-on. */
+  profile?: AgentProfile;
+  base: AgentProfileBase;
+  vanilla: boolean;
+  /** Isolated provider config home (CLAUDE_CONFIG_DIR / CODEX_HOME), or undefined for host base. */
+  configHome?: string;
+  relayContext: boolean;
+  /** Bundled relay skills are available (Codex skills.config / Claude via the relay plugin). */
+  relaySkills: boolean;
+  /** Bundled relay plugin dir is passed (Claude only). */
+  relayPlugin: boolean;
+  /** Relay status-line context probe is injected (Claude only). */
+  statusLine: boolean;
+  /** Relay-provisioned skills materialized for this launch. */
+  skills: AssembledAsset[];
+  /** Relay-provisioned plugins (Claude --plugin-dir). Empty for Codex (no plugin surface). */
+  plugins: AssembledAsset[];
+  mcp: AssembledMcp;
+  instructions: AssembledInstructions;
+  /** Provider provisioning/vanilla/instruction launch-arg block, in launch order. */
+  args: string[];
+  /** Provisioning-derived env additions (the isolated config-home var). */
+  env: Record<string, string>;
+}
+
+// ── Bundled relay assets (relocated from the adapters so the assembler — not each
+// adapter — owns launch-arg construction; #557). Adapters re-export for test parity. ──
+
+const CLAUDE_RELAY_PLUGIN_DIR = resolve(import.meta.dir, "../plugins/claude");
+const CODEX_BUNDLED_SKILLS_DIR = resolve(import.meta.dir, "../plugins/codex/skills");
+
+export function bundledCodexSkillDirs(baseDir = CODEX_BUNDLED_SKILLS_DIR): string[] {
+  if (!existsSync(baseDir)) return [];
+  return readdirSync(baseDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(baseDir, entry.name, "SKILL.md")))
+    .map((entry) => join(baseDir, entry.name))
+    .sort();
+}
+
+export function bundledSkillConfigArgs(skillDirs = bundledCodexSkillDirs()): string[] {
+  if (skillDirs.length === 0) return [];
+  const skillsConfig = skillDirs.map((dir) => `{path=${tomlString(dir)},enabled=true}`).join(",");
+  return ["-c", `skills.config=[${skillsConfig}]`];
+}
+
+// #552 vanilla base (Codex): suppress the AGENTS.md project-doc cascade. project_doc_max_bytes
+// (default 32768) caps bytes Codex reads from AGENTS.md walking root→cwd; 0 stops before adding
+// any, so no repo (or fresh-CODEX_HOME global) project doc loads. The isolated CODEX_HOME already
+// drops host config.toml MCP/hooks; this closes the cwd-resident repo instruction channel.
+export function codexProjectDocSuppressionArgs(config: Pick<RunnerSpawnConfig, "agentProfile">): string[] {
+  return profileIsVanillaBase(config) ? ["-c", "project_doc_max_bytes=0"] : [];
+}
+
+function hasSettingsArg(args: string[]): boolean {
+  return args.some((arg) => arg === "--settings" || arg.startsWith("--settings="));
+}
+
+// Claude relay status-line + readable-thinking settings, injected only when no caller
+// --settings is already present (caller wins). Relocated from claude.ts (#557).
+export function sessionStatusLineSettingsArgs(...argLists: string[][]): string[] {
+  if (argLists.some(hasSettingsArg)) return [];
+  return ["--settings", JSON.stringify({
+    statusLine: { type: "command", command: "agent-relay context-probe --wrap", refreshInterval: 30 },
+    showThinkingSummaries: true,
+  })];
+}
+
+// ── Instruction disposition (the vanilla floor's effect on the host instruction cascade) ──
+
+function repoInstructionDisposition(profile: AgentProfile): AssembledInstructionDisposition {
+  if (profile.instructions.repoInstructions === "allow") return "allow";
+  if (profile.base === "vanilla") return "suppressed";
+  // Non-vanilla isolated bases can request ignore but have no launch-time enforcement yet.
+  return "unsupported";
+}
+
+function globalInstructionDisposition(profile: AgentProfile): AssembledInstructionDisposition {
+  if (profile.instructions.globalInstructions === "allow") return "allow";
+  if (profile.base !== "host") return "isolated";
+  return "unsupported";
+}
+
+function assembleInstructions(config: RunnerSpawnConfig): AssembledInstructions {
+  const profile = config.agentProfile;
+  return {
+    // A profile-less spawn is host-base: the full host instruction cascade is left available.
+    repo: profile ? repoInstructionDisposition(profile) : "allow",
+    global: profile ? globalInstructionDisposition(profile) : "allow",
+    systemPromptAppend: Boolean(config.systemPromptAppend?.trim()),
+    scopedKnowledge: "none",
+  };
+}
+
+// ── Per-provider arg assembly ──────────────────────────────────────────────────────
+
+function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfig, hostDefaultArgs: string[]): AssembledLaunch {
+  const configHome = providerHomePathFor("claude", config);
+  const vanilla = profileIsVanillaBase(config);
+  const relayPlugin = profileAllowsRelayFeature(config, "plugins");
+  const relaySkills = profileAllowsRelayFeature(config, "skills");
+  const statusLine = profileAllowsRelayFeature(config, "statusLine");
+
+  const skills = configHome ? resolveClaudeProvisionedSkills(configHome, config) : [];
+  const provisionedPlugins = configHome ? resolveClaudeProvisionedPlugins(configHome, config) : [];
+
+  // Plugin dirs (--plugin-dir loads explicitly, independent of --setting-sources):
+  //   relay-bundled plugin → only when relay.plugins (carries the relay monitor +
+  //     turn-lifecycle hooks #556, not reproducible via settings.json).
+  //   relay-provisioned plugins (#556) → materialized into the isolated home.
+  //   host plugin dirs → ONLY host-base profiles; isolated/vanilla must not pull them back in.
+  const relayPluginDirs = relayPlugin ? [CLAUDE_RELAY_PLUGIN_DIR] : [];
+  const provisionedPluginDirs = provisionedPlugins.map((p) => p.dir);
+  const hostPluginDirs = profileUsesHostProviderGlobals(config) ? providerConfig.pluginDirs : [];
+  const pluginDirs = [...new Set([...relayPluginDirs, ...provisionedPluginDirs, ...hostPluginDirs])];
+
+  const provisionedMcp = profileProvisioning(config).mcpServers;
+  const mcpServers = Object.keys(provisionedMcp).filter((name) => name !== RELAY_MCP_SERVER_NAME);
+  const relayEndpoint = profileAllowsRelayFeature(config, "mcp");
+
+  const instructions = assembleInstructions(config);
+
+  // Launch order matches the historical claude buildSpawnArgs block exactly so existing
+  // arg assertions hold: vanilla scope → plugin dirs → MCP → status-line → append.
+  const args = [
+    ...(vanilla ? ["--setting-sources", "user"] : []),
+    ...pluginDirs.flatMap((dir) => ["--plugin-dir", dir]),
+    ...claudeMcpLaunchArgs({
+      relayUrl: config.relayUrl,
+      ...(config.relayMcpEndpoint ? { endpoint: config.relayMcpEndpoint } : {}),
+      includeRelay: relayEndpoint,
+      servers: provisionedMcp,
+      strict: vanilla,
+    }),
+    ...(statusLine ? sessionStatusLineSettingsArgs(hostDefaultArgs, config.providerArgs) : []),
+    ...(config.systemPromptAppend ? ["--append-system-prompt", config.systemPromptAppend] : []),
+  ];
+
+  return {
+    provider: "claude",
+    ...(config.agentProfile ? { profile: config.agentProfile } : {}),
+    base: config.agentProfile?.base ?? "host",
+    vanilla,
+    ...(configHome ? { configHome } : {}),
+    relayContext: profileAllowsRelayFeature(config, "context"),
+    relaySkills,
+    relayPlugin,
+    statusLine,
+    skills: skills.map((s) => ({ name: s.name, dir: s.dir })),
+    plugins: provisionedPlugins.map((p) => ({ name: p.name, dir: p.dir })),
+    mcp: { relayEndpoint, strict: vanilla, servers: mcpServers },
+    instructions,
+    args,
+    env: configHome ? { CLAUDE_CONFIG_DIR: configHome } : {},
+  };
+}
+
+function assembleCodex(config: RunnerSpawnConfig, _providerConfig: ProviderConfig): AssembledLaunch {
+  const configHome = providerHomePathFor("codex", config);
+  const vanilla = profileIsVanillaBase(config);
+  const relaySkills = profileAllowsRelayFeature(config, "skills");
+  const relayEndpoint = profileAllowsRelayFeature(config, "mcp");
+
+  const provisionedSkills = configHome ? resolveCodexProvisionedSkills(configHome, config) : [];
+  const bundledSkillDirs = relaySkills ? bundledCodexSkillDirs() : [];
+  const skillDirs = [...bundledSkillDirs, ...provisionedSkills.map((s) => s.dir)];
+
+  const provisionedMcp = profileProvisioning(config).mcpServers;
+  const mcpServers = Object.keys(provisionedMcp).filter((name) => name !== RELAY_MCP_SERVER_NAME);
+
+  const instructions = assembleInstructions(config);
+
+  // The skills/MCP/project-doc block; core launch config (model/approval/listen) stays
+  // in the adapter. -c overrides are order-independent, so the assembled block is contiguous.
+  const args = [
+    ...bundledSkillConfigArgs(skillDirs),
+    ...(relayEndpoint ? relayMcpCodexConfigArgs(config.relayUrl, config.relayMcpEndpoint) : []),
+    ...codexProvisionedMcpArgs(provisionedMcp),
+    ...codexProjectDocSuppressionArgs(config),
+  ];
+
+  return {
+    provider: "codex",
+    ...(config.agentProfile ? { profile: config.agentProfile } : {}),
+    base: config.agentProfile?.base ?? "host",
+    vanilla,
+    ...(configHome ? { configHome } : {}),
+    relayContext: profileAllowsRelayFeature(config, "context"),
+    relaySkills,
+    relayPlugin: false,
+    statusLine: false,
+    skills: provisionedSkills.map((s) => ({ name: s.name, dir: s.dir })),
+    plugins: [],
+    mcp: { relayEndpoint, strict: false, servers: mcpServers },
+    instructions,
+    args,
+    env: configHome ? { CODEX_HOME: configHome } : {},
+  };
+}
+
+/**
+ * Assemble the launch for `provider` from the resolved profile + provisioning. PURE:
+ * resolves which declared assets exist (filesystem reads) but writes nothing. A missing
+ * `agentProfile` assembles the legacy default (host base, relay features on, no provisioning).
+ */
+export function assembleLaunch(provider: SpawnProvider, config: RunnerSpawnConfig, providerConfig: ProviderConfig): AssembledLaunch {
+  if (provider === "codex") return assembleCodex(config, providerConfig);
+  const hostDefaultArgs = profileUsesHostProviderGlobals(config) ? providerConfig.defaultArgs : [];
+  return assembleClaude(config, providerConfig, hostDefaultArgs);
+}
+
+/**
+ * Write the provisioned assets the assembly describes (Claude skills + plugins, Codex
+ * skills). Driven by the SAME resolvers `assembleLaunch` uses, so disk == launch ==
+ * report. Idempotent; the isolated home must already exist (prepare*ProfileHome). No-op
+ * for a host-base profile.
+ */
+export function materializeLaunchAssembly(provider: SpawnProvider, config: RunnerSpawnConfig): void {
+  const configHome = providerHomePathFor(provider, config);
+  if (!configHome) return;
+  if (provider === "claude") {
+    materializeResolvedAssets(resolveClaudeProvisionedSkills(configHome, config));
+    materializeResolvedAssets(resolveClaudeProvisionedPlugins(configHome, config));
+    return;
+  }
+  materializeResolvedAssets(resolveCodexProvisionedSkills(configHome, config));
+}

package/src/profile-home.ts

@@ -19,6 +19,15 @@ function profileRequiresIsolatedHome(config: RunnerSpawnConfig): boolean {
   return Boolean(config.agentProfile && config.agentProfile.base !== "host");
 }
 
+// #557 — PURE: the isolated provider config home path a launch WILL use, or undefined
+// for a host-base profile (which uses the provider's normal home). The launch assembler
+// computes the home this way to report it + build CLAUDE_CONFIG_DIR/skill/plugin paths
+// without side effects; prepare*ProfileHome creates it at the same path at spawn time.
+export function providerHomePathFor(provider: "claude" | "codex", config: RunnerSpawnConfig): string | undefined {
+  if (!profileRequiresIsolatedHome(config)) return undefined;
+  return providerHomePath(provider, config);
+}
+
 // First-run bootstrap (provider layer)
 // -------------------------------------
 // Isolated profile homes are keyed by instanceId, so every spawn gets a brand
@@ -70,6 +79,9 @@ function bootstrapClaudeFirstRun(claudeHome: string, config: RunnerSpawnConfig):
   // agent-relay communication instructions written into its config home.
   if (profileAllowsRelayFeature(config, "context")) writeClaudeRelayManual(claudeHome);
   seedClaudeConfigIfMissing(claudeHome, config);
+  // #554/#557 — relay-provisioned skills are materialized into <home>/skills by the launch
+  // assembler (materializeLaunchAssembly), the single owner of all provisioned-asset writes;
+  // the bootstrap only creates/auths the home so the assembler has somewhere to write.
   const sourceHome = process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
   return linkExistingAuthItems(sourceHome, claudeHome, CLAUDE_AUTH_ITEMS);
 }

package/src/profile-projection.ts

@@ -1,28 +1,42 @@
 import type { AgentProfile, AgentProfileProjectionEntry, AgentProfileProjectionReport, SpawnProvider } from "agent-relay-sdk";
+import type { AssembledLaunch } from "./launch-assembly";
+
+// #557 — the projection report DESCRIBES an AssembledLaunch, the same object the adapters
+// turn into launch args. It is no longer a separate re-derivation from the profile, so the
+// report and the real launch share one source of truth and cannot drift: change the
+// assembler and both the args AND this report change together. Every entry below reads a
+// field the assembler actually computed (relay gates, provisioned sets, instruction
+// disposition, vanilla mechanism, config home) — only the not-yet-enforced category modes
+// (mcp/hooks) and the purely-declarative env/permissions read straight off the profile.
 
 interface AgentProfileProjectionInput {
-  provider: SpawnProvider;
-  profile: AgentProfile;
+  assembled: AssembledLaunch;
   generatedAt?: number;
 }
 
 export function agentProfileProjectionReport(input: AgentProfileProjectionInput): AgentProfileProjectionReport {
+  const { assembled } = input;
+  const { provider } = assembled;
+  const profile = assembled.profile;
+  const generatedAt = input.generatedAt ?? Date.now();
   const entries: AgentProfileProjectionEntry[] = [];
   const add = (entry: AgentProfileProjectionEntry) => entries.push(entry);
-  const { provider, profile } = input;
-  const generatedAt = input.generatedAt ?? Date.now();
 
-  add(relayContextEntry(profile));
-  add(relaySkillsEntry(provider, profile));
-  add(relayPluginsEntry(provider, profile));
-  add(relayStatusLineEntry(provider, profile));
-  add(repoInstructionsEntry(profile));
-  add(globalInstructionsEntry(provider, profile));
-  add(mcpEntry(provider, profile));
-  add(hooksEntry(provider, profile));
-  add(filesystemEntry(profile));
-  add(configHomeEntry(provider, profile));
-  add(envEntry(profile));
+  add(relayContextEntry(assembled));
+  add(relaySkillsEntry(assembled));
+  add(relayPluginsEntry(assembled));
+  add(relayStatusLineEntry(assembled));
+  add(repoInstructionsEntry(assembled));
+  add(globalInstructionsEntry(assembled));
+  add(mcpEntry(assembled));
+  add(hooksEntry(assembled));
+  add(provisioningSkillsEntry(assembled));
+  add(provisioningPluginsEntry(assembled));
+  add(provisioningMcpEntry(assembled));
+  if (profile) add(filesystemEntry(profile));
+  add(configHomeEntry(assembled));
+  if (assembled.vanilla) add(vanillaLaunchEntry(provider));
+  if (profile) add(envEntry(profile));
 
   const warnings = entries
     .filter((entry) => entry.result === "partial" || entry.result === "unsupported")
@@ -32,9 +46,9 @@ export function agentProfileProjectionReport(input: AgentProfileProjectionInput)
     .map((entry) => entry.capability);
 
   return {
-    profileName: profile.name,
+    profileName: profile?.name ?? "default",
     provider,
-    base: profile.base,
+    base: assembled.base,
     generatedAt,
     entries,
     warnings,
@@ -42,74 +56,116 @@ export function agentProfileProjectionReport(input: AgentProfileProjectionInput)
   };
 }
 
-function relayContextEntry(profile: AgentProfile): AgentProfileProjectionEntry {
-  return profile.relay.context
+function relayContextEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  return a.relayContext
     ? applied("relay.context", "enabled", "Relay context is injected before Relay-delivered provider turns.")
     : applied("relay.context", "disabled", "Relay context injection is disabled by the profile.");
 }
 
-function relaySkillsEntry(provider: SpawnProvider, profile: AgentProfile): AgentProfileProjectionEntry {
-  if (provider === "codex") {
-    return profile.relay.skills
+function relaySkillsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  if (a.provider === "codex") {
+    return a.relaySkills
       ? applied("relay.skills", "enabled", "Bundled Agent Relay Codex skills are passed through Codex skills.config.")
       : applied("relay.skills", "disabled", "Bundled Agent Relay Codex skills are omitted.");
   }
-  return profile.relay.skills
+  return a.relaySkills
     ? applied("relay.skills", "enabled", "Agent Relay Claude skills are available through the bundled Relay plugin.")
-    : applied("relay.skills", "disabled", profile.relay.plugins
+    : applied("relay.skills", "disabled", a.relayPlugin
       ? "Claude does not expose an independent Relay skill switch; disabling skills requires disabling the Relay plugin."
       : "Bundled Agent Relay Claude plugin dirs are omitted, so Relay plugin-provided skills are unavailable.");
 }
 
-function relayPluginsEntry(provider: SpawnProvider, profile: AgentProfile): AgentProfileProjectionEntry {
-  if (provider === "claude") {
-    return profile.relay.plugins
+function relayPluginsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  if (a.provider === "claude") {
+    return a.relayPlugin
       ? applied("relay.plugins", "enabled", "Bundled Agent Relay Claude plugin dir is passed to Claude.")
       : applied("relay.plugins", "disabled", "Bundled Agent Relay Claude plugin dirs are omitted.");
   }
-  return notApplicable("relay.plugins", profile.relay.plugins ? "enabled" : "disabled", "Codex Relay integration uses skills/app-server delivery, not a Relay plugin dir.");
+  return notApplicable("relay.plugins", a.relaySkills ? "enabled" : "disabled", "Codex Relay integration uses skills/app-server delivery, not a Relay plugin dir.");
 }
 
-function relayStatusLineEntry(provider: SpawnProvider, profile: AgentProfile): AgentProfileProjectionEntry {
-  if (provider === "claude") {
-    return profile.relay.statusLine
+function relayStatusLineEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  if (a.provider === "claude") {
+    return a.statusLine
       ? applied("relay.statusLine", "enabled", "Agent Relay status-line context probe settings are injected when caller settings allow it.")
       : applied("relay.statusLine", "disabled", "Agent Relay status-line settings are omitted.");
   }
-  return notApplicable("relay.statusLine", profile.relay.statusLine ? "enabled" : "disabled", "Codex reports context through App Server events instead of a Relay status-line setting.");
+  return notApplicable("relay.statusLine", "disabled", "Codex reports context through App Server events instead of a Relay status-line setting.");
 }
 
-function repoInstructionsEntry(profile: AgentProfile): AgentProfileProjectionEntry {
-  if (profile.instructions.repoInstructions === "allow") {
-    return applied("instructions.repo", "allow", "Repo-local provider instructions are left available.");
+function repoInstructionsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const disposition = a.instructions.repo;
+  if (disposition === "allow") return applied("instructions.repo", "allow", "Repo-local provider instructions are left available.");
+  if (disposition === "suppressed") {
+    return applied("instructions.repo", "ignore", a.provider === "claude"
+      ? "Repo CLAUDE.md is suppressed: Claude launches with --setting-sources \"user\" (the project scope carrying repo CLAUDE.md is excluded; only the relay-built config home loads)."
+      : "Repo AGENTS.md is suppressed: Codex launches with project_doc_max_bytes=0 (no project doc loaded).");
   }
-  return unsupported("instructions.repo", "ignore", "Provider-specific repo instruction suppression is not projected yet.");
+  return unsupported("instructions.repo", "ignore", "Repo instruction suppression requires the vanilla base; isolated/minimal do not enforce it at launch yet.");
 }
 
-function globalInstructionsEntry(provider: SpawnProvider, profile: AgentProfile): AgentProfileProjectionEntry {
-  if (profile.instructions.globalInstructions === "allow") {
-    return applied("instructions.global", "allow", "Host/global provider instructions are left available.");
-  }
-  if (profile.base !== "host") {
-    return applied("instructions.global", "ignore", `${provider} uses an isolated provider config home, so host/global provider instructions are not loaded.`);
+// #552/#554/#555/#556 — the vanilla base's launch-time host suppression, naming the exact
+// provider mechanism the assembler emitted (Claude --setting-sources "user"; Codex
+// project_doc_max_bytes=0). OS-level admin/managed policy is beyond any client flag and is
+// called out so it isn't mistaken for a leak.
+function vanillaLaunchEntry(provider: SpawnProvider): AgentProfileProjectionEntry {
+  return provider === "claude"
+    ? applied("provider.vanilla", "--setting-sources user", "Claude launches the isolated config home under --setting-sources \"user\": host CLAUDE.md (repo + global), host skills/plugins/hooks, and host MCP (.mcp.json / ~/.claude.json) are all excluded; relay-provisioned assets in the home load. Auth, model, and built-in tools work normally. OS-level admin-managed policy still applies.")
+    : applied("provider.vanilla", "project_doc_max_bytes=0", "Codex launches with an isolated CODEX_HOME (no host config.toml MCP/hooks) and project_doc_max_bytes=0 (no AGENTS.md project doc, repo or global).");
+}
+
+function provisioningSkillsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const count = a.skills.length;
+  if (!count) return notApplicable("provisioning.skills", "none", "No relay-provisioned skills materialized for this launch.");
+  const names = ` (${a.skills.map((s) => s.name).join(", ")})`;
+  return applied("provisioning.skills", `${count}`, a.provider === "claude"
+    ? `Relay-provisioned skills materialized into the isolated config home skills/ dir, auto-discovered under --setting-sources "user"${names}.`
+    : `Relay-provisioned skills added to Codex skills.config from the isolated CODEX_HOME${names}.`);
+}
+
+function provisioningPluginsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  if (a.provider === "codex") {
+    const declared = (a.profile?.plugins ?? []).filter((p) => p.enabled).length;
+    return notApplicable("provisioning.plugins", `${declared}`, "Codex has no --plugin-dir surface; provisioned plugins apply to Claude only.");
   }
-  return unsupported("instructions.global", "ignore", `${provider} global instruction isolation requires an isolated provider config home.`);
+  const count = a.plugins.length;
+  if (!count) return notApplicable("provisioning.plugins", "none", "No relay-provisioned plugins materialized for this launch.");
+  const names = ` (${a.plugins.map((p) => p.name).join(", ")})`;
+  return applied("provisioning.plugins", `${count}`, `Relay-provisioned plugins passed to Claude via --plugin-dir${names}.`);
+}
+
+function provisioningMcpEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const names = a.mcp.servers;
+  if (!names.length) return notApplicable("provisioning.mcp", "none", "No relay-provisioned MCP servers materialized for this launch.");
+  const label = `${names.length} server${names.length === 1 ? "" : "s"}`;
+  return applied("provisioning.mcp", label, a.provider === "claude"
+    ? `Relay-provisioned MCP servers composed into --mcp-config (${names.join(", ")})${a.mcp.strict ? "; --strict-mcp-config guarantees only these load" : ""}.`
+    : `Relay-provisioned MCP servers emitted as -c mcp_servers.* overrides (${names.join(", ")}).`);
+}
+
+function globalInstructionsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const disposition = a.instructions.global;
+  if (disposition === "allow") return applied("instructions.global", "allow", "Host/global provider instructions are left available.");
+  if (disposition === "isolated") return applied("instructions.global", "ignore", `${a.provider} uses an isolated provider config home, so host/global provider instructions are not loaded.`);
+  return unsupported("instructions.global", "ignore", `${a.provider} global instruction isolation requires an isolated provider config home.`);
 }
 
-function mcpEntry(provider: SpawnProvider, profile: AgentProfile): AgentProfileProjectionEntry {
-  if (profile.mcp.mode === "host") return applied("mcp", "host", "Host provider MCP configuration is left available.");
-  if (profile.mcp.mode === "none" && profile.base !== "host") {
-    return applied("mcp", "none", `${provider} uses an isolated provider config home without host MCP configuration.`);
+function mcpEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const mode = a.profile?.mcp.mode ?? "host";
+  if (mode === "host") return applied("mcp", "host", "Host provider MCP configuration is left available.");
+  if (mode === "none" && a.base !== "host") {
+    return applied("mcp", "none", `${a.provider} uses an isolated provider config home without host MCP configuration.`);
   }
-  return unsupported("mcp", profile.mcp.mode, `${provider} MCP category projection is not enforced yet.`);
+  return unsupported("mcp", mode, `${a.provider} MCP category projection is not enforced yet.`);
 }
 
-function hooksEntry(provider: SpawnProvider, profile: AgentProfile): AgentProfileProjectionEntry {
-  if (profile.hooks.mode === "host") return applied("hooks", "host", "Host provider hooks are left available.");
-  if (profile.hooks.mode === "none" && profile.base !== "host") {
-    return applied("hooks", "none", `${provider} uses an isolated provider config home without host hook configuration.`);
+function hooksEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const mode = a.profile?.hooks.mode ?? "host";
+  if (mode === "host") return applied("hooks", "host", "Host provider hooks are left available.");
+  if (mode === "none" && a.base !== "host") {
+    return applied("hooks", "none", `${a.provider} uses an isolated provider config home without host hook configuration.`);
   }
-  return unsupported("hooks", profile.hooks.mode, `${provider} hook category projection is not enforced yet.`);
+  return unsupported("hooks", mode, `${a.provider} hook category projection is not enforced yet.`);
 }
 
 function filesystemEntry(profile: AgentProfile): AgentProfileProjectionEntry {
@@ -117,9 +173,9 @@ function filesystemEntry(profile: AgentProfile): AgentProfileProjectionEntry {
   return partial("permissions.filesystem", profile.permissions.filesystem, "Relay constrains spawn cwd through the orchestrator; provider-level filesystem sandbox projection is not complete yet.");
 }
 
-function configHomeEntry(provider: SpawnProvider, profile: AgentProfile): AgentProfileProjectionEntry {
-  if (profile.base === "host") return applied("provider.configHome", "host", "Provider uses the host's normal configuration home.");
-  return applied("provider.configHome", profile.base, `${provider} is launched with an Agent Relay managed provider config home and linked host auth where available.`);
+function configHomeEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  if (!a.configHome) return applied("provider.configHome", "host", "Provider uses the host's normal configuration home.");
+  return applied("provider.configHome", a.base, `${a.provider} is launched with an Agent Relay managed provider config home and linked host auth where available.`);
 }
 
 function envEntry(profile: AgentProfile): AgentProfileProjectionEntry {

package/src/provisioning.ts

@@ -0,0 +1,157 @@
+import { existsSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+import type { ProvisioningAssetFile, ResolvedProvisioning } from "agent-relay-sdk";
+import type { RunnerSpawnConfig } from "./adapter";
+
+// Runner-side materialization of the relay-resolved provisioning bundle
+// (#554/#555/#556). The relay resolves a profile's refs against the DB registry and
+// attaches the concrete definitions to profile.provisioning; here we turn those into
+// real on-disk dirs (skills/plugins). MCP is handled in relay-mcp.ts.
+//
+// #557 — split into PURE RESOLUTION (resolve* → where each asset lands, no writes) and
+// MATERIALIZATION (materialize* → the disk writes). The single launch assembler
+// (launch-assembly.ts) calls the resolvers to build BOTH the launch args and the
+// projection report, so what's reported can never drift from what's written; the
+// materialize* writers consume the same resolved entries, so what's written can never
+// drift from what's reported either. One resolution, three consumers.
+
+const EMPTY: ResolvedProvisioning = { skills: [], plugins: [], mcpServers: {} };
+
+export function profileProvisioning(config: Pick<RunnerSpawnConfig, "agentProfile">): ResolvedProvisioning {
+  const p = config.agentProfile?.provisioning;
+  if (!p) return EMPTY;
+  return { skills: p.skills ?? [], plugins: p.plugins ?? [], mcpServers: p.mcpServers ?? {} };
+}
+
+// A resolved provisioning asset: WHERE it lands (`dir`) and HOW it materializes
+// (`source`). `files` writes the inline set into `dir`; `link` symlinks a pre-existing
+// source dir at `dir`; `inPlace` uses the source dir as-is (no write, dir IS the source).
+export type ResolvedAssetSource =
+  | { kind: "files"; files: ProvisioningAssetFile[] }
+  | { kind: "link"; source: string }
+  | { kind: "inPlace" };
+export interface ResolvedAsset {
+  name: string;
+  dir: string;
+  source: ResolvedAssetSource;
+}
+
+function assetDirName(name: string): string {
+  return sanitizeFsName(name, { replacement: "-", collapse: false, maxLen: 120, fallback: "asset" });
+}
+
+function resolveExistingDir(dir: string, cwd: string): string | null {
+  const abs = isAbsolute(dir) ? dir : resolve(cwd, dir);
+  return existsSync(abs) ? abs : null;
+}
+
+function hasRootSkillManifest(files: ProvisioningAssetFile[]): boolean {
+  return files.some((f) => f.path === "SKILL.md");
+}
+
+// Write an inline file set into <dir>, guarding against path escapes from a malformed
+// registry entry. Shared by every files-source materialization.
+function writeInlineFiles(dir: string, files: ProvisioningAssetFile[]): void {
+  mkdirSync(dir, { recursive: true });
+  for (const file of files) {
+    const dest = resolve(dir, file.path);
+    if (!dest.startsWith(resolve(dir))) continue;
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, file.content, { mode: 0o600 });
+  }
+}
+
+// Perform the disk write a resolved asset describes. files → write inline; link →
+// (re)create the symlink; inPlace → nothing (the dir already exists at the source).
+// Best-effort for links: a failed link must not abort the launch.
+function materializeAsset(asset: ResolvedAsset): boolean {
+  if (asset.source.kind === "files") {
+    writeInlineFiles(asset.dir, asset.source.files);
+    return true;
+  }
+  if (asset.source.kind === "link") {
+    try {
+      mkdirSync(dirname(asset.dir), { recursive: true });
+      if (existsSync(asset.dir)) rmSync(asset.dir, { recursive: true, force: true });
+      symlinkSync(asset.source.source, asset.dir);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return existsSync(asset.dir);
+}
+
+// #554 (Claude) — each provisioned skill lands at <claudeHome>/skills/<name> so it's
+// auto-discovered under the launch's `--setting-sources "user"` scope (host skills
+// never bleed). Inline files are written there; a pre-existing dir is symlinked in.
+export function resolveClaudeProvisionedSkills(claudeHome: string, config: RunnerSpawnConfig): ResolvedAsset[] {
+  const { skills } = profileProvisioning(config);
+  const skillsRoot = join(claudeHome, "skills");
+  const resolved: ResolvedAsset[] = [];
+  for (const skill of skills) {
+    const dir = join(skillsRoot, assetDirName(skill.name));
+    if (skill.files?.length) {
+      resolved.push({ name: skill.name, dir, source: { kind: "files", files: skill.files } });
+      continue;
+    }
+    if (skill.dir) {
+      const source = resolveExistingDir(skill.dir, config.cwd);
+      if (source) resolved.push({ name: skill.name, dir, source: { kind: "link", source } });
+    }
+  }
+  return resolved;
+}
+
+// #556 (Claude) — each provisioned plugin resolves to a --plugin-dir. Inline plugins
+// materialize under <claudeHome>/relay-provisioned-plugins/<name>; declared dirs are
+// used in place. The resolved `dir` is appended to the launch's --plugin-dir set.
+export function resolveClaudeProvisionedPlugins(claudeHome: string, config: RunnerSpawnConfig): ResolvedAsset[] {
+  const { plugins } = profileProvisioning(config);
+  const parent = join(claudeHome, "relay-provisioned-plugins");
+  const resolved: ResolvedAsset[] = [];
+  for (const plugin of plugins) {
+    if (plugin.files?.length) {
+      resolved.push({ name: plugin.name, dir: join(parent, assetDirName(plugin.name)), source: { kind: "files", files: plugin.files } });
+      continue;
+    }
+    if (plugin.dir) {
+      const source = resolveExistingDir(plugin.dir, config.cwd);
+      if (source) resolved.push({ name: plugin.name, dir: source, source: { kind: "inPlace" } });
+    }
+  }
+  return resolved;
+}
+
+// #554 (Codex) — each provisioned skill resolves to a dir for `-c skills.config`.
+// Inline skills materialize under <codexHome>/relay-provisioned-skills/<name>; declared
+// dirs are used in place. Codex requires a SKILL.md at the dir root to register it, so
+// inline sets without one and dirs missing it are dropped at resolution time.
+export function resolveCodexProvisionedSkills(codexHome: string, config: RunnerSpawnConfig): ResolvedAsset[] {
+  const { skills } = profileProvisioning(config);
+  const parent = join(codexHome, "relay-provisioned-skills");
+  const resolved: ResolvedAsset[] = [];
+  for (const skill of skills) {
+    if (skill.files?.length) {
+      if (!hasRootSkillManifest(skill.files)) continue;
+      resolved.push({ name: skill.name, dir: join(parent, assetDirName(skill.name)), source: { kind: "files", files: skill.files } });
+      continue;
+    }
+    if (skill.dir) {
+      const source = resolveExistingDir(skill.dir, config.cwd);
+      if (source && existsSync(join(source, "SKILL.md"))) resolved.push({ name: skill.name, dir: source, source: { kind: "inPlace" } });
+    }
+  }
+  return resolved;
+}
+
+// Write the resolved assets to disk; returns the dirs that materialized successfully,
+// in resolution order. Idempotent — safe to re-run against an existing home.
+export function materializeResolvedAssets(assets: ResolvedAsset[]): string[] {
+  const dirs: string[] = [];
+  for (const asset of assets) {
+    if (materializeAsset(asset)) dirs.push(asset.dir);
+  }
+  return dirs;
+}

package/src/relay-mcp.ts

@@ -23,27 +23,6 @@ export function relayMcpEndpoint(relayUrl: string): string {
   return `${relayUrl.replace(/\/+$/, "")}${RELAY_MCP_PATH}`;
 }
 
-// Claude: additive `--mcp-config` JSON (NOT --strict-mcp-config, which would clobber
-// the user's own servers). HTTP transport, token via env-var expansion so it never
-// hits argv. Returns the full ["--mcp-config", "<json>"] arg pair.
-//
-// `endpoint` overrides the target URL: the runner passes its local MCP proxy URL (Stage 2,
-// #215) so the agent connects to the Runner, not the relay. Omitted → the direct relay endpoint.
-export function relayMcpClaudeConfigArg(relayUrl: string, endpoint?: string): string[] {
-  return [
-    "--mcp-config",
-    JSON.stringify({
-      mcpServers: {
-        [RELAY_MCP_SERVER_NAME]: {
-          type: "http",
-          url: endpoint ?? relayMcpEndpoint(relayUrl),
-          headers: { Authorization: `Bearer \${${RELAY_MCP_TOKEN_ENV}}` },
-        },
-      },
-    }),
-  ];
-}
-
 // Codex: `-c mcp_servers.<name>.*` overrides. `bearer_token_env_var` tells Codex to
 // read the token from the env var itself → transport resolves to streamable_http.
 // `endpoint` overrides the target URL (runner-local proxy, Stage 2 #215) — see above.
@@ -62,3 +41,64 @@ export function relayMcpCodexConfigArgs(relayUrl: string, endpoint?: string): st
 export function tomlString(value: string): string {
   return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
+
+// #555 — compose the launch MCP set from (the relay endpoint, if relay.mcp) PLUS the
+// profile's relay-provisioned servers. One `--mcp-config` JSON carries them all.
+// `strict` (vanilla) adds `--strict-mcp-config` so ONLY these load — host `.mcp.json`
+// / `~/.claude.json` are ignored even if a stray config exists (belt-and-suspenders
+// on top of the `--setting-sources "user"` scope that already excludes repo MCP).
+import type { ProvisioningMcpServer } from "agent-relay-sdk";
+
+function claudeMcpServerEntry(server: ProvisioningMcpServer): Record<string, unknown> {
+  const entry: Record<string, unknown> = {};
+  if (server.type) entry.type = server.type;
+  if (server.command) entry.command = server.command;
+  if (server.args?.length) entry.args = server.args;
+  if (server.env && Object.keys(server.env).length) entry.env = server.env;
+  if (server.url) entry.url = server.url;
+  if (server.headers && Object.keys(server.headers).length) entry.headers = server.headers;
+  return entry;
+}
+
+export function claudeMcpLaunchArgs(opts: {
+  relayUrl: string;
+  endpoint?: string;
+  includeRelay: boolean;
+  servers?: Record<string, ProvisioningMcpServer>;
+  strict?: boolean;
+}): string[] {
+  const mcpServers: Record<string, unknown> = {};
+  if (opts.includeRelay) {
+    mcpServers[RELAY_MCP_SERVER_NAME] = {
+      type: "http",
+      url: opts.endpoint ?? relayMcpEndpoint(opts.relayUrl),
+      headers: { Authorization: `Bearer \${${RELAY_MCP_TOKEN_ENV}}` },
+    };
+  }
+  for (const [name, server] of Object.entries(opts.servers ?? {})) {
+    // Never let a declared server shadow the relay endpoint (identity-bearing).
+    if (name === RELAY_MCP_SERVER_NAME) continue;
+    const entry = claudeMcpServerEntry(server);
+    if (Object.keys(entry).length) mcpServers[name] = entry;
+  }
+  // Nothing to inject and not enforcing strict isolation → don't pass an empty config.
+  if (Object.keys(mcpServers).length === 0 && !opts.strict) return [];
+  return ["--mcp-config", JSON.stringify({ mcpServers }), ...(opts.strict ? ["--strict-mcp-config"] : [])];
+}
+
+// #555 (Codex) — `-c mcp_servers.<name>.*` overrides for each relay-provisioned
+// server, the same shape relayMcpCodexConfigArgs uses for the relay endpoint.
+export function codexProvisionedMcpArgs(servers?: Record<string, ProvisioningMcpServer>): string[] {
+  const args: string[] = [];
+  for (const [name, server] of Object.entries(servers ?? {})) {
+    if (name === RELAY_MCP_SERVER_NAME) continue;
+    const key = `mcp_servers.${name}`;
+    if (server.command) args.push("-c", `${key}.command=${tomlString(server.command)}`);
+    if (server.args?.length) args.push("-c", `${key}.args=[${server.args.map(tomlString).join(",")}]`);
+    if (server.url) args.push("-c", `${key}.url=${tomlString(server.url)}`);
+    for (const [envKey, envVal] of Object.entries(server.env ?? {})) {
+      args.push("-c", `${key}.env.${envKey}=${tomlString(envVal)}`);
+    }
+  }
+  return args;
+}

package/src/runner-core.ts

@@ -378,7 +378,9 @@ export class AgentRunner {
         model: options.model ?? null,
         effort: options.effort ?? null,
         profile: options.profile ?? null,
-        agentProfile: options.agentProfile ? appliedAgentProfileMetadata(options.provider, options.agentProfile) : null,
+        // #557 — pass a spawn-shaped config so the projection describes the SAME assembled
+        // launch the adapter builds (env/controlPort are placeholders the pure assembler ignores).
+        agentProfile: options.agentProfile ? appliedAgentProfileMetadata(options.provider, options.agentProfile, { ...options, agentId: this.agentId, env: {}, controlPort: 0 } as RunnerSpawnConfig, options.providerConfig) : null,
         runnerId: options.runnerId,
         startedAt: options.startedAt,
         tmuxSession: this.providerTerminalSession() ?? options.tmuxSession ?? null,

package/src/runner-helpers.ts

@@ -2,8 +2,9 @@ import { closeSync, openSync, readSync, statSync } from "node:fs";
 import type { AgentProfile, ContextState, Message, ProviderCapabilities } from "agent-relay-sdk";
 import { errMessage } from "agent-relay-sdk";
 import { targetMatchesAgentIdentity } from "agent-relay-sdk/agent-target";
-import type { ProviderAdapter, SemanticStatus } from "./adapter";
+import type { ProviderAdapter, ProviderConfig, RunnerSpawnConfig, SemanticStatus } from "./adapter";
 import { agentProfileProjectionReport } from "./profile-projection";
+import { assembleLaunch } from "./launch-assembly";
 
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
 const LOG_TAIL_BYTES = 128 * 1024;
@@ -272,9 +273,17 @@ function runtimeProviderTerminalCapabilities(options: RuntimeProviderOptions): P
   return {};
 }
 
-export function appliedAgentProfileMetadata(provider: string, profile: AgentProfile): Record<string, unknown> {
-  const projection = provider === "claude" || provider === "codex"
-    ? agentProfileProjectionReport({ provider, profile })
+// #557 — the agent-card projection now DESCRIBES the assembled launch (same source the
+// adapter turns into args), so it can't drift from reality. `config`/`providerConfig` are
+// the spawn inputs; when present we assemble (pure — no disk writes here) and report that.
+export function appliedAgentProfileMetadata(
+  provider: string,
+  profile: AgentProfile,
+  config?: RunnerSpawnConfig,
+  providerConfig?: ProviderConfig,
+): Record<string, unknown> {
+  const projection = (provider === "claude" || provider === "codex") && config && providerConfig
+    ? agentProfileProjectionReport({ assembled: assembleLaunch(provider, config, providerConfig) })
     : undefined;
   return {
     name: profile.name,