impel-cli 0.20.13 → 0.20.15

package/src/agents.js

@@ -16,6 +16,7 @@ import {
   redactSecretText,
 } from "./config.js";
 import {
+  IMPEL_NATIVE_AGENT_TELEMETRY_ENV_NAMES,
   IMPEL_NATIVE_AGENT_MCP_TARGET,
   impelNativeAgentMcpInvocation,
 } from "./selfInvocation.js";
@@ -51,7 +52,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 = 9;
+export const MANAGED_AGENT_MANIFEST_VERSION = 10;
 
 const NATIVE_AGENT_TOOL_NAMES = [
   NATIVE_AGENT_RUN_TOOL,
@@ -631,8 +632,12 @@ function claudeAdapterInstructions(tenantId, agent) {
   ].join(" ");
 }
 
+export function nativeToolNamespace(serverName = MANAGED_AGENT_MCP_SERVER) {
+  return `mcp__${serverName}`;
+}
+
 function nativeToolName(toolName) {
-  return `mcp__${MANAGED_AGENT_MCP_SERVER}__${toolName}`;
+  return `${nativeToolNamespace()}__${toolName}`;
 }
 
 function codexAdapterInstructions(tenantId, agent) {
@@ -732,23 +737,46 @@ function renderClaudeAgent({ tenantId, agent, name, invocation, recoveryOnly = f
   return lines.join("\n");
 }
 
-function renderCodexAgent({ tenantId, agent, name, invocation, recoveryOnly = false }) {
+function codexInvocationEnvironment(invocation, { durableProfile = false } = {}) {
+  const entries = Object.entries(invocation.env || {});
+  if (!durableProfile) return entries;
+  const transient = new Set(IMPEL_NATIVE_AGENT_TELEMETRY_ENV_NAMES);
+  return entries.filter(([key]) => !transient.has(key));
+}
+
+function renderCodexConfiguration({
+  tenantId,
+  agent,
+  name,
+  invocation,
+  recoveryOnly = false,
+  durableProfile = false,
+  directCodeMode = true,
+}) {
   const description = recoveryOnly
     ? `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 || {})
+  const envEntries = codexInvocationEnvironment(invocation, { durableProfile })
     .map(([key, value]) => `${JSON.stringify(key)} = ${JSON.stringify(value)}`)
     .join(", ");
   const lines = [
-    `name = ${JSON.stringify(name)}`,
-    `description = ${JSON.stringify(description)}`,
+    ...(!durableProfile ? [
+      `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))}`,
     "",
+    ...(directCodeMode ? [
+      "[features.code_mode]",
+      "enabled = true",
+      `direct_only_tool_namespaces = [${JSON.stringify(nativeToolNamespace())}]`,
+      "",
+    ] : []),
     `[mcp_servers.${MANAGED_AGENT_MCP_SERVER}]`,
     `command = ${JSON.stringify(invocation.command)}`,
     `args = [${invocation.args.map((argument) => JSON.stringify(argument)).join(", ")}]`,
@@ -764,6 +792,14 @@ function renderCodexAgent({ tenantId, agent, name, invocation, recoveryOnly = fa
   return lines.join("\n");
 }
 
+function renderCodexAgent(options) {
+  return renderCodexConfiguration(options);
+}
+
+function renderCodexProfile(options) {
+  return renderCodexConfiguration({ ...options, durableProfile: true });
+}
+
 function boundNativeAgentInvocation(tenantId, agent, invocation, {
   policyFingerprint = nativeAgentPolicyFingerprint(agent),
   mode = usesDirectAnswer(agent) ? "answer" : "durable",
@@ -794,7 +830,7 @@ function boundNativeAgentInvocation(tenantId, agent, invocation, {
   };
 }
 
-export function renderManagedAgents(client, tenantId, agents, invocation = null) {
+export function renderManagedAgents(client, tenantId, agents, invocation = null, { directCodeMode = true } = {}) {
   if (client !== "claude" && client !== "codex") throw new Error(`unknown agent client ${client}`);
   const normalizedTenant = normalizeTenantId(tenantId);
   const fileStems = generatedAgentFileStems(normalizedTenant, agents);
@@ -811,20 +847,34 @@ export function renderManagedAgents(client, tenantId, agents, invocation = null)
     const boundInvocation = boundNativeAgentInvocation(normalizedTenant, agent, invocation);
     const contents = client === "claude"
       ? renderClaudeAgent({ tenantId: normalizedTenant, agent, name, invocation: boundInvocation })
-      : renderCodexAgent({ tenantId: normalizedTenant, agent, name, invocation: boundInvocation });
+      : renderCodexAgent({ tenantId: normalizedTenant, agent, name, invocation: boundInvocation, directCodeMode });
+    const profileName = client === "codex" ? fileStem : null;
     return {
       agentId: agent.agentId,
+      title: agent.title,
+      sideEffects: agent.sideEffects,
       scopeParam: agent.scopeParam,
       policyFingerprint: nativeAgentPolicyFingerprint(agent),
       retired: false,
       name,
       fileName: `${fileStem}${extension}`,
       contents,
+      ...(profileName ? {
+        profileName,
+        profileFileName: `${profileName}.config.toml`,
+        profileContents: renderCodexProfile({
+          tenantId: normalizedTenant,
+          agent,
+          name,
+          invocation: boundInvocation,
+          directCodeMode,
+        }),
+      } : {}),
     };
   });
 }
 
-function renderRetiredManagedAgents(client, tenantId, bindings, active, invocation = null) {
+function renderRetiredManagedAgents(client, tenantId, bindings, active, invocation = null, { directCodeMode = true } = {}) {
   const usedNames = new Set(active.map(({ name }) => name));
   const usedFiles = new Set(active.map(({ fileName }) => fileName));
   return bindings.map((binding) => {
@@ -865,15 +915,30 @@ function renderRetiredManagedAgents(client, tenantId, bindings, active, invocati
     });
     const contents = client === "claude"
       ? renderClaudeAgent({ tenantId, agent, name, invocation: boundInvocation, recoveryOnly: true })
-      : renderCodexAgent({ tenantId, agent, name, invocation: boundInvocation, recoveryOnly: true });
+      : renderCodexAgent({ tenantId, agent, name, invocation: boundInvocation, recoveryOnly: true, directCodeMode });
+    const profileName = client === "codex" ? path.basename(fileName, extension) : null;
     return {
       agentId: binding.agentId,
+      title: agent.title,
+      sideEffects: agent.sideEffects,
       scopeParam: binding.scopeParam,
       policyFingerprint: binding.policyFingerprint,
       retired: true,
       name,
       fileName,
       contents,
+      ...(profileName ? {
+        profileName,
+        profileFileName: `${profileName}.config.toml`,
+        profileContents: renderCodexProfile({
+          tenantId,
+          agent,
+          name,
+          invocation: boundInvocation,
+          recoveryOnly: true,
+          directCodeMode,
+        }),
+      } : {}),
     };
   });
 }
@@ -903,16 +968,112 @@ function readManifest(manifestPath) {
   }
 }
 
+function managedManifestPath(root) {
+  return path.join(root, "agents", MANAGED_AGENT_DIRECTORY, MANAGED_AGENT_MANIFEST);
+}
+
+function contentDigest(contents) {
+  return crypto.createHash("sha256").update(contents, "utf8").digest("hex");
+}
+
+function managedArtifactIsCurrent(root, relativePath, expectedDigest) {
+  if (typeof relativePath !== "string" || !relativePath || path.isAbsolute(relativePath)) return false;
+  const segments = relativePath.split("/");
+  if (segments.some((segment) => !segment || segment === "." || segment === "..")) return false;
+  if (!/^[a-f0-9]{64}$/u.test(expectedDigest || "")) return false;
+  const artifactPath = path.join(root, ...segments);
+  try {
+    if (fs.lstatSync(artifactPath).isSymbolicLink()) return false;
+    return contentDigest(fs.readFileSync(artifactPath, "utf8")) === expectedDigest;
+  } catch {
+    return false;
+  }
+}
+
+function managedArtifactExists(root, relativePath, expectedDigest) {
+  if (typeof relativePath !== "string" || !relativePath || path.isAbsolute(relativePath)) return false;
+  const segments = relativePath.split("/");
+  if (segments.some((segment) => !segment || segment === "." || segment === "..")) return false;
+  if (!/^[a-f0-9]{64}$/u.test(expectedDigest || "")) return false;
+  try {
+    const stat = fs.lstatSync(path.join(root, ...segments));
+    return stat.isFile() && !stat.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+export function readManagedAgentManifest(root) {
+  return readManifest(managedManifestPath(root));
+}
+
+export function resolveManagedCodexAgentProfile(root, tenantId, selector) {
+  const normalizedTenant = normalizeTenantId(tenantId);
+  const normalizedSelector = boundedString(selector, "agent selector", { max: 512 });
+  const manifest = readManagedAgentManifest(root);
+  if (!manifest
+    || manifest.version !== MANAGED_AGENT_MANIFEST_VERSION
+    || manifest.client !== "codex"
+    || manifest.tenantId !== normalizedTenant
+    || !Array.isArray(manifest.agents)) {
+    throw new Error("the managed Codex agent catalog is missing or stale; run `impel agents sync codex`");
+  }
+  const records = manifest.agents.filter((record) => record
+    && typeof record === "object"
+    && typeof record.profileName === "string"
+    && typeof record.profileFileName === "string");
+  const active = records.filter((record) => !record.retired);
+  let matches = active.filter((record) => record.agentId === normalizedSelector);
+  if (matches.length === 0) matches = active.filter((record) => record.title === normalizedSelector);
+  if (matches.length === 0) matches = active.filter((record) => record.profileName === normalizedSelector);
+  if (matches.length === 0 && records.some((record) => record.retired && [
+    record.agentId,
+    record.title,
+    record.profileName,
+  ].includes(normalizedSelector))) {
+    throw new Error(`managed Codex agent ${JSON.stringify(normalizedSelector)} is retired and cannot start new work`);
+  }
+  if (matches.length !== 1) {
+    const reason = matches.length > 1 ? "is ambiguous" : "was not found";
+    throw new Error(`managed Codex agent ${JSON.stringify(normalizedSelector)} ${reason} for tenant ${JSON.stringify(normalizedTenant)}`);
+  }
+  const [record] = matches;
+  if (path.basename(record.profileFileName) !== record.profileFileName
+    || record.profileFileName !== `${record.profileName}.config.toml`) {
+    throw new Error("the managed Codex agent profile mapping is invalid; run `impel agents sync codex`");
+  }
+  const relativePath = record.profileFileName;
+  if (!managedArtifactIsCurrent(root, relativePath, manifest.contentDigests?.[relativePath])) {
+    throw new Error("the managed Codex agent profile failed its integrity check; run `impel agents sync codex`");
+  }
+  return { ...record, path: path.join(root, relativePath) };
+}
+
 function profileIsFresh(profile, tenantId, now, ttlMs) {
-  const manifest = readManifest(path.join(profile.root, "agents", MANAGED_AGENT_DIRECTORY, MANAGED_AGENT_MANIFEST));
+  const manifest = readManagedAgentManifest(profile.root);
   if (!manifest || manifest.version !== MANAGED_AGENT_MANIFEST_VERSION || manifest.tenantId !== tenantId) return false;
+  if (!Array.isArray(manifest.files) || !manifest.contentDigests
+    || typeof manifest.contentDigests !== "object"
+    || Array.isArray(manifest.contentDigests)) return false;
+  const expectedDirectProfiles = profile.client === "codex" && profile.directProfiles !== false;
+  const expectedDirectCodeMode = profile.client === "codex" && profile.directCodeMode !== false;
+  if (manifest.directProfiles !== expectedDirectProfiles
+    || manifest.directCodeMode !== expectedDirectCodeMode) return false;
   const syncedAt = Date.parse(manifest.syncedAt || "");
   if (!Number.isFinite(syncedAt) || now - syncedAt >= ttlMs) return false;
-  return manifest.files.every((fileName) =>
-    typeof fileName === "string"
-    && path.basename(fileName) === fileName
-    && fs.existsSync(path.join(profile.root, "agents", fileName))
-  );
+  const artifacts = [
+    ...manifest.files.map((fileName) => `agents/${fileName}`),
+    ...(Array.isArray(manifest.profiles) ? manifest.profiles : []),
+  ];
+  // Renderer changes are invalidated by the manifest version/capability fields
+  // above. Keep ordinary launch freshness O(number of files) metadata-only;
+  // the explicitly selected direct profile gets a full SHA-256 verification
+  // in resolveManagedCodexAgentProfile before Codex starts.
+  return artifacts.every((relativePath) => managedArtifactExists(
+    profile.root,
+    relativePath,
+    manifest.contentDigests?.[relativePath],
+  ));
 }
 
 export function syncAgentProfile({
@@ -921,6 +1082,8 @@ export function syncAgentProfile({
   label,
   tenantId,
   agents,
+  directProfiles = client === "codex",
+  directCodeMode = client === "codex",
   now = Date.now(),
   nativeAgentRunsRoot = path.join(CONFIG_DIR, "native-agent-runs"),
 }) {
@@ -934,7 +1097,7 @@ export function syncAgentProfile({
   privateDirectory(managedDir);
   const manifestPath = path.join(managedDir, MANAGED_AGENT_MANIFEST);
   const prior = readManifest(manifestPath);
-  const active = renderManagedAgents(client, tenantId, agents);
+  const active = renderManagedAgents(client, tenantId, agents, null, { directCodeMode });
   const activeBindings = new Set(active.map((agent) =>
     `${agent.agentId}\0${agent.scopeParam}\0${agent.policyFingerprint}`
   ));
@@ -942,16 +1105,22 @@ export function syncAgentProfile({
     .filter((binding) => !activeBindings.has(
       `${binding.agentId}\0${binding.scopeParam}\0${binding.policyFingerprint}`,
     ));
-  const retired = renderRetiredManagedAgents(client, tenantId, retiredBindings, active);
+  const retired = renderRetiredManagedAgents(client, tenantId, retiredBindings, active, null, { directCodeMode });
   const rendered = [...active, ...retired];
   if (new Set(rendered.map(({ name }) => name)).size !== rendered.length
-    || new Set(rendered.map(({ fileName }) => fileName)).size !== rendered.length) {
+    || new Set(rendered.map(({ fileName }) => fileName)).size !== rendered.length
+    || (client === "codex" && directProfiles
+      && new Set(rendered.map(({ profileFileName }) => profileFileName)).size !== rendered.length)) {
     throw new Error("generated native-agent destinations are not unique");
   }
   const priorFiles = new Set(prior?.files || []);
+  const priorProfiles = new Set(prior?.profiles || []);
   const priorUsesDiscoveryRoot = Number.isInteger(prior?.version)
     && prior.version >= 2
     && prior.version <= MANAGED_AGENT_MANIFEST_VERSION;
+  const priorOwnsCodexProfiles = priorUsesDiscoveryRoot
+    && prior?.client === "codex"
+    && prior?.tenantId === tenantId;
 
   // Native clients discover standalone definitions directly under `agents/`.
   // Preflight every destination before writing so an unmanaged file with the
@@ -966,11 +1135,26 @@ export function syncAgentProfile({
         throw new Error(`refusing to overwrite symlinked native-agent file ${destination}`);
       }
     }
+    if (client === "codex" && directProfiles) {
+      const profileDestination = path.join(root, agent.profileFileName);
+      if (fs.existsSync(profileDestination)) {
+        if (fs.lstatSync(profileDestination).isSymbolicLink()) {
+          throw new Error(`refusing to overwrite symlinked Codex profile ${profileDestination}`);
+        }
+        if (!priorOwnsCodexProfiles || !priorProfiles.has(agent.profileFileName)) {
+          throw new Error(`refusing to overwrite unmanaged Codex profile ${profileDestination}`);
+        }
+      }
+    }
   }
   for (const agent of rendered) {
     atomicPrivateWrite(path.join(agentsDir, agent.fileName), agent.contents);
+    if (client === "codex" && directProfiles) atomicPrivateWrite(path.join(root, agent.profileFileName), agent.profileContents);
   }
   const currentFiles = new Set(rendered.map((agent) => agent.fileName));
+  const currentProfiles = new Set(client === "codex" && directProfiles
+    ? rendered.map((agent) => agent.profileFileName)
+    : []);
   for (const stale of prior?.files || []) {
     if (
       typeof stale === "string"
@@ -981,6 +1165,16 @@ export function syncAgentProfile({
       fs.rmSync(path.join(priorUsesDiscoveryRoot ? agentsDir : managedDir, stale), { force: true });
     }
   }
+  for (const stale of priorOwnsCodexProfiles ? prior.profiles || [] : []) {
+    if (
+      typeof stale === "string"
+      && path.basename(stale) === stale
+      && stale.endsWith(".config.toml")
+      && !currentProfiles.has(stale)
+    ) {
+      fs.rmSync(path.join(root, stale), { force: true });
+    }
+  }
   if (!priorUsesDiscoveryRoot) {
     for (const legacy of prior?.files || []) {
       if (
@@ -992,18 +1186,34 @@ export function syncAgentProfile({
       }
     }
   }
+  const contentDigests = Object.fromEntries(rendered.flatMap((agent) => [
+    [`agents/${agent.fileName}`, contentDigest(agent.contents)],
+    ...(client === "codex" && directProfiles
+      ? [[agent.profileFileName, contentDigest(agent.profileContents)]]
+      : []),
+  ]).sort(([left], [right]) => left.localeCompare(right)));
   atomicPrivateWrite(manifestPath, `${JSON.stringify({
     version: MANAGED_AGENT_MANIFEST_VERSION,
     tenantId,
     client,
+    directProfiles: client === "codex" && directProfiles,
+    directCodeMode: client === "codex" && directCodeMode,
     syncedAt: new Date(now).toISOString(),
     files: [...currentFiles].sort(),
+    profiles: [...currentProfiles].sort(),
+    contentDigests,
     agents: rendered.map((agent) => ({
       agentId: agent.agentId,
+      title: agent.title,
+      sideEffects: agent.sideEffects,
       scopeParam: agent.scopeParam,
       policyFingerprint: agent.policyFingerprint,
       retired: agent.retired,
       name: agent.name,
+      ...(client === "codex" && directProfiles ? {
+        profileName: agent.profileName,
+        profileFileName: agent.profileFileName,
+      } : {}),
     })),
   }, null, 2)}\n`);
   return {
@@ -1014,6 +1224,7 @@ export function syncAgentProfile({
     count: active.length,
     recoveryCount: retired.length,
     files: [...currentFiles],
+    profiles: [...currentProfiles],
   };
 }
 

package/src/apps.js

@@ -108,8 +108,8 @@ export const PINNED_VENDOR_APPS = Object.freeze({
       // The Microsoft Store manifest identifies this exact reviewed build.
       // Keep one Windows package version so the manifest contract and local
       // AppX validation cannot silently drift apart again.
-      packageVersion: "26.730.8199.0",
-      codexVersion: "0.147.0-alpha.1.2",
+      packageVersion: "26.803.5235.0",
+      codexVersion: "0.147.0-alpha.6.5",
       publisherId: "2p2nqsd0c76g0",
       executable: "app\\ChatGPT.exe",
       updateManifestUrl: "https://persistent.oaistatic.com/codex-app-prod/windows-store-update.json",
@@ -279,7 +279,9 @@ export function managedAppIdentity(target, tenantId = null, tenantName = null) {
 // transport and remove model-controlled upstream start/read polling.
 // 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;
+// 30: generate integrity-tracked top-level Codex profiles and direct code-mode
+// namespaces for fixed native-agent bindings.
+export const CURRENT_CONFIG_VERSION = 30;
 
 // Identifies the bundle-BUILDING logic — the asar patches, plist rewrites,
 // helper rebranding, and signing. A vendored bundle is rebuilt only when this

package/src/cli.js

@@ -35,6 +35,7 @@ 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 codex --agent <id|exact-title> ...    Run one fixed tenant agent without a parent hop
   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,10 @@ export function managedAgentProfiles(client, options = {}) {
       environment,
       homeDir,
     }),
+    ...(client === "codex" ? {
+      directProfiles: profile.label !== "Codex CLI (native profile)",
+      directCodeMode: profile.label !== "Codex CLI (native profile)",
+    } : {}),
   }));
 }
 

package/src/commands/launch.js

@@ -6,7 +6,7 @@ import {
   ensureImpelClaudeProfile,
   ensureImpelCodexProfile,
 } from "../cliProfiles.js";
-import { syncAgentProfilesSafe } from "../agents.js";
+import { resolveManagedCodexAgentProfile, syncAgentProfilesSafe } from "../agents.js";
 import {
   crossAppModelsEnabled,
   loadConfig,
@@ -77,7 +77,7 @@ const IMPEL_CODEX_RUNTIME_OVERRIDES = [
   "features.code_mode_host=false",
 ];
 
-export function impelLaunchArguments(tool, argv) {
+export function impelLaunchArguments(tool, argv, { codexAgentProfile = null } = {}) {
   if (!RUNTIME_BRAND.features.agents) return [...argv];
   if (tool === "claude") {
     return ["--append-system-prompt", IMPEL_CLAUDE_PARENT_DELEGATION_INSTRUCTIONS, ...argv];
@@ -86,8 +86,10 @@ export function impelLaunchArguments(tool, argv) {
     // `-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_PARENT_DELEGATION_INSTRUCTIONS)}`,
+      ...(codexAgentProfile ? ["--profile", codexAgentProfile] : [
+        "-c",
+        `developer_instructions=${JSON.stringify(IMPEL_CODEX_PARENT_DELEGATION_INSTRUCTIONS)}`,
+      ]),
       ...IMPEL_CODEX_RUNTIME_OVERRIDES.flatMap((override) => ["-c", override]),
       ...argv,
     ];
@@ -95,6 +97,91 @@ export function impelLaunchArguments(tool, argv) {
   throw new Error(`unsupported CLI launcher: ${tool}`);
 }
 
+const CODEX_AGENT_LOCKED_OPTIONS = new Set([
+  "-c",
+  "--config",
+  "-m",
+  "--model",
+  "-p",
+  "--profile",
+  "-s",
+  "--sandbox",
+  "-a",
+  "--ask-for-approval",
+  "--enable",
+  "--disable",
+  "--full-auto",
+  "--approve-for-me",
+  "--dangerously-bypass-approvals-and-sandbox",
+  "--dangerously-bypass-hook-trust",
+  "--oss",
+  "--local-provider",
+  "--search",
+]);
+
+function codexAgentLockedOption(argument) {
+  if (CODEX_AGENT_LOCKED_OPTIONS.has(argument)) return argument;
+  const withEquals = [...CODEX_AGENT_LOCKED_OPTIONS].find((option) =>
+    argument.startsWith(`${option}=`)
+  );
+  if (withEquals) return withEquals;
+  return ["-c", "-m", "-p", "-s", "-a"].find((option) =>
+    argument.length > option.length && argument.startsWith(option)
+  ) || null;
+}
+
+export function parseCodexAgentLaunchArguments(argv) {
+  const passthrough = [];
+  let selector = null;
+  let literal = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (literal) {
+      passthrough.push(argument);
+      continue;
+    }
+    if (argument === "--") {
+      literal = true;
+      passthrough.push(argument);
+      continue;
+    }
+    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);
+      if (typeof value !== "string" || !value.trim() || value.startsWith("-")) {
+        throw new Error("`--agent` requires an exact agent ID or title");
+      }
+      selector = value.trim();
+      continue;
+    }
+    passthrough.push(argument);
+  }
+  if (selector !== null) {
+    for (const argument of passthrough) {
+      if (argument === "--") break;
+      const locked = codexAgentLockedOption(argument);
+      if (locked) {
+        throw new Error(
+          `${locked} cannot be used with \`--agent\`; the managed profile locks model, instructions, tools, approvals, and sandbox policy`,
+        );
+      }
+    }
+  }
+  return { selector, argv: passthrough };
+}
+
+function codexJsonOutput(argv) {
+  return argv.some((argument) => argument === "--json" || argument.startsWith("--json="));
+}
+
+function agentSyncLogger(argv) {
+  if (!codexJsonOutput(argv)) return console;
+  return {
+    log: (...args) => console.error(...args),
+    warn: (...args) => console.error(...args),
+  };
+}
+
 function deleteEnvironmentKeys(environment, keys) {
   for (const key of keys) delete environment[key];
 }
@@ -174,6 +261,17 @@ function runNativeCli(tool, argv, environment) {
 }
 
 export async function cmdLaunch(tool, argv) {
+  let nativeArgv = [...argv];
+  let codexAgentSelector = null;
+  if (tool === "codex") {
+    try {
+      ({ selector: codexAgentSelector, argv: nativeArgv } = parseCodexAgentLaunchArguments(argv));
+    } catch (error) {
+      console.error(`impel codex: ${error.message}`);
+      process.exitCode = 1;
+      return;
+    }
+  }
   const config = loadConfig();
   if (!config?.pat) {
     console.error(`impel ${tool}: not authenticated. Run \`impel auth\` first.`);
@@ -199,7 +297,7 @@ export async function cmdLaunch(tool, argv) {
     return;
   }
   const gatewayCredential = tenantCredential(config.pat, tenantId);
-  if (!localInformationRequest(argv)) {
+  if (!localInformationRequest(nativeArgv)) {
     try {
       await assertLiveProviderReadiness({
         config,
@@ -252,13 +350,33 @@ export async function cmdLaunch(tool, argv) {
       credential: gatewayCredential,
       tenantId,
       staleOnly: true,
+      logger: agentSyncLogger(nativeArgv),
     });
   }
 
+  let codexAgentProfile = null;
+  if (codexAgentSelector !== null) {
+    try {
+      codexAgentProfile = resolveManagedCodexAgentProfile(
+        agentProfile.root,
+        tenantId,
+        codexAgentSelector,
+      ).profileName;
+    } catch (error) {
+      console.error(`impel codex: ${redactSecretText(error?.message || error)}`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   // Both vendor CLIs shell out to `git` for plugin/marketplace operations; on
   // a fresh Windows machine the installed git (typically the Impel-managed
   // MinGit) sits off the inherited PATH, so repair it for the child session.
   const { env: launchEnvironment } = withGitEnvironment(environment, { baseEnvironment: environment });
-  const exitCode = await runNativeCli(tool, impelLaunchArguments(tool, argv), launchEnvironment);
+  const exitCode = await runNativeCli(
+    tool,
+    impelLaunchArguments(tool, nativeArgv, { codexAgentProfile }),
+    launchEnvironment,
+  );
   if (exitCode !== 0) process.exitCode = exitCode;
 }