impel-cli 0.20.4 → 0.20.6

package/RELEASE_NOTES.md

@@ -1,5 +1,23 @@
 # Release notes
 
+## 0.20.6 — Native-agent canary controls
+
+- Gives Codex verbatim-relay parents one explicit 60-second blocking wait so
+  direct-answer children do not trigger short-poll model turns.
+- Forwards only the three opt-in, closed-schema native telemetry settings into
+  managed MCP processes; unrelated environment values remain excluded.
+
+## 0.20.5 — Faster managed native agents
+
+- Exposes exact bound tools eagerly on qualified Claude hosts while preserving
+  a measured durable fallback for Codex/ChatGPT code-mode hosts.
+- Reuses one upstream MCP session, validates one exact binding, and removes
+  duplicate model-catalog/auth-helper launch work.
+- Adds terminal-only 35-second reads, direct-answer continuation, durable
+  ambiguous-start recovery, and opt-in privacy-safe timing telemetry.
+- Adds independent rollback flags for eager exposure and terminal-only reads;
+  rollback never deletes active handles or runs.
+
 ## Native remote migration
 
 The former `impel remote handoff` implementation started a one-shot headless

package/docs/native-agent-host-capability-matrix.md

@@ -0,0 +1,38 @@
+# Native-agent host capability matrix
+
+Validated on 2026-08-07 with isolated temporary homes and tenant profiles. The
+matrix is intentionally pinned: a client upgrade must be re-qualified before it
+is treated as an eager host.
+
+| Surface | Pinned build | Exact selected tools | Selected path | Host behavior |
+| --- | --- | --- | --- | --- |
+| Claude Code | 2.1.212 | Yes, agent frontmatter `tools` | Eager | The bound run/answer, resume, and recovery tools are direct child tools. No catalog discovery or code-cell polling is required. |
+| Claude Desktop | 1.24012.9 (embedded Code 2.1.219) | Yes, agent frontmatter `tools` | Eager | Same direct-tool contract as Claude Code. |
+| Codex CLI | 0.146.0 | No; MCP tools remain code-mode-only | Durable fallback | `enabled_tools` narrows the server contract but the host still invokes through code mode. Discovery/polling overhead is measured separately and is not classified as eager completion. |
+| ChatGPT desktop Codex | 26.727.40816 (embedded Codex alpha) | No; MCP tools remain code-mode-only | Durable fallback | Uses the same bounded durable composite and recovery state as Codex CLI. |
+
+## Qualified contract
+
+- Eager profiles expose only the exact fixed binding's answer/run, resume, and
+  recovery tools. `IMPEL_NATIVE_EAGER_TRANSPORT=0` independently restores the
+  legacy host-visible tool configuration without deleting profiles or runs.
+- Every local composite keeps one upstream MCP session for its process lifetime,
+  validates the exact binding once, and persists the authoritative run handle
+  before ambiguous retries.
+- Forwarded waits are negotiated at no more than 35 seconds under the gateway's
+  45-second tool deadline. A local attachment returns a typed handle before the
+  outer host deadline and resume never opens a replacement run.
+- Parent guidance permits one spawn and one blocking wait. It forbids follow-up
+  nudges and independent synthesis while the child is running.
+- Host and transport traces must never include prompts, answers, credentials, or
+  decrypted provider material. Production measurements use correlation ids,
+  phase timestamps, counts, durations, build identifiers, and terminal classes
+  only.
+
+## Requalification
+
+Re-run temporary-home profile parsing, direct tool visibility, cancellation,
+typed continuation, byte-exact relay, and the 10/30/45/60/120-second bounded
+wait fixture after a pinned client changes. A build stays on durable fallback
+unless the child trace has zero `ALL_TOOLS`, `functions.exec`, and
+`functions.wait` entries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.20.4",
+  "version": "0.20.6",
   "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
     "RELEASE_NOTES.md",
     "bin",
     "docs/experimental-managed-cursor.md",
+    "docs/native-agent-host-capability-matrix.md",
     "src",
     "README.md"
   ],

package/src/agents.js

@@ -42,6 +42,7 @@ export const AGENT_SYNC_TTL_MS = 6 * 60 * 60 * 1000;
 export const MANAGED_AGENT_DIRECTORY = "impel-managed";
 export const MANAGED_AGENT_MANIFEST = ".manifest.json";
 export const NATIVE_AGENT_LIST_TOOL = "impel_specialists-list_native_agents";
+export const NATIVE_AGENT_GET_TOOL = "impel_specialists-get_native_agent";
 export const NATIVE_AGENT_START_TOOL = "impel_specialists-start_native_agent_run";
 export const NATIVE_AGENT_READ_TOOL = "impel_specialists-read_native_agent_run";
 export const NATIVE_AGENT_UPSTREAM_ANSWER_TOOL = "impel_specialists-answer_native_agent";
@@ -50,7 +51,7 @@ export const NATIVE_AGENT_RUN_TOOL = "run_native_agent";
 export const NATIVE_AGENT_RESUME_TOOL = "resume_native_agent_run";
 export const NATIVE_AGENT_RECOVER_TOOL = "recover_native_agent_runs";
 export const MANAGED_AGENT_MCP_SERVER = "impel_agent";
-export const MANAGED_AGENT_MANIFEST_VERSION = 7;
+export const MANAGED_AGENT_MANIFEST_VERSION = 8;
 
 const NATIVE_AGENT_TOOL_NAMES = [
   NATIVE_AGENT_RUN_TOOL,
@@ -59,7 +60,12 @@ const NATIVE_AGENT_TOOL_NAMES = [
 ];
 const NATIVE_AGENT_RECOVERY_TOOL_NAMES = [NATIVE_AGENT_RESUME_TOOL, NATIVE_AGENT_RECOVER_TOOL];
 function nativeAgentToolNames(agent) {
-  return usesDirectAnswer(agent) ? [NATIVE_AGENT_ANSWER_TOOL] : NATIVE_AGENT_TOOL_NAMES;
+  return usesDirectAnswer(agent)
+    ? [NATIVE_AGENT_ANSWER_TOOL, ...NATIVE_AGENT_RECOVERY_TOOL_NAMES]
+    : NATIVE_AGENT_TOOL_NAMES;
+}
+function eagerNativeAgentTransportEnabled() {
+  return process.env.IMPEL_NATIVE_EAGER_TRANSPORT !== "0";
 }
 const MAX_RETIRED_AGENT_BINDINGS = 50;
 const MAX_NATIVE_AGENT_STATE_BYTES = 512 * 1024;
@@ -602,6 +608,7 @@ function claudeAdapterInstructions(tenantId, agent) {
       `Confirm that the request fits the synchronized capabilities ${JSON.stringify(agent.capabilities)} and none of the exclusions ${JSON.stringify(agent.exclusions)}.${contextRequirement}`,
       sideEffectInstruction,
       `Call ${nativeToolName(NATIVE_AGENT_ANSWER_TOOL)} exactly once with question set to the complete assigned task, optional context set to one string containing all supplied context, and contextKeys naming the fields present in that string.`,
+      `If the bounded answer returns an ${JSON.stringify("impel.native-agent-run.v1")} continuation handle, call ${nativeToolName(NATIVE_AGENT_RESUME_TOOL)} with exactly that handle until terminal. Never call answer_native_agent again for this request.`,
       completionGuidance,
     ].join(" ");
   }
@@ -645,6 +652,7 @@ function codexAdapterInstructions(tenantId, agent) {
       `Confirm that the assigned request fits the cataloged capabilities ${JSON.stringify(agent.capabilities)} and none of the exclusions ${JSON.stringify(agent.exclusions)} before answering.${contextRequirement}`,
       sideEffectInstruction,
       `Call ${nativeToolName(NATIVE_AGENT_ANSWER_TOOL)} exactly once with question set to the complete assigned task, optional context set to one string containing all supplied context, and contextKeys naming the fields present in that string.`,
+      `If the bounded answer returns an ${JSON.stringify("impel.native-agent-run.v1")} continuation handle, call ${nativeToolName(NATIVE_AGENT_RESUME_TOOL)} with exactly that handle until terminal. Never call answer_native_agent again for this request.`,
       completionGuidance,
     ].join("\n\n");
   }
@@ -687,13 +695,15 @@ function renderClaudeAgent({ tenantId, agent, name, invocation, recoveryOnly = f
     ? `Recovery-only access to pending runs for retired Impel binding ${agent.agentId} in tenant ${tenantId}.`
     : customAgentDescription(tenantId, agent);
   const toolNames = recoveryOnly ? NATIVE_AGENT_RECOVERY_TOOL_NAMES : nativeAgentToolNames(agent);
+  const eager = eagerNativeAgentTransportEnabled();
   const lines = [
     "---",
     `name: ${JSON.stringify(name)}`,
     `description: ${JSON.stringify(description)}`,
-    "model: inherit",
-    "tools:",
-    ...toolNames.map((tool) => `  - ${JSON.stringify(nativeToolName(tool))}`),
+    "model: haiku",
+    ...(eager
+      ? ["tools:", ...toolNames.map((tool) => `  - ${JSON.stringify(nativeToolName(tool))}`)]
+      : []),
     "mcpServers:",
     `  - ${MANAGED_AGENT_MCP_SERVER}:`,
     "      type: stdio",
@@ -715,19 +725,24 @@ function renderCodexAgent({ tenantId, agent, name, invocation, recoveryOnly = fa
     ? `Recovery-only custom agent for pending runs from retired Impel binding ${agent.agentId} in tenant ${tenantId}.`
     : customAgentDescription(tenantId, agent);
   const toolNames = recoveryOnly ? NATIVE_AGENT_RECOVERY_TOOL_NAMES : nativeAgentToolNames(agent);
+  const eager = eagerNativeAgentTransportEnabled();
   const envEntries = Object.entries(invocation.env || {})
     .map(([key, value]) => `${JSON.stringify(key)} = ${JSON.stringify(value)}`)
     .join(", ");
   const lines = [
     `name = ${JSON.stringify(name)}`,
     `description = ${JSON.stringify(description)}`,
+    'model = "gpt-5.6-luna"',
+    'model_reasoning_effort = "low"',
     'sandbox_mode = "read-only"',
     `developer_instructions = ${JSON.stringify(recoveryOnly ? retiredAdapterInstructions(tenantId, agent) : codexAdapterInstructions(tenantId, agent))}`,
     "",
     `[mcp_servers.${MANAGED_AGENT_MCP_SERVER}]`,
     `command = ${JSON.stringify(invocation.command)}`,
     `args = [${invocation.args.map((argument) => JSON.stringify(argument)).join(", ")}]`,
-    `enabled_tools = [${toolNames.map((tool) => JSON.stringify(tool)).join(", ")}]`,
+    ...(eager
+      ? [`enabled_tools = [${toolNames.map((tool) => JSON.stringify(tool)).join(", ")}]`]
+      : []),
     ...(envEntries ? [`env = { ${envEntries} }`] : []),
     "",
   ];

package/src/cliProfiles.js

@@ -21,8 +21,12 @@ import { applyImpelClaudeSandbox } from "./claudeSandbox.js";
 import { renameWithWindowsRetry } from "./windowsFs.js";
 import { ensureClaudeSessionHooks, ensureCodexSessionHooks } from "./sessionHooks.js";
 import { RUNTIME_BRAND } from "./runtimeBrand.js";
+import { managedCodexCliCatalog } from "./codexCliCatalog.js";
 
 export const IMPEL_CLI_PROFILES_DIR = path.join(CONFIG_DIR, "cli");
+export const CODEX_GATEWAY_TOKEN_ENV = `${RUNTIME_BRAND.cli.providerId
+  .toUpperCase()
+  .replace(/[^A-Z0-9]+/gu, "_")}_CODEX_GATEWAY_TOKEN`;
 
 export function tenantCliProfilePaths(tenantId) {
   const root = path.join(IMPEL_CLI_PROFILES_DIR, "tenants", normalizeTenantId(tenantId));
@@ -30,6 +34,7 @@ export function tenantCliProfilePaths(tenantId) {
     root,
     claudeConfigDir: path.join(root, "claude"),
     codexHome: path.join(root, "codex"),
+    codexCatalog: path.join(root, "codex", "models.json"),
   };
 }
 
@@ -191,7 +196,6 @@ function splitTomlPreamble(text) {
 }
 
 function codexManagedBlock(gatewayUrl, tenantId) {
-  const auth = impelCliInvocation(["token", "--tenant", tenantId]);
   const providerId = RUNTIME_BRAND.cli.providerId;
   const lines = [
     CODEX_START_MARK,
@@ -200,12 +204,7 @@ function codexManagedBlock(gatewayUrl, tenantId) {
     `name = ${JSON.stringify(`${RUNTIME_BRAND.product.displayName} Gateway`)}`,
     `base_url = ${JSON.stringify(impelCodexBaseUrl(gatewayUrl))}`,
     'wire_api = "responses"',
-    "",
-    `[model_providers.${providerId}.auth]`,
-    `command = ${JSON.stringify(auth.command)}`,
-    `args = [${auth.args.map((argument) => JSON.stringify(argument)).join(", ")}]`,
-    "timeout_ms = 5000",
-    "refresh_interval_ms = 300000",
+    `env_key = ${JSON.stringify(CODEX_GATEWAY_TOKEN_ENV)}`,
   ];
   if (RUNTIME_BRAND.features.mcp) {
     const mcp = impelCliInvocation(["mcp", "--tenant", tenantId]);
@@ -231,7 +230,7 @@ function codexManagedBlock(gatewayUrl, tenantId) {
 
 export function ensureImpelCodexProfile(gatewayUrl, tenantId) {
   secureAllManagedCodexHomes({ cliRoot: IMPEL_CLI_PROFILES_DIR });
-  const codexHome = tenantCliProfilePaths(tenantId).codexHome;
+  const { codexHome, codexCatalog } = tenantCliProfilePaths(tenantId);
   secureManagedCodexHome(codexHome);
   const configPath = path.join(codexHome, "config.toml");
   const original = fs.existsSync(configPath) ? fs.readFileSync(configPath, "utf8") : "";
@@ -259,6 +258,10 @@ export function ensureImpelCodexProfile(gatewayUrl, tenantId) {
   let nextPreamble = CODEX_PROVIDER_LINE_RE.test(preamble)
     ? preamble.replace(CODEX_PROVIDER_LINE_RE, providerLine)
     : `${preamble.trimEnd()}${preamble.trim() ? "\n" : ""}${providerLine}\n`;
+  const catalogLine = `model_catalog_json = ${JSON.stringify(codexCatalog)}`;
+  nextPreamble = /^model_catalog_json[ \t]*=/mu.test(nextPreamble)
+    ? nextPreamble.replace(/^model_catalog_json[ \t]*=.*$/mu, catalogLine)
+    : `${nextPreamble.trimEnd()}\n${catalogLine}\n`;
   nextPreamble = nextPreamble.replace(/^bypass_hook_trust[ \t]*=[ \t]*(?:true|false)[ \t]*\n?/gm, "");
   const restText = rest.trim();
   const next = [nextPreamble.trimEnd(), codexManagedBlock(gatewayUrl, tenantId), restText]
@@ -267,7 +270,8 @@ export function ensureImpelCodexProfile(gatewayUrl, tenantId) {
     .concat("\n");
 
   writePrivateFile(configPath, hardenManagedCodexToml(next, configPath));
+  writePrivateFile(codexCatalog, `${JSON.stringify(managedCodexCliCatalog(), null, 2)}\n`);
   if (RUNTIME_BRAND.features.sessions) ensureCodexSessionHooks(codexHome, tenantId, "codex_cli");
   secureManagedCodexHome(codexHome);
-  return { codexHome, configPath };
+  return { codexHome, configPath, catalogPath: codexCatalog };
 }

package/src/codexCliCatalog.js

@@ -0,0 +1,56 @@
+const LEVELS = ["low", "medium", "high", "xhigh"].map((effort) => ({
+  effort,
+  description: `${effort} reasoning effort`,
+}));
+
+const MODELS = [
+  ["gpt-5.6-sol", "GPT-5.6-Sol", 1, "medium", "code_mode_only", "v2"],
+  ["gpt-5.6-terra", "GPT-5.6-Terra", 2, "medium", "code_mode_only", "v2"],
+  ["gpt-5.6-luna", "GPT-5.6-Luna", 3, "medium", "code_mode_only", "v1"],
+  ["gpt-5.5", "GPT-5.5", 7, "medium", null, null],
+  ["gpt-5.4", "GPT-5.4", 16, "medium", null, null],
+  ["gpt-5.4-mini", "GPT-5.4-Mini", 23, "medium", null, null],
+  ["gpt-5.3-codex-spark", "GPT-5.3-Codex-Spark", 26, "high", null, null],
+];
+
+// Reviewed static projection of the exact pinned Codex 0.146 catalog. Keeping
+// it process-local prevents the client from issuing unsupported online model
+// refreshes during every managed launch.
+export function managedCodexCliCatalog(now = new Date()) {
+  return {
+    fetched_at: now.toISOString(),
+    client_version: "impel-managed-codex-0.146",
+    models: MODELS.map(([slug, displayName, priority, effort, toolMode, multiAgentVersion]) => ({
+      slug,
+      display_name: displayName,
+      description: `Available through the Impel gateway (${slug}).`,
+      default_reasoning_level: effort,
+      supported_reasoning_levels: LEVELS,
+      service_tiers: [],
+      shell_type: "shell_command",
+      visibility: "list",
+      supported_in_api: true,
+      priority,
+      base_instructions: "You are Codex, an AI coding agent. Follow repository instructions and verify your work.",
+      include_skills_usage_instructions: false,
+      supports_reasoning_summaries: true,
+      default_reasoning_summary: "none",
+      support_verbosity: true,
+      default_verbosity: "low",
+      apply_patch_tool_type: "freeform",
+      web_search_tool_type: "text_and_image",
+      truncation_policy: { mode: "tokens", limit: 10_000 },
+      context_window: slug === "gpt-5.3-codex-spark" ? 128_000 : 272_000,
+      max_context_window: slug === "gpt-5.4" ? 1_000_000 : (slug === "gpt-5.3-codex-spark" ? 128_000 : 272_000),
+      effective_context_window_percent: 95,
+      experimental_supported_tools: [],
+      input_modalities: ["text", "image"],
+      supports_parallel_tool_calls: true,
+      supports_image_detail_original: true,
+      supports_search_tool: true,
+      use_responses_lite: slug.startsWith("gpt-5.6-"),
+      tool_mode: toolMode,
+      multi_agent_version: multiAgentVersion,
+    })),
+  };
+}

package/src/commands/launch.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import os from "node:os";
 
 import {
+  CODEX_GATEWAY_TOKEN_ENV,
   ensureImpelClaudeProfile,
   ensureImpelCodexProfile,
 } from "../cliProfiles.js";
@@ -40,7 +41,13 @@ const CLAUDE_DIRECT_AUTH_ENV = [
   "CLAUDE_CODE_USE_VERTEX",
 ];
 
-const CODEX_DIRECT_AUTH_ENV = ["CODEX_ACCESS_TOKEN", "CODEX_API_KEY", "OPENAI_API_KEY", "OPENAI_BASE_URL"];
+const CODEX_DIRECT_AUTH_ENV = [
+  "CODEX_ACCESS_TOKEN",
+  "CODEX_API_KEY",
+  "OPENAI_API_KEY",
+  "OPENAI_BASE_URL",
+  CODEX_GATEWAY_TOKEN_ENV,
+];
 export {
   escapeWindowsBareArgument,
   escapeWindowsBatchArgument,
@@ -231,6 +238,7 @@ export async function cmdLaunch(tool, argv) {
     agentProfile = { client: "codex", root: profile.codexHome, label: "Impel isolated Codex (impel codex)" };
     deleteEnvironmentKeys(environment, CODEX_DIRECT_AUTH_ENV);
     environment.CODEX_HOME = profile.codexHome;
+    environment[CODEX_GATEWAY_TOKEN_ENV] = gatewayCredential;
   } else {
     throw new Error(`unsupported CLI launcher: ${tool}`);
   }

package/src/commands/mcp.js

@@ -1,3 +1,4 @@
+import crypto from "node:crypto";
 import readline from "node:readline";
 
 import {
@@ -18,6 +19,7 @@ import {
   nativeAgentToolCallResult,
 } from "../nativeAgentTransport.js";
 import { IMPEL_NATIVE_AGENT_MCP_TARGET } from "../selfInvocation.js";
+import { createNativeAgentTelemetry } from "../nativeAgentTelemetry.js";
 import { ensureTenantSelection, normalizeTenantId, tenantCredential } from "../tenants.js";
 
 const TASKS_TARGET = "tasks";
@@ -195,6 +197,7 @@ export function runNativeAgentMcpServer({
   input = process.stdin,
   output = process.stdout,
   mode = "durable",
+  telemetry = () => {},
 }) {
   if (!["durable", "recovery", "answer"].includes(mode)) throw new Error("invalid native-agent MCP mode");
   const lines = readline.createInterface({ input, crlfDelay: Infinity });
@@ -219,6 +222,9 @@ export function runNativeAgentMcpServer({
     const controller = new AbortController();
     active.set(message.id, controller);
     const task = (async () => {
+      const correlationId = crypto.randomUUID();
+      const startedAt = Date.now();
+      let telemetryTool;
       try {
         if (message.method === "initialize") {
           write(nativeRpcResult(message.id, {
@@ -242,7 +248,9 @@ export function runNativeAgentMcpServer({
           throw new Error("unsupported native-agent MCP method");
         }
         const name = message.params?.name;
+        telemetryTool = name;
         const args = message.params?.arguments ?? {};
+        telemetry("local_tool_received", { correlationId, tool: name });
         const progressToken = nativeProgressToken(message);
         const onProgress = progressToken === null ? undefined : ({ status }) => {
           progress += 1;
@@ -261,17 +269,32 @@ export function runNativeAgentMcpServer({
           if (mode === "answer") throw new Error("direct-answer native-agent bindings cannot start durable runs");
           value = await transport.run(args, { signal: controller.signal, onProgress });
         } else if (name === NATIVE_AGENT_RESUME_TOOL) {
-          if (mode === "answer") throw new Error("direct-answer native-agent bindings have no runs to resume");
           value = await transport.resume(args, { signal: controller.signal, onProgress });
         } else if (name === NATIVE_AGENT_RECOVER_TOOL) {
-          if (mode === "answer") throw new Error("direct-answer native-agent bindings have no runs to recover");
           value = transport.recover(args);
         } else {
           throw new Error("unsupported native-agent MCP tool");
         }
+        const continued = value?.schema === "impel.native-agent-run.v1";
+        telemetry("local_tool_completed", {
+          correlationId,
+          tool: name,
+          outcome: continued ? "continued" : "succeeded",
+          status: typeof value?.status === "string" ? value.status : undefined,
+          durationMs: Date.now() - startedAt,
+          durableRunCreated: Boolean(value?.runId || value?.handle?.runId),
+        });
         write(nativeRpcResult(message.id, nativeAgentToolCallResult(value)));
       } catch (error) {
         const cancelled = error?.name === "AbortError";
+        if (message.method === "tools/call") {
+          telemetry("local_tool_completed", {
+            correlationId,
+            tool: telemetryTool,
+            outcome: cancelled ? "cancelled" : "failed",
+            durationMs: Date.now() - startedAt,
+          });
+        }
         write(JSON.stringify({
           jsonrpc: "2.0",
           id: message.id,
@@ -369,6 +392,15 @@ export async function cmdMcp(argv = []) {
   const gatewayUrl = config.gatewayUrl || resolveDefaultGateway();
   const credential = tasksTarget ? null : tenantCredential(config.pat, tenantId);
   if (nativeAgentTarget) {
+    const telemetry = createNativeAgentTelemetry({
+      tenantId,
+      agentId: flags["agent-id"],
+      scopeParam: flags["scope-param"],
+      mode: flags["recovery-only"] === true
+        ? "recovery"
+        : (flags["answer-only"] === true ? "answer" : "durable"),
+    });
+    telemetry("local_server_started");
     return runNativeAgentMcpServer({
       transport: new NativeAgentCompositeTransport({
         tenantId,
@@ -377,10 +409,12 @@ export async function cmdMcp(argv = []) {
         policyFingerprint: flags["policy-fingerprint"],
         gatewayUrl,
         credential,
+        telemetry,
       }),
       mode: flags["recovery-only"] === true
         ? "recovery"
         : (flags["answer-only"] === true ? "answer" : "durable"),
+      telemetry,
     });
   }
   const endpoint = tasksTarget ? null : `${gatewayUrl}/mcp`;

package/src/nativeAgentTelemetry.js

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { redactCredentialText, redactSecretText } from "./config.js";
+
+export const NATIVE_AGENT_TRANSPORT_VERSION = 2;
+
+const SAFE_ID = /^[A-Za-z0-9_.:@/-]{1,200}$/u;
+const SAFE_EVENTS = new Set([
+  "local_server_started",
+  "local_tool_received",
+  "local_tool_completed",
+  "session_prepared",
+  "upstream_request_completed",
+  "binding_completed",
+]);
+const SAFE_TOOLS = new Set([
+  "initialize",
+  "notifications/initialized",
+  "tools/list",
+  "get_native_agent",
+  "answer_native_agent",
+  "start_native_agent_run",
+  "read_native_agent_run",
+  "run_native_agent",
+  "resume_native_agent_run",
+  "recover_native_agent_runs",
+]);
+const SAFE_OUTCOMES = new Set(["succeeded", "continued", "failed", "cancelled", "ok", "error"]);
+
+function safeId(value) {
+  return typeof value === "string" && SAFE_ID.test(value) ? value : undefined;
+}
+
+function safeInteger(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+function appendPrivateJsonLine(filePath, value) {
+  const directory = path.dirname(filePath);
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  try {
+    fs.chmodSync(directory, 0o700);
+  } catch {
+    // Best effort on Windows.
+  }
+  const serialized = JSON.stringify(value);
+  if (redactCredentialText(serialized) !== serialized || redactSecretText(serialized) !== serialized) {
+    throw new Error("refusing to record sensitive native-agent telemetry");
+  }
+  fs.appendFileSync(filePath, `${serialized}\n`, { encoding: "utf8", mode: 0o600 });
+  try {
+    fs.chmodSync(filePath, 0o600);
+  } catch {
+    // Best effort on Windows.
+  }
+}
+
+/**
+ * Creates an opt-in, closed-schema performance recorder. It accepts identifiers,
+ * counters, durations, and terminal classes only; prompt and result fields do
+ * not exist in the schema.
+ */
+export function createNativeAgentTelemetry({
+  tenantId,
+  agentId,
+  scopeParam,
+  mode,
+  filePath = process.env.IMPEL_NATIVE_AGENT_TELEMETRY_PATH,
+  host = process.env.IMPEL_NATIVE_HOST,
+  hostBuild = process.env.IMPEL_NATIVE_HOST_BUILD,
+  now = Date.now,
+} = {}) {
+  if (!filePath) return () => {};
+  const fixed = {
+    schema: "impel.native-agent-telemetry.v1",
+    transportVersion: NATIVE_AGENT_TRANSPORT_VERSION,
+    tenantId: safeId(tenantId),
+    agentId: safeId(agentId),
+    scopeParam: safeId(scopeParam),
+    mode: safeId(mode),
+    host: safeId(host),
+    hostBuild: safeId(hostBuild),
+  };
+  return (event, fields = {}) => {
+    if (!SAFE_EVENTS.has(event)) return;
+    const record = {
+      ...fixed,
+      event,
+      timestamp: new Date(now()).toISOString(),
+      correlationId: safeId(fields.correlationId),
+      gatewayRequestId: safeId(fields.gatewayRequestId),
+      tool: SAFE_TOOLS.has(fields.tool) ? fields.tool : undefined,
+      outcome: SAFE_OUTCOMES.has(fields.outcome) ? fields.outcome : undefined,
+      status: safeId(fields.status),
+      durationMs: safeInteger(fields.durationMs),
+      pollCount: safeInteger(fields.pollCount),
+      handshakeReused: typeof fields.handshakeReused === "boolean" ? fields.handshakeReused : undefined,
+      bindingReused: typeof fields.bindingReused === "boolean" ? fields.bindingReused : undefined,
+      durableRunCreated: typeof fields.durableRunCreated === "boolean" ? fields.durableRunCreated : undefined,
+    };
+    try {
+      appendPrivateJsonLine(filePath, Object.fromEntries(
+        Object.entries(record).filter(([, value]) => value !== undefined),
+      ));
+    } catch {
+      // Performance telemetry is opt-in and best effort; it cannot break a run.
+    }
+  };
+}

package/src/nativeAgentTransport.js

@@ -10,7 +10,7 @@ import {
 } from "./config.js";
 import {
   NATIVE_AGENT_ANSWER_TOOL,
-  NATIVE_AGENT_LIST_TOOL,
+  NATIVE_AGENT_GET_TOOL,
   NATIVE_AGENT_READ_TOOL,
   NATIVE_AGENT_RECOVER_TOOL,
   NATIVE_AGENT_RESUME_TOOL,
@@ -41,9 +41,9 @@ const SAFE_BINDING_RE = /^[A-Za-z0-9_.:-]{1,160}$/u;
 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 = 50;
-const DEFAULT_ATTACHMENT_WINDOW_MS = 55_000;
-const DEFAULT_UPSTREAM_TIMEOUT_MS = 55_000;
+const MAX_WAIT_SECONDS = 35;
+const DEFAULT_ATTACHMENT_WINDOW_MS = 40_000;
+const DEFAULT_UPSTREAM_TIMEOUT_MS = 42_000;
 const DEFAULT_MAX_POLLS = 8;
 const DEFAULT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 const DEFAULT_MAX_RETAINED_RUNS = 500;
@@ -288,6 +288,7 @@ function readPrivateState(filePath, maxBytes) {
       "upstreamRunId",
       "status",
       "startAttempts",
+      "startMode",
       "createdAt",
       "updatedAt",
       "fence",
@@ -296,6 +297,7 @@ function readPrivateState(filePath, maxBytes) {
       "result",
       "output",
       "error",
+      "version",
     ], "native-agent run state");
     if (!SAFE_INVOCATION_RE.test(state.invocationId)
       || normalizeTenantId(state.tenantId) !== state.tenantId
@@ -309,10 +311,14 @@ function readPrivateState(filePath, maxBytes) {
       || !state.status
       || !Number.isSafeInteger(state.startAttempts)
       || state.startAttempts < 0
+      || (state.startMode !== undefined
+        && state.startMode !== "durable"
+        && state.startMode !== "answer")
       || !Number.isFinite(Date.parse(state.createdAt))
       || !Number.isFinite(Date.parse(state.updatedAt))
       || (state.fence !== undefined && (!Number.isSafeInteger(state.fence) || state.fence < 0))
       || (state.sequence !== undefined && (!Number.isSafeInteger(state.sequence) || state.sequence < 0))
+      || (state.version !== undefined && (!Number.isSafeInteger(state.version) || state.version < 0))
       || (state.upstreamRunId !== null && (typeof state.upstreamRunId !== "string" || !state.upstreamRunId))) {
       throw new Error("invalid field");
     }
@@ -449,10 +455,13 @@ function applyUpstreamPayload(state, payload, now) {
   if (Object.hasOwn(payload, "error")) {
     state.error = redactOpaqueValue(payload.error, state.idempotencyKey);
   }
+  if (Number.isSafeInteger(payload.version) && payload.version >= 0) {
+    state.version = payload.version;
+  }
   state.updatedAt = new Date(now).toISOString();
 }
 
-/** Use the read tool's advertised integer maximum, never exceeding 50 seconds. */
+/** Use the read tool's advertised integer maximum, never exceeding 35 seconds. */
 export function negotiateNativeAgentWaitSeconds(tools) {
   const readTool = Array.isArray(tools)
     ? tools.find((tool) => tool?.name === NATIVE_AGENT_READ_TOOL)
@@ -575,6 +584,9 @@ export class NativeAgentUpstreamSession {
     timeoutMs = DEFAULT_UPSTREAM_TIMEOUT_MS,
     maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES,
     signal,
+    telemetry = () => {},
+    now = Date.now,
+    requestIdFactory = crypto.randomUUID,
   }) {
     this.endpoint = `${normalizeGatewayUrl(gatewayUrl)}/mcp`;
     this.credential = credential;
@@ -582,16 +594,24 @@ export class NativeAgentUpstreamSession {
     this.timeoutMs = timeoutMs;
     this.maxResponseBytes = maxResponseBytes;
     this.signal = signal;
+    this.telemetry = telemetry;
+    this.now = now;
+    this.requestIdFactory = requestIdFactory;
     this.sessionId = null;
     this.nextId = 1;
   }
 
-  async post(message) {
-    throwIfAborted(this.signal);
+  async post(message, { signal = this.signal } = {}) {
+    throwIfAborted(signal);
+    const startedAt = this.now();
+    const correlationId = this.requestIdFactory();
+    const tool = message.method === "tools/call"
+      ? String(message.params?.name || "").replace(/^impel_specialists-/u, "")
+      : message.method;
     const controller = new AbortController();
     let timedOut = false;
     const onAbort = () => controller.abort();
-    this.signal?.addEventListener("abort", onAbort, { once: true });
+    signal?.addEventListener("abort", onAbort, { once: true });
     const timeout = setTimeout(() => {
       timedOut = true;
       controller.abort();
@@ -605,6 +625,7 @@ export class NativeAgentUpstreamSession {
           Authorization: `Bearer ${this.credential}`,
           "Content-Type": "application/json",
           Accept: "application/json, text/event-stream",
+          "X-Impel-Client-Request-Id": correlationId,
           ...(this.sessionId ? { "Mcp-Session-Id": this.sessionId } : {}),
         },
         body: JSON.stringify(message),
@@ -612,13 +633,26 @@ export class NativeAgentUpstreamSession {
       });
       body = await readBoundedResponseBody(response, this.maxResponseBytes);
     } catch (error) {
-      if (this.signal?.aborted) throw abortError();
+      this.telemetry("upstream_request_completed", {
+        correlationId,
+        tool,
+        outcome: signal?.aborted ? "cancelled" : "error",
+        durationMs: this.now() - startedAt,
+      });
+      if (signal?.aborted) throw abortError();
       const detail = timedOut ? "request timed out" : redactSecretText(error?.message || error);
       throw new NativeAgentUpstreamError(`native-agent MCP request failed: ${detail}`, { ambiguous: true });
     } finally {
       clearTimeout(timeout);
-      this.signal?.removeEventListener("abort", onAbort);
-    }
+      signal?.removeEventListener("abort", onAbort);
+    }
+    this.telemetry("upstream_request_completed", {
+      correlationId,
+      gatewayRequestId: response.headers.get("x-request-id") || undefined,
+      tool,
+      outcome: response.ok ? "ok" : "error",
+      durationMs: this.now() - startedAt,
+    });
     this.sessionId = response.headers.get("mcp-session-id") || this.sessionId;
     if (!response.ok) {
       throw new NativeAgentUpstreamError(`native-agent MCP returned HTTP ${response.status}`, {
@@ -634,7 +668,7 @@ export class NativeAgentUpstreamSession {
     }
   }
 
-  async initialize() {
+  async initialize({ signal } = {}) {
     const id = this.nextId++;
     const initialized = await this.post({
       jsonrpc: "2.0",
@@ -645,14 +679,17 @@ export class NativeAgentUpstreamSession {
         capabilities: {},
         clientInfo: { name: "impel-cli-native-agent-transport", version: "1.0.0" },
       },
-    });
+    }, { signal });
     const response = initialized.find((message) => message?.id === id);
     if (!response?.result || response.error) {
       throw new NativeAgentUpstreamError("native-agent MCP initialization failed");
     }
-    await this.post({ jsonrpc: "2.0", method: "notifications/initialized", params: {} });
+    await this.post({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }, { signal });
     const toolsId = this.nextId++;
-    const listed = await this.post({ jsonrpc: "2.0", id: toolsId, method: "tools/list", params: {} });
+    const listed = await this.post(
+      { jsonrpc: "2.0", id: toolsId, method: "tools/list", params: {} },
+      { signal },
+    );
     const toolsResponse = listed.find((message) => message?.id === toolsId);
     if (toolsResponse?.error || !Array.isArray(toolsResponse?.result?.tools)) {
       throw new NativeAgentUpstreamError("native-agent MCP returned no tool catalog");
@@ -660,7 +697,7 @@ export class NativeAgentUpstreamSession {
     return toolsResponse.result.tools;
   }
 
-  async call(name, args) {
+  async call(name, args, { signal } = {}) {
     const id = this.nextId++;
     try {
       const messages = await this.post({
@@ -668,7 +705,7 @@ export class NativeAgentUpstreamSession {
         id,
         method: "tools/call",
         params: { name, arguments: args },
-      });
+      }, { signal });
       return toolPayload(messages.find((message) => message?.id === id));
     } catch (error) {
       if (name === NATIVE_AGENT_START_TOOL
@@ -715,6 +752,7 @@ export class NativeAgentCompositeTransport {
     beforeStateRename,
     beforeRevisionCompaction,
     beforePruneDelete,
+    telemetry = () => {},
   }) {
     this.tenantId = normalizeTenantId(tenantId);
     for (const [field, value] of Object.entries({ agentId, scopeParam })) {
@@ -756,14 +794,19 @@ export class NativeAgentCompositeTransport {
     this.beforeStateRename = beforeStateRename;
     this.beforeRevisionCompaction = beforeRevisionCompaction;
     this.beforePruneDelete = beforePruneDelete;
-    this.sessionFactory = sessionFactory || (({ signal }) => new NativeAgentUpstreamSession({
+    this.telemetry = telemetry;
+    this.sessionFactory = sessionFactory || (() => new NativeAgentUpstreamSession({
       gatewayUrl: this.gatewayUrl,
       credential: this.credential,
       fetchImpl: this.fetchImpl,
       timeoutMs: this.upstreamTimeoutMs,
       maxResponseBytes: this.maxResponseBytes,
-      signal,
+      telemetry: this.telemetry,
+      now: this.now,
+      requestIdFactory: this.randomUUID,
     }));
+    this.preparedSession = null;
+    this.preparedAgent = null;
   }
 
   statePath(invocationId) {
@@ -1505,15 +1548,38 @@ export class NativeAgentCompositeTransport {
   }
 
   async prepareExistingSession(signal) {
-    const session = await this.sessionFactory({ signal });
-    const tools = await session.initialize();
-    return { session, waitSeconds: negotiateNativeAgentWaitSeconds(tools) };
+    const reused = Boolean(this.preparedSession);
+    const startedAt = this.now();
+    if (!this.preparedSession) {
+      this.preparedSession = (async () => {
+        const session = await this.sessionFactory({ signal });
+        const tools = await session.initialize({ signal });
+        return { session, waitSeconds: negotiateNativeAgentWaitSeconds(tools) };
+      })();
+      this.preparedSession.catch(() => {
+        this.preparedSession = null;
+      });
+    }
+    const prepared = await this.preparedSession;
+    this.telemetry("session_prepared", {
+      durationMs: this.now() - startedAt,
+      handshakeReused: reused,
+    });
+    return prepared;
   }
 
   async prepareNewSession(signal) {
     const prepared = await this.prepareExistingSession(signal);
+    const startedAt = this.now();
+    if (this.preparedAgent) {
+      this.telemetry("binding_completed", { durationMs: 0, bindingReused: true });
+      return { ...prepared, agent: this.preparedAgent };
+    }
     const catalog = normalizeNativeAgentCatalog(
-      await prepared.session.call(NATIVE_AGENT_LIST_TOOL, {}),
+      await prepared.session.call(NATIVE_AGENT_GET_TOOL, {
+        agentId: this.agentId,
+        scopeParam: this.scopeParam,
+      }, { signal }),
       this.tenantId,
     );
     const matches = catalog.agents.filter((agent) =>
@@ -1523,13 +1589,21 @@ export class NativeAgentCompositeTransport {
     if (nativeAgentPolicyFingerprint(matches[0]) !== this.policyFingerprint) {
       throw new Error("native-agent catalog policy fingerprint changed; synchronize agents again");
     }
-    return { ...prepared, agent: matches[0] };
+    this.preparedAgent = matches[0];
+    this.telemetry("binding_completed", {
+      durationMs: this.now() - startedAt,
+      bindingReused: false,
+    });
+    return { ...prepared, agent: this.preparedAgent };
   }
 
   async preparePersistedStartSession(signal, state) {
     const prepared = await this.prepareExistingSession(signal);
     const catalog = normalizeNativeAgentCatalog(
-      await prepared.session.call(NATIVE_AGENT_LIST_TOOL, {}),
+      await prepared.session.call(NATIVE_AGENT_GET_TOOL, {
+        agentId: state.agentId,
+        scopeParam: state.scopeParam,
+      }, { signal }),
       this.tenantId,
     );
     const matches = catalog.agents.filter((agent) =>
@@ -1586,47 +1660,14 @@ export class NativeAgentCompositeTransport {
     };
   }
 
-  async answer(args, { signal } = {}) {
-    throwIfAborted(signal);
-    const prepared = await this.prepareNewSession(signal);
-    if (prepared.agent.directAnswer !== true) {
-      throw new Error("native-agent binding is not configured for direct answers");
-    }
-    if (prepared.agent.sideEffects === "writes") {
-      throw new Error(
-        "write-capable native agents must use start/resume instead of answer_native_agent",
-      );
-    }
-    const payload = await prepared.session.call(
-      NATIVE_AGENT_UPSTREAM_ANSWER_TOOL,
-      this.normalizeAnswerArguments(args, prepared.agent),
-    );
-    const finalText = extractAnswerFinalText(payload);
-    if (finalText === null) throw new Error("native-agent answer returned no forUser or answer");
-    return {
-      ...(typeof payload.forUser === "string" && payload.forUser.trim()
-        ? { forUser: payload.forUser }
-        : {}),
-      ...(typeof payload.answer === "string" && payload.answer.trim()
-        ? { answer: payload.answer }
-        : {}),
-      agentId: this.agentId,
-      scopeParam: this.scopeParam,
-    };
-  }
-
-  async run(args, { signal, onProgress } = {}) {
-    throwIfAborted(signal);
-    this.ensureRoots();
-    const attachment = boundedAttachmentSignal(signal, this.attachmentWindowMs);
-    let state = null;
-    let lock = null;
+  allocateState(startArguments, { startMode = "durable" } = {}) {
     let admission = null;
     try {
-      const prepared = await this.prepareNewSession(attachment.signal);
-      const startArguments = this.normalizeRunArguments(args, prepared.agent);
+      this.ensureRoots();
       admission = this.acquireAdmissionLock();
-      if (!admission) throw new Error("native-agent run allocation is busy; retry without changing the request");
+      if (!admission) {
+        throw new Error("native-agent run allocation is busy; retry without changing the request");
+      }
       this.prune(this.now(), { reserve: 1, guard: () => admission.assert() });
       admission.assert();
       const invocationId = this.randomUUID();
@@ -1640,7 +1681,7 @@ export class NativeAgentCompositeTransport {
         startArguments,
       });
       const timestamp = new Date(this.now()).toISOString();
-      state = {
+      const state = {
         schema: STATE_SCHEMA,
         invocationId,
         tenantId: this.tenantId,
@@ -1653,15 +1694,83 @@ export class NativeAgentCompositeTransport {
         upstreamRunId: null,
         status: "starting",
         startAttempts: 0,
+        ...(startMode === "answer" ? { startMode } : {}),
         createdAt: timestamp,
         updatedAt: timestamp,
       };
+      this.persist(state);
+      return state;
+    } finally {
+      admission?.release();
+    }
+  }
+
+  async answer(args, { signal } = {}) {
+    throwIfAborted(signal);
+    const attachment = boundedAttachmentSignal(signal, this.attachmentWindowMs);
+    let state = null;
+    let lock = null;
+    try {
+      const prepared = await this.prepareNewSession(attachment.signal);
+      if (prepared.agent.directAnswer !== true) {
+        throw new Error("native-agent binding is not configured for direct answers");
+      }
+      if (prepared.agent.sideEffects === "writes") {
+        throw new Error(
+          "write-capable native agents must use start/resume instead of answer_native_agent",
+        );
+      }
+      const answerArguments = this.normalizeAnswerArguments(args, prepared.agent);
+      const startArguments = this.normalizeRunArguments({
+        task: answerArguments.question,
+        ...(args.context !== undefined ? { context: args.context } : {}),
+        contextKeys: args.contextKeys ?? [],
+      }, prepared.agent);
+      state = this.allocateState(startArguments, { startMode: "answer" });
+      lock = this.acquireLock(state.invocationId);
+      if (!lock) return handleForState(state);
+      const result = await this.attach(state, prepared, {
+        signal: attachment.signal,
+        lock,
+      });
+      if (result?.schema === NATIVE_AGENT_RESULT_SCHEMA && result.status === "succeeded") {
+        return {
+          forUser: result.finalText,
+          answer: result.finalText,
+          agentId: this.agentId,
+          scopeParam: this.scopeParam,
+        };
+      }
+      return result;
+    } catch (error) {
+      if (!state) throw error;
+      if (lock) {
+        try {
+          this.persistDiagnostic(state, error, lock);
+        } catch {
+          // The persisted handle remains authoritative after a lost lease.
+        }
+      }
+      return handleForState(state);
+    } finally {
+      lock?.release();
+      attachment.dispose();
+    }
+  }
+
+  async run(args, { signal, onProgress } = {}) {
+    throwIfAborted(signal);
+    this.ensureRoots();
+    const attachment = boundedAttachmentSignal(signal, this.attachmentWindowMs);
+    let state = null;
+    let lock = null;
+    try {
+      const prepared = await this.prepareNewSession(attachment.signal);
+      const startArguments = this.normalizeRunArguments(args, prepared.agent);
+      state = this.allocateState(startArguments);
       // The durable identity and exact retry arguments exist before the first
       // upstream byte is sent.
-      this.persist(state);
-      admission.release();
-      admission = null;
-      lock = this.acquireLock(invocationId);
+      lock = this.acquireLock(state.invocationId);
       if (!lock) return handleForState(state);
       return await this.attach(state, prepared, {
         signal: attachment.signal,
@@ -1677,7 +1786,6 @@ export class NativeAgentCompositeTransport {
       }
       throw error;
     } finally {
-      admission?.release();
       lock?.release();
       attachment.dispose();
     }
@@ -1893,7 +2001,47 @@ export class NativeAgentCompositeTransport {
           state.updatedAt = new Date(this.now()).toISOString();
           this.persist(state, lock);
           try {
-            started = await session.call(NATIVE_AGENT_START_TOOL, state.startArguments);
+            const answerMode = state.startMode === "answer";
+            const outboundArguments = answerMode
+              ? {
+                  agentId: state.agentId,
+                  scopeParam: state.scopeParam,
+                  question: state.startArguments.task,
+                  ...(state.startArguments.context !== undefined
+                    ? { context: state.startArguments.context }
+                    : {}),
+                  contextKeys: state.startArguments.contextKeys ?? [],
+                  idempotencyKey: state.idempotencyKey,
+                }
+              : state.startArguments;
+            started = await session.call(
+              answerMode ? NATIVE_AGENT_UPSTREAM_ANSWER_TOOL : NATIVE_AGENT_START_TOOL,
+              outboundArguments,
+              { signal },
+            );
+            if (answerMode) {
+              if (!started?.runId) {
+                throw new Error("native-agent answer returned no durable runId");
+              }
+              const answerText = extractAnswerFinalText(started);
+              if (started.status === "succeeded" && answerText !== null) {
+                started = {
+                  runId: started.runId,
+                  status: "succeeded",
+                  result: { finalText: answerText },
+                  ...(Number.isSafeInteger(started.version)
+                    ? { version: started.version }
+                    : {}),
+                };
+              } else if (
+                started.status !== "continuation_required"
+                || started.durableRunCreated !== true
+              ) {
+                throw new Error(
+                  "native-agent answer returned neither a terminal answer nor a durable continuation",
+                );
+              }
+            }
             break;
           } catch (error) {
             if (error?.name === "AbortError") throw error;
@@ -1935,7 +2083,9 @@ export class NativeAgentCompositeTransport {
         const observed = await session.call(NATIVE_AGENT_READ_TOOL, {
           runId: state.upstreamRunId,
           waitSeconds: boundedWait,
-        });
+          terminalOnly: process.env.IMPEL_NATIVE_TERMINAL_ONLY_READS !== "0",
+          ...(Number.isSafeInteger(state.version) ? { sinceVersion: state.version } : {}),
+        }, { signal });
         this.commitPayload(state, observed, lock);
         onProgress?.({ status: state.status, runId: state.upstreamRunId, poll: poll + 1 });
         result = resultForState(state);
@@ -1980,31 +2130,29 @@ const HANDLE_SCHEMA = {
 
 export function nativeAgentCompositeTools({ mode = "durable" } = {}) {
   if (!["durable", "recovery", "answer"].includes(mode)) throw new Error("invalid native-agent MCP mode");
-  if (mode === "answer") {
-    return [{
-      name: NATIVE_AGENT_ANSWER_TOOL,
-      description: "Answer once through the direct-answer native agent fixed by this MCP server.",
-      inputSchema: {
-        type: "object",
-        additionalProperties: false,
-        anyOf: [
-          { required: ["question"], not: { required: ["task"] } },
-          { required: ["task"], not: { required: ["question"] } },
-        ],
-        properties: {
-          question: { type: "string", minLength: 1, maxLength: 40_000 },
-          task: { type: "string", minLength: 1, maxLength: 40_000 },
-          context: { type: "string", maxLength: 40_000 },
-          contextKeys: {
-            type: "array",
-            maxItems: 30,
-            uniqueItems: true,
-            items: { type: "string", minLength: 1, maxLength: 160 },
-          },
+  const answerTool = {
+    name: NATIVE_AGENT_ANSWER_TOOL,
+    description: "Answer once through the direct-answer native agent fixed by this MCP server.",
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      anyOf: [
+        { required: ["question"], not: { required: ["task"] } },
+        { required: ["task"], not: { required: ["question"] } },
+      ],
+      properties: {
+        question: { type: "string", minLength: 1, maxLength: 40_000 },
+        task: { type: "string", minLength: 1, maxLength: 40_000 },
+        context: { type: "string", maxLength: 40_000 },
+        contextKeys: {
+          type: "array",
+          maxItems: 30,
+          uniqueItems: true,
+          items: { type: "string", minLength: 1, maxLength: 160 },
         },
       },
-    }];
-  }
+    },
+  };
   const tools = [
     {
       name: NATIVE_AGENT_RUN_TOOL,
@@ -2045,6 +2193,9 @@ export function nativeAgentCompositeTools({ mode = "durable" } = {}) {
       },
     },
   ];
+  if (mode === "answer") {
+    return [answerTool, ...tools.filter(({ name }) => name !== NATIVE_AGENT_RUN_TOOL)];
+  }
   return mode === "recovery" ? tools.filter(({ name }) => name !== NATIVE_AGENT_RUN_TOOL) : tools;
 }
 

package/src/selfInvocation.js

@@ -67,12 +67,27 @@ export function impelCliInvocation(args = [], options = {}) {
 export const IMPEL_MANAGED_MCP_ENV = brandedEnvironmentName("MANAGED_MCP");
 export const IMPEL_TASKS_MCP_SERVER_NAME = `${RUNTIME_BRAND.cli.providerId}-tasks`;
 export const IMPEL_NATIVE_AGENT_MCP_TARGET = "native-agent";
+export const IMPEL_NATIVE_AGENT_TELEMETRY_ENV_NAMES = [
+  "IMPEL_NATIVE_AGENT_TELEMETRY_PATH",
+  "IMPEL_NATIVE_HOST",
+  "IMPEL_NATIVE_HOST_BUILD",
+];
+
+function managedMcpEnvironment(environment = process.env) {
+  const telemetry = Object.fromEntries(
+    IMPEL_NATIVE_AGENT_TELEMETRY_ENV_NAMES.flatMap((name) => {
+      const value = environment?.[name];
+      return typeof value === "string" && value.length > 0 ? [[name, value]] : [];
+    }),
+  );
+  return { [IMPEL_MANAGED_MCP_ENV]: "1", ...telemetry };
+}
 
 export function impelMcpInvocation(args = [], options = {}) {
   return {
     type: "stdio",
     ...impelCliInvocation(["mcp", ...args], options),
-    env: { [IMPEL_MANAGED_MCP_ENV]: "1" },
+    env: managedMcpEnvironment(options.environment),
   };
 }
 

package/src/verbatimRelay.js

@@ -13,7 +13,8 @@ export function parentVerbatimRelayAppendix() {
   return (
     `When an explicit custom agent's catalog-derived description declares ${VERBATIM_RELAY_OPT_IN_MARKER}, ` +
     `spawn it with ${VERBATIM_SPAWN_REQUIREMENT} and relay its finalText verbatim with ${VERBATIM_FINAL_TEXT_CONSTRAINTS}; ` +
-    "preserve Sources sections and citations exactly. " +
+    "preserve Sources sections and citations exactly. Start one child, then use one blocking wait sized for the child budget; " +
+    "on Codex, call wait_agent exactly once with timeout_ms=60000. Do not send follow-ups, short-poll the child, or synthesize while it is running. " +
     "Custom agents without that declaration keep the default delegation behavior."
   );
 }