impel-cli 0.20.2-beta.1 → 0.20.4

package/README.md

@@ -182,89 +182,82 @@ impel codex exec "review this repository"
 
 ## Remote Fargate sessions
 
-Start a disposable AWS Fargate runner for the current Git repository:
+Remote operations use the tenant broker. The laptop sends its PAT only to that
+broker; the runner receives a separate run-bound credential. Production modes
+do not call AWS and do not require an AWS profile.
 
-```sh
-impel remote up --provider codex
-```
-
-The command creates a one-day, provider-scoped disposable PAT, starts the
-TTL-bounded task, installs a concrete SSH alias, transfers Git history plus the
-tracked and nonignored working tree, restores recognized Node/Python lockfile
-dependencies, and uploads the disposable credential only through encrypted
-SSH. The user's stored PAT, ignored files, SSH agent, Keychain, and environment
-are not copied. Select variables explicitly when they are genuinely required:
-
-```sh
-impel remote up --provider claude --env API_HOST,FEATURE_FLAG
-```
-
-Use the remote session from a terminal:
+The public modes are deliberately asymmetric:
 
 ```sh
-impel remote status
-impel remote attach --provider codex
-impel remote attach --provider claude
-```
+# Same Codex Desktop chat, through the documented SSH run-location handoff.
+impel remote handoff . --provider codex --mode native --session <sessions-uuid>
 
-For Codex Desktop on macOS, open the native connection flow:
+# New provider-native branch from a closed exact checkpoint.
+impel remote dispatch . --provider codex --mode fork --session <sessions-uuid> \
+  --checkpoint <archive> --checkpoint-manifest <manifest>
+impel remote dispatch . --provider claude --mode fork --session <sessions-uuid> \
+  --checkpoint <archive> --checkpoint-manifest <manifest>
 
-```sh
-impel remote attach --provider codex --desktop
+# Explicit non-exact context/workspace transfer.
+impel remote dispatch . --provider claude --mode portable --session <sessions-uuid>
 ```
 
-Save `/workspace/repo` as the remote project. In an existing Codex chat, use
-the footer's run-location picker and choose the generated SSH host. Codex then
-uses its supported SSH app-server transport to move the chat and Git state and
-stream prompts, approvals, tools, diffs, and output in the local app.
-
-Claude Desktop can open a new native SSH session on the same alias. Claude does
-not expose an arbitrary-host equivalent of Codex's exact chat handoff. To move
-an existing Impel Claude/Codex CLI session, checkpoint it and create a remote
-continuation or fork:
+`--session` is the required lowercase UUID of the Impel Sessions binding for
+the chat. It is required for native, fork, and portable broker creates. It is
+not the provider-native Codex thread ID or Claude session ID; fork checkpoints
+carry that separate provider identity in their closed manifest. The CLI never
+invents a Sessions binding or substitutes a provider thread ID for one.
+
+Every request negotiates the broker's versioned capability response before a
+run is created. Unsupported combinations fail locally or before provisioning;
+the CLI never changes native/fork to portable automatically. Gateway-backed
+Claude has no native Anthropic Remote Control path. Codex App Server supports
+fork/portable, not a Desktop native-handoff claim.
+
+For a native request started in Codex CLI, run `/app` first so Desktop opens the
+same saved chat. The CLI waits for explicit confirmation and then negotiates
+the Desktop capability. It writes a run-specific SSH host whose `ProxyCommand`
+asks the broker for a fresh single-use connection lease on every OpenSSH
+connection. The private Ed25519 key remains local; only its public key is sent
+to the broker. No AWS credentials or initiating PAT enter the task.
+
+Codex Desktop and the tunnel must remain awake and online for ChatGPT Remote.
+For laptop-independent control, use the App Server fork/portable path and the
+Impel viewer. Once the broker reports the run as `running`, create a fresh
+one-time browser link without persisting its exchange secret locally:
 
 ```sh
-impel remote dispatch --provider claude --session <session-id> --fork
-impel remote dispatch --provider codex --session <session-id> --fork
+impel remote viewer <run-id>
 ```
 
-The installable `remote-control` skill turns this into an in-app handoff. Ask
-Claude Code or Codex to run the current session remotely, or invoke the skill
-directly, and it resolves the current Claude session/Codex thread id before
-running:
-
-```sh
-impel remote handoff . --provider <codex|claude> --session <session-id>
-```
-
-Unlike `up` or `dispatch`, `handoff` launches a detached headless worker inside
-Fargate and follows the provider's structured event stream. Inference, tools,
-commands, and edits execute in the runner; the local app only displays the
-stream. Normal completion stops the task, revokes its disposable PAT, and
-removes its SSH alias. To let the task continue without keeping the stream
-open, add `--detach`, then reconnect later:
-
-```sh
-impel remote follow <run-id>
-```
-
-If the viewer disconnects, the detached worker keeps running and its normal
-session hooks continue syncing the remote transcript to `impel-sessions`. The
-task TTL remains the fallback stop and credential-revocation boundary.
-
-Remote vendor commands run in dangerous/bypass mode as the unprivileged
-`agent` user; the disposable Fargate task is the isolation boundary. Existing
-Impel lifecycle hooks continue mirroring remote transcripts to
-`impel-sessions`. Stop the task and revoke its credential when finished:
+The exchange secret is carried only in the URL fragment and the viewer removes
+it immediately after exchanging it for a run-bound HttpOnly cookie. Handback is
+also explicit: select **This computer** in Desktop,
+wait for the remote child to exit, then run:
 
 ```sh
-impel remote down --yes
+impel remote handback <run-id> --yes
 ```
 
-The current lifecycle client requires macOS or Linux, OpenSSH, the AWS CLI, the
-AWS Session Manager plugin, and permission to use the deployed
-`impel-remote-dev` stack. Use `impel remote help` for region, profile, TTL,
-dependency, and setup overrides.
+The broker stops and revokes only after both the provider/SSH close signal and
+the confirmation. A lost tunnel receives reconnect grace and is not treated as
+successful handback. `--abandon` requests forced safe cleanup; it never starts
+a local writer.
+
+Brokered fork/portable runs capture an immutable workspace artifact that keeps
+Git history and the exact staged, unstaged, deleted, untracked, executable,
+rename, binary, and intent-to-add state distinct. Conflict, submodule, LFS,
+unsafe-link, case-collision, and size-limit cases fail before upload. Exact
+provider checkpoints must be closed, versioned, quiesced, and hash-verified.
+After create assigns the run ID, the CLI rehashes the isolated staging archive,
+adds only a canonical run-bound `manifest.json`, and uploads the closed result;
+mirrored open session files are never labeled exact.
+
+The former one-shot worker remains only as a short-lived rollback through
+`--mode portable-legacy` plus `IMPEL_REMOTE_ENABLE_PORTABLE_LEGACY=1`. It is
+never selected implicitly and is scheduled for removal on 2026-10-31 together
+with direct AWS, PAT upload, and SSH file-tail behavior. See
+[RELEASE_NOTES.md](RELEASE_NOTES.md).
 
 Changing the selected tenant does not install, remove, or rewrite any other
 tenant. It changes only the default used by CLI launches and selected-tenant

package/RELEASE_NOTES.md

@@ -0,0 +1,13 @@
+# Release notes
+
+## Native remote migration
+
+The former `impel remote handoff` implementation started a one-shot headless
+continuation and did not transfer a live provider session. The unqualified
+spelling no longer invokes that worker.
+
+Until **2026-10-31**, operators may invoke the rollback implementation only by
+setting `IMPEL_REMOTE_ENABLE_PORTABLE_LEGACY=1` and passing
+`--mode portable-legacy`. It is never selected implicitly. The flag, worker,
+direct AWS/SSM path, PAT upload, SSH file tail, and its invocation counter are
+scheduled for removal together after the native/broker acceptance gates pass.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.20.2-beta.1",
+  "version": "0.20.4",
   "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "./extension": "./src/extension/index.js"
   },
   "files": [
+    "RELEASE_NOTES.md",
     "bin",
     "docs/experimental-managed-cursor.md",
     "src",

package/src/agents.js

@@ -19,7 +19,23 @@ import {
   IMPEL_NATIVE_AGENT_MCP_TARGET,
   impelNativeAgentMcpInvocation,
 } from "./selfInvocation.js";
+import {
+  adapterAnswerFaithfulCompletionGuidance,
+  adapterAnswerVerbatimCompletionGuidance,
+  claudeAnswerFaithfulCompletionGuidance,
+  claudeAnswerVerbatimCompletionGuidance,
+  usesDirectAnswer,
+} from "./directAnswer.js";
 import { normalizeTenantId } from "./tenants.js";
+import {
+  adapterCallerSpawnGuidance,
+  adapterFaithfulCompletionGuidance,
+  adapterVerbatimCompletionGuidance,
+  claudeFaithfulCompletionGuidance,
+  claudeVerbatimCompletionGuidance,
+  customAgentVerbatimDescriptionLead,
+  usesVerbatimRelay,
+} from "./verbatimRelay.js";
 import { renameWithWindowsRetry } from "./windowsFs.js";
 
 export const AGENT_SYNC_TTL_MS = 6 * 60 * 60 * 1000;
@@ -28,11 +44,13 @@ export const MANAGED_AGENT_MANIFEST = ".manifest.json";
 export const NATIVE_AGENT_LIST_TOOL = "impel_specialists-list_native_agents";
 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";
+export const NATIVE_AGENT_ANSWER_TOOL = "answer_native_agent";
 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 = 6;
+export const MANAGED_AGENT_MANIFEST_VERSION = 7;
 
 const NATIVE_AGENT_TOOL_NAMES = [
   NATIVE_AGENT_RUN_TOOL,
@@ -40,6 +58,9 @@ const NATIVE_AGENT_TOOL_NAMES = [
   NATIVE_AGENT_RECOVER_TOOL,
 ];
 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;
+}
 const MAX_RETIRED_AGENT_BINDINGS = 50;
 const MAX_NATIVE_AGENT_STATE_BYTES = 512 * 1024;
 const TERMINAL_NATIVE_AGENT_STATUSES = new Set(["succeeded", "failed", "cancelled", "canceled"]);
@@ -140,6 +161,12 @@ export function normalizeNativeAgentCatalog(payload, expectedTenantId) {
       throw new Error(`native-agent catalog returned duplicate binding ${binding}`);
     }
     seenBindings.add(binding);
+    if (agent.verbatimRelay !== undefined && typeof agent.verbatimRelay !== "boolean") {
+      throw new Error("native-agent catalog returned an invalid verbatimRelay");
+    }
+    if (agent.directAnswer !== undefined && typeof agent.directAnswer !== "boolean") {
+      throw new Error("native-agent catalog returned an invalid directAnswer");
+    }
     return {
       agentId,
       title: boundedString(agent.title, "title", { max: 160 }),
@@ -150,6 +177,8 @@ export function normalizeNativeAgentCatalog(payload, expectedTenantId) {
       exclusions: stringList(agent.exclusions, "exclusions"),
       requiredContext: stringList(agent.requiredContext, "requiredContext"),
       sideEffects: enumString(agent.sideEffects, "sideEffects", ["read-only", "writes"]),
+      ...(agent.verbatimRelay === true ? { verbatimRelay: true } : {}),
+      ...(agent.directAnswer === true ? { directAnswer: true } : {}),
     };
   });
   return { orgId: tenantId, agents };
@@ -559,14 +588,35 @@ function claudeAdapterInstructions(tenantId, agent) {
   const sideEffectInstruction = agent.sideEffects === "writes"
     ? `The synchronized policy declares that this agent writes user or workspace data. Use this adapter only when the user explicitly selected this exact agent for the current request. If the agent was chosen automatically or the selection is ambiguous, do not start it and ask the user to select it explicitly.`
     : `The synchronized policy declares that this agent is read-only.`;
+  const callerGuidance = usesVerbatimRelay(agent)
+    ? adapterCallerSpawnGuidance("Claude")
+    : null;
+  if (usesDirectAnswer(agent)) {
+    const completionGuidance = usesVerbatimRelay(agent)
+      ? claudeAnswerVerbatimCompletionGuidance()
+      : claudeAnswerFaithfulCompletionGuidance();
+    return [
+      `You are a thin transport adapter for the exact Impel native agent ${JSON.stringify(agent.agentId)} in tenant ${JSON.stringify(tenantId)}.`,
+      ...(callerGuidance ? [callerGuidance] : []),
+      `Do not perform the assigned task yourself and do not delegate to any other 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.`,
+      completionGuidance,
+    ].join(" ");
+  }
+  const completionGuidance = usesVerbatimRelay(agent)
+    ? claudeVerbatimCompletionGuidance()
+    : claudeFaithfulCompletionGuidance();
   return [
     `You are a thin transport adapter for the exact Impel native agent ${JSON.stringify(agent.agentId)} in tenant ${JSON.stringify(tenantId)}.`,
+    ...(callerGuidance ? [callerGuidance] : []),
     `Do not perform the assigned task yourself and do not delegate to any other 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_RUN_TOOL)} exactly once with task 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 that call returns an ${JSON.stringify("impel.native-agent-run.v1")} handle, call ${nativeToolName(NATIVE_AGENT_RESUME_TOOL)} with exactly that same handle until the transport returns a terminal result. If the call is cancelled, the connection closes, or its result is unknown before you receive a handle, call ${nativeToolName(NATIVE_AGENT_RECOVER_TOOL)} with {} and resume the newest returned pending handle; if multiple handles cannot be safely associated with this request, report them instead of choosing. Never call run_native_agent again for this request, and never restart, nudge, replace, or independently poll the upstream run.`,
-    `When it succeeds, return finalText byte-for-byte as the answer with no preface or rewriting. When it fails, return the preserved runId, output, and error. Never invent or independently synthesize a replacement result.`,
+    completionGuidance,
   ].join(" ");
 }
 
@@ -581,15 +631,35 @@ function codexAdapterInstructions(tenantId, agent) {
   const sideEffectInstruction = agent.sideEffects === "writes"
     ? `The synchronized policy declares that this agent writes user or workspace data. Use this adapter only when the user explicitly selected this exact agent for the current request. If the agent was chosen automatically or the selection is ambiguous, ask the user to select this exact agent explicitly.`
     : `The synchronized policy declares that this agent is read-only.`;
+  const callerGuidance = usesVerbatimRelay(agent)
+    ? adapterCallerSpawnGuidance("Codex")
+    : null;
+  if (usesDirectAnswer(agent)) {
+    const completionGuidance = usesVerbatimRelay(agent)
+      ? adapterAnswerVerbatimCompletionGuidance()
+      : adapterAnswerFaithfulCompletionGuidance();
+    return [
+      `You are a thin transport adapter for the exact Impel native agent ${JSON.stringify(agent.agentId)} in tenant ${JSON.stringify(tenantId)}.`,
+      ...(callerGuidance ? [callerGuidance] : []),
+      `Do not perform the assigned task yourself, do not delegate to any other agent, and do not independently synthesize the result.`,
+      `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.`,
+      completionGuidance,
+    ].join("\n\n");
+  }
+  const completionGuidance = usesVerbatimRelay(agent)
+    ? adapterVerbatimCompletionGuidance()
+    : adapterFaithfulCompletionGuidance();
   return [
     `You are a thin transport adapter for the exact Impel native agent ${JSON.stringify(agent.agentId)} in tenant ${JSON.stringify(tenantId)}.`,
-    `Callers must spawn this explicit custom Codex agent with fork_turns="none" and must relay your result verbatim; this is caller guidance and cannot enforce host spawn behavior.`,
+    ...(callerGuidance ? [callerGuidance] : []),
     `Do not perform the assigned task yourself, do not delegate to any other agent, and do not independently synthesize or rewrite the result.`,
     `Confirm that the assigned request fits the cataloged capabilities ${JSON.stringify(agent.capabilities)} and none of the exclusions ${JSON.stringify(agent.exclusions)} before starting.${contextRequirement}`,
     sideEffectInstruction,
     `Call ${nativeToolName(NATIVE_AGENT_RUN_TOOL)} exactly once with the complete task, optional context string, and supplied context keys. If it returns an ${JSON.stringify("impel.native-agent-run.v1")} handle, call ${nativeToolName(NATIVE_AGENT_RESUME_TOOL)} with exactly that same handle until the transport returns a terminal result. If the call is cancelled, the connection closes, or its result is unknown before you receive a handle, call ${nativeToolName(NATIVE_AGENT_RECOVER_TOOL)} with {} and resume the newest returned pending handle; if multiple handles cannot be safely associated with this request, report them instead of choosing. Never call run_native_agent again for this request, and never restart, nudge, replace, or independently poll the upstream run.`,
     `While a remote wait is healthy, the parent must not message, follow up with, or interrupt this adapter.`,
-    `Return successful finalText byte-for-byte with no preface, rewriting, Markdown changes, or independent synthesis. A failure preserves the durable runId, output, and error.`,
+    completionGuidance,
   ].join("\n\n");
 }
 
@@ -602,11 +672,21 @@ function retiredAdapterInstructions(tenantId, agent) {
   ].join(" ");
 }
 
+function customAgentDescription(tenantId, agent) {
+  const sideEffects = agent.sideEffects === "writes"
+    ? " (may write user or workspace data)"
+    : " (read-only)";
+  return (usesVerbatimRelay(agent)
+    ? `${customAgentVerbatimDescriptionLead()}. Runs ${agent.title} for Impel tenant ${tenantId}${sideEffects}: ${agent.description}`
+    : `Explicitly runs ${agent.title} for Impel tenant ${tenantId}${sideEffects}: ${agent.description}`
+  ).slice(0, 900);
+}
+
 function renderClaudeAgent({ tenantId, agent, name, invocation, recoveryOnly = false }) {
   const description = recoveryOnly
     ? `Recovery-only access to pending runs for retired Impel binding ${agent.agentId} in tenant ${tenantId}.`
-    : `Explicitly runs ${agent.title} for Impel tenant ${tenantId}${agent.sideEffects === "writes" ? " (may write user or workspace data)" : " (read-only)"}: ${agent.description}`.slice(0, 900);
-  const toolNames = recoveryOnly ? NATIVE_AGENT_RECOVERY_TOOL_NAMES : NATIVE_AGENT_TOOL_NAMES;
+    : customAgentDescription(tenantId, agent);
+  const toolNames = recoveryOnly ? NATIVE_AGENT_RECOVERY_TOOL_NAMES : nativeAgentToolNames(agent);
   const lines = [
     "---",
     `name: ${JSON.stringify(name)}`,
@@ -633,8 +713,8 @@ function renderClaudeAgent({ tenantId, agent, name, invocation, recoveryOnly = f
 function renderCodexAgent({ tenantId, agent, name, invocation, recoveryOnly = false }) {
   const description = recoveryOnly
     ? `Recovery-only custom agent for pending runs from retired Impel binding ${agent.agentId} in tenant ${tenantId}.`
-    : `Explicit custom agent: callers must use fork_turns="none" and relay its result verbatim. Runs ${agent.title} for Impel tenant ${tenantId}${agent.sideEffects === "writes" ? " (may write user or workspace data)" : " (read-only)"}: ${agent.description}`.slice(0, 900);
-  const toolNames = recoveryOnly ? NATIVE_AGENT_RECOVERY_TOOL_NAMES : NATIVE_AGENT_TOOL_NAMES;
+    : customAgentDescription(tenantId, agent);
+  const toolNames = recoveryOnly ? NATIVE_AGENT_RECOVERY_TOOL_NAMES : nativeAgentToolNames(agent);
   const envEntries = Object.entries(invocation.env || {})
     .map(([key, value]) => `${JSON.stringify(key)} = ${JSON.stringify(value)}`)
     .join(", ");
@@ -659,7 +739,7 @@ function renderCodexAgent({ tenantId, agent, name, invocation, recoveryOnly = fa
 
 function boundNativeAgentInvocation(tenantId, agent, invocation, {
   policyFingerprint = nativeAgentPolicyFingerprint(agent),
-  recoveryOnly = false,
+  mode = usesDirectAnswer(agent) ? "answer" : "durable",
 } = {}) {
   if (!invocation) {
     return impelNativeAgentMcpInvocation({
@@ -667,7 +747,7 @@ function boundNativeAgentInvocation(tenantId, agent, invocation, {
       agentId: agent.agentId,
       scopeParam: agent.scopeParam,
       policyFingerprint,
-      recoveryOnly,
+      mode,
     });
   }
   const mcpIndex = invocation.args?.lastIndexOf("mcp") ?? -1;
@@ -681,7 +761,8 @@ function boundNativeAgentInvocation(tenantId, agent, invocation, {
       "--agent-id", agent.agentId,
       "--scope-param", agent.scopeParam,
       "--policy-fingerprint", policyFingerprint,
-      ...(recoveryOnly ? ["--recovery-only"] : []),
+      ...(mode === "recovery" ? ["--recovery-only"] : []),
+      ...(mode === "answer" ? ["--answer-only"] : []),
     ],
   };
 }
@@ -753,7 +834,7 @@ function renderRetiredManagedAgents(client, tenantId, bindings, active, invocati
     };
     const boundInvocation = boundNativeAgentInvocation(tenantId, agent, invocation, {
       policyFingerprint: binding.policyFingerprint,
-      recoveryOnly: true,
+      mode: "recovery",
     });
     const contents = client === "claude"
       ? renderClaudeAgent({ tenantId, agent, name, invocation: boundInvocation, recoveryOnly: true })
@@ -841,7 +922,7 @@ export function syncAgentProfile({
     throw new Error("generated native-agent destinations are not unique");
   }
   const priorFiles = new Set(prior?.files || []);
-  const priorUsesDiscoveryRoot = [2, 3, 4, 5, MANAGED_AGENT_MANIFEST_VERSION].includes(prior?.version);
+  const priorUsesDiscoveryRoot = [2, 3, 4, 5, 6, MANAGED_AGENT_MANIFEST_VERSION].includes(prior?.version);
 
   // Native clients discover standalone definitions directly under `agents/`.
   // Preflight every destination before writing so an unmanaged file with the

package/src/apps.js

@@ -22,6 +22,7 @@ import { ensureClaudeSessionHooks, ensureCodexSessionHooks } from "./sessionHook
 import { ADHOC_IDENTITY, codesignIdentityArgs, desiredSigningMode, resolveSigningIdentity } from "./codesign.js";
 import { applyImpelClaudeSandbox } from "./claudeSandbox.js";
 import { brandedEnvironmentName, RUNTIME_BRAND } from "./runtimeBrand.js";
+import { IMPEL_CODEX_PARENT_DELEGATION_INSTRUCTIONS } from "./commands/launch.js";
 
 export const CLAUDE_CONFIG_ID = "1ced0000-0000-4000-8000-000000000001";
 const CHATGPT_CONFIG_START = `# >>> ${RUNTIME_BRAND.cli.command} app managed gateway >>>`;
@@ -276,7 +277,9 @@ export function managedAppIdentity(target, tenantId = null, tenantName = null) {
 // and ChatGPT/Codex profiles without changing the specialist MCP server.
 // 28: bind generated native-agent profiles to the durable local composite MCP
 // transport and remove model-controlled upstream start/read polling.
-export const CURRENT_CONFIG_VERSION = 28;
+// 29: add marker-aware custom-agent verbatim relay guidance to ChatGPT and
+// expose direct-answer native agents through their one-shot local MCP binding.
+export const CURRENT_CONFIG_VERSION = 29;
 
 // Identifies the bundle-BUILDING logic — the asar patches, plist rewrites,
 // helper rebranding, and signing. A vendored bundle is rebuilt only when this
@@ -1335,6 +1338,14 @@ function writeChatGPTConfig(
     }
   }
 
+  const unmanagedToml = stripManagedChatGPTToml(currentToml);
+  const userDeveloperInstructions = readTopLevelTomlString(unmanagedToml, "developer_instructions");
+  const developerInstructions = userDeveloperInstructions
+    ? `${userDeveloperInstructions}\n\n${IMPEL_CODEX_PARENT_DELEGATION_INSTRUCTIONS}`
+    : IMPEL_CODEX_PARENT_DELEGATION_INSTRUCTIONS;
+  const preservedToml = userDeveloperInstructions
+    ? removeTopLevelTomlString(unmanagedToml, "developer_instructions")
+    : unmanagedToml;
   const managedToml = [
     CHATGPT_CONFIG_START,
     `# Managed by \`${RUNTIME_BRAND.cli.command} app update\`. This profile is isolated from ~/.codex.`,
@@ -1347,6 +1358,9 @@ function writeChatGPTConfig(
     `model_catalog_json = ${tomlString(paths.chatgpt.catalog)}`,
     ...(selectedEffort ? [`model_reasoning_effort = ${tomlString(selectedEffort)}`] : []),
     ...(selectedTier ? [`service_tier = ${tomlString(selectedTier)}`] : []),
+    ...(RUNTIME_BRAND.features.agents
+      ? [`developer_instructions = ${tomlString(developerInstructions)}`]
+      : []),
     "",
     // The built-in ChatGPT provider derives its inference endpoint from
     // chatgpt.com even when chatgpt_base_url points at the gateway. Keep the
@@ -1383,7 +1397,7 @@ function writeChatGPTConfig(
     ] : []),
     CHATGPT_CONFIG_END,
   ].join("\n");
-  const mergedToml = mergeManagedChatGPTToml(currentToml, managedToml);
+  const mergedToml = mergeManagedChatGPTToml(preservedToml, managedToml);
   writeAtomic(configPath, hardenManagedCodexToml(mergedToml, configPath), 0o600);
   secureManagedCodexHome(paths.chatgpt.codexHome);
 }
@@ -1605,6 +1619,16 @@ function readTopLevelTomlString(toml, key) {
   }
 }
 
+function removeTopLevelTomlString(toml, key) {
+  const tableIndex = toml.search(/^\s*\[/mu);
+  const topLevelEnd = tableIndex === -1 ? toml.length : tableIndex;
+  const topLevel = toml.slice(0, topLevelEnd).replace(
+    new RegExp(`^\\s*${escapeRegex(key)}\\s*=\\s*"(?:[^"\\\\]|\\\\.)*"\\s*\\r?\\n?`, "mu"),
+    "",
+  );
+  return topLevel + toml.slice(topLevelEnd);
+}
+
 /**
  * Rewrite one tenant's app token helper with the current node/CLI paths.
  * Cheap and Impel-owned, so install recovery can use it to heal helpers whose

package/src/cli.js

@@ -35,7 +35,8 @@ Get started:
 Work:
   impel claude [args...]                      Launch Claude Code with an isolated Impel profile
   impel codex [args...]                       Launch Codex with an isolated Impel profile
-  impel remote up|status|attach|down          Run a local repository on AWS Fargate
+  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
   impel tenant current                        Show the CLI's current organization
   impel tenant use <org>                      Select the organization for CLI launches

package/src/commands/launch.js

@@ -15,6 +15,7 @@ import {
   saveConfig,
 } from "../config.js";
 import { impelClaudeBaseUrl, impelCrossAppClaudeBaseUrl } from "../claudeSetup.js";
+import { parentVerbatimRelayAppendix } from "../verbatimRelay.js";
 import { withGitEnvironment } from "../skills.js";
 import { assertProviderScopes, ensureTenantSelection, tenantCredential } from "../tenants.js";
 import { maybePrintUpdateNotice } from "../updates.js";
@@ -49,10 +50,18 @@ export {
 
 export const IMPEL_SPECIALIST_DELEGATION_INSTRUCTIONS = `You are running in an Impel tenant-scoped session. Before starting any non-trivial task, call the Impel MCP tool list_specialists. If exactly one available specialist clearly matches the user's request, its capabilities and its exclusions, delegate the complete request by calling start_specialist_run exactly once with a stable idempotency key, then call read_specialist_run until it reaches a terminal state. When the run succeeds, use the specialist's result as your response instead of redoing the work. If no specialist clearly matches, the tools are unavailable, or the run fails, continue normally yourself. Do not delegate trivial requests, do not call a specialist excluded from the request, and never invent a specialist result.`;
 
+export const IMPEL_CUSTOM_AGENT_VERBATIM_RELAY_APPENDIX = parentVerbatimRelayAppendix();
+
+export const IMPEL_CLAUDE_PARENT_DELEGATION_INSTRUCTIONS =
+  `${IMPEL_SPECIALIST_DELEGATION_INSTRUCTIONS} ${IMPEL_CUSTOM_AGENT_VERBATIM_RELAY_APPENDIX}`;
+
 export const IMPEL_CODEX_SPECIALIST_DELEGATION_INSTRUCTIONS =
   `${IMPEL_SPECIALIST_DELEGATION_INSTRUCTIONS} ` +
   `Codex can defer MCP tools behind tool_search. If an Impel specialist tool is not directly visible, call tool_search for its exact name before treating it as unavailable: impel_specialists-list_specialists for discovery, impel_specialists-start_specialist_run to delegate, and impel_specialists-read_specialist_run to poll the result. Use the returned tool for the same one-run delegation flow.`;
 
+export const IMPEL_CODEX_PARENT_DELEGATION_INSTRUCTIONS =
+  `${IMPEL_CODEX_SPECIALIST_DELEGATION_INSTRUCTIONS} ${IMPEL_CUSTOM_AGENT_VERBATIM_RELAY_APPENDIX}`;
+
 const IMPEL_CODEX_RUNTIME_OVERRIDES = [
   // Codex models may select code mode even when the standalone
   // `codex-code-mode-host` companion is not present in the vendor install.
@@ -64,14 +73,14 @@ const IMPEL_CODEX_RUNTIME_OVERRIDES = [
 export function impelLaunchArguments(tool, argv) {
   if (!RUNTIME_BRAND.features.agents) return [...argv];
   if (tool === "claude") {
-    return ["--append-system-prompt", IMPEL_SPECIALIST_DELEGATION_INSTRUCTIONS, ...argv];
+    return ["--append-system-prompt", IMPEL_CLAUDE_PARENT_DELEGATION_INSTRUCTIONS, ...argv];
   }
   if (tool === "codex") {
     // `-c` is a Codex global option, so it must precede subcommands such as
     // `exec`, `resume`, and `mcp`. JSON strings are valid TOML basic strings.
     return [
       "-c",
-      `developer_instructions=${JSON.stringify(IMPEL_CODEX_SPECIALIST_DELEGATION_INSTRUCTIONS)}`,
+      `developer_instructions=${JSON.stringify(IMPEL_CODEX_PARENT_DELEGATION_INSTRUCTIONS)}`,
       ...IMPEL_CODEX_RUNTIME_OVERRIDES.flatMap((override) => ["-c", override]),
       ...argv,
     ];

package/src/commands/mcp.js

@@ -9,6 +9,7 @@ import {
 } from "../config.js";
 import { parseFlags } from "../args.js";
 import {
+  NATIVE_AGENT_ANSWER_TOOL,
   NATIVE_AGENT_RECOVER_TOOL,
   NATIVE_AGENT_RESUME_TOOL,
   NATIVE_AGENT_RUN_TOOL,
@@ -193,8 +194,9 @@ export function runNativeAgentMcpServer({
   transport,
   input = process.stdin,
   output = process.stdout,
-  recoveryOnly = false,
+  mode = "durable",
 }) {
+  if (!["durable", "recovery", "answer"].includes(mode)) throw new Error("invalid native-agent MCP mode");
   const lines = readline.createInterface({ input, crlfDelay: Infinity });
   const active = new Map();
   const pending = new Set();
@@ -231,7 +233,9 @@ export function runNativeAgentMcpServer({
           return;
         }
         if (message.method === "tools/list") {
-          write(nativeRpcResult(message.id, { tools: nativeAgentCompositeTools({ recoveryOnly }) }));
+          write(nativeRpcResult(message.id, {
+            tools: nativeAgentCompositeTools({ mode }),
+          }));
           return;
         }
         if (message.method !== "tools/call") {
@@ -249,12 +253,18 @@ export function runNativeAgentMcpServer({
           }));
         };
         let value;
-        if (name === NATIVE_AGENT_RUN_TOOL) {
-          if (recoveryOnly) throw new Error("retired native-agent bindings cannot start new runs");
+        if (name === NATIVE_AGENT_ANSWER_TOOL) {
+          if (mode !== "answer") throw new Error("this native-agent binding cannot answer directly");
+          value = await transport.answer(args, { signal: controller.signal });
+        } else if (name === NATIVE_AGENT_RUN_TOOL) {
+          if (mode === "recovery") throw new Error("retired native-agent bindings cannot start new runs");
+          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");
@@ -268,7 +278,9 @@ export function runNativeAgentMcpServer({
           error: {
             code: cancelled ? -32800 : -32000,
             message: cancelled
-              ? "Native-agent attachment cancelled; resume it with the same handle."
+              ? (mode === "answer"
+                ? "Direct-answer native-agent call cancelled; retry the answer request if needed."
+                : "Native-agent attachment cancelled; resume it with the same handle.")
               : redactSecretText(error?.message || error),
           },
         }));
@@ -306,6 +318,7 @@ export async function cmdMcp(argv = []) {
     "scope-param": { type: "string" },
     "policy-fingerprint": { type: "string" },
     "recovery-only": { type: "boolean" },
+    "answer-only": { type: "boolean" },
   });
   const targetSpecified = Object.hasOwn(flags, "target");
   if (targetSpecified && ![TASKS_TARGET, IMPEL_NATIVE_AGENT_MCP_TARGET].includes(flags.target)) {
@@ -323,7 +336,10 @@ export async function cmdMcp(argv = []) {
     }
   }
   if (nativeAgentTarget) {
-    const expectedFlags = ["target", "tenant", "agent-id", "scope-param", "policy-fingerprint", "recovery-only"];
+    const expectedFlags = [
+      "target", "tenant", "agent-id", "scope-param", "policy-fingerprint",
+      "recovery-only", "answer-only",
+    ];
     const unsupportedFlags = Object.keys(flags).filter((name) => !expectedFlags.includes(name));
     if (unsupportedFlags.length > 0 || positionals.length > 0) {
       throw new Error("unsupported native-agent MCP arguments");
@@ -333,10 +349,14 @@ export async function cmdMcp(argv = []) {
         throw new Error(`native-agent MCP requires a fixed --${flag} argument`);
       }
     }
+    if (flags["recovery-only"] === true && flags["answer-only"] === true) {
+      throw new Error("native-agent MCP cannot be both recovery-only and answer-only");
+    }
   } else if (!tasksTarget && (Object.hasOwn(flags, "agent-id")
     || Object.hasOwn(flags, "scope-param")
     || Object.hasOwn(flags, "policy-fingerprint")
-    || Object.hasOwn(flags, "recovery-only"))) {
+    || Object.hasOwn(flags, "recovery-only")
+    || Object.hasOwn(flags, "answer-only"))) {
     throw new Error("native-agent binding flags require `--target native-agent`");
   }
   const config = loadConfig();
@@ -358,7 +378,9 @@ export async function cmdMcp(argv = []) {
         gatewayUrl,
         credential,
       }),
-      recoveryOnly: flags["recovery-only"] === true,
+      mode: flags["recovery-only"] === true
+        ? "recovery"
+        : (flags["answer-only"] === true ? "answer" : "durable"),
     });
   }
   const endpoint = tasksTarget ? null : `${gatewayUrl}/mcp`;