@wix/pathgrade 1.0.28 → 1.0.29

package/dist/agents/claude.js

@@ -88,10 +88,11 @@ export class ClaudeAgent extends BaseAgent {
             hostEnv,
             sandboxProfile: this.deps.sandboxProfile,
         });
-        const claudeCodeExecutable = resolveClaudeCodeExecutable({
-            agentOptionsExecutable: this.opts.claudeCodeExecutable,
-            envExecutable,
-        });
+        const claudeCodeExecutable = sessionOptions?.admittedClaudeCodeExecutable
+            ?? resolveClaudeCodeExecutable({
+                agentOptionsExecutable: this.opts.claudeCodeExecutable,
+                envExecutable,
+            });
         const mcpMountOptions = {
             workspacePath,
             mcpConfigPath: sessionOptions?.mcpConfigPath,

package/dist/internal/direct-mcp-v2/claude-direct-mcp.d.ts

@@ -2,7 +2,7 @@ import { type McpSdkServerConfigWithInstance, type Options as ClaudeSdkOptions,
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { type CleanupReport } from './cleanup.js';
 import { type MaterializedProjection } from './materialize.js';
-import type { EvidenceEnvelope, ScenarioArtifact, ScenarioMachineV2 } from './types.js';
+import type { AdmittedRuntimeProfile, EvidenceEnvelope, ScenarioArtifact, ScenarioMachineV2 } from './types.js';
 export declare const CLAUDE_DIRECT_MCP_FLAG = "PATHGRADE_INTERNAL_CLAUDE_DIRECT_MCP_V2";
 export type ClaudeDirectMcpChecks = {
     runtimeAdmitted: boolean;
@@ -19,6 +19,7 @@ export type ClaudeDirectMcpChecks = {
 export type ClaudeDirectMcpTrialResult = {
     selected: true;
     profileFingerprint: string;
+    runtimeProfile: AdmittedRuntimeProfile;
     artifact: ScenarioArtifact;
     evidence: readonly EvidenceEnvelope[];
     checks: ClaudeDirectMcpChecks;

package/dist/internal/direct-mcp-v2/claude-direct-mcp.js

@@ -11,19 +11,35 @@ import { compileScenario } from './compiler.js';
 import { IdempotentTrialCleaner, persistTrialArtifact, TrialExecutionError, TrialResourceRegistry, scanBearerSurfaces } from './cleanup.js';
 import { PrivateReplayVault, replayPrivateEvidence, verifyEvidenceChain } from './evidence.js';
 import { ScenarioHostReducer } from './host-reducer.js';
+import { sha256Canonical } from './json.js';
 import { materializeProjection } from './materialize.js';
 import { projectEndpoints } from './projection.js';
-import { admitRuntimeProfile } from './runtime-profile.js';
+import { admitRuntimeLock } from './runtime-lock.js';
 import { createInvocationBarrier, startScenarioHttpHost } from './scenario-http-host.js';
-import { CLAUDE_DIRECT_MCP_DARWIN_ARM64_PROFILE, CLAUDE_DIRECT_MCP_NORMALIZED_HANDSHAKE } from './claude-profile.js';
+import { observeClaudeRuntimeControlPlane, resolveClaudeScenarioExecutable, selectClaudeRuntimeTarget, } from './claude-profile.js';
 export const CLAUDE_DIRECT_MCP_FLAG = 'PATHGRADE_INTERNAL_CLAUDE_DIRECT_MCP_V2';
 const disabledProfiles = new Map();
+function runtimeLockFingerprint(lock) {
+    return sha256Canonical(lock);
+}
 export function isClaudeDirectMcpSelected(environment = process.env) {
-    const fingerprint = CLAUDE_DIRECT_MCP_DARWIN_ARM64_PROFILE.profileFingerprint;
-    return environment[CLAUDE_DIRECT_MCP_FLAG] === '1' && !disabledProfiles.has(fingerprint);
+    if (environment[CLAUDE_DIRECT_MCP_FLAG] !== '1')
+        return false;
+    try {
+        const fingerprint = selectClaudeRuntimeTarget().lock;
+        return !disabledProfiles.has(runtimeLockFingerprint(fingerprint));
+    }
+    catch {
+        return false;
+    }
 }
 export function claudeDirectMcpDisableReason() {
-    return disabledProfiles.get(CLAUDE_DIRECT_MCP_DARWIN_ARM64_PROFILE.profileFingerprint);
+    try {
+        return disabledProfiles.get(runtimeLockFingerprint(selectClaudeRuntimeTarget().lock));
+    }
+    catch {
+        return undefined;
+    }
 }
 /** Test-only reset for proving the fail-closed process latch. */
 // oxlint-disable-next-line inhuman/no-empty-wrappers -- This test seam exposes Map.clear without exposing mutable production state.
@@ -82,17 +98,18 @@ export function createClaudeParentBridges(options) {
 }
 export async function runClaudeDirectMcpTrial(options) {
     const environment = options.environment ?? process.env;
-    const profile = CLAUDE_DIRECT_MCP_DARWIN_ARM64_PROFILE;
+    const target = selectClaudeRuntimeTarget();
+    const fingerprint = runtimeLockFingerprint(target.lock);
     if (!isClaudeDirectMcpSelected(environment)) {
-        const reason = disabledProfiles.get(profile.profileFingerprint);
+        const reason = disabledProfiles.get(fingerprint);
         throw new Error(reason ? `Claude direct MCP disabled for admitted profile: ${reason}` : `${CLAUDE_DIRECT_MCP_FLAG} is disabled`);
     }
     try {
-        return await executeTrial({ ...options, environment });
+        return await executeTrial({ ...options, environment, target });
     }
     catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
-        disabledProfiles.set(profile.profileFingerprint, reason.slice(0, 500));
+        disabledProfiles.set(fingerprint, reason.slice(0, 500));
         throw error;
     }
 }
@@ -179,21 +196,21 @@ async function executeTrial(options) {
         zeroBearer: () => { host.bearer.fill(0); macKey.fill(0); replayVault.dispose(); },
     });
     try {
-        const admission = await admitRuntimeProfile(CLAUDE_DIRECT_MCP_DARWIN_ARM64_PROFILE, {
+        const admission = await admitRuntimeLock(options.target.lock, {
             provider: 'claude',
             platform: process.platform,
             architecture: process.arch,
+            resolvedExecutable: await resolveClaudeScenarioExecutable(options.target),
             environment: runtimeEnv,
             forbiddenSecrets: [host.bearer.toString(), `Bearer ${host.bearer.toString()}`],
             initializeControlPlane: async () => {
                 await options.initializeControlPlane?.();
-                if (typeof createSdkMcpServer !== 'function' || typeof (options.query ?? sdkQuery) !== 'function')
-                    throw new Error('Claude SDK parent bridge methods unavailable');
-                return { normalizedHandshake: CLAUDE_DIRECT_MCP_NORMALIZED_HANDSHAKE, capabilities: CLAUDE_DIRECT_MCP_DARWIN_ARM64_PROFILE.requiredCapabilities, close: async () => undefined };
+                return observeClaudeRuntimeControlPlane({
+                    createSdkMcpServer,
+                    query: options.query ?? sdkQuery,
+                });
             },
         });
-        if (!admission.ok)
-            throw new Error(`RUNTIME_NOT_ADMITTED: ${admission.reason}`);
         reducer.markAdmitted();
         const projected = projectEndpoints(host.endpoints, admission.profile);
         if (!Array.isArray(projected))
@@ -212,7 +229,7 @@ async function executeTrial(options) {
         }
         reducer.markReady();
         const query = options.query ?? sdkQuery;
-        const queryOptions = { query, runtimeEnv, workspacePath, model: options.model, profilePath: CLAUDE_DIRECT_MCP_DARWIN_ARM64_PROFILE.command.absolutePath, mcpServers: bridges, spawnClaudeCodeProcess };
+        const queryOptions = { query, runtimeEnv, workspacePath, model: options.model, profilePath: admission.commandPath, mcpServers: bridges, spawnClaudeCodeProcess };
         reducer.beginTurn('direct-call', 'claude');
         const normal = await runQuery(queryOptions, `Invoke mcp__demo__${effectfulCase.pureToolId} exactly once with ${JSON.stringify(effectfulCase.pureArgs)}, then invoke mcp__demo__${effectfulCase.effectfulToolId} exactly once with ${JSON.stringify(effectfulCase.errorArgs)}. Wait for both results and do not use any other tool.`);
         if (normal.status !== 'success')
@@ -262,7 +279,8 @@ async function executeTrial(options) {
             throw new Error(`CLEANUP_FAILED: ${JSON.stringify(cleanup.failures)}`);
         return {
             selected: true,
-            profileFingerprint: CLAUDE_DIRECT_MCP_DARWIN_ARM64_PROFILE.profileFingerprint,
+            profileFingerprint: admission.identity.lockFingerprint,
+            runtimeProfile: admission.profile,
             artifact: compiled.artifact,
             evidence: reducer.ledger.events(),
             checks: { runtimeAdmitted: true, secretFreeProject: true, directCall: true, structuredToolError: true, fencedCancellation: true, providerTerminal: true, hostQuiescent: hostQuiescentBeforeCleanup, postCancelReuse: true, privateReplay: true, cleanup: true },

package/dist/internal/direct-mcp-v2/claude-profile.d.ts

@@ -1,9 +1,35 @@
-import type { RuntimeLock } from './runtime-lock.js';
-import type { JsonObject, RuntimeCapabilityProfile } from './types.js';
+import type { RuntimeLock, RuntimeLockControlPlane } from './runtime-lock.js';
+import type { JsonObject } from './types.js';
 export declare const CLAUDE_DIRECT_MCP_NORMALIZED_HANDSHAKE: JsonObject;
-/** Reviewed macOS arm64 pin captured by RFC 0006. Other platforms fail closed. */
-export declare const CLAUDE_DIRECT_MCP_DARWIN_ARM64_PROFILE: RuntimeCapabilityProfile;
-/** Code-owned relocatable identity lock for the admitted public Claude SDK slice. */
+export declare const CLAUDE_DIRECT_MCP_CAPABILITIES: {
+    readonly streamableHttp: true;
+    readonly controlPlaneHeaders: true;
+    readonly parentOwnedSdkMcp: true;
+    readonly cancellation: "abort-controller";
+};
+/** Code-owned relocatable identity lock captured by RFC 0006. */
 export declare const CLAUDE_DIRECT_MCP_DARWIN_ARM64_LOCK: RuntimeLock;
-/** Resolve the bundled platform binary relative to the installed SDK package. */
-export declare function resolveClaudeScenarioExecutable(): Promise<string>;
+/** Provisional Linux x64 glibc lock; CI re-verifies every artifact before admission. */
+export declare const CLAUDE_DIRECT_MCP_LINUX_X64_GLIBC_LOCK: RuntimeLock;
+export type ClaudeRuntimeTarget = {
+    id: 'darwin-arm64' | 'linux-x64-glibc';
+    platform: 'darwin' | 'linux';
+    architecture: 'arm64' | 'x64';
+    libc?: 'glibc';
+    packageName: string;
+    lock: RuntimeLock;
+};
+export declare const CLAUDE_RUNTIME_TARGETS: readonly ClaudeRuntimeTarget[];
+export type ClaudeRuntimeEnvironment = {
+    platform: string;
+    architecture: string;
+    libc?: string;
+};
+export declare function detectClaudeRuntimeEnvironment(): ClaudeRuntimeEnvironment;
+export declare function selectClaudeRuntimeTarget(environment?: ClaudeRuntimeEnvironment): ClaudeRuntimeTarget;
+/** Resolve the selected optional-package binary through Node package resolution. */
+export declare function resolveClaudeScenarioExecutable(target?: ClaudeRuntimeTarget): Promise<string>;
+export declare function observeClaudeRuntimeControlPlane(options: {
+    createSdkMcpServer: unknown;
+    query: unknown;
+}): RuntimeLockControlPlane;

package/dist/internal/direct-mcp-v2/claude-profile.js

@@ -1,5 +1,5 @@
-import { access, realpath } from 'node:fs/promises';
 import { constants } from 'node:fs';
+import { access, realpath } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 export const CLAUDE_DIRECT_MCP_NORMALIZED_HANDSHAKE = {
@@ -13,85 +13,117 @@ export const CLAUDE_DIRECT_MCP_NORMALIZED_HANDSHAKE = {
     cancellation: 'abort-controller',
     sdkMethods: ['createSdkMcpServer', 'query'],
 };
-/** Reviewed macOS arm64 pin captured by RFC 0006. Other platforms fail closed. */
-export const CLAUDE_DIRECT_MCP_DARWIN_ARM64_PROFILE = {
-    format: 'pathgrade-direct-mcp-runtime-profile-v1',
-    provider: 'claude',
-    platform: 'darwin',
-    architecture: 'arm64',
-    controlPlane: 'native-sdk-parent-bridge',
-    command: {
-        absolutePath: '/Users/nadavlac/projects/agent-evals/node_modules/@anthropic-ai/claude-agent-sdk-darwin-arm64/claude',
+export const CLAUDE_DIRECT_MCP_CAPABILITIES = {
+    streamableHttp: true,
+    controlPlaneHeaders: true,
+    parentOwnedSdkMcp: true,
+    cancellation: 'abort-controller',
+};
+const SDK_SHA256 = '48bde6aeabf7e71ad5528bf52c8feb1642c21f505ea2495c70f39db7df226d97';
+const ZOD_SHA256 = '2a3455cecff4f7021c92d0a3e2e5fc170c0448dc5cc261160127e08f4888a9c2';
+const NORMALIZED_HANDSHAKE_SHA256 = '990b779b75145c8d7bcc8cfebcb5b9c1aae30eb1436393b38e7e997941ecc162';
+const CLAUDE_VERSION = '2.1.141 (Claude Code)';
+const COMMAND_ARTIFACT = 'claude-code-bundled-2.1.141';
+function claudeLock(options) {
+    return {
+        format: 'pathgrade-direct-mcp-runtime-lock-v1',
+        provider: 'claude',
+        platform: options.platform,
+        architecture: options.architecture,
+        controlPlane: 'native-sdk-parent-bridge',
+        version: CLAUDE_VERSION,
+        commandArtifact: COMMAND_ARTIFACT,
         args: [],
         versionArgs: ['--version'],
-    },
-    expectedVersion: '2.1.141 (Claude Code)',
-    artifacts: [
-        {
-            label: 'claude-agent-sdk-0.2.141',
-            absolutePath: '/Users/nadavlac/projects/agent-evals/node_modules/@anthropic-ai/claude-agent-sdk/sdk.mjs',
-            sha256: '48bde6aeabf7e71ad5528bf52c8feb1642c21f505ea2495c70f39db7df226d97',
-        },
-        {
-            label: 'claude-code-bundled-2.1.141',
-            absolutePath: '/Users/nadavlac/projects/agent-evals/node_modules/@anthropic-ai/claude-agent-sdk-darwin-arm64/claude',
-            sha256: '31ac95bb19a33b1d0cddd3f3ff594bf8bfd2be5051cd2af7867109641cab705e',
-        },
-        {
-            label: 'zod-4.3.6-commonjs-entry',
-            absolutePath: '/Users/nadavlac/projects/agent-evals/node_modules/zod/index.cjs',
-            sha256: '2a3455cecff4f7021c92d0a3e2e5fc170c0448dc5cc261160127e08f4888a9c2',
-        },
-    ],
-    requiredCapabilities: {
-        streamableHttp: true,
-        controlPlaneHeaders: true,
-        parentOwnedSdkMcp: true,
-        cancellation: 'abort-controller',
-    },
-    profileFingerprint: '463d1485d70e542cf2a356cae007469a7d94d0e848a26d9e9b7470dbc5262104',
-    runtimeCapabilityFingerprint: '990b779b75145c8d7bcc8cfebcb5b9c1aae30eb1436393b38e7e997941ecc162',
-};
-/** Code-owned relocatable identity lock for the admitted public Claude SDK slice. */
-export const CLAUDE_DIRECT_MCP_DARWIN_ARM64_LOCK = {
-    format: 'pathgrade-direct-mcp-runtime-lock-v1',
-    provider: 'claude',
+        artifacts: [
+            { id: 'claude-agent-sdk-0.2.141', relativePath: '@anthropic-ai/claude-agent-sdk/sdk.mjs', sha256: SDK_SHA256 },
+            { id: COMMAND_ARTIFACT, relativePath: `${options.packageName}/claude`, sha256: options.commandSha256 },
+            { id: 'zod-4.3.6-commonjs-entry', relativePath: 'zod/index.cjs', sha256: ZOD_SHA256 },
+        ],
+        capabilities: CLAUDE_DIRECT_MCP_CAPABILITIES,
+        normalizedHandshakeSha256: NORMALIZED_HANDSHAKE_SHA256,
+    };
+}
+/** Code-owned relocatable identity lock captured by RFC 0006. */
+export const CLAUDE_DIRECT_MCP_DARWIN_ARM64_LOCK = claudeLock({
     platform: 'darwin',
     architecture: 'arm64',
-    controlPlane: 'native-sdk-parent-bridge',
-    version: CLAUDE_DIRECT_MCP_DARWIN_ARM64_PROFILE.expectedVersion,
-    commandArtifact: 'claude-code-bundled-2.1.141',
-    args: CLAUDE_DIRECT_MCP_DARWIN_ARM64_PROFILE.command.args,
-    versionArgs: CLAUDE_DIRECT_MCP_DARWIN_ARM64_PROFILE.command.versionArgs,
-    artifacts: [
-        {
-            id: 'claude-agent-sdk-0.2.141',
-            relativePath: '@anthropic-ai/claude-agent-sdk/sdk.mjs',
-            sha256: CLAUDE_DIRECT_MCP_DARWIN_ARM64_PROFILE.artifacts[0].sha256,
-        },
-        {
-            id: 'claude-code-bundled-2.1.141',
-            relativePath: '@anthropic-ai/claude-agent-sdk-darwin-arm64/claude',
-            sha256: CLAUDE_DIRECT_MCP_DARWIN_ARM64_PROFILE.artifacts[1].sha256,
-        },
-        {
-            id: 'zod-4.3.6-commonjs-entry',
-            relativePath: 'zod/index.cjs',
-            sha256: CLAUDE_DIRECT_MCP_DARWIN_ARM64_PROFILE.artifacts[2].sha256,
-        },
-    ],
-    capabilities: CLAUDE_DIRECT_MCP_DARWIN_ARM64_PROFILE.requiredCapabilities,
-    normalizedHandshakeSha256: CLAUDE_DIRECT_MCP_DARWIN_ARM64_PROFILE.runtimeCapabilityFingerprint,
-};
-/** Resolve the bundled platform binary relative to the installed SDK package. */
-export async function resolveClaudeScenarioExecutable() {
-    const sdkEntry = createRequire(import.meta.url).resolve('@anthropic-ai/claude-agent-sdk');
-    const candidate = join(dirname(sdkEntry), '..', 'claude-agent-sdk-darwin-arm64', 'claude');
+    packageName: '@anthropic-ai/claude-agent-sdk-darwin-arm64',
+    commandSha256: '31ac95bb19a33b1d0cddd3f3ff594bf8bfd2be5051cd2af7867109641cab705e',
+});
+/** Provisional Linux x64 glibc lock; CI re-verifies every artifact before admission. */
+export const CLAUDE_DIRECT_MCP_LINUX_X64_GLIBC_LOCK = claudeLock({
+    platform: 'linux',
+    architecture: 'x64',
+    packageName: '@anthropic-ai/claude-agent-sdk-linux-x64',
+    commandSha256: '832be26e8f15b2ae99e520a22b034fc4bfad1cb5b84de6b706487072c56bb42e',
+});
+export const CLAUDE_RUNTIME_TARGETS = [
+    {
+        id: 'darwin-arm64',
+        platform: 'darwin',
+        architecture: 'arm64',
+        packageName: '@anthropic-ai/claude-agent-sdk-darwin-arm64',
+        lock: CLAUDE_DIRECT_MCP_DARWIN_ARM64_LOCK,
+    },
+    {
+        id: 'linux-x64-glibc',
+        platform: 'linux',
+        architecture: 'x64',
+        libc: 'glibc',
+        packageName: '@anthropic-ai/claude-agent-sdk-linux-x64',
+        lock: CLAUDE_DIRECT_MCP_LINUX_X64_GLIBC_LOCK,
+    },
+];
+export function detectClaudeRuntimeEnvironment() {
+    if (process.platform !== 'linux')
+        return { platform: process.platform, architecture: process.arch };
+    const report = process.report?.getReport();
+    const glibc = report?.header?.glibcVersionRuntime;
+    return {
+        platform: process.platform,
+        architecture: process.arch,
+        libc: typeof glibc === 'string' && glibc.length > 0 ? 'glibc' : 'unknown',
+    };
+}
+export function selectClaudeRuntimeTarget(environment = detectClaudeRuntimeEnvironment()) {
+    const target = CLAUDE_RUNTIME_TARGETS.find((candidate) => (candidate.platform === environment.platform
+        && candidate.architecture === environment.architecture
+        && candidate.libc === environment.libc));
+    if (!target) {
+        const identity = [environment.platform, environment.architecture, environment.libc].filter(Boolean).join('-');
+        throw new Error(`RUNTIME_NOT_ADMITTED: unsupported Claude runtime target: ${identity}`);
+    }
+    return target;
+}
+/** Resolve the selected optional-package binary through Node package resolution. */
+export async function resolveClaudeScenarioExecutable(target = selectClaudeRuntimeTarget()) {
+    let packageJson;
+    try {
+        packageJson = createRequire(import.meta.url).resolve(`${target.packageName}/package.json`);
+    }
+    catch {
+        throw new Error(`RUNTIME_NOT_ADMITTED: missing Claude runtime package: ${target.packageName}`);
+    }
+    const candidate = join(dirname(packageJson), 'claude');
     try {
         await access(candidate, constants.X_OK);
         return realpath(candidate);
     }
     catch {
-        throw new Error('RUNTIME_NOT_ADMITTED: no bundled Claude executable was discovered');
+        throw new Error(`RUNTIME_NOT_ADMITTED: Claude runtime executable is unavailable: ${target.id}`);
+    }
+}
+export function observeClaudeRuntimeControlPlane(options) {
+    if (typeof options.createSdkMcpServer !== 'function' || typeof options.query !== 'function') {
+        throw new Error('Claude SDK parent bridge methods unavailable');
+    }
+    if (typeof AbortController !== 'function' || typeof AbortController.prototype.abort !== 'function') {
+        throw new Error('Claude AbortController cancellation unavailable');
     }
+    return {
+        normalizedHandshake: CLAUDE_DIRECT_MCP_NORMALIZED_HANDSHAKE,
+        capabilities: CLAUDE_DIRECT_MCP_CAPABILITIES,
+        close: async () => undefined,
+    };
 }

package/dist/internal/direct-mcp-v2/public-scenario-runtime.js

@@ -8,7 +8,7 @@ import { projectEndpoints } from './projection.js';
 import { admitRuntimeLock } from './runtime-lock.js';
 import { startScenarioHttpHost } from './scenario-http-host.js';
 import { createClaudeParentBridges } from './claude-direct-mcp.js';
-import { CLAUDE_DIRECT_MCP_DARWIN_ARM64_LOCK, CLAUDE_DIRECT_MCP_NORMALIZED_HANDSHAKE, resolveClaudeScenarioExecutable } from './claude-profile.js';
+import { observeClaudeRuntimeControlPlane, resolveClaudeScenarioExecutable, selectClaudeRuntimeTarget } from './claude-profile.js';
 const defaultCoordinatorDependencies = {
     startHost: startScenarioHttpHost,
     scanBearerSurfaces,
@@ -286,8 +286,10 @@ function scenarioScanRoots(workspacePath, environment) {
         ].filter((path) => typeof path === 'string' && path.length > 0))];
 }
 export async function startPublicClaudeScenarioRuntime(options, dependencies = {}) {
-    const lock = dependencies.lock ?? CLAUDE_DIRECT_MCP_DARWIN_ARM64_LOCK;
-    const resolveExecutable = dependencies.resolveExecutable ?? resolveClaudeScenarioExecutable;
+    const target = dependencies.lock ? undefined : selectClaudeRuntimeTarget();
+    const lock = dependencies.lock ?? target.lock;
+    const resolveExecutable = dependencies.resolveExecutable
+        ?? (async () => resolveClaudeScenarioExecutable(target));
     const coordinator = await startScenarioCoordinator({
         ...options,
         provider: 'claude',
@@ -301,16 +303,10 @@ export async function startPublicClaudeScenarioRuntime(options, dependencies = {
                 environment: options.environment,
                 forbiddenSecrets: [bearer.slice('Bearer '.length), bearer],
                 ...(dependencies.commandVersion ? { commandVersion: dependencies.commandVersion } : {}),
-                initializeControlPlane: async () => {
-                    if (typeof createSdkMcpServer !== 'function' || typeof sdkQuery !== 'function') {
-                        throw new Error('Claude SDK parent bridge methods unavailable');
-                    }
-                    return {
-                        normalizedHandshake: CLAUDE_DIRECT_MCP_NORMALIZED_HANDSHAKE,
-                        capabilities: lock.capabilities,
-                        close: async () => undefined,
-                    };
-                },
+                initializeControlPlane: async () => observeClaudeRuntimeControlPlane({
+                    createSdkMcpServer,
+                    query: sdkQuery,
+                }),
             });
             const projected = projectEndpoints(context.endpoints, admission.profile);
             if (!Array.isArray(projected))
@@ -320,7 +316,7 @@ export async function startPublicClaudeScenarioRuntime(options, dependencies = {
             }));
             const bridges = createClaudeParentBridges({ artifact: options.artifact, projections: materialized });
             return {
-                value: bridges,
+                value: { bridges, commandPath: admission.commandPath },
                 async interrupt() { },
                 async waitForTerminal() { },
                 async close() {
@@ -340,9 +336,10 @@ export async function startPublicClaudeScenarioRuntime(options, dependencies = {
         },
     });
     return {
-        claudeServers: coordinator.attachment,
+        claudeServers: coordinator.attachment.bridges,
         configureSession(sessionOptions) {
-            sessionOptions.scenarioMcpServers = coordinator.attachment;
+            sessionOptions.scenarioMcpServers = coordinator.attachment.bridges;
+            sessionOptions.admittedClaudeCodeExecutable = coordinator.attachment.commandPath;
         },
         beginTurn: coordinator.beginTurn,
         settleTurn: coordinator.settleTurn,

package/dist/types.d.ts

@@ -423,6 +423,8 @@ export interface AgentSessionOptions {
     scriptedMcpHost?: import('./providers/scripted-mcp-mock-host.js').ScriptedMcpMockHost;
     /** Parent-owned public ScenarioMachineV2 bridge; never serialized into child config. */
     scenarioMcpServers?: Record<string, import('@anthropic-ai/claude-agent-sdk').McpSdkServerConfigWithInstance>;
+    /** RuntimeLock-admitted Claude executable; wins over developer overrides for ScenarioMachineV2 sessions. */
+    admittedClaudeCodeExecutable?: string;
     /** Parent-owned admitted Codex app-server mount; projected only into thread/start memory. */
     codexScenarioMount?: import('./agents/codex-app-server/scenario-mount.js').CodexScenarioMount;
     /** Runtime-only values inherited by drivers and persistence sinks for redaction. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/pathgrade",
-  "version": "1.0.28",
+  "version": "1.0.29",
   "packageManager": "yarn@4.12.0",
   "description": "Evaluate whether AI agents discover and use your skills correctly",
   "exports": {
@@ -140,5 +140,5 @@
     "typescript": "^5.9.3",
     "zod": "4.3.6"
   },
-  "falconPackageHash": "f8df1d8950a1ce263fb945ab13722fdb8328a2f761153de0df90d0e9"
+  "falconPackageHash": "126198d020df14b3e6fceef3b0325ac5e84411c5e1b544a0167de604"
 }