impel-cli 0.20.42 → 0.20.44

package/src/agents.js

@@ -21,8 +21,10 @@ import {
   IMPEL_NATIVE_AGENT_ATTACHMENT_WINDOW_ENV,
   IMPEL_NATIVE_AGENT_TELEMETRY_ENV_NAMES,
   IMPEL_NATIVE_AGENT_MCP_TARGET,
+  IMPEL_NATIVE_BENCHMARK_ENV,
   impelCliInvocation,
   impelNativeAgentMcpInvocation,
+  nativeBenchmarkHeaderValue,
 } from "./selfInvocation.js";
 import {
   adapterAnswerFaithfulCompletionGuidance,
@@ -86,8 +88,11 @@ function eagerNativeAgentTransportEnabled() {
   return process.env.IMPEL_NATIVE_EAGER_TRANSPORT !== "0";
 }
 
-function enabledProfileFlag(environment, name) {
-  return ["1", "true"].includes(String(environment?.[name] || "").toLowerCase());
+function enabledProfileFlag(environment, name, { defaultEnabled = false } = {}) {
+  const configured = String(environment?.[name] || "").toLowerCase();
+  if (["1", "true"].includes(configured)) return true;
+  if (["0", "false"].includes(configured)) return false;
+  return defaultEnabled;
 }
 
 export function nativeParentDirectEnabled(environment = process.env) {
@@ -95,7 +100,11 @@ export function nativeParentDirectEnabled(environment = process.env) {
 }
 
 export function nativeSlashCommandsEnabled(environment = process.env) {
-  return enabledProfileFlag(environment, IMPEL_NATIVE_SLASH_COMMANDS_ENV);
+  // This surface is additive: the relay agent remains installed. Keep the
+  // explicit false literals as a symmetric rollback for managed profiles.
+  return enabledProfileFlag(environment, IMPEL_NATIVE_SLASH_COMMANDS_ENV, {
+    defaultEnabled: true,
+  });
 }
 const MAX_RETIRED_AGENT_BINDINGS = 50;
 const MAX_NATIVE_AGENT_STATE_BYTES = 512 * 1024;
@@ -670,6 +679,116 @@ function nativeToolName(toolName) {
   return `${nativeToolNamespace()}__${toolName}`;
 }
 
+const CLAUDE_PARENT_DIRECT_TOOL_PERMISSIONS = Object.freeze([
+  NATIVE_AGENT_ANSWER_TOOL,
+  NATIVE_AGENT_RESUME_TOOL,
+].map((tool) => nativeToolName(tool)));
+
+function parentDirectPermissionTools(renderedAgents) {
+  const trusted = new Set(CLAUDE_PARENT_DIRECT_TOOL_PERMISSIONS);
+  const tools = [...new Set(renderedAgents.flatMap((agent) =>
+    agent.parentLaunchDefinition?.tools || []
+  ))];
+  if (!tools.every((tool) => trusted.has(tool))) {
+    throw new Error("the managed Claude parent-direct permission grant is invalid");
+  }
+  return tools;
+}
+
+function priorParentDirectPermissionGrants(prior, ownsManagedProfile) {
+  const grants = ownsManagedProfile ? prior?.nativeParentDirectPermissionGrants : null;
+  const trusted = new Set(CLAUDE_PARENT_DIRECT_TOOL_PERMISSIONS);
+  if (!Array.isArray(grants)
+    || new Set(grants).size !== grants.length
+    || !grants.every((tool) => trusted.has(tool))) return [];
+  return [...grants];
+}
+
+function readClaudeSettingsForPermissions(settingsPath) {
+  let raw;
+  try {
+    const stat = fs.lstatSync(settingsPath);
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+      throw new Error(`refusing to update unsafe Claude settings path ${settingsPath}`);
+    }
+    raw = fs.readFileSync(settingsPath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return { settings: {} };
+    throw error;
+  }
+  try {
+    const settings = raw.trim() ? JSON.parse(raw) : {};
+    if (!settings || typeof settings !== "object" || Array.isArray(settings)) throw new Error();
+    return { settings };
+  } catch {
+    throw new Error(`${settingsPath} exists but isn't a valid JSON object. Fix or remove it, then re-run.`);
+  }
+}
+
+function syncClaudeParentDirectPermissions(root, desiredTools, priorGrants) {
+  if (desiredTools.length === 0 && priorGrants.length === 0) return [];
+
+  const settingsPath = path.join(root, "settings.json");
+  const { settings } = readClaudeSettingsForPermissions(settingsPath);
+  const permissionsExisted = Object.hasOwn(settings, "permissions");
+  if (permissionsExisted && (
+    !settings.permissions
+    || typeof settings.permissions !== "object"
+    || Array.isArray(settings.permissions)
+  )) {
+    throw new Error(`${settingsPath} has an invalid permissions value. Fix or remove it, then re-run.`);
+  }
+  const permissions = permissionsExisted ? { ...settings.permissions } : {};
+  if (Object.hasOwn(permissions, "allow") && (
+    !Array.isArray(permissions.allow)
+    || !permissions.allow.every((rule) => typeof rule === "string")
+  )) {
+    throw new Error(`${settingsPath} has an invalid permissions.allow value. Fix or remove it, then re-run.`);
+  }
+
+  const desired = new Set(desiredTools);
+  const previouslyManaged = new Set(priorGrants);
+  const allow = Array.isArray(permissions.allow) ? [...permissions.allow] : [];
+  const nextAllow = allow.filter((rule) => !previouslyManaged.has(rule) || desired.has(rule));
+  const managedGrants = [];
+  for (const tool of desiredTools) {
+    if (previouslyManaged.has(tool)) {
+      managedGrants.push(tool);
+      if (!nextAllow.includes(tool)) nextAllow.push(tool);
+    } else if (!nextAllow.includes(tool)) {
+      managedGrants.push(tool);
+      nextAllow.push(tool);
+    }
+  }
+
+  // permissions.allow is Claude's ordinary pre-approval surface. Record only
+  // entries this sync actually adds, so turning the experiment back off can
+  // remove them without claiming any operator-authored permission rule.
+  if (JSON.stringify(allow) !== JSON.stringify(nextAllow)) {
+    settings.permissions = { ...permissions, allow: nextAllow };
+    atomicPrivateWrite(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  }
+  return managedGrants;
+}
+
+function claudeParentDirectPermissionsCurrent(root, manifest) {
+  try {
+    const desiredTools = parentDirectPermissionTools(
+      Array.isArray(manifest.agents) ? manifest.agents.map((record) => ({
+        parentLaunchDefinition: record?.launchMode === "parent-direct"
+          ? record.parentLaunchDefinition
+          : null,
+      })) : [],
+    );
+    if (desiredTools.length === 0) return true;
+    const { settings } = readClaudeSettingsForPermissions(path.join(root, "settings.json"));
+    const allow = settings.permissions?.allow;
+    return Array.isArray(allow) && desiredTools.every((tool) => allow.includes(tool));
+  } catch {
+    return false;
+  }
+}
+
 function codexAdapterInstructions(tenantId, agent) {
   const contextRequirement = agent.requiredContext.length
     ? ` Required context keys are ${JSON.stringify(agent.requiredContext)}; if any are absent, ask for them before starting the run.`
@@ -814,7 +933,7 @@ function claudeParentDirectDefinition({ tenantId, agent, invocation }) {
   return {
     prompt: claudeParentDirectInstructions(tenantId, agent),
     permissionMode: "bypassPermissions",
-    tools: [NATIVE_AGENT_ANSWER_TOOL, NATIVE_AGENT_RESUME_TOOL].map((tool) => nativeToolName(tool)),
+    tools: [...CLAUDE_PARENT_DIRECT_TOOL_PERMISSIONS],
     mcpServers: [{
       [MANAGED_AGENT_MCP_SERVER]: {
         type: "stdio",
@@ -826,11 +945,35 @@ function claudeParentDirectDefinition({ tenantId, agent, invocation }) {
   };
 }
 
+function nativeAgentTelemetryEnvironment(environment = process.env) {
+  return Object.fromEntries(IMPEL_NATIVE_AGENT_TELEMETRY_ENV_NAMES.flatMap((name) => {
+    const value = environment?.[name];
+    return typeof value === "string" && value.length > 0 ? [[name, value]] : [];
+  }));
+}
+
+function telemetryEnvironmentMatches(recorded, expected) {
+  const normalizedRecorded = recorded === undefined ? {} : recorded;
+  return normalizedRecorded
+    && typeof normalizedRecorded === "object"
+    && !Array.isArray(normalizedRecorded)
+    && JSON.stringify(normalizedRecorded) === JSON.stringify(expected);
+}
+
 function codexInvocationEnvironment(invocation, { durableProfile = false } = {}) {
   const entries = Object.entries(invocation.env || {});
   const transient = new Set(IMPEL_NATIVE_AGENT_TELEMETRY_ENV_NAMES);
+  // Ordinary durable profiles must never retain a one-off telemetry path.
+  // The native Codex profiler is different: it generates a throwaway profile
+  // for the whole benchmark cohort and needs Codex's explicit MCP environment
+  // map to carry that cohort path into the server process. The isolated root is
+  // removed after the cohort, so benchmark-tagged telemetry cannot linger in
+  // an operator's managed profile.
+  const isolatedBenchmark = nativeBenchmarkHeaderValue(invocation.env || {}) !== null;
   return [
-    ...(durableProfile ? entries.filter(([key]) => !transient.has(key)) : entries),
+    ...(durableProfile && !isolatedBenchmark
+      ? entries.filter(([key]) => !transient.has(key))
+      : entries),
     [IMPEL_NATIVE_AGENT_ATTACHMENT_WINDOW_ENV, String(CODEX_NATIVE_AGENT_ATTACHMENT_WINDOW_MS)],
   ];
 }
@@ -914,6 +1057,7 @@ function boundNativeAgentInvocation(tenantId, agent, invocation, {
   policyFingerprint = nativeAgentPolicyFingerprint(agent),
   mode = usesDirectAnswer(agent) ? "answer" : "durable",
   answerToolAttribution = false,
+  environment = process.env,
 } = {}) {
   const bound = !invocation
     ? impelNativeAgentMcpInvocation({
@@ -922,7 +1066,7 @@ function boundNativeAgentInvocation(tenantId, agent, invocation, {
       scopeParam: agent.scopeParam,
       policyFingerprint,
       mode,
-    })
+    }, { environment })
     : (() => {
       const mcpIndex = invocation.args?.lastIndexOf("mcp") ?? -1;
       if (mcpIndex < 0) throw new Error("native-agent MCP invocation has no mcp command");
@@ -948,6 +1092,7 @@ function boundNativeAgentInvocation(tenantId, agent, invocation, {
 export function renderManagedAgents(client, tenantId, agents, invocation = null, {
   directCodeMode = true,
   nativeParentDirect = false,
+  environment = process.env,
 } = {}) {
   if (client !== "claude" && client !== "codex") throw new Error(`unknown agent client ${client}`);
   const normalizedTenant = normalizeTenantId(tenantId);
@@ -965,6 +1110,7 @@ export function renderManagedAgents(client, tenantId, agents, invocation = null,
     const parentDirect = client === "claude" && nativeParentDirect && usesDirectAnswer(agent);
     const boundInvocation = boundNativeAgentInvocation(normalizedTenant, agent, invocation, {
       answerToolAttribution: parentDirect,
+      environment,
     });
     const claudeRendered = client === "claude" && !parentDirect
       ? renderClaudeAgent({ tenantId: normalizedTenant, agent, name, invocation: boundInvocation })
@@ -1059,7 +1205,10 @@ export function renderManagedClaudeSlashCommands(tenantId, agents, invocation =
   });
 }
 
-function renderRetiredManagedAgents(client, tenantId, bindings, active, invocation = null, { directCodeMode = true } = {}) {
+function renderRetiredManagedAgents(client, tenantId, bindings, active, invocation = null, {
+  directCodeMode = true,
+  environment = process.env,
+} = {}) {
   const usedNames = new Set(active.map(({ name }) => name));
   const usedFiles = new Set(active.map(({ fileName }) => fileName));
   return bindings.map((binding) => {
@@ -1097,6 +1246,7 @@ function renderRetiredManagedAgents(client, tenantId, bindings, active, invocati
     const boundInvocation = boundNativeAgentInvocation(tenantId, agent, invocation, {
       policyFingerprint: binding.policyFingerprint,
       mode: "recovery",
+      environment,
     });
     const claudeRendered = client === "claude"
       ? renderClaudeAgent({ tenantId, agent, name, invocation: boundInvocation, recoveryOnly: true })
@@ -1233,7 +1383,11 @@ function validateClaudeLaunchDefinition(record, tenantId) {
     throw new Error("the managed Claude launch definition is invalid; run `impel agents sync claude`");
   }
   const server = definition.mcpServers[0][MANAGED_AGENT_MCP_SERVER];
-  const allowedEnvironment = new Set([IMPEL_MANAGED_MCP_ENV, ...IMPEL_NATIVE_AGENT_TELEMETRY_ENV_NAMES]);
+  const allowedEnvironment = new Set([
+    IMPEL_MANAGED_MCP_ENV,
+    ...IMPEL_NATIVE_AGENT_TELEMETRY_ENV_NAMES,
+    IMPEL_NATIVE_BENCHMARK_ENV,
+  ]);
   if (!exactObjectKeys(server, ["type", "command", "args", "env"])
     || server.type !== "stdio"
     || typeof server.command !== "string"
@@ -1274,8 +1428,7 @@ function validateClaudeLaunchDefinition(record, tenantId) {
 
 function validateClaudeParentLaunchDefinition(record, tenantId) {
   const definition = record.parentLaunchDefinition;
-  const expectedTools = [NATIVE_AGENT_ANSWER_TOOL, NATIVE_AGENT_RESUME_TOOL]
-    .map((name) => nativeToolName(name));
+  const expectedTools = CLAUDE_PARENT_DIRECT_TOOL_PERMISSIONS;
   if (!exactObjectKeys(definition, ["prompt", "permissionMode", "tools", "mcpServers"])
     || definition.prompt !== claudeParentDirectInstructions(tenantId, record)
     || definition.permissionMode !== "bypassPermissions"
@@ -1286,7 +1439,11 @@ function validateClaudeParentLaunchDefinition(record, tenantId) {
     throw new Error("the managed Claude parent-direct definition is invalid; run `impel agents sync claude`");
   }
   const server = definition.mcpServers[0][MANAGED_AGENT_MCP_SERVER];
-  const allowedEnvironment = new Set([IMPEL_MANAGED_MCP_ENV, ...IMPEL_NATIVE_AGENT_TELEMETRY_ENV_NAMES]);
+  const allowedEnvironment = new Set([
+    IMPEL_MANAGED_MCP_ENV,
+    ...IMPEL_NATIVE_AGENT_TELEMETRY_ENV_NAMES,
+    IMPEL_NATIVE_BENCHMARK_ENV,
+  ]);
   if (!exactObjectKeys(server, ["type", "command", "args", "env"])
     || server.type !== "stdio"
     || typeof server.command !== "string"
@@ -1519,24 +1676,39 @@ function profileIsFresh(profile, tenantId, now, ttlMs) {
   if (!Array.isArray(manifest.files) || !manifest.contentDigests
     || typeof manifest.contentDigests !== "object"
     || Array.isArray(manifest.contentDigests)) return false;
+  const profileEnvironment = profile.environment ?? process.env;
   const expectedDirectProfiles = profile.client === "codex" && profile.directProfiles !== false;
   const expectedDirectCodeMode = profile.client === "codex" && profile.directCodeMode !== false;
   const expectedNativeParentDirect = profile.client === "claude"
-    && (profile.nativeParentDirect ?? nativeParentDirectEnabled());
+    && (profile.nativeParentDirect ?? nativeParentDirectEnabled(profileEnvironment));
   const expectedNativeSlashCommands = profile.client === "claude"
-    && (profile.nativeSlashCommands ?? nativeSlashCommandsEnabled());
+    && (profile.nativeSlashCommands ?? nativeSlashCommandsEnabled(profileEnvironment));
   const expectedNativeIntercept = profile.client === "claude"
-    && (profile.nativeIntercept ?? nativeInterceptEnabled());
+    && (profile.nativeIntercept ?? nativeInterceptEnabled(profileEnvironment));
   const expectedNativeInterceptTimeoutMs = expectedNativeIntercept
-    ? (profile.nativeInterceptTimeoutMs ?? nativeInterceptTimeoutMs())
+    ? (profile.nativeInterceptTimeoutMs ?? nativeInterceptTimeoutMs(profileEnvironment))
     : null;
+  const expectedTelemetryEnvironment = nativeAgentTelemetryEnvironment(
+    profileEnvironment,
+  );
+  const expectedBenchmark = nativeBenchmarkHeaderValue(
+    profileEnvironment,
+  ) !== null;
   if (manifest.directProfiles !== expectedDirectProfiles
     || manifest.directCodeMode !== expectedDirectCodeMode
     || Boolean(manifest.nativeParentDirect) !== expectedNativeParentDirect
     || Boolean(manifest.nativeSlashCommands) !== expectedNativeSlashCommands
     || Boolean(manifest.nativeIntercept) !== expectedNativeIntercept
+    || !telemetryEnvironmentMatches(
+      manifest.nativeAgentTelemetryEnvironment,
+      expectedTelemetryEnvironment,
+    )
+    || Boolean(manifest.nativeBenchmark) !== expectedBenchmark
     || (expectedNativeIntercept
       && manifest.nativeInterceptTimeoutMs !== expectedNativeInterceptTimeoutMs)) return false;
+  if (expectedNativeParentDirect && !claudeParentDirectPermissionsCurrent(profile.root, manifest)) {
+    return false;
+  }
   const syncedAt = Date.parse(manifest.syncedAt || "");
   if (!Number.isFinite(syncedAt) || now - syncedAt >= ttlMs) return false;
   const artifacts = [
@@ -1565,10 +1737,14 @@ export function syncAgentProfile({
   agents,
   directProfiles = client === "codex",
   directCodeMode = client === "codex",
-  nativeParentDirect = client === "claude" && nativeParentDirectEnabled(),
-  nativeSlashCommands = client === "claude" && nativeSlashCommandsEnabled(),
-  nativeIntercept = client === "claude" && nativeInterceptEnabled(),
-  nativeInterceptTimeoutMs: interceptTimeoutMs = nativeIntercept ? nativeInterceptTimeoutMs() : null,
+  environment = process.env,
+  nativeParentDirect = client === "claude" && nativeParentDirectEnabled(environment),
+  nativeSlashCommands = client === "claude" && nativeSlashCommandsEnabled(environment),
+  nativeIntercept = client === "claude" && nativeInterceptEnabled(environment),
+  nativeInterceptTimeoutMs: interceptTimeoutMs = nativeIntercept
+    ? nativeInterceptTimeoutMs(environment)
+    : null,
+  invocation = null,
   now = Date.now(),
   nativeAgentRunsRoot = path.join(CONFIG_DIR, "native-agent-runs"),
 }) {
@@ -1588,9 +1764,10 @@ export function syncAgentProfile({
     && fs.lstatSync(commandsDir).isSymbolicLink()) {
     throw new Error(`refusing to use symlinked native-agent path ${commandsDir}`);
   }
-  const active = renderManagedAgents(client, tenantId, agents, null, {
+  const active = renderManagedAgents(client, tenantId, agents, invocation, {
     directCodeMode,
     nativeParentDirect,
+    environment,
   });
   const activeBindings = new Set(active.map((agent) =>
     `${agent.agentId}\0${agent.scopeParam}\0${agent.policyFingerprint}`
@@ -1599,7 +1776,10 @@ export function syncAgentProfile({
     .filter((binding) => !activeBindings.has(
       `${binding.agentId}\0${binding.scopeParam}\0${binding.policyFingerprint}`,
     ));
-  const retired = renderRetiredManagedAgents(client, tenantId, retiredBindings, active, null, { directCodeMode });
+  const retired = renderRetiredManagedAgents(client, tenantId, retiredBindings, active, invocation, {
+    directCodeMode,
+    environment,
+  });
   const rendered = [...active, ...retired];
   const commands = client === "claude" && nativeSlashCommands
     ? renderManagedClaudeSlashCommands(tenantId, agents)
@@ -1679,6 +1859,13 @@ export function syncAgentProfile({
       }
     }
   }
+  const parentDirectPermissions = client === "claude"
+    ? syncClaudeParentDirectPermissions(
+      root,
+      parentDirectPermissionTools(rendered),
+      priorParentDirectPermissionGrants(prior, priorOwnsManagedFiles),
+    )
+    : null;
   for (const agent of rendered) {
     if (agent.fileName) atomicPrivateWrite(path.join(agentsDir, agent.fileName), agent.contents);
     if (client === "codex" && directProfiles) atomicPrivateWrite(path.join(root, agent.profileFileName), agent.profileContents);
@@ -1755,6 +1942,8 @@ export function syncAgentProfile({
     `commands/${command.fileName}`,
     contentDigest(command.contents),
   ])).sort(([left], [right]) => left.localeCompare(right)));
+  const telemetryEnvironment = nativeAgentTelemetryEnvironment(environment);
+  const benchmark = nativeBenchmarkHeaderValue(environment);
   atomicPrivateWrite(manifestPath, `${JSON.stringify({
     version: MANAGED_AGENT_MANIFEST_VERSION,
     tenantId,
@@ -1762,11 +1951,18 @@ export function syncAgentProfile({
     directProfiles: client === "codex" && directProfiles,
     directCodeMode: client === "codex" && directCodeMode,
     ...(client === "claude" && nativeParentDirect ? { nativeParentDirect: true } : {}),
+    ...(client === "claude" && parentDirectPermissions.length > 0 ? {
+      nativeParentDirectPermissionGrants: parentDirectPermissions,
+    } : {}),
     ...(client === "claude" && nativeSlashCommands ? { nativeSlashCommands: true } : {}),
     ...(client === "claude" && nativeIntercept ? {
       nativeIntercept: true,
       nativeInterceptTimeoutMs: interceptTimeoutMs,
     } : {}),
+    ...(Object.keys(telemetryEnvironment).length > 0 ? {
+      nativeAgentTelemetryEnvironment: telemetryEnvironment,
+    } : {}),
+    ...(benchmark ? { nativeBenchmark: true } : {}),
     syncedAt: new Date(now).toISOString(),
     files: [...currentFiles].sort(),
     ...(client === "claude" && nativeSlashCommands ? { commands: [...currentCommands].sort() } : {}),

package/src/cli.js

@@ -38,6 +38,7 @@ Work:
   impel claude --agent <id|exact-title> ...   Run one fixed tenant agent without a parent hop
   impel codex [args...]                       Launch Codex with an isolated Impel profile
   impel codex --agent <id|exact-title> ...    Run one fixed tenant agent without a parent hop
+  impel codex --benchmark ...                 Tag native-agent MCP calls as benchmark traffic
   impel remote handoff|dispatch|handback      Move or control provider-native sessions remotely
   impel remote status|viewer|proxy            Inspect, control, or connect to a remote run
   impel tenant list                           List accessible organizations

package/src/commands/agents.js

@@ -38,6 +38,7 @@ export function managedAgentProfiles(client, options = {}) {
       environment,
       homeDir,
     }),
+    environment,
     ...(client === "codex" ? {
       directProfiles: profile.label !== "Codex CLI (native profile)",
       directCodeMode: profile.label !== "Codex CLI (native profile)",

package/src/commands/launch.js

@@ -24,9 +24,8 @@ import { parentVerbatimRelayAppendix } from "../verbatimRelay.js";
 import { withGitEnvironment } from "../skills.js";
 import { assertProviderScopes, ensureTenantSelection, tenantCredential } from "../tenants.js";
 import { maybePrintUpdateNotice } from "../updates.js";
-import {
-  nativeSpawnInvocation,
-} from "../nativeProcess.js";
+import { nativeSpawnInvocation } from "../nativeProcess.js";
+import { IMPEL_NATIVE_BENCHMARK_ENV } from "../selfInvocation.js";
 import { resolveReviewedVendorCliBinary } from "../vendorCliBinaries.js";
 import { PINNED_VENDOR_CLI_VERSIONS } from "../vendorCliVersions.js";
 import { RUNTIME_BRAND } from "../runtimeBrand.js";
@@ -305,6 +304,7 @@ function codexAgentLockedOption(argument) {
 export function parseCodexAgentLaunchArguments(argv) {
   const passthrough = [];
   let selector = null;
+  let benchmark = false;
   let literal = false;
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
@@ -317,6 +317,14 @@ export function parseCodexAgentLaunchArguments(argv) {
       passthrough.push(argument);
       continue;
     }
+    if (argument === "--benchmark") {
+      if (benchmark) throw new Error("`--benchmark` may be specified only once");
+      benchmark = true;
+      continue;
+    }
+    if (argument.startsWith("--benchmark=")) {
+      throw new Error("`--benchmark` does not accept a value");
+    }
     if (argument === "--agent" || argument.startsWith("--agent=")) {
       if (selector !== null) throw new Error("`--agent` may be specified only once");
       const value = argument === "--agent" ? argv[index += 1] : argument.slice("--agent=".length);
@@ -339,7 +347,7 @@ export function parseCodexAgentLaunchArguments(argv) {
       }
     }
   }
-  return { selector, argv: passthrough };
+  return { selector, benchmark, argv: passthrough };
 }
 
 function codexJsonOutput(argv) {
@@ -436,11 +444,16 @@ export async function cmdLaunch(tool, argv) {
   let nativeArgv = [...argv];
   let claudeAgentSelector = null;
   let codexAgentSelector = null;
+  let codexBenchmark = false;
   if (tool === "claude" && RUNTIME_BRAND.features.agents) {
     ({ selector: claudeAgentSelector, argv: nativeArgv } = parseClaudeAgentLaunchArguments(argv));
   } else if (tool === "codex") {
     try {
-      ({ selector: codexAgentSelector, argv: nativeArgv } = parseCodexAgentLaunchArguments(argv));
+      ({
+        selector: codexAgentSelector,
+        benchmark: codexBenchmark,
+        argv: nativeArgv,
+      } = parseCodexAgentLaunchArguments(argv));
     } catch (error) {
       console.error(`impel codex: ${error.message}`);
       process.exitCode = 1;
@@ -489,12 +502,18 @@ export async function cmdLaunch(tool, argv) {
     }
   }
   const environment = { ...process.env };
+  if (codexBenchmark) environment[IMPEL_NATIVE_BENCHMARK_ENV] = "1";
   environment.IMPEL_TENANT_ID = tenantId;
   let agentProfile;
 
   if (tool === "claude") {
     const profile = ensureImpelClaudeProfile(gatewayUrl, tenantId, { crossAppModels });
-    agentProfile = { client: "claude", root: profile.configDir, label: "Impel isolated Claude (impel claude)" };
+    agentProfile = {
+      client: "claude",
+      root: profile.configDir,
+      label: "Impel isolated Claude (impel claude)",
+      environment,
+    };
     deleteEnvironmentKeys(environment, CLAUDE_DIRECT_AUTH_ENV);
     delete environment.CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY;
     environment.CLAUDE_CONFIG_DIR = profile.configDir;
@@ -508,7 +527,12 @@ export async function cmdLaunch(tool, argv) {
     environment.ANTHROPIC_AUTH_TOKEN = gatewayCredential;
   } else if (tool === "codex") {
     const profile = ensureImpelCodexProfile(gatewayUrl, tenantId);
-    agentProfile = { client: "codex", root: profile.codexHome, label: "Impel isolated Codex (impel codex)" };
+    agentProfile = {
+      client: "codex",
+      root: profile.codexHome,
+      label: "Impel isolated Codex (impel codex)",
+      environment,
+    };
     deleteEnvironmentKeys(environment, CODEX_DIRECT_AUTH_ENV);
     environment.CODEX_HOME = profile.codexHome;
     environment[CODEX_GATEWAY_TOKEN_ENV] = gatewayCredential;

package/src/managedProfileVersion.js

@@ -1,4 +1,4 @@
 // Fleet generation shared by managed-profile writers and upstream clients.
 // Keep this isolated from apps.js so latency-sensitive transports do not load
 // desktop bundle machinery just to identify their managed config contract.
-export const CURRENT_CONFIG_VERSION = 35;
+export const CURRENT_CONFIG_VERSION = 36;

package/src/nativeAgentTransport.js

@@ -25,6 +25,7 @@ import {
 import { extractAnswerFinalText } from "./directAnswer.js";
 import {
   IMPEL_NATIVE_AGENT_ATTACHMENT_WINDOW_ENV,
+  nativeBenchmarkHeaderValue,
 } from "./selfInvocation.js";
 import { normalizeTenantId } from "./tenants.js";
 import { renameWithWindowsRetry } from "./windowsFs.js";
@@ -40,6 +41,7 @@ export {
 export const NATIVE_AGENT_HANDLE_SCHEMA = "impel.native-agent-run.v1";
 export const NATIVE_AGENT_RESULT_SCHEMA = "impel.native-agent-result.v1";
 export const NATIVE_AGENT_RECOVERY_SCHEMA = "impel.native-agent-recovery.v1";
+export const NATIVE_AGENT_BENCHMARK_HEADER = "X-Impel-Client-Benchmark";
 export const NATIVE_AGENT_CLIENT_BUILD = `cli/${JSON.parse(
   fs.readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"),
 ).version}+manifest.v${CURRENT_CONFIG_VERSION}`;
@@ -52,8 +54,8 @@ const SAFE_FINGERPRINT_RE = /^[a-f0-9]{64}$/u;
 const SAFE_INVOCATION_RE = /^[a-f0-9-]{36}$/u;
 const DEFAULT_WAIT_SECONDS = 20;
 const MAX_WAIT_SECONDS = 35;
-const DEFAULT_ATTACHMENT_WINDOW_MS = 40_000;
-const DEFAULT_UPSTREAM_TIMEOUT_MS = 42_000;
+export const DEFAULT_ATTACHMENT_WINDOW_MS = 40_000;
+export const DEFAULT_UPSTREAM_TIMEOUT_MS = 42_000;
 const DEFAULT_ANSWER_HEDGE_MS = 38_000;
 const DEFAULT_MAX_POLLS = 8;
 const DEFAULT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
@@ -742,6 +744,7 @@ export class NativeAgentUpstreamSession {
     answerHedgeMs = nativeAgentAnswerHedgeMs(),
     setTimeoutImpl = setTimeout,
     clearTimeoutImpl = clearTimeout,
+    environment = process.env,
   }) {
     this.endpoint = `${normalizeGatewayUrl(gatewayUrl)}/mcp`;
     this.credential = credential;
@@ -755,6 +758,7 @@ export class NativeAgentUpstreamSession {
     this.answerHedgeMs = Math.max(0, answerHedgeMs);
     this.setTimeoutImpl = setTimeoutImpl;
     this.clearTimeoutImpl = clearTimeoutImpl;
+    this.benchmarkHeaderValue = nativeBenchmarkHeaderValue(environment);
     this.sessionId = null;
     this.nextId = 1;
   }
@@ -785,6 +789,9 @@ export class NativeAgentUpstreamSession {
           Accept: "application/json, text/event-stream",
           "X-Impel-Client-Request-Id": correlationId,
           "X-Impel-Client-Build": NATIVE_AGENT_CLIENT_BUILD,
+          ...(this.benchmarkHeaderValue
+            ? { [NATIVE_AGENT_BENCHMARK_HEADER]: this.benchmarkHeaderValue }
+            : {}),
           ...(this.sessionId ? { "Mcp-Session-Id": this.sessionId } : {}),
         },
         body: JSON.stringify(message),

package/src/selfInvocation.js

@@ -82,9 +82,23 @@ export const IMPEL_NATIVE_AGENT_TELEMETRY_ENV_NAMES = [
   "IMPEL_NATIVE_HOST",
   "IMPEL_NATIVE_HOST_BUILD",
 ];
+export const IMPEL_NATIVE_BENCHMARK_ENV = "IMPEL_NATIVE_BENCHMARK";
 export const IMPEL_NATIVE_AGENT_ATTACHMENT_WINDOW_ENV = "IMPEL_NATIVE_AGENT_ATTACHMENT_WINDOW_MS";
 export const CODEX_NATIVE_AGENT_ATTACHMENT_WINDOW_MS = 100_000;
 
+const SAFE_NATIVE_BENCHMARK_HEADER_VALUE = /^[\x21-\x7e]{1,128}$/u;
+
+export function nativeBenchmarkHeaderValue(environment = process.env) {
+  const value = environment?.[IMPEL_NATIVE_BENCHMARK_ENV];
+  if (value === undefined) return null;
+  if (typeof value !== "string"
+    || value !== "1"
+    || !SAFE_NATIVE_BENCHMARK_HEADER_VALUE.test(value)) {
+    throw new Error(`${IMPEL_NATIVE_BENCHMARK_ENV} must be exactly 1 using visible ASCII`);
+  }
+  return value;
+}
+
 function managedMcpEnvironment(environment = process.env) {
   const telemetry = Object.fromEntries(
     IMPEL_NATIVE_AGENT_TELEMETRY_ENV_NAMES.flatMap((name) => {
@@ -92,7 +106,12 @@ function managedMcpEnvironment(environment = process.env) {
       return typeof value === "string" && value.length > 0 ? [[name, value]] : [];
     }),
   );
-  return { [IMPEL_MANAGED_MCP_ENV]: "1", ...telemetry };
+  const benchmark = nativeBenchmarkHeaderValue(environment);
+  return {
+    [IMPEL_MANAGED_MCP_ENV]: "1",
+    ...telemetry,
+    ...(benchmark ? { [IMPEL_NATIVE_BENCHMARK_ENV]: benchmark } : {}),
+  };
 }
 
 export function impelMcpInvocation(args = [], options = {}) {