agent-relay-runner 0.102.1 → 0.103.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.102.1",
+  "version": "0.103.4",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,8 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.83"
+    "agent-relay-providers": "0.102.2",
+    "agent-relay-sdk": "0.2.87"
   },
   "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.102.1",
+  "version": "0.103.4",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/plugins/claude/monitors/relay-monitor.provisioned.mjs

@@ -6,10 +6,32 @@ function isRecord(value) {
 // sdk/src/types/constants.ts
 var DEFAULT_RELAY_PORT = 4850;
 var DEFAULT_RELAY_URL = `http://127.0.0.1:${DEFAULT_RELAY_PORT}`;
-// sdk/src/provider-catalog.ts
+// providers/registry.ts
+var PROVIDER_ID_RE = /^[a-z][a-z0-9-]*$/;
+var manifests = new Map;
+function registerProvider(manifest) {
+  if (!PROVIDER_ID_RE.test(manifest.id)) {
+    throw new Error(`invalid provider id: ${manifest.id}`);
+  }
+  if (!manifest.label.trim()) {
+    throw new Error(`provider ${manifest.id} is missing a label`);
+  }
+  if (!manifest.icon.trim()) {
+    throw new Error(`provider ${manifest.id} is missing an icon`);
+  }
+  if (manifests.has(manifest.id)) {
+    throw new Error(`provider already registered: ${manifest.id}`);
+  }
+  manifests.set(manifest.id, manifest);
+}
+function getAllManifests() {
+  return [...manifests.values()];
+}
+var accountKeyAliasResolvers = new Map;
+
+// providers/claude.ts
 var CLAUDE_LOW_TO_MAX = ["low", "medium", "high", "max"];
 var CLAUDE_LOW_TO_XHIGH_MAX = ["low", "medium", "high", "xhigh", "max"];
-var CODEX_REASONING = ["low", "medium", "high", "xhigh"];
 var CONTEXT_200K = { value: 200000, source: "catalog", confidence: "declared" };
 var CONTEXT_1M = { value: 1e6, source: "catalog", confidence: "declared" };
 var CODE_MODEL_CAPABILITIES = {
@@ -26,16 +48,26 @@ var CODE_MODEL_CAPABILITIES = {
   source: "catalog",
   confidence: "declared"
 };
+var quotaWindows = [
+  { name: "five_hour", unit: "%", reset: true },
+  { name: "seven_day", unit: "%", reset: true }
+];
 function codeModel(limits) {
   return {
     ...limits ? { limits } : {},
     capabilities: CODE_MODEL_CAPABILITIES
   };
 }
-var PROVIDER_CATALOG = {
-  claude: {
-    provider: "claude",
-    label: "Claude Code",
+var claudeProviderManifest = {
+  id: "claude",
+  label: "Claude",
+  icon: "\uD83D\uDFE0",
+  launch: {
+    managedPolicyPrompt: {
+      alwaysOn: "append-system-prompt"
+    }
+  },
+  catalog: {
     defaultModel: "sonnet-4.6",
     models: [
       { alias: "fable-5", label: "Fable 5", providerModel: "claude-fable-5", efforts: CLAUDE_LOW_TO_XHIGH_MAX, defaultEffort: "medium", unavailable: "suspended by export-control directive, 2026-06-12", ...codeModel({ contextWindowTokens: CONTEXT_1M }) },
@@ -50,20 +82,210 @@ var PROVIDER_CATALOG = {
       { alias: "haiku", label: "Haiku", providerModel: "haiku", efforts: [], ...codeModel() }
     ]
   },
-  codex: {
-    provider: "codex",
-    label: "Codex",
+  quotaWindows: [...quotaWindows],
+  capabilityDefaults: {
+    lifecycle: {
+      managed: true,
+      shutdownHard: { when: "headless", value: true, otherwise: false },
+      restartHard: { when: "headless", value: true, otherwise: false },
+      semanticStatus: true,
+      reconnect: true
+    },
+    session: {
+      fileRead: true,
+      fileWrite: { when: "approval:not-read-only", value: true, otherwise: false },
+      shell: true,
+      shellMode: { open: "unrestricted", guarded: "guarded", readOnly: "read-only-guarded" }
+    },
+    context: {
+      managed: "headless",
+      compact: { when: "headless", value: true, otherwise: false },
+      clear: { when: "headless", value: true, otherwise: false },
+      inject: true,
+      resumePreference: ["native", "clear-inject", "none"]
+    },
+    quota: {
+      supported: true,
+      source: "probe",
+      unit: "%",
+      windows: [...quotaWindows]
+    },
+    terminal: {
+      mode: "live",
+      condition: "headless",
+      live: { read: true, write: true }
+    },
+    liveSession: {
+      capture: true,
+      inject: true,
+      interrupt: true,
+      promptEcho: true,
+      reasoning: true,
+      slashCommands: true
+    }
+  },
+  slashCommands: ["/clear", "/compact", "/model", "/help"],
+  resume: { supported: true, idFormat: "uuid-v4", idPattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" },
+  home: { configDir: ".claude", envPrefix: "CLAUDE", configDirEnvVar: "CLAUDE_CONFIG_DIR", quotaCredentialFile: ".credentials.json", authItems: [".credentials.json", "statsig"] },
+  provisioning: {
+    pluginManifestPath: ".claude-plugin/plugin.json",
+    bundledPlugin: {
+      ref: "agent-relay-claude-plugin",
+      dir: "runner/plugins/claude",
+      title: "Agent Relay Claude plugin",
+      description: "Bundled Agent Relay Claude plugin, materialized whole through the provisioning registry.",
+      omitFiles: ["monitors/relay-monitor.provisioned.mjs"],
+      fileOverrides: [{ path: "monitors/relay-monitor.ts", sourcePath: "monitors/relay-monitor.provisioned.mjs" }]
+    }
+  },
+  upgrade: {
+    packages: ["agent-relay-runner", "agent-relay-plugin"],
+    detectPackages: ["agent-relay-runner"],
+    detectCommands: ["claude"]
+  },
+  probe: {
+    command: "claude",
+    args: ["--version"],
+    healthCheck: "claude --version",
+    featureChecks: [{ name: "rig", command: "claude-rig", homeDir: ".claude-rig" }]
+  },
+  quotaPoll: { strategy: "none" },
+  shim: { kind: "claude-relay" }
+};
+registerProvider(claudeProviderManifest);
+
+// providers/codex.ts
+var CODEX_REASONING = ["low", "medium", "high", "xhigh"];
+var CONTEXT_200K2 = { value: 200000, source: "catalog", confidence: "declared" };
+var CODE_MODEL_CAPABILITIES2 = {
+  modalities: {
+    input: { text: true, image: true },
+    output: { text: true }
+  },
+  tools: {
+    code: true,
+    review: true,
+    debug: true,
+    refactor: true
+  },
+  source: "catalog",
+  confidence: "declared"
+};
+var quotaWindows2 = [
+  { name: "primary", unit: "%", reset: true },
+  { name: "secondary", unit: "%", reset: true }
+];
+function codeModel2(limits) {
+  return {
+    ...limits ? { limits } : {},
+    capabilities: CODE_MODEL_CAPABILITIES2
+  };
+}
+var codexProviderManifest = {
+  id: "codex",
+  label: "Codex",
+  icon: "\u2328\uFE0F",
+  launch: {
+    managedPolicyPrompt: {
+      alwaysOn: "prompt"
+    }
+  },
+  catalog: {
     defaultModel: "gpt-5.5",
     models: [
-      { alias: "gpt-5.5", label: "GPT-5.5", providerModel: "gpt-5.5", efforts: CODEX_REASONING, defaultEffort: "medium", ...codeModel({ contextWindowTokens: CONTEXT_200K }) },
-      { alias: "gpt-5.4", label: "GPT-5.4", providerModel: "gpt-5.4", efforts: CODEX_REASONING, defaultEffort: "medium", ...codeModel({ contextWindowTokens: CONTEXT_200K }) },
-      { alias: "gpt-5.4-mini", label: "GPT-5.4 Mini", providerModel: "gpt-5.4-mini", efforts: CODEX_REASONING, defaultEffort: "medium", ...codeModel({ contextWindowTokens: CONTEXT_200K }) },
-      { alias: "gpt-5.3-codex", label: "GPT-5.3 Codex", providerModel: "gpt-5.3-codex", efforts: CODEX_REASONING, defaultEffort: "medium", ...codeModel({ contextWindowTokens: CONTEXT_200K }) },
-      { alias: "gpt-5.3-codex-spark", label: "GPT-5.3 Codex Spark", providerModel: "gpt-5.3-codex-spark", efforts: CODEX_REASONING, defaultEffort: "high", ...codeModel({ contextWindowTokens: CONTEXT_200K }) },
-      { alias: "gpt-5.2", label: "GPT-5.2", providerModel: "gpt-5.2", efforts: CODEX_REASONING, defaultEffort: "medium", ...codeModel({ contextWindowTokens: CONTEXT_200K }) }
+      { alias: "gpt-5.5", label: "GPT-5.5", providerModel: "gpt-5.5", efforts: CODEX_REASONING, defaultEffort: "medium", ...codeModel2({ contextWindowTokens: CONTEXT_200K2 }) },
+      { alias: "gpt-5.4", label: "GPT-5.4", providerModel: "gpt-5.4", efforts: CODEX_REASONING, defaultEffort: "medium", ...codeModel2({ contextWindowTokens: CONTEXT_200K2 }) },
+      { alias: "gpt-5.4-mini", label: "GPT-5.4 Mini", providerModel: "gpt-5.4-mini", efforts: CODEX_REASONING, defaultEffort: "medium", ...codeModel2({ contextWindowTokens: CONTEXT_200K2 }) },
+      { alias: "gpt-5.3-codex", label: "GPT-5.3 Codex", providerModel: "gpt-5.3-codex", efforts: CODEX_REASONING, defaultEffort: "medium", ...codeModel2({ contextWindowTokens: CONTEXT_200K2 }) },
+      { alias: "gpt-5.3-codex-spark", label: "GPT-5.3 Codex Spark", providerModel: "gpt-5.3-codex-spark", efforts: CODEX_REASONING, defaultEffort: "high", ...codeModel2({ contextWindowTokens: CONTEXT_200K2 }) },
+      { alias: "gpt-5.2", label: "GPT-5.2", providerModel: "gpt-5.2", efforts: CODEX_REASONING, defaultEffort: "medium", ...codeModel2({ contextWindowTokens: CONTEXT_200K2 }) }
     ]
-  }
+  },
+  quotaWindows: [...quotaWindows2],
+  capabilityDefaults: {
+    lifecycle: {
+      managed: true,
+      shutdownHard: true,
+      restartHard: true,
+      semanticStatus: true,
+      reconnect: true
+    },
+    session: {
+      fileRead: true,
+      fileWrite: { when: "approval:not-read-only", value: true, otherwise: false },
+      shell: { when: "approval:not-read-only", value: true, otherwise: false },
+      shellMode: { open: "unrestricted", guarded: "guarded", readOnly: "none" }
+    },
+    context: {
+      managed: "always",
+      compact: true,
+      clear: true,
+      inject: true,
+      resumePreference: ["native", "clear-inject", "none"]
+    },
+    quota: {
+      supported: true,
+      source: "probe",
+      unit: "%",
+      windows: [...quotaWindows2]
+    },
+    terminal: {
+      mode: "attach",
+      attach: {
+        create: true,
+        read: true,
+        write: true,
+        detach: true
+      }
+    },
+    liveSession: {
+      capture: true,
+      inject: true,
+      interrupt: true,
+      promptEcho: true,
+      reasoning: true,
+      slashCommands: true
+    }
+  },
+  slashCommands: ["/compact", "/new"],
+  resume: { supported: true, idFormat: "codex-thread-id", idPattern: "[\\w-]+" },
+  home: { configDir: ".codex", envPrefix: "CODEX", configDirEnvVar: "CODEX_HOME", quotaCredentialFile: "auth.json", authItems: ["auth.json", "installation_id"] },
+  provisioning: {
+    pluginManifestPath: ".codex-plugin/plugin.json",
+    bundledSkills: {
+      refPrefix: "agent-relay-codex-",
+      dir: "runner/plugins/codex/skills",
+      titlePrefix: "Agent Relay Codex skill: ",
+      description: "Bundled Agent Relay Codex skill, materialized through the provisioning registry.",
+      entryFile: "SKILL.md"
+    }
+  },
+  upgrade: {
+    packages: ["agent-relay-runner", "agent-relay-codex"],
+    detectPackages: ["agent-relay-runner", "agent-relay-codex"],
+    detectCommands: ["codex-relay", "agent-relay-runner"]
+  },
+  probe: {
+    command: "codex",
+    args: ["--version"],
+    healthCheck: "codex --version"
+  },
+  quotaPoll: { strategy: "codex-app-server" },
+  shim: { kind: "codex-relay", extraBinPaths: ["codex/bin/codex"], cleanLegacyHooks: true }
 };
+registerProvider(codexProviderManifest);
+// sdk/src/types/agents.ts
+var SPAWN_PROVIDERS = getAllManifests().map((manifest) => manifest.id);
+// sdk/src/provider-catalog.ts
+function manifestToCatalogEntry(manifest) {
+  return {
+    provider: manifest.id,
+    label: manifest.label,
+    defaultModel: manifest.catalog.defaultModel,
+    models: manifest.catalog.models
+  };
+}
+var PROVIDER_CATALOG = Object.fromEntries(getAllManifests().map((manifest) => [manifest.id, manifestToCatalogEntry(manifest)]));
 // sdk/src/reconnect.ts
 import { setTimeout as delay } from "timers/promises";
 var DEFAULTS = {

package/src/{claude-quota-harvest.ts → adapters/claude-quota-harvest.ts}

@@ -1,7 +1,7 @@
 import type { QuotaState, RelayHttpClient } from "agent-relay-sdk";
 import { quotaStateFromProbeMetrics } from "agent-relay-sdk/context-probe";
-import { readRunnerContextProbeState } from "./context-probe-state";
-import { DEFAULT_PROVIDER_QUOTA_CONFIG, normalizeProviderQuotaConfig, resolveClaudeStatuslineQuotaIdentity } from "./quota";
+import { readRunnerContextProbeState } from "../context-probe-state";
+import { DEFAULT_PROVIDER_QUOTA_CONFIG, normalizeProviderQuotaConfig, resolveClaudeStatuslineQuotaIdentity } from "../quota";
 
 const PASSIVE_QUOTA_CONFIG_REFRESH_MS = 60_000;
 const PASSIVE_QUOTA_SAMPLE_STALE_MS = 10 * 60_000;

package/src/config.ts

@@ -5,6 +5,7 @@ import { dirname, join, resolve } from "node:path";
 import { DEFAULT_RELAY_URL, RELAY_TOKEN_HEADER, errMessage, stringValue } from "agent-relay-sdk";
 import type { SettingEntry, WorkspaceMetadata } from "agent-relay-sdk";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+import { getManifest } from "agent-relay-providers";
 
 interface ProviderConfig {
   command: string;
@@ -40,11 +41,15 @@ function providersDir(home = agentRelayHome()): string {
   return join(home, "providers");
 }
 
+const DEFAULT_PROVIDER_ARGS: Record<string, string[]> = {
+  claude: ["--dangerously-skip-permissions"],
+};
+
 export function defaultProviderConfig(provider: string): ProviderConfig {
-  const command = provider === "claude" ? "claude" : provider;
+  const manifest = getManifest(provider);
   return {
-    command,
-    defaultArgs: provider === "claude" ? ["--dangerously-skip-permissions"] : [],
+    command: manifest?.probe?.command ?? provider,
+    defaultArgs: DEFAULT_PROVIDER_ARGS[provider] ?? [],
     env: {},
     pluginDirs: [],
     defaultCapabilities: ["chat", "code", "review"],

package/src/index.ts

@@ -26,6 +26,7 @@ import { createProviderAdapter } from "./providers";
 import { VERSION } from "./version";
 import type { AgentProfile, RelayInjectionCategory, SpawnProvider, WorkspaceMetadata } from "agent-relay-sdk";
 import { errMessage, isRecord, normalizeAgentLifecycle, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+import { getAllManifests } from "agent-relay-providers";
 import type { RunnerRelayInjectionEvent } from "./relay-injection-events";
 
 interface CliOptions {
@@ -233,9 +234,20 @@ export function isVersionRequest(argv: string[]): boolean {
   return ownArgs.some((arg) => arg === "--version" || arg === "-v");
 }
 
-function parseArgs(argv: string[]): CliOptions {
+function detectProviderFromBin(argv: string[]): SpawnProvider {
   const bin = [argv[1], process.env._].map((s) => basename(s || "")).join(" ");
-  let provider: SpawnProvider = bin.includes("claude") ? "claude" : "codex";
+  for (const manifest of getAllManifests()) {
+    if (bin.includes(manifest.id)) return manifest.id as SpawnProvider;
+  }
+  return getAllManifests()[0]?.id as SpawnProvider ?? "claude";
+}
+
+function isRegisteredProvider(value: string): value is SpawnProvider {
+  return getAllManifests().some((m) => m.id === value);
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  let provider = detectProviderFromBin(argv);
   const relayArgs = argv.slice(2);
   const providerSep = relayArgs.indexOf("--");
   const ownArgs = providerSep >= 0 ? relayArgs.slice(0, providerSep) : relayArgs;
@@ -258,7 +270,7 @@ function parseArgs(argv: string[]): CliOptions {
 
   for (let i = 0; i < ownArgs.length; i++) {
     const arg = ownArgs[i];
-    if (arg === "claude" || arg === "codex") provider = arg;
+    if (arg && isRegisteredProvider(arg)) provider = arg;
     else if (arg === "--headless") headless = true;
     else if (arg === "--model" && ownArgs[i + 1]) model = ownArgs[++i];
     else if (arg === "--effort" && ownArgs[i + 1]) effort = ownArgs[++i];
@@ -338,9 +350,10 @@ function signalPromise(): Promise<number> {
   });
 }
 
-export function detectApprovalModeFromArgs(provider: string, defaultArgs: string[], providerArgs: string[]): string | undefined {
-  const allArgs = [...defaultArgs, ...providerArgs];
-  if (provider === "claude") {
+type ApprovalModeDetector = (allArgs: string[]) => string | undefined;
+
+const APPROVAL_MODE_DETECTORS: Record<string, ApprovalModeDetector> = {
+  claude(allArgs) {
     if (allArgs.includes("--dangerously-skip-permissions")) return "open";
     const modeIdx = allArgs.lastIndexOf("--permission-mode");
     if (modeIdx >= 0) {
@@ -349,8 +362,8 @@ export function detectApprovalModeFromArgs(provider: string, defaultArgs: string
       if (mode === "default") return "guarded";
     }
     return undefined;
-  }
-  if (provider === "codex") {
+  },
+  codex(allArgs) {
     if (allArgs.includes("--yolo")) return "open";
     for (let i = 0; i < allArgs.length; i++) {
       if (allArgs[i] === "-c" || allArgs[i] === "--config") {
@@ -360,8 +373,12 @@ export function detectApprovalModeFromArgs(provider: string, defaultArgs: string
       }
     }
     return undefined;
-  }
-  return undefined;
+  },
+};
+
+export function detectApprovalModeFromArgs(provider: string, defaultArgs: string[], providerArgs: string[]): string | undefined {
+  const detector = APPROVAL_MODE_DETECTORS[provider];
+  return detector ? detector([...defaultArgs, ...providerArgs]) : undefined;
 }
 
 if (import.meta.main) {

package/src/launch-assembly.ts

@@ -8,12 +8,13 @@ import {
   type RunnerSpawnConfig,
 } from "./adapter";
 import {
-  claudeProjectConfigProjectionOn,
+  projectConfigProjectionOn,
   hostUserScopeMcpServers,
-  profileUsesClaudeHostProviderGlobals,
+  profileUsesProviderHostGlobals,
   providerHomePathFor,
   providerProvisioningHomePathFor,
 } from "./profile-home";
+import { getManifest } from "agent-relay-providers";
 import { claudeLaunchPromptGateSettings } from "./claude-prompt-gates";
 import {
   materializeResolvedAssets,
@@ -229,7 +230,7 @@ function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfi
   const configHome = providerHomePathFor("claude", config);
   const assetHome = providerProvisioningHomePathFor("claude", config);
   const vanilla = profileIsVanillaBase(config);
-  const projectConfigProjection = claudeProjectConfigProjectionOn(config);
+  const projectConfigProjection = projectConfigProjectionOn(config);
   const relayPlugin = profileAllowsRelayFeature(config, "plugins");
   const relaySkills = profileAllowsRelayFeature(config, "skills");
   const statusLine = profileAllowsRelayFeature(config, "statusLine");
@@ -248,7 +249,7 @@ function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfi
   //   host plugin dirs → ONLY host-base profiles; isolated/vanilla must not pull them back in.
   const relayPluginDirs = !config.agentProfile && relayPlugin ? [CLAUDE_RELAY_PLUGIN_DIR] : [];
   const provisionedPluginDirs = provisionedPlugins.map((p) => p.dir);
-  const hostPluginDirs = profileUsesClaudeHostProviderGlobals(config) ? providerConfig.pluginDirs : [];
+  const hostPluginDirs = profileUsesProviderHostGlobals(config) ? providerConfig.pluginDirs : [];
   const pluginDirs = [...new Set([...relayPluginDirs, ...provisionedPluginDirs, ...hostPluginDirs])];
 
   const provisionedMcp = profileProvisioning(config).mcpServers;
@@ -295,7 +296,7 @@ function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfi
   // still excluded) when the launch both uses the host config home AND its mcp mode is host.
   // An isolated/minimal base has its own config home and never had the real host's user MCP,
   // so it stays relay+provisioned only even if a profile sets mode:"host".
-  const usesHostMcp = profileUsesClaudeHostProviderGlobals(config)
+  const usesHostMcp = profileUsesProviderHostGlobals(config)
     && (!config.agentProfile || config.agentProfile.mcp.mode === "host");
   const hostMcp = usesHostMcp ? hostUserScopeMcpServers() : {};
   const hostMcpServers = Object.keys(hostMcp).filter(
@@ -346,7 +347,7 @@ function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfi
     },
     instructions,
     args,
-    env: configHome ? { CLAUDE_CONFIG_DIR: configHome } : {},
+    env: configHomeEnv("claude", configHome),
   };
 }
 
@@ -418,19 +419,58 @@ function assembleCodex(config: RunnerSpawnConfig, _providerConfig: ProviderConfi
     },
     instructions,
     args,
-    env: configHome ? { CODEX_HOME: configHome } : {},
+    env: configHomeEnv("codex", configHome),
   };
 }
 
+// ── Manifest-driven env + dispatch ────────────────────────────────────────────
+
+function configHomeEnv(provider: string, configHome: string | undefined): Record<string, string> {
+  if (!configHome) return {};
+  const manifest = getManifest(provider);
+  const envVar = manifest?.home?.configDirEnvVar;
+  return envVar ? { [envVar]: configHome } : {};
+}
+
+type Assembler = (config: RunnerSpawnConfig, providerConfig: ProviderConfig, hostDefaultArgs: string[]) => AssembledLaunch;
+type Materializer = (config: RunnerSpawnConfig) => void;
+
+const ASSEMBLERS: Record<string, Assembler> = {
+  claude: assembleClaude,
+  codex: (config, providerConfig) => assembleCodex(config, providerConfig),
+};
+
+const MATERIALIZERS: Record<string, Materializer> = {
+  claude: materializeClaudeAssets,
+  codex: materializeCodexAssets,
+};
+
+function materializeClaudeAssets(config: RunnerSpawnConfig): void {
+  const configHome = providerHomePathFor("claude", config);
+  const assetHome = providerProvisioningHomePathFor("claude", config);
+  if (configHome) {
+    const skills = resolveClaudeProvisionedSkills(configHome, config);
+    materializeResolvedAssets(skills);
+    materializeResolvedAssets(resolveClaudeProjectSkills(configHome, config, new Set(skills.map((s) => s.name))));
+  }
+  if (assetHome) materializeResolvedAssets(resolveClaudeProvisionedPlugins(assetHome, config));
+}
+
+function materializeCodexAssets(config: RunnerSpawnConfig): void {
+  const assetHome = providerProvisioningHomePathFor("codex", config);
+  if (assetHome) materializeResolvedAssets(resolveCodexProvisionedSkills(assetHome, config));
+}
+
 /**
  * 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 = profileUsesClaudeHostProviderGlobals(config) ? providerConfig.defaultArgs : [];
-  return assembleClaude(config, providerConfig, hostDefaultArgs);
+  const assembler = ASSEMBLERS[provider];
+  if (!assembler) throw new Error(`no launch assembler registered for provider: ${provider}`);
+  const hostDefaultArgs = profileUsesProviderHostGlobals(config) ? providerConfig.defaultArgs : [];
+  return assembler(config, providerConfig, hostDefaultArgs);
 }
 
 /**
@@ -443,14 +483,6 @@ export function materializeLaunchAssembly(provider: SpawnProvider, config: Runne
   const configHome = providerHomePathFor(provider, config);
   const assetHome = providerProvisioningHomePathFor(provider, config);
   if (!configHome && !assetHome) return;
-  if (provider === "claude") {
-    if (configHome) {
-      const skills = resolveClaudeProvisionedSkills(configHome, config);
-      materializeResolvedAssets(skills);
-      materializeResolvedAssets(resolveClaudeProjectSkills(configHome, config, new Set(skills.map((s) => s.name))));
-    }
-    if (assetHome) materializeResolvedAssets(resolveClaudeProvisionedPlugins(assetHome, config));
-    return;
-  }
-  if (assetHome) materializeResolvedAssets(resolveCodexProvisionedSkills(assetHome, config));
+  const materializer = MATERIALIZERS[provider];
+  if (materializer) materializer(config);
 }

package/src/profile-home.ts

@@ -2,7 +2,8 @@ import { existsSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
-import type { ProvisioningMcpServer } from "agent-relay-sdk";
+import type { ProvisioningMcpServer, SpawnProvider } from "agent-relay-sdk";
+import { getManifest } from "agent-relay-providers";
 import { profileAllowsRelayFeature, type RunnerSpawnConfig } from "./adapter";
 import { CLAUDE_RELAY_MANUAL } from "./relay-instructions";
 import { providerHomeRootFromEnv } from "./config";
@@ -17,25 +18,31 @@ export function profileUsesHostProviderGlobals(config: { agentProfile?: RunnerSp
   return !config.agentProfile || config.agentProfile.base === "host";
 }
 
-export function claudeProjectConfigProjectionOn(config: { agentProfile?: RunnerSpawnConfig["agentProfile"] }): boolean {
+export function projectConfigProjectionOn(config: { agentProfile?: RunnerSpawnConfig["agentProfile"] }): boolean {
   return Boolean(config.agentProfile?.projectSkills || config.agentProfile?.projectSettings);
 }
 
-export function profileUsesClaudeHostProviderGlobals(config: { agentProfile?: RunnerSpawnConfig["agentProfile"] }): boolean {
-  return profileUsesHostProviderGlobals(config) && !claudeProjectConfigProjectionOn(config);
+/** @deprecated Use {@link projectConfigProjectionOn}. */
+export { projectConfigProjectionOn as claudeProjectConfigProjectionOn };
+
+export function profileUsesProviderHostGlobals(config: { agentProfile?: RunnerSpawnConfig["agentProfile"] }): boolean {
+  return profileUsesHostProviderGlobals(config) && !projectConfigProjectionOn(config);
 }
 
-function profileRequiresIsolatedHome(provider: "claude" | "codex", config: RunnerSpawnConfig): boolean {
+/** @deprecated Use {@link profileUsesProviderHostGlobals}. */
+export { profileUsesProviderHostGlobals as profileUsesClaudeHostProviderGlobals };
+
+function profileRequiresIsolatedHome(_provider: SpawnProvider, config: RunnerSpawnConfig): boolean {
   if (!config.agentProfile) return false;
   if (config.agentProfile.base !== "host") return true;
-  return provider === "claude" && claudeProjectConfigProjectionOn(config);
+  return projectConfigProjectionOn(config);
 }
 
 // #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 {
+export function providerHomePathFor(provider: SpawnProvider, config: RunnerSpawnConfig): string | undefined {
   if (!profileRequiresIsolatedHome(provider, config)) return undefined;
   return providerHomePath(provider, config);
 }
@@ -44,7 +51,7 @@ export function providerHomePathFor(provider: "claude" | "codex", config: Runner
 // host-base profiles, where the provider's real config home stays in use. This path is
 // only passed explicitly through launch args such as Codex skills.config or Claude
 // --plugin-dir; it does not imply CODEX_HOME/CLAUDE_CONFIG_DIR isolation.
-export function providerProvisioningHomePathFor(provider: "claude" | "codex", config: RunnerSpawnConfig): string | undefined {
+export function providerProvisioningHomePathFor(provider: SpawnProvider, config: RunnerSpawnConfig): string | undefined {
   if (!config.agentProfile) return undefined;
   return providerHomePathFor(provider, config) ?? join(providerHomePath(provider, config), "provisioning");
 }
@@ -67,44 +74,45 @@ export function providerProvisioningHomePathFor(provider: "claude" | "codex", co
 // (claude-rig / host-base launches dodge all of this via onboarded host config +
 // --dangerously-skip-permissions; only isolated homes need the bootstrap.)
 
-// Host auth items symlinked into a fresh isolated home so the provider is
-// launch-ready without a re-login. One list per provider — single source.
-const CODEX_AUTH_ITEMS = ["auth.json", "installation_id"];
-const CLAUDE_AUTH_ITEMS = [".credentials.json", "statsig"];
+// Provider-specific first-run bootstrap hooks, registered at module load.
+type BootstrapHook = (home: string, config: RunnerSpawnConfig) => void;
+const BOOTSTRAP_HOOKS = new Map<string, BootstrapHook>();
 
-// Shared skeleton for both providers: gate on isolated-profile, make the
-// instance-keyed home, run the provider-specific first-run bootstrap. The
-// bootstrap step is the only genuinely provider-specific part.
-function prepareProviderHome(provider: "claude" | "codex", config: RunnerSpawnConfig): ProviderHome | undefined {
+// Shared skeleton: gate on isolated-profile, make the instance-keyed home,
+// link auth items from the manifest, and run any registered first-run hook.
+function prepareProviderHome(provider: SpawnProvider, config: RunnerSpawnConfig): ProviderHome | undefined {
   if (!profileRequiresIsolatedHome(provider, config)) return undefined;
   const target = providerHomePath(provider, config);
   mkdirSync(target, { recursive: true });
-  const authLinked = provider === "codex"
-    ? bootstrapCodexFirstRun(target, config)
-    : bootstrapClaudeFirstRun(target, config);
+  const hook = BOOTSTRAP_HOOKS.get(provider);
+  if (hook) hook(target, config);
+  const manifest = getManifest(provider);
+  const authItems = manifest?.home?.authItems ?? [];
+  const sourceHome = providerSourceHome(provider);
+  const authLinked = linkExistingAuthItems(sourceHome, target, authItems);
   return { path: target, authLinked };
 }
 
 export const prepareCodexProfileHome = (config: RunnerSpawnConfig) => prepareProviderHome("codex", config);
 export const prepareClaudeProfileHome = (config: RunnerSpawnConfig) => prepareProviderHome("claude", config);
 
-function bootstrapCodexFirstRun(codexHome: string, config: RunnerSpawnConfig): string[] {
+function bootstrapCodexFirstRun(codexHome: string, config: RunnerSpawnConfig): void {
   trustWorkspaceForCodex(codexHome, config);
-  const sourceHome = process.env.CODEX_HOME || join(homedir(), ".codex");
-  return linkExistingAuthItems(sourceHome, codexHome, CODEX_AUTH_ITEMS);
 }
 
-function bootstrapClaudeFirstRun(claudeHome: string, config: RunnerSpawnConfig): string[] {
-  // Only inject the Relay usage manual when the profile actually wants a Relay
-  // surface. An isolated-research profile (relay.context disabled) must not get
-  // agent-relay communication instructions written into its config home.
+function bootstrapClaudeFirstRun(claudeHome: string, config: RunnerSpawnConfig): void {
   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);
+}
+
+BOOTSTRAP_HOOKS.set("codex", bootstrapCodexFirstRun);
+BOOTSTRAP_HOOKS.set("claude", bootstrapClaudeFirstRun);
+
+function providerSourceHome(provider: string): string {
+  const manifest = getManifest(provider);
+  const envVar = manifest?.home?.configDirEnvVar;
+  const configDir = manifest?.home?.configDir ?? `.${provider}`;
+  return (envVar && process.env[envVar]) || join(homedir(), configDir);
 }
 
 function seedClaudeConfigIfMissing(claudeHome: string, config: RunnerSpawnConfig): void {
@@ -139,7 +147,7 @@ export function hostUserScopeMcpServers(): Record<string, ProvisioningMcpServer>
   return servers as Record<string, ProvisioningMcpServer>;
 }
 
-function providerHomePath(provider: "claude" | "codex", config: RunnerSpawnConfig): string {
+function providerHomePath(provider: SpawnProvider, config: RunnerSpawnConfig): string {
   const root = providerHomeRootFromEnv();
   const profileName = sanitizePathPart(config.agentProfile?.name || config.profile || "profile");
   const instance = sanitizePathPart(config.instanceId || config.runnerId);

package/src/profile-projection.ts

@@ -1,4 +1,5 @@
 import type { AgentProfile, AgentProfileProjectionEntry, AgentProfileProjectionReport, SpawnProvider } from "agent-relay-sdk";
+import { getManifest } from "agent-relay-providers";
 import type { AssembledLaunch } from "./launch-assembly";
 
 // #557 — the projection report DESCRIBES an AssembledLaunch, the same object the adapters
@@ -68,43 +69,52 @@ function relayContextEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
 }
 
 function relaySkillsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
-  if (a.provider === "codex") {
+  const manifest = getManifest(a.provider);
+  const label = manifest?.label ?? a.provider;
+  const hasPluginSurface = Boolean(manifest?.provisioning?.bundledPlugin);
+  if (!hasPluginSurface) {
     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.");
+      ? applied("relay.skills", "enabled", `Bundled Agent Relay ${label} skills are passed through the provider's skill delivery mechanism.`)
+      : applied("relay.skills", "disabled", `Bundled Agent Relay ${label} skills are omitted.`);
   }
   return a.relaySkills
-    ? applied("relay.skills", "enabled", "Agent Relay Claude skills are available through the bundled Relay plugin.")
+    ? applied("relay.skills", "enabled", `Agent Relay ${label} skills are available through the bundled Relay plugin.`)
     : 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.");
+      ? `${label} does not expose an independent Relay skill switch; disabling skills requires disabling the Relay plugin.`
+      : `Bundled Agent Relay ${label} plugin dirs are omitted, so Relay plugin-provided skills are unavailable.`);
 }
 
 function relayPluginsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
-  if (a.provider === "claude") {
+  const manifest = getManifest(a.provider);
+  const label = manifest?.label ?? a.provider;
+  const hasPluginSurface = Boolean(manifest?.provisioning?.bundledPlugin);
+  if (hasPluginSurface) {
     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.");
+      ? applied("relay.plugins", "enabled", `Bundled Agent Relay ${label} plugin dir is passed to ${label}.`)
+      : applied("relay.plugins", "disabled", `Bundled Agent Relay ${label} plugin dirs are omitted.`);
   }
-  return notApplicable("relay.plugins", a.relaySkills ? "enabled" : "disabled", "Codex Relay integration uses skills/app-server delivery, not a Relay plugin dir.");
+  return notApplicable("relay.plugins", a.relaySkills ? "enabled" : "disabled", `${label} Relay integration uses skills/app-server delivery, not a Relay plugin dir.`);
 }
 
 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.");
+  const manifest = getManifest(a.provider);
+  const label = manifest?.label ?? a.provider;
+  if (a.statusLine) {
+    return applied("relay.statusLine", "enabled", "Agent Relay status-line context probe settings are injected when caller settings allow it.");
   }
-  return notApplicable("relay.statusLine", "disabled", "Codex reports context through App Server events instead of a Relay status-line setting.");
+  const hasPluginSurface = Boolean(manifest?.provisioning?.bundledPlugin);
+  if (hasPluginSurface) {
+    return applied("relay.statusLine", "disabled", "Agent Relay status-line settings are omitted.");
+  }
+  return notApplicable("relay.statusLine", "disabled", `${label} reports context through provider-native events instead of a Relay status-line setting.`);
 }
 
 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).");
+    const label = getManifest(a.provider)?.label ?? a.provider;
+    return applied("instructions.repo", "ignore", `Repo project instructions are suppressed: ${label} launches with the vanilla base mechanism (provider-specific suppression of repo instructions).`);
   }
   return unsupported("instructions.repo", "ignore", "Repo instruction suppression requires the vanilla base; isolated/minimal do not enforce it at launch yet.");
 }
@@ -113,39 +123,55 @@ function repoInstructionsEntry(a: AssembledLaunch): AgentProfileProjectionEntry
 // 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.
+const VANILLA_MECHANISM: Record<string, { requested: string; detail: string }> = {
+  claude: {
+    requested: "--setting-sources user",
+    detail: "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.",
+  },
+  codex: {
+    requested: "project_doc_max_bytes=0",
+    detail: "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 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).");
+  const label = getManifest(provider)?.label ?? provider;
+  const mechanism = VANILLA_MECHANISM[provider];
+  return applied(
+    "provider.vanilla",
+    mechanism?.requested ?? "active",
+    mechanism?.detail ?? `${label} launches with the vanilla base: an isolated provider config home and provider-specific repo instruction suppression. Auth, model, and built-in tools work normally.`,
+  );
 }
 
 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}.`);
+  const label = getManifest(a.provider)?.label ?? a.provider;
+  return applied("provisioning.skills", `${count}`, `Relay-provisioned skills materialized for ${label} from the isolated provider config home${names}.`);
 }
 
 function provisioningPluginsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
-  if (a.provider === "codex") {
+  const manifest = getManifest(a.provider);
+  const label = manifest?.label ?? a.provider;
+  const hasPluginSurface = Boolean(manifest?.provisioning?.bundledPlugin);
+  if (!hasPluginSurface) {
     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 notApplicable("provisioning.plugins", `${declared}`, `${label} has no plugin surface; provisioned plugins apply to plugin-capable providers only.`);
   }
   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}.`);
+  return applied("provisioning.plugins", `${count}`, `Relay-provisioned plugins passed to ${label} via the plugin dir mechanism${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(", ")}).`);
+  const count = `${names.length} server${names.length === 1 ? "" : "s"}`;
+  const providerLabel = getManifest(a.provider)?.label ?? a.provider;
+  return applied("provisioning.mcp", count, `Relay-provisioned MCP servers injected for ${providerLabel} (${names.join(", ")})${a.mcp.strict ? "; strict mode guarantees only declared servers load" : ""}.`);
 }
 
 function provisioningSkippedEntries(a: AssembledLaunch): AgentProfileProjectionEntry[] {
@@ -164,16 +190,14 @@ function projectMcpEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
   const names = a.mcp.projectServers;
   if (!optedIn) return notApplicable("projectMcp", "off", "Project .mcp.json projection is off (opt in via the projectMcp profile/spawn option).");
   if (!names.length) return applied("projectMcp", "none", "Project .mcp.json projection is on, but the spawn cwd declared no injectable MCP servers.");
-  const label = `${names.length} server${names.length === 1 ? "" : "s"}`;
-  return applied("projectMcp", label, a.provider === "claude"
-    ? `Project .mcp.json servers composed into --mcp-config (${names.join(", ")})${a.mcp.strict ? "; survives --strict-mcp-config" : ""}.`
-    : `Project .mcp.json servers emitted as -c mcp_servers.* overrides (${names.join(", ")}).`);
+  const count = `${names.length} server${names.length === 1 ? "" : "s"}`;
+  return applied("projectMcp", count, `Project .mcp.json servers injected for this launch (${names.join(", ")})${a.mcp.strict ? "; survives strict MCP mode" : ""}.`);
 }
 
 function projectSkillsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
   const optedIn = Boolean(a.profile?.projectSkills);
   if (!optedIn) return notApplicable("projectSkills", "off", "Project .claude/skills projection is off (opt in via the projectSkills profile/spawn option).");
-  if (a.provider !== "claude") return notApplicable("projectSkills", "unsupported", "Project .claude/skills projection applies to Claude launches only.");
+  if (!getManifest(a.provider)?.provisioning?.bundledPlugin) return notApplicable("projectSkills", "unsupported", "Project skills projection applies to plugin-capable providers only.");
   if (!a.projectSkills.length) return applied("projectSkills", "none", "Project .claude/skills projection is on, but the spawn cwd declared no valid skill dirs.");
   const names = a.projectSkills.map((s) => s.name).join(", ");
   return applied("projectSkills", `${a.projectSkills.length}`, `Project .claude skills materialized into Relay's managed Claude config home (${names}); host/global skills are excluded.`);
@@ -182,7 +206,7 @@ function projectSkillsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
 function projectSettingsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
   const optedIn = Boolean(a.profile?.projectSettings);
   if (!optedIn) return notApplicable("projectSettings", "off", "Project .claude/settings.json projection is off (opt in via the projectSettings profile/spawn option).");
-  if (a.provider !== "claude") return notApplicable("projectSettings", "unsupported", "Project .claude/settings.json projection applies to Claude launches only.");
+  if (!getManifest(a.provider)?.provisioning?.bundledPlugin) return notApplicable("projectSettings", "unsupported", "Project settings projection applies to plugin-capable providers only.");
   const ignored = a.projectSettings.ignoredKeys.length ? `; ignored security keys: ${a.projectSettings.ignoredKeys.join(", ")}` : "";
   return applied("projectSettings", a.projectSettings.keys.length ? `${a.projectSettings.keys.length} keys` : "none", `Project .claude/settings.json was sanitized and injected through --settings; Relay approvalMode/permission gates remain authoritative${ignored}.`);
 }
@@ -194,9 +218,7 @@ function sharedMcpEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
   const optedIn = Boolean(a.profile?.sharedMcp);
   const listener = a.mcp.sharedListener;
   if (!optedIn || !listener) return notApplicable("sharedMcp", "off", "Shared host-listener MCP is off for this resolved profile; non-identity MCP is injected per-agent.");
-  return applied("sharedMcp", "on", a.provider === "claude"
-    ? `Non-identity MCP (e.g. tokenlean, github) routed through the shared callmux listener (${listener.url}) via a per-agent 'callmux bridge --cwd "$WORKTREE"', injected into --mcp-config (survives --strict-mcp-config); session survives a listener restart, session-cwd isolated. Relay endpoint stays per-agent (#215).`
-    : `Non-identity MCP (e.g. tokenlean, github) routed through the shared callmux listener (${listener.url}) via a per-agent 'callmux bridge --cwd "$WORKTREE"' emitted as -c mcp_servers.* overrides; session survives a listener restart, session-cwd isolated. Relay endpoint stays per-agent (#215).`);
+  return applied("sharedMcp", "on", `Non-identity MCP (e.g. tokenlean, github) routed through the shared callmux listener (${listener.url}) via a per-agent 'callmux bridge --cwd "$WORKTREE"'; session survives a listener restart, session-cwd isolated. Relay endpoint stays per-agent.`);
 }
 
 function globalInstructionsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {

package/src/providers.ts

@@ -8,11 +8,13 @@ interface RunnerProviderRegistration {
   createAdapter: () => ProviderAdapter;
 }
 
-const RUNNER_PROVIDERS: Record<SpawnProvider, RunnerProviderRegistration> = {
+const RUNNER_PROVIDERS: Record<string, RunnerProviderRegistration> = {
   claude: { provider: "claude", createAdapter: () => new ClaudeAdapter() },
   codex: { provider: "codex", createAdapter: () => new CodexAdapter() },
 };
 
 export function createProviderAdapter(provider: SpawnProvider): ProviderAdapter {
-  return RUNNER_PROVIDERS[provider].createAdapter();
+  const registration = RUNNER_PROVIDERS[provider];
+  if (!registration) throw new Error(`unsupported provider adapter: ${provider}`);
+  return registration.createAdapter();
 }

package/src/relay-injection-events.ts

@@ -1,4 +1,5 @@
-import type { MessageSessionMeta, RelayInjectionCategory, SpawnProvider } from "agent-relay-sdk";
+import type { MessageSessionMeta, RelayInjectionCategory } from "agent-relay-sdk";
+import { isSpawnProvider } from "agent-relay-sdk";
 import type { ProviderConfig, RunnerSpawnConfig } from "./adapter";
 import { assembleLaunch } from "./launch-assembly";
 
@@ -30,13 +31,9 @@ interface RunnerLaunchInjectionInput {
   timestamp?: number;
 }
 
-function supportsLaunchAssembly(provider: string): provider is SpawnProvider {
-  return provider === "claude" || provider === "codex";
-}
-
 function launchInjectionEvents(input: RunnerLaunchInjectionInput): KeyedRelayInjectionEvent[] {
   const events: KeyedRelayInjectionEvent[] = (input.carried ?? []).map((event, index) => ({ key: `spawn-${index}`, event }));
-  if (!supportsLaunchAssembly(input.provider)) return events;
+  if (!isSpawnProvider(input.provider)) return events;
   const assembled = assembleLaunch(input.provider, input.config, input.providerConfig);
   const toolCount = assembled.skills.length + assembled.plugins.length + assembled.mcp.servers.length
     + assembled.projectSkills.length

package/src/runner-core.ts

@@ -11,13 +11,14 @@ import { computeLivenessSignal, type LivenessInputs } from "./liveness";
 import type { ManagedProcess, ProviderAdapter, ProviderConfig, ProviderPermissionDecision, ProviderPermissionDecisionInput, ProviderSessionEvent, ProviderStatusUpdate, RunnerSpawnConfig, SemanticStatus, TerminalAttachSpec } from "./adapter";
 import { messagesWithCachedAttachments } from "./attachment-cache";
 import { ClaimTracker } from "./claim-tracker";
-import { ClaudeQuotaHarvest } from "./claude-quota-harvest";
+import { ClaudeQuotaHarvest } from "./adapters/claude-quota-harvest";
 import { readRunnerContextProbeState } from "./context-probe-state";
 import { startControlServer, type ControlServer, type ResolvedPermissionPrompt } from "./control-server";
 import { ReplyObligationCache, obligationRequiresExplicitReply, responseCaptureReplyRoute } from "./reply-obligation-cache";
 import { Outbox, type OutboxRecord } from "./outbox";
 import { extractLastAssistantTurn, extractLastAssistantTurnAfterEntry, countTranscriptEntries, extractFinalAssistantMessage, extractFinalAssistantMessageAfterEntry, extractHookAssistantMessage, extractLatestTurnSteps, stepDedupKeys, transcriptLooksComplete } from "./adapters/claude-transcript";
-import { profileUsesClaudeHostProviderGlobals, profileUsesHostProviderGlobals } from "./profile-home";
+import { getManifest } from "agent-relay-providers";
+import { profileUsesProviderHostGlobals } from "./profile-home";
 import { RELAY_MCP_TOKEN_ENV, relayMcpEndpoint, resolveSharedMcpUrl } from "./relay-mcp";
 import { RelayMcpProxy } from "./relay-mcp-proxy";
 import { runtimeMetadata } from "./version";
@@ -530,7 +531,7 @@ export class AgentRunner {
   private async spawnProvider(opts: { resumeId?: string; suppressPrompt?: boolean } = {}): Promise<ManagedProcess> {
     this.providerSessionId = crypto.randomUUID();
     this.lastTranscriptPath = undefined;
-    const includeProviderGlobals = this.options.provider === "claude" ? profileUsesClaudeHostProviderGlobals(this.options) : profileUsesHostProviderGlobals(this.options);
+    const includeProviderGlobals = profileUsesProviderHostGlobals(this.options);
     const env = {
       ...process.env as Record<string, string>,
       ...(includeProviderGlobals ? this.options.providerConfig.env : {}),
@@ -874,7 +875,7 @@ export class AgentRunner {
       ...(answers ? { answers } : {}),
     };
     if (this.control?.resolvePermissionDecision(input)) {
-      return { approvalId, decision, provider: "claude" };
+      return { approvalId, decision, provider: this.options.provider };
     }
     if (!this.process) throw new Error("provider process is unavailable");
     if (!this.options.adapter.respondToPermissionDecision) throw new Error("provider does not support permission decisions");
@@ -987,7 +988,7 @@ export class AgentRunner {
       });
 
       const nativeSelfResume = this.nativeSelfResume.active;
-      if (nativeSelfResume && this.options.provider === "claude") {
+      if (nativeSelfResume && getManifest(this.options.provider)?.resume?.supported) {
         await recoverNativeSelfResumeExit({ handoff: nativeSelfResume, tracker: this.nativeSelfResume, providerSessionId: this.providerSessionId, status, diagnostics, now, publishTimeline: (event) => this.publishRunnerTimelineEvent(event), setTerminalProviderExit: (marker) => { this.terminalProviderExit = marker; }, setProviderStatus: (update) => this.setProviderStatus(update), restartProvider: (resumeId) => this.restartProvider(resumeId ? { resumeId } : { suppressPrompt: true }), publishStatus: () => this.publishStatus(), scheduleDrain: () => this.scheduleDrain() });
         return;
       }
@@ -1089,7 +1090,7 @@ export class AgentRunner {
   }
 
   private shouldStopUnexpectedProviderExit(diagnostics: Record<string, unknown>): boolean {
-    return this.options.provider === "claude" && diagnostics.exitCommandInProgress !== true;
+    return getManifest(this.options.provider)?.launch?.managedPolicyPrompt?.alwaysOn === "append-system-prompt" && diagnostics.exitCommandInProgress !== true;
   }
 
   private async shutdownProvider(hard: boolean, timeoutMs = this.options.providerConfig.headless.shutdownTimeoutMs): Promise<void> {
@@ -1246,9 +1247,9 @@ export class AgentRunner {
       this.compactionMidTurn = false;
       this.busyReconciler.disarm();
       this.stopReasoningTail();
-      // #417: claude enforces obligations via the stop.sh hook; for every other provider
-      // re-inject any pending spawner obligation so it surfaces the /reply command.
-      if (this.options.provider !== "claude") void this.reInjectPendingObligation();
+      // Providers with append-system-prompt policy use lifecycle hooks for obligation handling;
+      // others need the runner to re-inject pending obligations on idle.
+      if (getManifest(this.options.provider)?.launch?.managedPolicyPrompt?.alwaysOn !== "append-system-prompt") void this.reInjectPendingObligation();
     }
     // A genuine restart back to forward progress clears the terminal-exit marker so a later offline
     // doesn't re-announce a stale provider exit.

package/src/runner-helpers.ts

@@ -1,6 +1,8 @@
 import { closeSync, openSync, readSync, statSync } from "node:fs";
 import type { AgentProfile, ContextState, Message, ProviderCapabilities, ProviderState, QuotaState } from "agent-relay-sdk";
-import { errMessage } from "agent-relay-sdk";
+import { errMessage, isSpawnProvider } from "agent-relay-sdk";
+import { getManifest } from "agent-relay-providers";
+import type { BooleanCapabilityDefault, ProviderCapabilityCondition } from "agent-relay-providers";
 import { targetMatchesAgentIdentity } from "agent-relay-sdk/agent-target";
 import type { ProviderAdapter, ProviderConfig, RunnerSpawnConfig, SemanticStatus } from "./adapter";
 import { agentProfileProjectionReport } from "./profile-projection";
@@ -8,7 +10,6 @@ import { assembleLaunch } from "./launch-assembly";
 
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
 const LOG_TAIL_BYTES = 128 * 1024;
-const CLAUDE_RESUME_RE = /\bclaude\s+--resume\s+([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b/gi;
 const RUNNER_CLAIMED_GUIDANCE_RE = /\s*Claim this task before working it, then update task status when finished\.\s*$/;
 
 interface RuntimeProviderOptions {
@@ -131,16 +132,24 @@ export function runnerShouldRestartUnexpectedProviderExit(
     && input.hasTerminalSession;
 }
 
-export function latestClaudeResumeIdFromText(text: string): string | undefined {
+function resumeLogExtractionRe(provider: string): RegExp | undefined {
+  const manifest = getManifest(provider);
+  const resume = manifest?.resume as { supported: boolean; idPattern?: string } | undefined;
+  if (!resume?.supported || !resume.idPattern || !manifest?.probe?.command) return undefined;
+  return new RegExp(`\\b${manifest.probe.command}\\s+--resume\\s+(${resume.idPattern})\\b`, "gi");
+}
+
+export function latestResumeIdFromText(provider: string, text: string): string | undefined {
+  const re = resumeLogExtractionRe(provider);
+  if (!re) return undefined;
   let latest: string | undefined;
-  CLAUDE_RESUME_RE.lastIndex = 0;
-  for (let match = CLAUDE_RESUME_RE.exec(text); match; match = CLAUDE_RESUME_RE.exec(text)) {
+  for (let match = re.exec(text); match; match = re.exec(text)) {
     latest = match[1];
   }
   return latest;
 }
 
-export function latestClaudeResumeIdFromLogFile(path: string): string | undefined {
+export function latestResumeIdFromLogFile(provider: string, path: string): string | undefined {
   let fd: number | undefined;
   try {
     const stat = statSync(path);
@@ -149,7 +158,7 @@ export function latestClaudeResumeIdFromLogFile(path: string): string | undefine
     const buffer = Buffer.alloc(length);
     fd = openSync(path, "r");
     readSync(fd, buffer, 0, length, offset);
-    return latestClaudeResumeIdFromText(buffer.toString("utf8"));
+    return latestResumeIdFromText(provider, buffer.toString("utf8"));
   } catch {
     return undefined;
   } finally {
@@ -173,7 +182,7 @@ export function providerExitDiagnostics(input: {
   const tmuxSession = typeof input.processMeta?.tmuxSession === "string" ? input.processMeta.tmuxSession : undefined;
   const tmuxSocket = typeof input.processMeta?.tmuxSocket === "string" ? input.processMeta.tmuxSocket : undefined;
   const exitSource = tmuxSession ? "tmux-session-ended" : input.hasProcess ? "process-exit" : "provider-status";
-  const claudeResumeId = input.provider === "claude" && input.logFile ? latestClaudeResumeIdFromLogFile(input.logFile) : undefined;
+  const claudeResumeId = getManifest(input.provider)?.resume?.supported && input.logFile ? latestResumeIdFromLogFile(input.provider, input.logFile) : undefined;
   return {
     status: input.status,
     runtimeMs: Number.isFinite(input.runtimeMs) ? input.runtimeMs : null,
@@ -225,18 +234,39 @@ export function lifecycleCapabilities(): Record<string, true> {
   };
 }
 
+function resolveCondition(condition: ProviderCapabilityCondition, options: RuntimeProviderOptions): boolean {
+  switch (condition) {
+    case "always": return true;
+    case "never": return false;
+    case "headless": return options.headless;
+    case "interactive": return !options.headless;
+    case "approval:read-only": return options.approvalMode === "read-only";
+    case "approval:not-read-only": return options.approvalMode !== "read-only";
+    case "adapter:compact-supports-instructions": return Boolean(options.adapter.compactSupportsInstructions);
+    case "adapter:clear-context": return Boolean(options.adapter.clearContext);
+    default: return false;
+  }
+}
+
+function resolveBooleanDefault(def: BooleanCapabilityDefault, options: RuntimeProviderOptions): boolean {
+  if (typeof def === "boolean") return def;
+  return resolveCondition(def.when, options) ? def.value : def.otherwise;
+}
+
 export function runtimeProviderCapabilities(options: RuntimeProviderOptions, contextState?: ContextState, probeModel?: ProbeModelInfo, quotaState?: QuotaState): ProviderCapabilities {
+  const manifest = getManifest(options.provider);
+  const capDefaults = manifest?.capabilityDefaults;
   const model = options.model ?? probeModel?.model;
   const effort = options.effort ?? probeModel?.effort;
   const modelSource = options.model ? "runtime" as const : probeModel?.model ? "provider" as const : "runtime" as const;
   const shellMode = runtimeShellMode(options);
   return {
     lifecycle: {
-      managed: true,
-      shutdownHard: options.provider === "claude" ? options.headless : true,
-      restartHard: options.provider === "claude" ? options.headless : true,
-      semanticStatus: true,
-      reconnect: true,
+      managed: capDefaults?.lifecycle?.managed ?? true,
+      shutdownHard: capDefaults?.lifecycle?.shutdownHard !== undefined ? resolveBooleanDefault(capDefaults.lifecycle.shutdownHard, options) : true,
+      restartHard: capDefaults?.lifecycle?.restartHard !== undefined ? resolveBooleanDefault(capDefaults.lifecycle.restartHard, options) : true,
+      semanticStatus: capDefaults?.lifecycle?.semanticStatus ?? true,
+      reconnect: capDefaults?.lifecycle?.reconnect ?? true,
     },
     model: {
       provider: options.provider,
@@ -266,7 +296,7 @@ export function runtimeProviderCapabilities(options: RuntimeProviderOptions, con
       interrupt: Boolean(options.adapter.interrupt),
       promptEcho: true,
       reasoning: true,
-      slashCommands: options.provider === "claude" || options.provider === "codex",
+      slashCommands: capDefaults?.liveSession?.slashCommands ?? false,
     },
     source: "runtime",
     confidence: "reported",
@@ -275,34 +305,23 @@ export function runtimeProviderCapabilities(options: RuntimeProviderOptions, con
 }
 
 function runtimeShellMode(options: RuntimeProviderOptions): NonNullable<NonNullable<ProviderCapabilities["session"]>["shellMode"]> {
-  if (options.approvalMode === "read-only") {
-    return options.provider === "claude" ? "read-only-guarded" : "none";
-  }
-  return options.approvalMode === "open" ? "unrestricted" : "guarded";
+  const manifest = getManifest(options.provider);
+  const shellModeMap = manifest?.capabilityDefaults?.session?.shellMode;
+  if (options.approvalMode === "read-only") return (shellModeMap?.readOnly ?? "none") as NonNullable<NonNullable<ProviderCapabilities["session"]>["shellMode"]>;
+  if (options.approvalMode === "open") return (shellModeMap?.open ?? "unrestricted") as NonNullable<NonNullable<ProviderCapabilities["session"]>["shellMode"]>;
+  return (shellModeMap?.guarded ?? "guarded") as NonNullable<NonNullable<ProviderCapabilities["session"]>["shellMode"]>;
 }
 
 function runtimeProviderTerminalCapabilities(options: RuntimeProviderOptions): Pick<ProviderCapabilities, "terminal"> {
-  if (options.provider === "claude" && options.headless) {
-    return {
-      terminal: {
-        live: {
-          read: true,
-          write: true,
-        },
-      },
-    };
+  const manifest = getManifest(options.provider);
+  const termDefaults = manifest?.capabilityDefaults?.terminal;
+  if (!termDefaults || termDefaults.mode === "none") return {};
+  if (termDefaults.condition && !resolveCondition(termDefaults.condition, options)) return {};
+  if (termDefaults.mode === "live" && termDefaults.live) {
+    return { terminal: { live: termDefaults.live } };
   }
-  if (options.provider === "codex") {
-    return {
-      terminal: {
-        attach: {
-          create: true,
-          read: true,
-          write: true,
-          detach: true,
-        },
-      },
-    };
+  if (termDefaults.mode === "attach" && termDefaults.attach) {
+    return { terminal: { attach: termDefaults.attach } };
   }
   return {};
 }
@@ -316,7 +335,7 @@ export function appliedAgentProfileMetadata(
   config?: RunnerSpawnConfig,
   providerConfig?: ProviderConfig,
 ): Record<string, unknown> {
-  const projection = (provider === "claude" || provider === "codex") && config && providerConfig
+  const projection = isSpawnProvider(provider) && config && providerConfig
     ? agentProfileProjectionReport({ assembled: assembleLaunch(provider, config, providerConfig) })
     : undefined;
   return {
@@ -340,29 +359,30 @@ export function appliedAgentProfileMetadata(
 }
 
 function runtimeProviderContextCapabilities(options: RuntimeProviderOptions, contextState?: ContextState): Pick<ProviderCapabilities, "context"> {
+  const manifest = getManifest(options.provider);
+  const ctxDefaults = manifest?.capabilityDefaults?.context;
   const context: NonNullable<ProviderCapabilities["context"]> = { resume: "none" };
-  const supportsManagedContext = options.provider === "codex" || (options.provider === "claude" && options.headless);
+  const supportsManagedContext = ctxDefaults?.managed ? resolveCondition(ctxDefaults.managed, options) : false;
   if (contextState) {
     context.stats = { source: contextState.source, confidence: contextState.confidence };
     if (typeof contextState.tokensMax === "number" && Number.isFinite(contextState.tokensMax)) {
       context.windowTokens = contextState.tokensMax;
     }
   }
-  if (supportsManagedContext) {
-    context.compact = true;
-    context.clear = true;
+  if (ctxDefaults) {
+    if (resolveBooleanDefault(ctxDefaults.compact, options)) context.compact = true;
+    if (resolveBooleanDefault(ctxDefaults.clear, options)) context.clear = true;
+    context.inject = ctxDefaults.inject;
   }
-  context.inject = true;
   if (supportsManagedContext && options.adapter.compact && options.adapter.compactSupportsInstructions) context.resume = "native";
   else if (supportsManagedContext && options.adapter.clearContext) context.resume = "clear-inject";
   return Object.keys(context).length ? { context } : {};
 }
 
 function runtimeProviderQuotaCapabilities(options: RuntimeProviderOptions, quotaState?: QuotaState): Pick<ProviderCapabilities, "quota"> {
-  if (options.provider !== "claude" && options.provider !== "codex") return {};
-  const fallbackWindows = options.provider === "claude"
-    ? [{ name: "five_hour", unit: "%" as const, reset: true }, { name: "seven_day", unit: "%" as const, reset: true }]
-    : [{ name: "primary", unit: "%" as const, reset: true }, { name: "secondary", unit: "%" as const, reset: true }];
+  const manifest = getManifest(options.provider);
+  const quotaDefaults = manifest?.capabilityDefaults?.quota;
+  if (!quotaDefaults?.supported) return {};
   return {
     quota: {
       supported: true,
@@ -372,7 +392,7 @@ function runtimeProviderQuotaCapabilities(options: RuntimeProviderOptions, quota
         name: window.name,
         unit: window.unit,
         reset: window.resetsAt !== undefined,
-      })) ?? fallbackWindows,
+      })) ?? manifest!.quotaWindows.map(w => ({ name: w.name, unit: w.unit as "%" | "tokens" | "requests", reset: w.reset })),
     },
   };
 }

package/src/runner.ts

@@ -1,6 +1,6 @@
 export { AgentRunner } from "./runner-core";
 export {
-  latestClaudeResumeIdFromText,
+  latestResumeIdFromText,
   runnerAgentStatus,
   runnerBusErrorAction,
   runnerMessageMatches,

package/src/version.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CONTRACT_VERSIONS } from "agent-relay-sdk";
+import { getManifest } from "agent-relay-providers";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8")) as { name?: string; version?: string };
@@ -26,6 +27,7 @@ export const RUNTIME_CAPABILITIES = {
 } as const;
 
 export function runtimeMetadata(provider?: string) {
+  const manifest = provider ? getManifest(provider) : undefined;
   return {
     package: {
       name: PACKAGE_NAME,
@@ -34,8 +36,8 @@ export function runtimeMetadata(provider?: string) {
     contracts: CONTRACTS,
     capabilities: {
       ...RUNTIME_CAPABILITIES,
-      ...(provider === "claude" ? { bundledClaudePlugin: true } : {}),
-      ...(provider === "codex" ? { bundledCodexSkills: true } : {}),
+      ...(manifest?.provisioning?.bundledPlugin ? { bundledPlugin: true } : {}),
+      ...(manifest?.provisioning?.bundledSkills ? { bundledSkills: true } : {}),
     },
   };
 }