agent-relay-runner 0.91.3 → 0.92.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.91.3",
+  "version": "0.92.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.70"
+    "agent-relay-sdk": "0.2.72"
   },
   "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.91.3",
+  "version": "0.92.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapters/claude.ts

@@ -9,10 +9,11 @@ import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import { profileAllowsRelayFeature, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderStatusUpdate, type RunnerSpawnConfig, type SemanticStatus, type SpawnArgs } from "../adapter";
 import { collectClaudeSessionEvents } from "./claude-transcript";
 import type { SessionEvent } from "../session-insights";
-import { prepareClaudeProfileHome, profileUsesHostProviderGlobals } from "../profile-home";
+import { prepareClaudeProfileHome, profileUsesClaudeHostProviderGlobals } from "../profile-home";
 import { assembleLaunch, materializeLaunchAssembly, sessionStatusLineSettingsArgs } from "../launch-assembly";
 import { claudeProviderMessageText } from "./claude-delivery";
-import { buildRateLimitProviderState, gatedClaudeRateLimitStatus, parseClaudeRateLimitPane } from "../rate-limit";
+import { buildRateLimitProviderState, parseClaudeRateLimitPane } from "../rate-limit";
+import { evaluateClaudePromptGatePane, initialClaudePromptGatePaneState, type ClaudePromptGatePaneState } from "../claude-prompt-gates";
 
 export class ClaudeAdapter implements ProviderAdapter {
   readonly provider = "claude";
@@ -24,10 +25,7 @@ export class ClaudeAdapter implements ProviderAdapter {
   private tmuxWatcher?: Timer;
   private turnWatcher?: Timer;
   private modelUnavailableReported = false;
-  // #286: true while a usage-limit modal is being held, so the pane watcher dismisses
-  // it + emits the hold once (not every 2s tick). Cleared when the modal leaves the pane.
-  private rateLimitReported = false;
-  private rateLimitPaneDetections = 0;
+  private promptGatePaneState: ClaudePromptGatePaneState = initialClaudePromptGatePaneState();
 
   onStatusChange(cb: (status: ProviderStatusUpdate) => void): void {
     this.statusCb = cb;
@@ -223,7 +221,7 @@ export class ClaudeAdapter implements ProviderAdapter {
     // 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 defaultArgs = profileUsesClaudeHostProviderGlobals(config) ? providerConfig.defaultArgs : [];
     // #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
@@ -236,7 +234,7 @@ export class ClaudeAdapter implements ProviderAdapter {
     // 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
     // rig key just errors out). Only host-base profiles may use claude-rig.
-    const usesClaudeRig = isClaudeRig && profileUsesHostProviderGlobals(config);
+    const usesClaudeRig = isClaudeRig && profileUsesClaudeHostProviderGlobals(config);
     const bypassRigDefaults = config.headless && usesClaudeRig && config.approvalMode !== "open";
     const rigPrefix = usesClaudeRig && !bypassRigDefaults && config.rig ? ["launch", config.rig] : [];
     const command = !usesClaudeRig || bypassRigDefaults || (!config.rig && !findClaudeRigRC(config.cwd))
@@ -309,6 +307,7 @@ export class ClaudeAdapter implements ProviderAdapter {
   private async spawnHeadless(config: RunnerSpawnConfig, spawnArgs: SpawnArgs): Promise<ManagedProcess> {
     const { sessionName, socketName, args: tmuxArgs } = this.buildTmuxArgs(config, spawnArgs);
     this.modelUnavailableReported = false;
+    this.promptGatePaneState = initialClaudePromptGatePaneState();
 
     Bun.spawnSync(tmuxCommand(socketName, "kill-session", "-t", sessionName), {
       stdin: "ignore", stdout: "ignore", stderr: "ignore",
@@ -370,30 +369,27 @@ export class ClaudeAdapter implements ProviderAdapter {
         this.statusCb(status);
         return;
       }
-      // #286/#655: the subscription usage-limit modal fires no hook, so detect it
-      // from the pane. Act only after consecutive non-busy detections; a live turn
-      // mentioning quota/reset text must not be escaped or held.
-      const rateLimit = gatedClaudeRateLimitStatus(pane, {
-        consecutiveDetections: this.rateLimitPaneDetections,
-        reported: this.rateLimitReported,
-      }, { sessionName, busy: claudePaneIsBusy(pane) });
-      this.rateLimitPaneDetections = rateLimit.state.consecutiveDetections;
-      this.rateLimitReported = rateLimit.state.reported;
-      if (rateLimit.status) {
-        this.dismissRateLimitModal(sessionName, socketName);
-        this.statusCb(rateLimit.status);
+      // #663: prompt-gate fallback. Known gates should be prevented before launch;
+      // this catches missed/new blocking panes with the same #655 debounce + busy
+      // guard used for rate-limit holds.
+      const promptGate = evaluateClaudePromptGatePane(pane, this.promptGatePaneState, {
+        sessionName,
+        busy: claudePaneIsBusy(pane),
+      });
+      this.promptGatePaneState = promptGate.state;
+      if (promptGate.action) {
+        this.sendPromptGateKeystroke(sessionName, promptGate.action.keystroke, socketName);
+        if (promptGate.status) this.statusCb(promptGate.status);
       }
     }, 2000);
   }
 
-  // Send Escape to dismiss the confirmed usage-limit modal — the "wait" choice,
-  // which returns the agent to a normal idle prompt. Best-effort:
-  // a failed send-keys must never wedge the pane watcher.
-  private dismissRateLimitModal(sessionName: string, socketName?: string): void {
+  // Best-effort: a failed auto-dismiss must not wedge the pane watcher.
+  private sendPromptGateKeystroke(sessionName: string, keystroke: string, socketName?: string): void {
     try {
-      Bun.spawnSync(tmuxCommand(socketName, "send-keys", "-t", sessionName, "Escape"), { stdin: "ignore", stdout: "ignore", stderr: "ignore" });
+      Bun.spawnSync(tmuxCommand(socketName, "send-keys", "-t", sessionName, keystroke), { stdin: "ignore", stdout: "ignore", stderr: "ignore" });
     } catch {
-      // ignore — the hold still publishes; worst case the modal lingers until the next tick.
+      // ignore; the timeline/status still publishes, and the next watcher tick can observe whether the pane moved.
     }
   }
 

package/src/adapters/codex.ts

@@ -101,7 +101,29 @@ export class CodexAdapter implements ProviderAdapter {
     const client = process.meta?.client as CodexAppClient | undefined;
     if (!client?.isConnected()) return "unknown";
     const threadId = typeof process.meta?.threadId === "string" ? process.meta.threadId : "";
-    if (!this.activeTurnId) return "idle";
+    // #651: when no local activeTurnId, don't short-circuit to idle — query the app-server.
+    // turn/started can arrive after processing begins (or be missed entirely); a stale-idle
+    // probe would make a busy agent appear idle to the coordinator. Same fallback as #653's
+    // ensureMainTurnActive path, but for the pull (probe) direction, not the push (event) one.
+    if (!this.activeTurnId) {
+      if (!threadId) return "idle";
+      try {
+        const read = await client.threadRead(threadId, true);
+        const thread = isRecord(read.thread) ? read.thread : undefined;
+        const turns = Array.isArray(thread?.turns) ? thread.turns : [];
+        const inProgressTurn = turns.find((t) => isRecord(t) && stringValue(t.status) === "inProgress");
+        if (inProgressTurn) {
+          // Synthesize the active turn (same path as ensureMainTurnActive on item events).
+          this.ensureMainTurnActive(stringValue(inProgressTurn.id));
+          return "busy";
+        }
+        const threadStatus = statusType(thread?.status);
+        if (threadStatus === "active") return "busy";
+        return "idle";
+      } catch {
+        return "unknown";
+      }
+    }
     if (!threadId) return "busy";
     try {
       const read = await client.threadRead(threadId, true);

package/src/claude-prompt-gates.ts

@@ -0,0 +1,268 @@
+import { resolve } from "node:path";
+import { isRecord } from "agent-relay-sdk";
+import type { ProviderStatusUpdate, RunnerSpawnConfig } from "./adapter";
+import { buildRateLimitProviderState, parseClaudeRateLimitPane } from "./rate-limit";
+
+export interface ClaudeConfigPromptGatePrevention {
+  id: string;
+  description: string;
+  apply(seed: Record<string, unknown>, context: { host?: Record<string, unknown>; config: RunnerSpawnConfig }): void;
+}
+
+export interface ClaudeLaunchPromptGatePrevention {
+  id: string;
+  description: string;
+  apply(config: RunnerSpawnConfig): { strictMcpConfig?: boolean };
+}
+
+type PaneGateMatch = { message?: string; resetAt?: number; kind?: "usage_limit" | "transient_overload"; errorType?: string };
+
+interface ClaudePanePromptGate {
+  id: string;
+  label: string;
+  policy: string;
+  keystroke: string;
+  minDetections: number;
+  match(text: string, nowMs?: number): PaneGateMatch | null;
+  providerState?(match: PaneGateMatch, context: ClaudePromptGatePaneContext): Record<string, unknown>;
+}
+
+export interface ClaudePromptGatePaneState {
+  currentGateId?: string;
+  consecutiveDetections: number;
+  handledGateId?: string;
+}
+
+export interface ClaudePromptGatePaneContext {
+  sessionName?: string;
+  busy?: boolean;
+  nowMs?: number;
+}
+
+export interface ClaudePromptGateAction {
+  gateId: string;
+  label: string;
+  policy: string;
+  keystroke: string;
+  source: "claude-pane";
+}
+
+export interface ClaudePromptGatePaneResult {
+  action?: ClaudePromptGateAction;
+  status?: ProviderStatusUpdate;
+  state: ClaudePromptGatePaneState;
+}
+
+export const claudeConfigPromptGatePreventions: ClaudeConfigPromptGatePrevention[] = [
+  {
+    id: "first-run-onboarding",
+    description: "Pre-accept Claude Code's first-run onboarding gate.",
+    apply(seed, { host }) {
+      seed.hasCompletedOnboarding = true;
+      if (typeof host?.lastOnboardingVersion === "string") seed.lastOnboardingVersion = host.lastOnboardingVersion;
+    },
+  },
+  {
+    id: "theme-selection",
+    description: "Pre-seed a theme so the first-run theme picker does not render.",
+    apply(seed, { host }) {
+      seed.theme = typeof host?.theme === "string" ? host.theme : "dark";
+    },
+  },
+  {
+    id: "bypass-permissions-mode",
+    description: "Pre-accept Claude's open-approval bypass-permissions modal.",
+    apply(seed, { config }) {
+      if (config.approvalMode === "open") seed.bypassPermissionsModeAccepted = true;
+    },
+  },
+  {
+    id: "workspace-trust",
+    description: "Trust the managed spawn cwd and clear project onboarding.",
+    apply(seed, { config }) {
+      if (!config.cwd) return;
+      seed.projects = {
+        ...(isRecord(seed.projects) ? seed.projects : {}),
+        [resolve(config.cwd)]: { hasTrustDialogAccepted: true, hasCompletedProjectOnboarding: true },
+      };
+    },
+  },
+];
+
+export const claudeLaunchPromptGatePreventions: ClaudeLaunchPromptGatePrevention[] = [
+  {
+    id: "project-mcp-discovery",
+    description: "Use strict controlled MCP config so Claude never prompts for ambient project .mcp.json servers.",
+    apply() {
+      return { strictMcpConfig: true };
+    },
+  },
+];
+
+const panePromptGates: ClaudePanePromptGate[] = [
+  {
+    id: "usage-limit",
+    label: "Usage limit",
+    policy: "wait-for-reset",
+    keystroke: "Escape",
+    minDetections: 2,
+    match: (text, nowMs) => parseClaudeRateLimitPane(text, nowMs),
+    providerState(match, context) {
+      return buildRateLimitProviderState({
+        errorType: match.errorType ?? "session_limit",
+        kind: match.kind ?? "usage_limit",
+        ...(match.resetAt ? { resetAt: match.resetAt } : {}),
+        message: match.message,
+        source: context.sessionName ? `claude-pane:${context.sessionName}` : "claude-pane",
+      });
+    },
+  },
+  {
+    id: "workspace-trust",
+    label: "Workspace trust",
+    policy: "accept-trusted-workspace",
+    keystroke: "Enter",
+    minDetections: 2,
+    match: (text) => /do you trust (?:the files in )?(?:this folder|this project|this directory)/i.test(text)
+      && /\b(?:yes|proceed|trust|continue)\b/i.test(text)
+      ? { message: lineMatching(text, /do you trust/i) }
+      : null,
+  },
+  {
+    id: "bypass-permissions-mode",
+    label: "Bypass permissions mode",
+    policy: "accept-configured-open-approval",
+    keystroke: "Enter",
+    minDetections: 2,
+    match: (text) => /bypass permissions mode/i.test(text) && /\b(?:accept|proceed|continue|yes)\b/i.test(text)
+      ? { message: lineMatching(text, /bypass permissions mode/i) }
+      : null,
+  },
+  {
+    id: "project-mcp-discovery",
+    label: "Project MCP discovery",
+    policy: "reject-ambient-project-mcp",
+    keystroke: "Escape",
+    minDetections: 2,
+    match: (text) => /\bnew MCP servers? found\b/i.test(text) && /\b(?:select|enable|servers?)\b/i.test(text)
+      ? { message: lineMatching(text, /new MCP servers? found/i) }
+      : null,
+  },
+  {
+    id: "theme-selection",
+    label: "Theme selection",
+    policy: "accept-default-theme",
+    keystroke: "Enter",
+    minDetections: 2,
+    match: (text) => /choose (?:the )?(?:text style|theme).*Claude Code/i.test(text) && /\b(?:dark|light) mode\b/i.test(text)
+      ? { message: lineMatching(text, /choose/i) }
+      : null,
+  },
+  {
+    id: "first-run-onboarding",
+    label: "First-run onboarding",
+    policy: "accept-onboarding",
+    keystroke: "Enter",
+    minDetections: 2,
+    match: (text) => /welcome to Claude Code/i.test(text) && /\b(?:let'?s get started|continue|get started)\b/i.test(text)
+      ? { message: lineMatching(text, /welcome to Claude Code/i) }
+      : null,
+  },
+];
+
+export function applyClaudeConfigPromptGatePreventions(
+  seed: Record<string, unknown>,
+  host: Record<string, unknown> | undefined,
+  config: RunnerSpawnConfig,
+): Record<string, unknown> {
+  const next = { ...seed };
+  for (const prevention of claudeConfigPromptGatePreventions) prevention.apply(next, { host, config });
+  return next;
+}
+
+export function claudeLaunchPromptGateSettings(config: RunnerSpawnConfig): { strictMcpConfig: boolean } {
+  return {
+    strictMcpConfig: claudeLaunchPromptGatePreventions.some((prevention) => prevention.apply(config).strictMcpConfig === true),
+  };
+}
+
+export function initialClaudePromptGatePaneState(): ClaudePromptGatePaneState {
+  return { consecutiveDetections: 0 };
+}
+
+export function evaluateClaudePromptGatePane(
+  text: string,
+  state: ClaudePromptGatePaneState,
+  context: ClaudePromptGatePaneContext = {},
+): ClaudePromptGatePaneResult {
+  const detected = firstDetectedPaneGate(text, context.nowMs);
+  if (!detected) return { state: initialClaudePromptGatePaneState() };
+  if (context.busy) {
+    return { state: { ...state, currentGateId: undefined, consecutiveDetections: 0 } };
+  }
+  if (state.handledGateId === detected.entry.id) {
+    return { state };
+  }
+
+  const consecutiveDetections = state.currentGateId === detected.entry.id ? state.consecutiveDetections + 1 : 1;
+  const nextState: ClaudePromptGatePaneState = {
+    currentGateId: detected.entry.id,
+    consecutiveDetections,
+    ...(state.handledGateId ? { handledGateId: state.handledGateId } : {}),
+  };
+  if (consecutiveDetections < detected.entry.minDetections) return { state: nextState };
+
+  const action: ClaudePromptGateAction = {
+    gateId: detected.entry.id,
+    label: detected.entry.label,
+    policy: detected.entry.policy,
+    keystroke: detected.entry.keystroke,
+    source: "claude-pane",
+  };
+  return {
+    action,
+    status: promptGateStatus(detected.entry, detected.match, action, context),
+    state: { ...nextState, handledGateId: detected.entry.id },
+  };
+}
+
+function firstDetectedPaneGate(text: string, nowMs?: number): { entry: ClaudePanePromptGate; match: PaneGateMatch } | null {
+  for (const entry of panePromptGates) {
+    const match = entry.match(text, nowMs);
+    if (match) return { entry, match };
+  }
+  return null;
+}
+
+function promptGateStatus(
+  entry: ClaudePanePromptGate,
+  match: PaneGateMatch,
+  action: ClaudePromptGateAction,
+  context: ClaudePromptGatePaneContext,
+): ProviderStatusUpdate {
+  const metadata = {
+    eventType: "claude.prompt_gate.auto_handled",
+    gateId: action.gateId,
+    policy: action.policy,
+    keystroke: action.keystroke,
+    source: action.source,
+    ...(context.sessionName ? { sessionName: context.sessionName } : {}),
+  };
+  return {
+    status: "idle",
+    clear: ["subagent"],
+    ...(entry.providerState ? { providerState: entry.providerState(match, context) } : {}),
+    timeline: {
+      status: "claude.prompt_gate.auto_handled",
+      id: `claude-prompt-gate-${entry.id}-${Date.now()}`,
+      timestamp: Date.now(),
+      title: "Claude prompt gate auto-handled",
+      body: match.message ?? `${entry.label} dismissed with ${entry.keystroke}`,
+      metadata,
+    },
+  };
+}
+
+function lineMatching(text: string, pattern: RegExp): string | undefined {
+  return text.split(/\r?\n/).map((line) => line.trim()).find((line) => pattern.test(line));
+}

package/src/launch-assembly.ts

@@ -7,9 +7,17 @@ import {
   type ProviderConfig,
   type RunnerSpawnConfig,
 } from "./adapter";
-import { hostUserScopeMcpServers, profileUsesHostProviderGlobals, providerHomePathFor } from "./profile-home";
+import {
+  claudeProjectConfigProjectionOn,
+  hostUserScopeMcpServers,
+  profileUsesClaudeHostProviderGlobals,
+  providerHomePathFor,
+} from "./profile-home";
+import { claudeLaunchPromptGateSettings } from "./claude-prompt-gates";
 import {
   materializeResolvedAssets,
+  resolveClaudeProjectSkills,
+  resolveProjectClaudeSettings,
   resolveClaudeProvisionedPlugins,
   resolveClaudeProvisionedSkills,
   resolveCodexProvisionedSkills,
@@ -115,6 +123,10 @@ export interface AssembledLaunch {
   statusLine: boolean;
   /** Relay-provisioned skills materialized for this launch. */
   skills: AssembledAsset[];
+  /** Project `.claude/skills` materialized for this Claude launch (#668). */
+  projectSkills: AssembledAsset[];
+  /** Project `.claude/settings.json` sanitized and injected for this Claude launch (#669). */
+  projectSettings: { applied: boolean; keys: string[]; ignoredKeys: string[]; file?: string };
   /** Relay-provisioned plugins (Claude --plugin-dir). Empty for Codex (no plugin surface). */
   plugins: AssembledAsset[];
   mcp: AssembledMcp;
@@ -161,10 +173,27 @@ function hasSettingsArg(args: string[]): boolean {
 // --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({
+  return ["--settings", JSON.stringify(relayStatusLineSettings())];
+}
+
+function relayStatusLineSettings(): Record<string, unknown> {
+  return {
     statusLine: { type: "command", command: "agent-relay context-probe --wrap", refreshInterval: 30 },
     showThinkingSummaries: true,
-  })];
+  };
+}
+
+function claudeSettingsArgs(
+  projectSettings: Record<string, unknown>,
+  includeStatusLine: boolean,
+  ...argLists: string[][]
+): string[] {
+  if (argLists.some(hasSettingsArg)) return [];
+  const settings = {
+    ...projectSettings,
+    ...(includeStatusLine ? relayStatusLineSettings() : {}),
+  };
+  return Object.keys(settings).length ? ["--settings", JSON.stringify(settings)] : [];
 }
 
 // ── Instruction disposition (the vanilla floor's effect on the host instruction cascade) ──
@@ -198,11 +227,16 @@ function assembleInstructions(config: RunnerSpawnConfig): AssembledInstructions
 function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfig, hostDefaultArgs: string[]): AssembledLaunch {
   const configHome = providerHomePathFor("claude", config);
   const vanilla = profileIsVanillaBase(config);
+  const projectConfigProjection = claudeProjectConfigProjectionOn(config);
   const relayPlugin = profileAllowsRelayFeature(config, "plugins");
   const relaySkills = profileAllowsRelayFeature(config, "skills");
   const statusLine = profileAllowsRelayFeature(config, "statusLine");
 
   const skills = configHome ? resolveClaudeProvisionedSkills(configHome, config) : [];
+  const projectSkills = configHome
+    ? resolveClaudeProjectSkills(configHome, config, new Set(skills.map((s) => s.name)))
+    : [];
+  const projectSettings = resolveProjectClaudeSettings(config);
   const provisionedPlugins = configHome ? resolveClaudeProvisionedPlugins(configHome, config) : [];
 
   // Plugin dirs (--plugin-dir loads explicitly, independent of --setting-sources):
@@ -212,7 +246,7 @@ function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfi
   //   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 hostPluginDirs = profileUsesClaudeHostProviderGlobals(config) ? providerConfig.pluginDirs : [];
   const pluginDirs = [...new Set([...relayPluginDirs, ...provisionedPluginDirs, ...hostPluginDirs])];
 
   const provisionedMcp = profileProvisioning(config).mcpServers;
@@ -247,16 +281,10 @@ function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfi
     : {};
   const declaredMcp = { ...projectMcp, ...provisionedMcp, ...sharedMcp };
 
-  // #662 — EVERY managed Claude launch is --strict-mcp-config, not just vanilla. A managed
-  // agent runs headless (no human at the keyboard), so Claude's blocking "N new MCP servers
-  // found in this project — select to enable" modal (raised on UNDECIDED cwd `.mcp.json`
-  // servers) wedges the session forever, burning quota. Relay owns MCP: everything relay
-  // decides should load is injected via --mcp-config, which strict PRESERVES; strict only
-  // blocks what relay DIDN'T inject — above all the cwd project `.mcp.json` (the modal's
-  // source), which stays excluded. The relay plugin (monitor + turn hooks) loads via
-  // --plugin-dir and ships no MCP server, so it is untouched. Was `vanilla`-only, which left
-  // host/minimal/isolated bases exposed to the modal wedge.
-  const strictMcp = true;
+  // #662/#663 — strict controlled MCP is a Claude prompt-gate prevention entry, not a
+  // launch-assembly special case. It prevents the blocking "N new MCP servers found in
+  // this project" modal while preserving every relay-declared server in --mcp-config.
+  const strictMcp = claudeLaunchPromptGateSettings(config).strictMcpConfig;
 
   // #662 follow-up — strict drops ALL on-disk config, including the host user-scope
   // `~/.claude.json` MCP that a host-base agent loaded ambiently before strict. That
@@ -265,7 +293,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 = profileUsesHostProviderGlobals(config)
+  const usesHostMcp = profileUsesClaudeHostProviderGlobals(config)
     && (!config.agentProfile || config.agentProfile.mcp.mode === "host");
   const hostMcp = usesHostMcp ? hostUserScopeMcpServers() : {};
   const hostMcpServers = Object.keys(hostMcp).filter(
@@ -277,7 +305,7 @@ function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfi
   // 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"] : []),
+    ...(vanilla || projectConfigProjection ? ["--setting-sources", "user"] : []),
     ...pluginDirs.flatMap((dir) => ["--plugin-dir", dir]),
     ...claudeMcpLaunchArgs({
       relayUrl: config.relayUrl,
@@ -287,7 +315,7 @@ function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfi
       hostServers: hostMcp,
       strict: strictMcp,
     }),
-    ...(statusLine ? sessionStatusLineSettingsArgs(hostDefaultArgs, config.providerArgs) : []),
+    ...claudeSettingsArgs(projectSettings.settings, statusLine, hostDefaultArgs, config.providerArgs),
     ...(config.systemPromptAppend ? ["--append-system-prompt", config.systemPromptAppend] : []),
   ];
 
@@ -302,6 +330,13 @@ function assembleClaude(config: RunnerSpawnConfig, providerConfig: ProviderConfi
     relayPlugin,
     statusLine,
     skills: skills.map((s) => ({ name: s.name, dir: s.dir })),
+    projectSkills: projectSkills.map((s) => ({ name: s.name, dir: s.dir })),
+    projectSettings: {
+      applied: projectSettings.applied,
+      keys: projectSettings.keys,
+      ignoredKeys: projectSettings.ignoredKeys,
+      ...(projectSettings.file ? { file: projectSettings.file } : {}),
+    },
     plugins: provisionedPlugins.map((p) => ({ name: p.name, dir: p.dir })),
     mcp: {
       relayEndpoint, strict: strictMcp, servers: mcpServers, projectServers, hostServers: hostMcpServers,
@@ -371,6 +406,8 @@ function assembleCodex(config: RunnerSpawnConfig, _providerConfig: ProviderConfi
     relayPlugin: false,
     statusLine: false,
     skills: provisionedSkills.map((s) => ({ name: s.name, dir: s.dir })),
+    projectSkills: [],
+    projectSettings: { applied: false, keys: [], ignoredKeys: [] },
     plugins: [],
     mcp: {
       relayEndpoint, strict: false, servers: mcpServers, projectServers, hostServers: [],
@@ -389,7 +426,7 @@ function assembleCodex(config: RunnerSpawnConfig, _providerConfig: ProviderConfi
  */
 export function assembleLaunch(provider: SpawnProvider, config: RunnerSpawnConfig, providerConfig: ProviderConfig): AssembledLaunch {
   if (provider === "codex") return assembleCodex(config, providerConfig);
-  const hostDefaultArgs = profileUsesHostProviderGlobals(config) ? providerConfig.defaultArgs : [];
+  const hostDefaultArgs = profileUsesClaudeHostProviderGlobals(config) ? providerConfig.defaultArgs : [];
   return assembleClaude(config, providerConfig, hostDefaultArgs);
 }
 
@@ -403,7 +440,9 @@ export function materializeLaunchAssembly(provider: SpawnProvider, config: Runne
   const configHome = providerHomePathFor(provider, config);
   if (!configHome) return;
   if (provider === "claude") {
-    materializeResolvedAssets(resolveClaudeProvisionedSkills(configHome, config));
+    const skills = resolveClaudeProvisionedSkills(configHome, config);
+    materializeResolvedAssets(skills);
+    materializeResolvedAssets(resolveClaudeProjectSkills(configHome, config, new Set(skills.map((s) => s.name))));
     materializeResolvedAssets(resolveClaudeProvisionedPlugins(configHome, config));
     return;
   }

package/src/profile-home.ts

@@ -6,6 +6,7 @@ import type { ProvisioningMcpServer } from "agent-relay-sdk";
 import { profileAllowsRelayFeature, type RunnerSpawnConfig } from "./adapter";
 import { CLAUDE_RELAY_MANUAL } from "./relay-instructions";
 import { providerHomeRootFromEnv } from "./config";
+import { applyClaudeConfigPromptGatePreventions } from "./claude-prompt-gates";
 
 type ProviderHome = {
   path: string;
@@ -16,8 +17,18 @@ export function profileUsesHostProviderGlobals(config: { agentProfile?: RunnerSp
   return !config.agentProfile || config.agentProfile.base === "host";
 }
 
-function profileRequiresIsolatedHome(config: RunnerSpawnConfig): boolean {
-  return Boolean(config.agentProfile && config.agentProfile.base !== "host");
+export function claudeProjectConfigProjectionOn(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);
+}
+
+function profileRequiresIsolatedHome(provider: "claude" | "codex", config: RunnerSpawnConfig): boolean {
+  if (!config.agentProfile) return false;
+  if (config.agentProfile.base !== "host") return true;
+  return provider === "claude" && claudeProjectConfigProjectionOn(config);
 }
 
 // #557 — PURE: the isolated provider config home path a launch WILL use, or undefined
@@ -25,7 +36,7 @@ function profileRequiresIsolatedHome(config: RunnerSpawnConfig): boolean {
 // 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;
+  if (!profileRequiresIsolatedHome(provider, config)) return undefined;
   return providerHomePath(provider, config);
 }
 
@@ -56,7 +67,7 @@ const CLAUDE_AUTH_ITEMS = [".credentials.json", "statsig"];
 // 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 {
-  if (!profileRequiresIsolatedHome(config)) return undefined;
+  if (!profileRequiresIsolatedHome(provider, config)) return undefined;
   const target = providerHomePath(provider, config);
   mkdirSync(target, { recursive: true });
   const authLinked = provider === "codex"
@@ -91,20 +102,7 @@ function seedClaudeConfigIfMissing(claudeHome: string, config: RunnerSpawnConfig
   const path = join(claudeHome, ".claude.json");
   if (existsSync(path)) return;
   const host = readHostClaudeConfig();
-  const seed: Record<string, unknown> = {
-    hasCompletedOnboarding: true,
-    theme: typeof host?.theme === "string" ? host.theme : "dark",
-  };
-  if (typeof host?.lastOnboardingVersion === "string") seed.lastOnboardingVersion = host.lastOnboardingVersion;
-  // Open approval = headless launch adds --dangerously-skip-permissions, which has
-  // its OWN first-run gate ("Bypass Permissions mode" accept/exit). Pre-accept it,
-  // or the agent stalls there exactly like the onboarding/trust gates.
-  if (config.approvalMode === "open") seed.bypassPermissionsModeAccepted = true;
-  if (config.cwd) {
-    seed.projects = {
-      [resolve(config.cwd)]: { hasTrustDialogAccepted: true, hasCompletedProjectOnboarding: true },
-    };
-  }
+  const seed = applyClaudeConfigPromptGatePreventions({}, host, config);
   writeFileSync(path, JSON.stringify(seed, null, 2), { mode: 0o600 });
 }
 

package/src/profile-projection.ts

@@ -34,6 +34,8 @@ export function agentProfileProjectionReport(input: AgentProfileProjectionInput)
   add(provisioningPluginsEntry(assembled));
   add(provisioningMcpEntry(assembled));
   add(projectMcpEntry(assembled));
+  add(projectSkillsEntry(assembled));
+  add(projectSettingsEntry(assembled));
   add(sharedMcpEntry(assembled));
   if (profile) add(filesystemEntry(profile));
   add(configHomeEntry(assembled));
@@ -159,14 +161,30 @@ function projectMcpEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
     : `Project .mcp.json servers emitted as -c mcp_servers.* overrides (${names.join(", ")}).`);
 }
 
-// #672 — shared host-listener MCP provenance. `not-applicable` when the profile/spawn didn't
-// opt in (the default); `applied` reports the per-agent `callmux bridge` routing the agent's
-// non-identity MCP (tokenlean, github) through the shared listener it points at. The server SET
-// is owned by the listener config, so this surfaces the route + URL, not an enumerated list.
+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 (!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.`);
+}
+
+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.");
+  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}.`);
+}
+
+// #672/#689 — shared host-listener MCP provenance. `applied` reports the per-agent `callmux
+// bridge` route. `not-applicable` means the resolved profile kept shared MCP off (for example a
+// zero-host profile, explicit false, or global kill-switch normalization before launch).
 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 (opt in via the sharedMcp profile/spawn option); non-identity MCP is injected per-agent.");
+  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).`);

package/src/provisioning.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, 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, ProvisioningMcpServer, ResolvedProvisioning } from "agent-relay-sdk";
@@ -74,6 +74,88 @@ export function resolveProjectMcpServers(
   return out;
 }
 
+export function resolveClaudeProjectSkills(
+  claudeHome: string,
+  config: Pick<RunnerSpawnConfig, "agentProfile" | "cwd">,
+  reservedNames: ReadonlySet<string> = new Set(),
+): ResolvedAsset[] {
+  if (!config.agentProfile?.projectSkills) return [];
+  const skillsRoot = join(config.cwd, ".claude", "skills");
+  if (!existsSync(skillsRoot)) return [];
+  const targetRoot = join(claudeHome, "skills");
+  const resolved: ResolvedAsset[] = [];
+  for (const entry of readdirSync(skillsRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory() || reservedNames.has(entry.name)) continue;
+    const source = join(skillsRoot, entry.name);
+    if (!existsSync(join(source, "SKILL.md"))) continue;
+    resolved.push({
+      name: entry.name,
+      dir: join(targetRoot, assetDirName(entry.name)),
+      source: { kind: "link", source },
+    });
+  }
+  return resolved.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+const UNSAFE_PROJECT_CLAUDE_SETTINGS = new Set([
+  "apiKeyHelper",
+  "allowDangerouslySkipPermissions",
+  "allowedTools",
+  "disabledMcpjsonServers",
+  "disallowedTools",
+  "enableAllProjectMcpServers",
+  "enabledMcpjsonServers",
+  "env",
+  "hooks",
+  "mcpServers",
+  "permissionMode",
+  "permissions",
+  "statusLine",
+  "tools",
+]);
+
+export interface ResolvedProjectClaudeSettings {
+  applied: boolean;
+  settings: Record<string, unknown>;
+  keys: string[];
+  ignoredKeys: string[];
+  file?: string;
+}
+
+export function resolveProjectClaudeSettings(
+  config: Pick<RunnerSpawnConfig, "agentProfile" | "cwd">,
+): ResolvedProjectClaudeSettings {
+  if (!config.agentProfile?.projectSettings) return { applied: false, settings: {}, keys: [], ignoredKeys: [] };
+  const file = join(config.cwd, ".claude", "settings.json");
+  if (!existsSync(file)) return { applied: true, settings: {}, keys: [], ignoredKeys: [], file };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (err) {
+    console.warn(`project .claude/settings.json projection: failed to parse ${file}: ${(err as Error).message}`);
+    return { applied: true, settings: {}, keys: [], ignoredKeys: [], file };
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { applied: true, settings: {}, keys: [], ignoredKeys: [], file };
+  }
+  const settings: Record<string, unknown> = {};
+  const ignoredKeys: string[] = [];
+  for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
+    if (UNSAFE_PROJECT_CLAUDE_SETTINGS.has(key)) {
+      ignoredKeys.push(key);
+      continue;
+    }
+    settings[key] = value;
+  }
+  return {
+    applied: true,
+    settings,
+    keys: Object.keys(settings).sort(),
+    ignoredKeys: ignoredKeys.sort(),
+    file,
+  };
+}
+
 // 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).

package/src/rate-limit.ts

@@ -1,5 +1,4 @@
 // #286 — shared rate-limit hold construction + Claude pane detection.
-import type { ProviderStatusUpdate } from "./adapter";
 //
 // Two detection arms feed the SAME provider-neutral `blocked` hold:
 //   1. The StopFailure hook (clean API-error turn-end: API-429/auth/billing) → control-server.
@@ -126,38 +125,6 @@ function parseClaudeTransientOverloadPane(text: string): PaneRateLimit | null {
   };
 }
 
-export interface ClaudeRateLimitPaneGateState {
-  consecutiveDetections: number;
-  reported: boolean;
-}
-
-export function gatedClaudeRateLimitStatus(
-  text: string,
-  state: ClaudeRateLimitPaneGateState,
-  options: { sessionName?: string; busy?: boolean } = {},
-): { status: ProviderStatusUpdate | null; state: ClaudeRateLimitPaneGateState } {
-  const parsed = parseClaudeRateLimitPane(text);
-  if (!parsed) return { status: null, state: { consecutiveDetections: 0, reported: false } };
-  if (options.busy) return { status: null, state: { consecutiveDetections: 0, reported: state.reported } };
-  const nextState = { consecutiveDetections: state.consecutiveDetections + 1, reported: state.reported };
-  if (nextState.reported || nextState.consecutiveDetections < 2) return { status: null, state: nextState };
-  nextState.reported = true;
-  return {
-    status: {
-      status: "idle",
-      clear: ["subagent"],
-      providerState: buildRateLimitProviderState({
-        errorType: parsed.errorType ?? "session_limit",
-        kind: parsed.kind ?? "usage_limit",
-        ...(parsed.resetAt ? { resetAt: parsed.resetAt } : {}),
-        message: parsed.message,
-        source: options.sessionName ? `claude-pane:${options.sessionName}` : "claude-pane",
-      }),
-    },
-    state: nextState,
-  };
-}
-
 // The clean limit line containing the match offset, stripped of box-drawing chrome.
 function limitLineAt(text: string, index: number): string {
   const start = text.lastIndexOf("\n", index) + 1;

package/src/relay-injection-events.ts

@@ -39,7 +39,9 @@ function launchInjectionEvents(input: RunnerLaunchInjectionInput): KeyedRelayInj
   if (!supportsLaunchAssembly(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
     + assembled.mcp.projectServers.length
+    + (assembled.projectSettings.applied ? 1 : 0)
     + (assembled.relaySkills ? 1 : 0)
     + (assembled.relayPlugin ? 1 : 0)
     + (assembled.mcp.relayEndpoint ? 1 : 0)
@@ -51,6 +53,8 @@ function launchInjectionEvents(input: RunnerLaunchInjectionInput): KeyedRelayInj
     assembled.statusLine ? "status line" : "",
     assembled.mcp.relayEndpoint ? "relay MCP" : "",
     assembled.skills.length ? `${assembled.skills.length} skill${assembled.skills.length === 1 ? "" : "s"}` : "",
+    assembled.projectSkills.length ? `${assembled.projectSkills.length} project skill${assembled.projectSkills.length === 1 ? "" : "s"}` : "",
+    assembled.projectSettings.applied ? "project settings" : "",
     assembled.plugins.length ? `${assembled.plugins.length} plugin${assembled.plugins.length === 1 ? "" : "s"}` : "",
     assembled.mcp.servers.length ? `${assembled.mcp.servers.length} MCP server${assembled.mcp.servers.length === 1 ? "" : "s"}` : "",
     assembled.mcp.projectServers.length ? `${assembled.mcp.projectServers.length} project MCP server${assembled.mcp.projectServers.length === 1 ? "" : "s"}` : "",
@@ -70,6 +74,8 @@ function launchInjectionEvents(input: RunnerLaunchInjectionInput): KeyedRelayInj
         relayPlugin: assembled.relayPlugin,
         statusLine: assembled.statusLine,
         skills: assembled.skills,
+        projectSkills: assembled.projectSkills,
+        projectSettings: assembled.projectSettings,
         plugins: assembled.plugins,
         mcp: assembled.mcp,
       },

package/src/runner-core.ts

@@ -16,7 +16,7 @@ import { startControlServer, type ControlServer } 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 { profileUsesHostProviderGlobals } from "./profile-home";
+import { profileUsesClaudeHostProviderGlobals, profileUsesHostProviderGlobals } from "./profile-home";
 import { RELAY_MCP_TOKEN_ENV, relayMcpEndpoint, resolveSharedMcpUrl } from "./relay-mcp";
 import { RelayMcpProxy } from "./relay-mcp-proxy";
 import { runtimeMetadata } from "./version";
@@ -526,7 +526,7 @@ export class AgentRunner {
   private async spawnProvider(opts: { resumeId?: string; suppressPrompt?: boolean } = {}): Promise<ManagedProcess> {
     this.providerSessionId = crypto.randomUUID();
     this.lastTranscriptPath = undefined;
-    const includeProviderGlobals = profileUsesHostProviderGlobals(this.options);
+    const includeProviderGlobals = this.options.provider === "claude" ? profileUsesClaudeHostProviderGlobals(this.options) : profileUsesHostProviderGlobals(this.options);
     const env = {
       ...process.env as Record<string, string>,
       ...(includeProviderGlobals ? this.options.providerConfig.env : {}),