impel-cli 0.9.1 → 0.10.0

package/README.md

@@ -118,7 +118,8 @@ impel setup [--pat <pat>] [--tenant <org>] [--skip-apps] [--skip-clis]
                                               apps, then installs the vendored Impel apps on macOS;
                                               installs missing vendor CLIs on Windows)
 impel update [--check] [--skip-apps]         Update EVERYTHING: reinstall the CLI from npm, then
-                                             cascade to `app update all` and `skills sync all`
+                                             cascade to `app update all`, `skills sync all`, and
+                                             `agents sync all`
 impel auth [--pat <pat>] [--gateway <url>] [--app <url>]
                                              Store your Impel PAT + URLs
 impel pat create --label <label> [options]    Mint a personal PAT through the control plane
@@ -147,15 +148,16 @@ impel use account [claude|codex|all]         Revert to your own login    (defaul
 impel off [claude|codex|all]                 Alias for `impel use account`
 
 impel skills sync [claude|codex|all]         Sync Bifrost shared skills into managed clients (default: all)
+impel agents sync [claude|codex|all]         Sync the selected tenant's specialists as native agents
 
 impel status                                 Launcher readiness + native mode + gateway reachability
 impel app install [target] [--tenant <org>]  Install isolated apps for one tenant
 impel app update [target] [--tenant <org>]   Refresh that tenant's apps, configs, and models
-impel app refresh [target] [--tenant <org>]  Configs/catalog/skills only; safe while apps run
+impel app refresh [target] [--tenant <org>]  Configs/catalog/skills/agents only; safe while apps run
                                              (--stale-only: no-op unless 6h+ since last sync)
 impel app status [target] [--tenant <org>]   Show tenant launcher/vendor status
-impel app open [target] [--tenant <org>]     Launch isolated instances (fast path: opens
-                                             immediately when nothing changed since last open;
+impel app open [target] [--tenant <org>]     Install/configure a tenant on first use, then launch
+                                             it (later opens are immediate when nothing changed;
                                              a detached stale-only refresh keeps things current)
 impel app uninstall [target] [--tenant <org>] [--keep-data]
                                              Remove one tenant's Impel-managed app files
@@ -236,7 +238,8 @@ One command brings everything current, in dependency order: the CLI itself
 (`npm install -g impel-cli@latest` from npm, with no GitHub credentials),
 then — re-executing the freshly installed build — `impel app update all`
 (close running apps, install the CLI-pinned vendor builds, rebuild the vendored Impel apps)
-and `impel skills sync all` across every managed profile.
+followed by `impel skills sync all` and `impel agents sync all` across every
+managed profile.
 
 Update discovery compares the installed package version with npm's public
 `latest` metadata, cached for 6 hours in
@@ -248,8 +251,8 @@ remote is ahead, and refresh the cache in a detached background process when
 it's stale (TTY-only, never blocks a launch; set `IMPEL_SKIP_UPDATE_CHECK=1`
 to silence). The Impel desktop apps keep themselves current too: their token
 helper kicks off a detached `impel app refresh --stale-only` on use, which
-re-syncs configs, the model catalog, and skills at most every 6 hours — safe
-while the apps are running because it never swaps an app bundle.
+re-syncs configs, the model catalog, skills, and native agents at most every six
+hours — safe while the apps are running because it never swaps an app bundle.
 
 ### `impel tasks ...`  (aliases `impel task`, `impel tickets`, `impel ticket`)
 
@@ -292,9 +295,13 @@ On macOS, desktop app state is isolated under
 bundles in `~/Applications`, with names such as `Impel Claude (Acme)` and
 `Impel ChatGPT (Acme)`, stable tenant-specific bundle identifiers, and fixed
 tenant profile/auth paths. Different tenants can stay open concurrently.
-`impel app open --tenant <org>` refreshes and launches a tenant directly without
-changing the globally selected tenant. Switching tenants never deletes local
-history or projects; each tenant's preserved profile reopens independently.
+`impel app open --tenant <org>` installs and configures a missing tenant variant
+on first use, then launches it directly without changing the globally selected
+tenant. Later opens use the existing isolated app and profile. Switching tenants
+never deletes local history or projects; each tenant's preserved profile reopens
+independently. The first-use setup still requires an authenticated user PAT and
+live membership in the requested organization; it does not create a PAT per
+tenant.
 Windows Claude Desktop keeps each
 tenant under `%LOCALAPPDATA%\Claude-3p\Impel\<org>` and launches the unchanged
 signed vendor executable with that profile selected. Windows ChatGPT keeps its
@@ -385,7 +392,9 @@ MCP entry point, reads the PAT from the owner-only Impel
 config, and proxies JSON-RPC to `<gateway>/mcp`; the PAT is never written into
 either client's MCP configuration. Available specialists are discovered at
 runtime, so publishing a new opted-in specialist does not require another CLI
-release.
+release. The same authenticated catalog is rendered into native Claude Code
+and Codex agent definitions. Each definition carries only the direct
+`impel mcp --tenant <org>` subprocess invocation, never the PAT itself.
 
 ### Isolated CLI launchers
 
@@ -460,8 +469,9 @@ the selected tenant's 3P gateway configuration beneath Anthropic's reserved
 normal Claude profile unchanged. `impel app install codex` installs/updates
 OpenAI's `OpenAI.Codex` Store package, stages its unchanged signed app payload
 inside Impel's shared app cache, and writes separate Codex and Chromium
-profiles. `impel app open claude` and `impel app open codex` launch those
-isolated profiles without changing either normal vendor profile.
+profiles. `impel app open claude` and `impel app open codex` install a missing
+official app and configure the selected tenant on first use, then launch the
+isolated profile without changing either normal vendor profile.
 
 For Claude, the Impel PAT is supplied only to the launched child process as an
 authentication token and disappears when that process exits; it is never
@@ -579,6 +589,53 @@ best-effort: if a client CLI, its `plugin` subcommand, or the gateway is
 unavailable, it logs a warning and moves on — it never fails the parent command.
 Set `IMPEL_SKIP_SKILL_SYNC=1` to disable it entirely (offline/CI).
 
+### `impel agents sync [claude|codex|all]`
+
+Fetches the selected organization's opted-in specialist catalog through the
+authenticated Impel MCP endpoint, then generates native custom-agent files for
+every managed profile:
+
+- Claude Code: `<CLAUDE_CONFIG_DIR>/agents/impel-managed/*.md`
+- Codex / ChatGPT Codex mode: `<CODEX_HOME>/agents/impel-managed/*.toml`
+
+Each generated agent is bound to one exact specialist `agentId` and
+`scopeParam`. It verifies that specialist is still available, starts one
+idempotent run, polls the durable run to a terminal state, and returns
+`result.finalText` without repeating the work. The files include a tenant-bound
+MCP subprocess definition so they also work in isolated desktop profiles. They
+never contain the PAT; the subprocess reads it from Impel's owner-only config
+when invoked.
+
+The sync writes atomically and records a manifest beside the generated files.
+It removes only stale filenames from that manifest, so user-authored agents are
+never deleted. Automatic refreshes are best-effort and retain the last good
+catalog when the gateway is unavailable; the explicit command exits non-zero
+on failure. Set `IMPEL_SKIP_AGENT_SYNC=1` to keep the current generated catalog
+without contacting the gateway.
+
+Start a new task after syncing. Claude Code detects updates to an existing
+`agents/` directory within a few seconds, but if the sync created that directory
+for the first time while Claude was already running, restart Claude once.
+
+Invocation uses the clients' native agent behavior:
+
+```text
+# Claude Code / Claude Desktop Code tab: guaranteed explicit selection
+@agent-impel-acme-research-agent investigate the dependency change
+
+# Claude blocking CLI
+claude --agent impel-acme-research-agent -p "investigate the dependency change"
+
+# Codex CLI / ChatGPT desktop Codex task
+Use the configured impel-acme-research-agent subagent for this request and wait for it.
+```
+
+Claude exposes native custom agents in its `@` typeahead. Current Codex releases
+load and display the generated native agents but do not provide an `@agent`
+mention target; named spawning remains model-mediated and may also be limited by
+the active MultiAgentV2 tool schema. Use `/agent` in Codex to inspect spawned
+agent threads.
+
 ### `impel status`
 
 Shows whether the isolated CLI launchers are ready, and whether each native
@@ -602,10 +659,8 @@ Codex CLI and the Codex IDE extension / desktop app share the same
 ### Windows Claude and ChatGPT Desktop
 
 ```powershell
-impel app install claude
 impel app open claude
 impel app status claude
-impel app install codex
 impel app open codex
 impel app status codex
 ```
@@ -630,7 +685,8 @@ app-target names.
 
 ### macOS Claude and ChatGPT
 
-`impel app install` creates tenant-specific apps such as
+The first `impel app open --tenant <org>` (or an explicit `impel app install`)
+creates tenant-specific apps such as
 `Impel Claude (acme).app` and `Impel ChatGPT (acme).app` in `~/Applications`.
 Their visible bundle names use the organization display name, for example
 `Impel Claude (Acme)` and `Impel ChatGPT (Acme)`. Each tenant/product pair has
@@ -657,11 +713,10 @@ a stable, unique bundle identifier and gateway configuration:
 - Neither app changes `~/.claude`, `~/.claude.json`, `~/.codex`, or the
   normal vendor app's browser/profile data.
 
-Install or open several tenants without changing the current selection:
+Open several tenants without changing the current selection. A missing variant
+is installed and configured automatically before it opens:
 
 ```sh
-impel app install all --tenant acme
-impel app install all --tenant globex
 impel app open all --tenant acme
 impel app open all --tenant globex
 ```
@@ -672,7 +727,7 @@ successful tenant-specific rebuild.
 
 The official Claude and ChatGPT apps remain separate installations and keep
 their normal accounts, updater, profiles, and bundle identities. Each CLI
-release pins exact, tested vendor builds (v0.9.0 pins Claude `1.20186.9` and
+release pins exact, tested vendor builds (v0.10.0 pins Claude `1.20186.9` and
 ChatGPT `26.707.72221`) and their archive SHA-256 digests. The installer reuses
 an existing official app only when its version exactly matches; otherwise it
 downloads the pinned signed archive into Impel's managed vendor cache under

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Configure Claude Code and Codex CLI to talk to Impel's gateway, authenticated by an Impel Personal Access Token",
   "type": "module",
   "bin": {

package/src/agents.js

@@ -0,0 +1,480 @@
+// Synchronizes tenant-scoped Impel specialists into the native custom-agent
+// registries used by Claude Code and Codex. Unlike the public shared-skill
+// marketplace, the specialist catalog is authenticated and organization
+// specific, so it is fetched through the selected tenant's MCP session.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { normalizeGatewayUrl, redactSecretText } from "./config.js";
+import { impelMcpInvocation } from "./selfInvocation.js";
+import { normalizeTenantId } from "./tenants.js";
+
+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 SPECIALIST_LIST_TOOL = "impel_specialists-list_specialists";
+export const SPECIALIST_START_TOOL = "impel_specialists-start_specialist_run";
+export const SPECIALIST_READ_TOOL = "impel_specialists-read_specialist_run";
+export const MANAGED_AGENT_MCP_SERVER = "impel_agent";
+
+const SPECIALIST_TOOL_NAMES = [
+  SPECIALIST_LIST_TOOL,
+  SPECIALIST_START_TOOL,
+  SPECIALIST_READ_TOOL,
+];
+const SAFE_SPECIALIST_ID_RE = /^[A-Za-z0-9_.:-]{1,160}$/u;
+const SAFE_SCOPE_PARAM_RE = /^[A-Za-z0-9_.:-]{1,160}$/u;
+const MAX_CATALOG_ITEMS = 500;
+
+function privateDirectory(directory) {
+  if (fs.existsSync(directory) && fs.lstatSync(directory).isSymbolicLink()) {
+    throw new Error(`refusing to use symlinked managed-agent directory ${directory}`);
+  }
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  try {
+    fs.chmodSync(directory, 0o700);
+  } catch {
+    // Best effort on Windows.
+  }
+}
+
+function atomicPrivateWrite(filePath, contents) {
+  privateDirectory(path.dirname(filePath));
+  const temporaryPath = `${filePath}.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`;
+  try {
+    fs.writeFileSync(temporaryPath, contents, { mode: 0o600 });
+    fs.renameSync(temporaryPath, filePath);
+    try {
+      fs.chmodSync(filePath, 0o600);
+    } catch {
+      // Best effort on Windows.
+    }
+  } finally {
+    try {
+      fs.rmSync(temporaryPath, { force: true });
+    } catch {
+      // The normal rename path already removed it.
+    }
+  }
+}
+
+function boundedString(value, field, { max = 1024, pattern = null } = {}) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`specialist catalog returned an invalid ${field}`);
+  }
+  const normalized = value.trim();
+  if (normalized.length > max || (pattern && !pattern.test(normalized))) {
+    throw new Error(`specialist catalog returned an invalid ${field}`);
+  }
+  return normalized;
+}
+
+function stringList(value, field) {
+  if (!Array.isArray(value) || value.length > 100) {
+    throw new Error(`specialist catalog returned an invalid ${field}`);
+  }
+  return value.map((item) => boundedString(item, field, { max: 512 }));
+}
+
+export function normalizeSpecialistCatalog(payload, expectedTenantId) {
+  const tenantId = normalizeTenantId(expectedTenantId);
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("specialist catalog returned an invalid response");
+  }
+  if (normalizeTenantId(payload.orgId) !== tenantId) {
+    throw new Error("specialist catalog returned the wrong organization");
+  }
+  if (!Array.isArray(payload.specialists) || payload.specialists.length > MAX_CATALOG_ITEMS) {
+    throw new Error("specialist catalog returned an invalid specialists list");
+  }
+
+  const seenIds = new Set();
+  const specialists = payload.specialists.map((specialist) => {
+    if (!specialist || typeof specialist !== "object" || Array.isArray(specialist)) {
+      throw new Error("specialist catalog returned an invalid specialist");
+    }
+    const agentId = boundedString(specialist.agentId, "agentId", {
+      max: 160,
+      pattern: SAFE_SPECIALIST_ID_RE,
+    });
+    if (seenIds.has(agentId)) throw new Error(`specialist catalog returned duplicate agentId ${agentId}`);
+    seenIds.add(agentId);
+    return {
+      agentId,
+      title: boundedString(specialist.title, "title", { max: 160 }),
+      description: boundedString(specialist.description, "description", { max: 1024 }),
+      scopeParam: boundedString(specialist.scopeParam, "scopeParam", {
+        max: 160,
+        pattern: SAFE_SCOPE_PARAM_RE,
+      }),
+      provider: boundedString(specialist.provider, "provider", { max: 80 }),
+      capabilities: stringList(specialist.capabilities, "capabilities"),
+      exclusions: stringList(specialist.exclusions, "exclusions"),
+      requiredContext: stringList(specialist.requiredContext, "requiredContext"),
+      sideEffects: boundedString(specialist.sideEffects, "sideEffects", { max: 256 }),
+    };
+  });
+  return { orgId: tenantId, specialists };
+}
+
+function decodeMcpResponse(contentType, body) {
+  if (!body.trim()) return [];
+  if (!String(contentType || "").toLowerCase().includes("text/event-stream")) {
+    return [JSON.parse(body)];
+  }
+  return body
+    .split(/\r?\n/u)
+    .filter((line) => line.startsWith("data:"))
+    .map((line) => line.slice(5).trim())
+    .filter((line) => line && line !== "[DONE]")
+    .map((line) => JSON.parse(line));
+}
+
+async function postMcp({ endpoint, credential, sessionId, message, fetchImpl, timeoutMs }) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  let response;
+  try {
+    response = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${credential}`,
+        "Content-Type": "application/json",
+        Accept: "application/json, text/event-stream",
+        ...(sessionId ? { "Mcp-Session-Id": sessionId } : {}),
+      },
+      body: JSON.stringify(message),
+      signal: controller.signal,
+    });
+  } catch (error) {
+    const detail = error?.name === "AbortError" ? "request timed out" : error?.message || error;
+    throw new Error(`specialist MCP request failed: ${redactSecretText(detail)}`);
+  } finally {
+    clearTimeout(timeout);
+  }
+  const body = await response.text();
+  if (!response.ok) {
+    throw new Error(`specialist MCP returned HTTP ${response.status}`);
+  }
+  return {
+    sessionId: response.headers.get("mcp-session-id") || sessionId || null,
+    messages: decodeMcpResponse(response.headers.get("content-type"), body),
+  };
+}
+
+function responseForId(messages, id) {
+  return messages.find((message) => message?.id === id) || null;
+}
+
+function specialistPayloadFromToolResult(message) {
+  if (!message) throw new Error("specialist MCP returned no tool result");
+  if (message.error) {
+    throw new Error(redactSecretText(message.error.message || "specialist MCP tool failed"));
+  }
+  const result = message.result;
+  if (result?.isError) throw new Error("specialist MCP list tool returned an error");
+  if (result?.structuredContent && typeof result.structuredContent === "object") {
+    return result.structuredContent;
+  }
+  const text = result?.content?.find((item) => item?.type === "text" && typeof item.text === "string")?.text;
+  if (!text) throw new Error("specialist MCP list tool returned no catalog");
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error("specialist MCP list tool returned invalid JSON");
+  }
+}
+
+export async function fetchSpecialistCatalog({
+  gatewayUrl,
+  credential,
+  tenantId,
+  fetchImpl = fetch,
+  timeoutMs = 20_000,
+}) {
+  if (!credential) throw new Error("a tenant credential is required for agent sync");
+  const endpoint = `${normalizeGatewayUrl(gatewayUrl)}/mcp`;
+  let sessionId = null;
+  const initialized = await postMcp({
+    endpoint,
+    credential,
+    sessionId,
+    fetchImpl,
+    timeoutMs,
+    message: {
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: "2025-06-18",
+        capabilities: {},
+        clientInfo: { name: "impel-cli-agent-sync", version: "1.0.0" },
+      },
+    },
+  });
+  sessionId = initialized.sessionId;
+  const initializeMessage = responseForId(initialized.messages, 1);
+  if (initializeMessage?.error || !initializeMessage?.result) {
+    throw new Error("specialist MCP initialization failed");
+  }
+
+  const ready = await postMcp({
+    endpoint,
+    credential,
+    sessionId,
+    fetchImpl,
+    timeoutMs,
+    message: { jsonrpc: "2.0", method: "notifications/initialized", params: {} },
+  });
+  sessionId = ready.sessionId;
+  const listed = await postMcp({
+    endpoint,
+    credential,
+    sessionId,
+    fetchImpl,
+    timeoutMs,
+    message: {
+      jsonrpc: "2.0",
+      id: 2,
+      method: "tools/call",
+      params: { name: SPECIALIST_LIST_TOOL, arguments: {} },
+    },
+  });
+  return normalizeSpecialistCatalog(
+    specialistPayloadFromToolResult(responseForId(listed.messages, 2)),
+    tenantId,
+  );
+}
+
+function slug(value) {
+  return String(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, "-")
+    .replace(/^-+|-+$/gu, "")
+    .slice(0, 48) || "agent";
+}
+
+function generatedAgentNames(tenantId, specialists) {
+  const used = new Map();
+  return specialists.map((specialist) => {
+    const base = `impel-${slug(tenantId)}-${slug(specialist.agentId)}`.slice(0, 63).replace(/-+$/u, "");
+    const previous = used.get(base);
+    used.set(base, (previous || 0) + 1);
+    if (!previous) return base;
+    const suffix = crypto.createHash("sha256").update(specialist.agentId).digest("hex").slice(0, 8);
+    return `${base.slice(0, 54)}-${suffix}`;
+  });
+}
+
+function adapterInstructions(tenantId, specialist) {
+  const toolName = nativeToolName;
+  const contextRequirement = specialist.requiredContext.length
+    ? ` Required context keys are ${JSON.stringify(specialist.requiredContext)}; if any are absent, ask for them before starting the run.`
+    : "";
+  return [
+    `You are a thin transport adapter for the exact Impel specialist ${JSON.stringify(specialist.agentId)} in tenant ${JSON.stringify(tenantId)}.`,
+    `Do not perform the assigned task yourself and do not delegate to any other specialist.`,
+    `First call ${toolName(SPECIALIST_LIST_TOOL)} and verify that the exact agentId is still available. If it is unavailable or its policy excludes the request, stop with that explicit error.`,
+    `Call ${toolName(SPECIALIST_START_TOOL)} exactly once with agentId ${JSON.stringify(specialist.agentId)}, scopeParam ${JSON.stringify(specialist.scopeParam)}, task set to the complete assigned task, context and contextKeys containing all supplied context, and one stable idempotencyKey that you reuse for this logical task.${contextRequirement}`,
+    `Then call ${toolName(SPECIALIST_READ_TOOL)} with the returned runId and waitSeconds 20 until the run reaches a terminal state.`,
+    `When it succeeds, return result.finalText faithfully as the answer. When it fails, return the durable runId, preserved output, and error. Never invent or independently synthesize a replacement result.`,
+  ].join(" ");
+}
+
+function nativeToolName(toolName) {
+  return `mcp__${MANAGED_AGENT_MCP_SERVER}__${toolName}`;
+}
+
+function renderClaudeAgent({ tenantId, specialist, name, invocation }) {
+  const description = `Runs ${specialist.title} for Impel tenant ${tenantId}: ${specialist.description}`.slice(0, 900);
+  const lines = [
+    "---",
+    `name: ${JSON.stringify(name)}`,
+    `description: ${JSON.stringify(description)}`,
+    "model: inherit",
+    "tools:",
+    ...SPECIALIST_TOOL_NAMES.map((tool) => `  - ${JSON.stringify(nativeToolName(tool))}`),
+    "mcpServers:",
+    `  - ${MANAGED_AGENT_MCP_SERVER}:`,
+    "      type: stdio",
+    `      command: ${JSON.stringify(invocation.command)}`,
+    "      args:",
+    ...invocation.args.map((argument) => `        - ${JSON.stringify(argument)}`),
+    "      env:",
+    ...Object.entries(invocation.env || {}).map(([key, value]) => `        ${key}: ${JSON.stringify(value)}`),
+    "---",
+    "",
+    adapterInstructions(tenantId, specialist),
+    "",
+  ];
+  return lines.join("\n");
+}
+
+function renderCodexAgent({ tenantId, specialist, name, invocation }) {
+  const description = `Runs ${specialist.title} for Impel tenant ${tenantId}: ${specialist.description}`.slice(0, 900);
+  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)}`,
+    'sandbox_mode = "read-only"',
+    `developer_instructions = ${JSON.stringify(adapterInstructions(tenantId, specialist))}`,
+    "",
+    `[mcp_servers.${MANAGED_AGENT_MCP_SERVER}]`,
+    `command = ${JSON.stringify(invocation.command)}`,
+    `args = [${invocation.args.map((argument) => JSON.stringify(argument)).join(", ")}]`,
+    `enabled_tools = [${SPECIALIST_TOOL_NAMES.map((tool) => JSON.stringify(tool)).join(", ")}]`,
+    ...(envEntries ? [`env = { ${envEntries} }`] : []),
+    "",
+  ];
+  for (const tool of SPECIALIST_TOOL_NAMES) {
+    lines.push(`[mcp_servers.${MANAGED_AGENT_MCP_SERVER}.tools.${JSON.stringify(tool)}]`, 'approval_mode = "approve"', "");
+  }
+  return lines.join("\n");
+}
+
+export function renderManagedAgents(client, tenantId, specialists, invocation = impelMcpInvocation(["--tenant", tenantId])) {
+  if (client !== "claude" && client !== "codex") throw new Error(`unknown agent client ${client}`);
+  const normalizedTenant = normalizeTenantId(tenantId);
+  const names = generatedAgentNames(normalizedTenant, specialists);
+  return specialists.map((specialist, index) => {
+    const name = names[index];
+    const extension = client === "claude" ? ".md" : ".toml";
+    const contents = client === "claude"
+      ? renderClaudeAgent({ tenantId: normalizedTenant, specialist, name, invocation })
+      : renderCodexAgent({ tenantId: normalizedTenant, specialist, name, invocation });
+    return { agentId: specialist.agentId, name, fileName: `${name}${extension}`, contents };
+  });
+}
+
+export function agentProfileRoot(client, {
+  env = {},
+  environment = process.env,
+  homeDir = os.homedir(),
+} = {}) {
+  if (client === "claude") {
+    return env.CLAUDE_CONFIG_DIR || environment.CLAUDE_CONFIG_DIR || path.join(homeDir, ".claude");
+  }
+  if (client === "codex") {
+    return env.CODEX_HOME || environment.CODEX_HOME || path.join(homeDir, ".codex");
+  }
+  throw new Error(`unknown agent client ${client}`);
+}
+
+function readManifest(manifestPath) {
+  try {
+    const value = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    if (!value || typeof value !== "object" || !Array.isArray(value.files)) return null;
+    return value;
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    return null;
+  }
+}
+
+function profileIsFresh(profile, tenantId, now, ttlMs) {
+  const manifest = readManifest(path.join(profile.root, "agents", MANAGED_AGENT_DIRECTORY, MANAGED_AGENT_MANIFEST));
+  if (!manifest || manifest.tenantId !== tenantId) 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", MANAGED_AGENT_DIRECTORY, fileName))
+  );
+}
+
+export function syncAgentProfile({ client, root, label, tenantId, specialists, now = Date.now() }) {
+  const agentsDir = path.join(root, "agents");
+  for (const candidate of [root, agentsDir]) {
+    if (fs.existsSync(candidate) && fs.lstatSync(candidate).isSymbolicLink()) {
+      throw new Error(`refusing to use symlinked native-agent path ${candidate}`);
+    }
+  }
+  const managedDir = path.join(agentsDir, MANAGED_AGENT_DIRECTORY);
+  privateDirectory(managedDir);
+  const manifestPath = path.join(managedDir, MANAGED_AGENT_MANIFEST);
+  const prior = readManifest(manifestPath);
+  const rendered = renderManagedAgents(client, tenantId, specialists);
+
+  for (const agent of rendered) {
+    atomicPrivateWrite(path.join(managedDir, agent.fileName), agent.contents);
+  }
+  const currentFiles = new Set(rendered.map((agent) => agent.fileName));
+  for (const stale of prior?.files || []) {
+    if (
+      typeof stale === "string"
+      && path.basename(stale) === stale
+      && !currentFiles.has(stale)
+      && (stale.endsWith(".md") || stale.endsWith(".toml"))
+    ) {
+      fs.rmSync(path.join(managedDir, stale), { force: true });
+    }
+  }
+  atomicPrivateWrite(manifestPath, `${JSON.stringify({
+    version: 1,
+    tenantId,
+    client,
+    syncedAt: new Date(now).toISOString(),
+    files: [...currentFiles].sort(),
+    agents: rendered.map(({ agentId, name }) => ({ agentId, name })),
+  }, null, 2)}\n`);
+  return { client, root, label, synced: true, count: rendered.length, files: [...currentFiles] };
+}
+
+export async function syncAgentProfiles({
+  profiles,
+  gatewayUrl,
+  credential,
+  tenantId,
+  staleOnly = false,
+  ttlMs = AGENT_SYNC_TTL_MS,
+  now = Date.now(),
+  fetchCatalog = fetchSpecialistCatalog,
+  logger = console,
+}) {
+  if (process.env.IMPEL_SKIP_AGENT_SYNC === "1" || process.env.IMPEL_SKIP_AGENT_SYNC === "true") {
+    return profiles.map((profile) => ({ ...profile, skipped: true, reason: "disabled" }));
+  }
+  const normalizedTenant = normalizeTenantId(tenantId);
+  const pending = staleOnly
+    ? profiles.filter((profile) => !profileIsFresh(profile, normalizedTenant, now, ttlMs))
+    : profiles;
+  const skipped = profiles
+    .filter((profile) => !pending.includes(profile))
+    .map((profile) => ({ ...profile, skipped: true, reason: "fresh" }));
+  if (pending.length === 0) return skipped;
+
+  const catalog = await fetchCatalog({ gatewayUrl, credential, tenantId: normalizedTenant });
+  const results = [];
+  for (const profile of pending) {
+    const result = syncAgentProfile({
+      ...profile,
+      tenantId: normalizedTenant,
+      specialists: catalog.specialists,
+      now,
+    });
+    logger.log(`Agents: ${profile.label || profile.client} up to date (${result.count} tenant specialist${result.count === 1 ? "" : "s"}).`);
+    results.push(result);
+  }
+  return [...results, ...skipped];
+}
+
+export async function syncAgentProfilesSafe(options) {
+  try {
+    return await syncAgentProfiles(options);
+  } catch (error) {
+    const logger = options?.logger || console;
+    logger.warn(`impel: agent sync failed (${redactSecretText(error?.message || error)}); keeping the last good native-agent catalog.`);
+    return (options?.profiles || []).map((profile) => ({
+      ...profile,
+      synced: false,
+      reason: "error",
+      error: redactSecretText(error?.message || error),
+    }));
+  }
+}

package/src/cli.js

@@ -11,6 +11,7 @@ import { cmdApps } from "./commands/apps.js";
 import { cmdMcp } from "./commands/mcp.js";
 import { cmdLaunch } from "./commands/launch.js";
 import { cmdSkills } from "./commands/skills.js";
+import { cmdAgents } from "./commands/agents.js";
 import { cmdTenant } from "./commands/tenant.js";
 import { cmdDoctor } from "./commands/doctor.js";
 import { cmdSetup } from "./commands/setup.js";
@@ -24,12 +25,12 @@ Get started:
                                               platform clients, gateway verification
                                               (--pat <pat> --tenant <org> --skip-apps/--skip-clis)
   impel update                                Update everything: the CLI itself, then the
-                                              Impel apps and skills (--check, --skip-apps)
+                                              Impel apps, skills, and agents (--check, --skip-apps)
 
 Run:
   impel claude [args...]                      Launch Claude Code with an isolated Impel profile
   impel codex [args...]                       Launch Codex with an isolated Impel profile
-  impel app open [target] [--tenant <org>]    Open that tenant's isolated desktop app(s)
+  impel app open [target] [--tenant <org>]    Install/configure on first use, then open the app(s)
   impel status                                Tenant, PAT, per-tool mode, gateway reachability
   impel doctor [--tenant <org>|--all-tenants] Synthetic provider, routing, and latency checks
 
@@ -43,12 +44,13 @@ Manage:
   impel token [--tenant <org>]                Print the selected-tenant bearer
   impel mcp                                   Run the local Impel MCP stdio bridge
   impel skills sync [claude|codex|all]        Sync shared skills into managed clients
+  impel agents sync [claude|codex|all]        Sync tenant specialists as native subagents
 
 Desktop apps (macOS and Windows):
   target is claude, chatgpt/codex, or all (default: all)
   impel app install [target] [--tenant <org>] Install that tenant's isolated app/profile
   impel app update [target] [--tenant <org>]  Update vendor apps and managed profiles
-  impel app refresh [target] [--tenant <org>] Configs/catalog/skills only; safe while apps run
+  impel app refresh [target] [--tenant <org>] Configs/catalog/skills/agents only; safe while apps run
   impel app status [target] [--tenant <org>]  Show isolated app and vendor versions
   impel app uninstall [target] [--tenant <org>] [--keep-data]
                                               Remove only that tenant's managed apps/data
@@ -65,6 +67,7 @@ Env:
   IMPEL_GATEWAY_URL   Default gateway URL when --gateway isn't passed.
   IMPEL_APP_URL       Default app/control-plane URL for setup, auth, PATs, and tasks.
   IMPEL_SKIP_UPDATE_CHECK=1   Silence launch-time update notices.
+  IMPEL_SKIP_AGENT_SYNC=1     Keep the last native-agent catalog without refreshing it.
 
 Config file:
   ~/.config/impel/config.json (mode 0600)
@@ -144,6 +147,10 @@ export async function main(argv) {
     case "skill":
       return cmdSkills(rest);
 
+    case "agents":
+    case "agent":
+      return cmdAgents(rest);
+
     case "on":
       return runUse("gateway", rest[0]);
 

package/src/commands/agents.js

@@ -0,0 +1,96 @@
+// `impel agents sync [claude|codex|all]` — synchronize the selected tenant's
+// opted-in Impel specialists into every managed native custom-agent registry.
+
+import os from "node:os";
+
+import { agentProfileRoot, syncAgentProfiles } from "../agents.js";
+import { loadConfig, normalizeGatewayUrl, redactSecretText, resolveDefaultGateway } from "../config.js";
+import { ensureTenantSelection, tenantCredential } from "../tenants.js";
+import { managedSkillProfiles } from "./skills.js";
+
+const HELP = `impel agents - sync tenant specialists as native custom agents
+
+Usage:
+  impel agents sync [claude|codex|all]
+
+The selected tenant's authenticated specialist catalog is written into every
+managed native profile. The default target is all.`;
+
+function normalizeAgentTarget(token) {
+  if (token === undefined || token === "all") return "all";
+  if (token === "claude") return "claude";
+  if (token === "codex" || token === "codex-cli" || token === "codex-app" || token === "chatgpt") {
+    return "codex";
+  }
+  return null;
+}
+
+export function managedAgentProfiles(client, options = {}) {
+  const homeDir = options.homeDir || os.homedir();
+  const environment = options.environment || process.env;
+  return managedSkillProfiles(client, options).map((profile) => ({
+    client,
+    label: profile.label,
+    root: agentProfileRoot(client, {
+      env: profile.env,
+      environment,
+      homeDir,
+    }),
+  }));
+}
+
+export async function cmdAgents(argv, overrides = {}) {
+  const [action = "sync", targetToken] = argv;
+  if (["help", "--help", "-h"].includes(action)) {
+    console.log(HELP);
+    return;
+  }
+  if (action !== "sync") {
+    console.error(`impel agents: unknown action "${action}". Try \`impel agents sync [claude|codex|all]\`.`);
+    process.exitCode = 1;
+    return;
+  }
+  const target = normalizeAgentTarget(targetToken);
+  if (target === null) {
+    console.error(`impel agents: unknown target "${targetToken}". Use \`claude\`, \`codex\`, or \`all\`.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const io = {
+    loadConfig,
+    ensureTenantSelection,
+    syncAgentProfiles,
+    managedAgentProfiles,
+    environment: process.env,
+    homeDir: os.homedir(),
+    ...overrides,
+  };
+  const config = io.loadConfig();
+  if (!config?.pat) {
+    console.error("impel agents: not authenticated; run `impel setup` (or `impel auth`) first.");
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const selected = await io.ensureTenantSelection(config);
+    const tenantId = selected.tenantId;
+    const gatewayUrl = normalizeGatewayUrl(config.gatewayUrl || resolveDefaultGateway());
+    const clients = target === "all" ? ["claude", "codex"] : [target];
+    const profiles = clients.flatMap((client) => io.managedAgentProfiles(client, {
+      tenantId,
+      environment: io.environment,
+      homeDir: io.homeDir,
+    }));
+    await io.syncAgentProfiles({
+      profiles,
+      gatewayUrl,
+      credential: tenantCredential(config.pat, tenantId),
+      tenantId,
+    });
+  } catch (error) {
+    console.error(`impel agents: ${redactSecretText(error?.message || error)}`);
+    process.exitCode = 1;
+  }
+}

package/src/commands/apps.js

@@ -37,6 +37,7 @@ import {
   removeManagedApps,
 } from "../apps.js";
 import { resolveSkillsGateway, syncSkillsSafe } from "../skills.js";
+import { syncAgentProfilesSafe } from "../agents.js";
 import { secureManagedCodexHome } from "../codexSecurity.js";
 import { impelCliInvocation } from "../selfInvocation.js";
 import {
@@ -63,6 +64,13 @@ function appSkillTarget(target, paths) {
   return { client: "codex", env: { CODEX_HOME: paths.chatgpt.codexHome }, label: "Impel ChatGPT app" };
 }
 
+function appAgentProfile(target, paths) {
+  if (target === "claude") {
+    return { client: "claude", root: paths.claude.userData, label: "Impel Claude app" };
+  }
+  return { client: "codex", root: paths.chatgpt.codexHome, label: "Impel ChatGPT app" };
+}
+
 function windowsAppTargets(targetToken) {
   if (targetToken === undefined || targetToken === "all") return ["claude", "chatgpt"];
   if (targetToken === "claude") return ["claude"];
@@ -137,6 +145,7 @@ export async function cmdWindowsApps(argv, overrides = {}) {
     installFiles: installManagedAppFiles,
     removeApps: removeManagedApps,
     syncSkills: syncSkillsSafe,
+    syncAgents: syncAgentProfilesSafe,
     selectedConfig: selectedAppConfig,
     ...overrides,
   };
@@ -207,13 +216,26 @@ export async function cmdWindowsApps(argv, overrides = {}) {
       claudeUserData: actionUserData,
       tenantName: config.tenantName,
     });
+    const profileWasInstalled = {
+      claude: fs.existsSync(path.join(
+        actionPaths.claude.userData,
+        "configLibrary",
+        `${CLAUDE_CONFIG_ID}.json`,
+      )),
+      chatgpt: fs.existsSync(path.join(actionPaths.chatgpt.codexHome, "config.toml")),
+    };
     const vendorPaths = {};
     for (const target of targets) {
       const isClaude = target === "claude";
       const find = isClaude ? io.findClaudeApp : io.findChatGPTApp;
       const ensure = isClaude ? io.ensureClaudeApp : io.ensureChatGPTApp;
       let binary = find(io.environment);
-      if ((action === "install" || action === "update") && !flags["skip-vendor"]) {
+      const shouldEnsureVendor = !flags["skip-vendor"] && (
+        action === "install"
+        || action === "update"
+        || (action === "open" && !binary)
+      );
+      if (shouldEnsureVendor) {
         const vendor = ensure({ update: action === "update" }, { environment: io.environment });
         binary = vendor.binary;
         console.log(`${target}: vendor app ${vendor.action}`);
@@ -252,15 +274,24 @@ export async function cmdWindowsApps(argv, overrides = {}) {
       claudeUserData: userData,
       tenantName: config.tenantName,
     });
-    if (action === "install" || action === "update" || action === "refresh") {
-      const verb = action === "install" ? "Installed" : action === "update" ? "Updated" : "Refreshed";
-      for (const target of targets) {
+    const configuredTargets = action === "open"
+      ? targets.filter((target) => !profileWasInstalled[target])
+      : targets;
+    if (action === "install" || action === "update" || action === "refresh" || configuredTargets.length > 0) {
+      const verb = action === "update" ? "Updated" : action === "refresh" ? "Refreshed" : "Installed";
+      for (const target of configuredTargets) {
         const profile = target === "claude" ? tenantPaths.claude.userData : tenantPaths.chatgpt.root;
         console.log(`${verb} Impel ${target === "claude" ? "Claude" : "ChatGPT"} profile at ${profile}`);
         const { client, env, label } = appSkillTarget(target, tenantPaths);
         await io.syncSkills({ client, gatewayUrl: resolveSkillsGateway(config.gatewayUrl), env, label });
         if (target === "chatgpt") secureManagedCodexHome(tenantPaths.chatgpt.codexHome);
       }
+      await io.syncAgents({
+        profiles: targets.map((target) => appAgentProfile(target, tenantPaths)),
+        gatewayUrl: config.gatewayUrl,
+        credential: config.pat,
+        tenantId: config.tenantId,
+      });
       console.log(`Models: ${catalog.models.length} from ${catalog.source}. The signed vendor apps and their normal profiles were not changed.`);
     }
     if (action === "open") {
@@ -358,43 +389,12 @@ export async function cmdApps(argv, overrides = {}) {
 
     const config = await selectedAppConfig(targets, flags.tenant || null);
     const statuses = appStatus(targets, os.homedir(), config.tenantId, config.tenantName);
-    const legacyPaths = appPaths(os.homedir());
-    for (const status of statuses) {
-      if (!status.launcherInstalled && !fs.existsSync(legacyPaths[status.target].launcher)) {
-        throw new Error(`${status.label} is not installed; run \`impel app install ${status.target}\``);
-      }
-      if (!status.vendorPath) throw new Error(`${status.label} vendor app is unavailable; reinstall the vendor app first`);
-    }
-    let catalog;
-    try {
-      catalog = await fetchGatewayModels(config);
-    } catch (error) {
-      throw new Error(
-        `tenant model catalog is unavailable (${redactSecretText(error.message)}); the selected tenant app was not opened`,
-      );
-    }
-    // Only stale bundles pay the clone + codesign rebuild; a bundle swap needs
-    // its app closed, and quitting is fine here since we relaunch right after.
-    const staleBundleTargets = statuses
-      .filter((status) => !bundleIsCurrent(status))
-      .map((status) => status.target);
-    if (staleBundleTargets.length > 0) {
-      await quitBlockingApps(staleBundleTargets, {
-        tenantId: config.tenantId,
-        tenantName: config.tenantName,
-      });
-    }
-    installManagedAppFiles({
+    await provisionAndOpenManagedApps({
       config,
       targets,
-      models: catalog.models,
+      statuses,
       homeDir: os.homedir(),
-      vendorPaths: Object.fromEntries(statuses.map((status) => [status.target, status.vendorPath])),
-      writeBundles: staleBundleTargets,
-    });
-    for (const status of appStatus(targets, os.homedir(), config.tenantId, config.tenantName)) {
-      spawnSync("/usr/bin/open", ["-n", status.launcher], { stdio: "inherit" });
-    }
+    }, overrides);
     return;
   }
   if (action !== "install" && action !== "update") {
@@ -443,6 +443,113 @@ export async function cmdApps(argv, overrides = {}) {
     await syncSkillsSafe({ client, gatewayUrl, env, label });
     if (item.target === "chatgpt") secureManagedCodexHome(paths.chatgpt.codexHome);
   }
+  const syncAgents = overrides.syncAgents || syncAgentProfilesSafe;
+  await syncAgents({
+    profiles: installed.map((item) => appAgentProfile(item.target, paths)),
+    gatewayUrl: config.gatewayUrl,
+    credential: config.pat,
+    tenantId: config.tenantId,
+  });
+}
+
+/**
+ * Complete the slow `app open` path. A first open is intentionally equivalent
+ * to an install for the selected tenant: verify or install the pinned vendor,
+ * build the isolated bundle/profile, sync skills, and only then launch it.
+ * Existing current installs never reach this helper because fastOpenLaunchers
+ * handles them without network or rebuild work.
+ */
+export async function provisionAndOpenManagedApps({
+  config,
+  targets,
+  statuses,
+  homeDir = os.homedir(),
+}, overrides = {}) {
+  const io = {
+    fetchModels: fetchGatewayModels,
+    ensureVendor: ensureVendorApp,
+    bundleCurrent: bundleIsCurrent,
+    quitApps: quitBlockingApps,
+    installFiles: installManagedAppFiles,
+    syncSkills: syncSkillsSafe,
+    syncAgents: syncAgentProfilesSafe,
+    secureCodexHome: secureManagedCodexHome,
+    openLauncher: (launcher) => spawnSync("/usr/bin/open", ["-n", launcher], { stdio: "inherit" }),
+    log: (message) => console.log(message),
+    ...overrides,
+  };
+
+  // Resolve the live tenant catalog before installing or changing anything.
+  // This keeps unavailable/unauthorized tenants fail-closed on first use.
+  let catalog;
+  try {
+    catalog = await io.fetchModels(config);
+  } catch (error) {
+    throw new Error(
+      `tenant model catalog is unavailable (${redactSecretText(error?.message || error)}); the selected tenant app was not opened`,
+    );
+  }
+
+  const vendorPaths = {};
+  for (const status of statuses) {
+    let vendorPath = status.vendorPath;
+    if (!vendorPath) {
+      const result = io.ensureVendor(status.target, { homeDir });
+      vendorPath = result.path;
+      io.log(`${status.target}: vendor app ${result.action}${result.note ? ` (${result.note})` : ""}`);
+      if (!vendorPath) {
+        throw new Error(`${status.target} verified vendor app is unavailable; retry the pinned download`);
+      }
+    }
+    vendorPaths[status.target] = vendorPath;
+  }
+
+  // Only stale or absent bundles pay the clone + codesign rebuild. The model
+  // catalog and vendor checks above finish before any running apps are closed.
+  const staleBundleTargets = statuses
+    .filter((status) => !io.bundleCurrent(status))
+    .map((status) => status.target);
+  if (staleBundleTargets.length > 0) {
+    await io.quitApps(staleBundleTargets, {
+      tenantId: config.tenantId,
+      tenantName: config.tenantName,
+    });
+  }
+
+  const installed = io.installFiles({
+    config,
+    targets,
+    models: catalog.models,
+    homeDir,
+    vendorPaths,
+    writeBundles: staleBundleTargets,
+  });
+  const newlyInstalled = new Set(
+    statuses.filter((status) => !status.launcherInstalled).map((status) => status.target),
+  );
+  for (const item of installed) {
+    if (newlyInstalled.has(item.target)) {
+      io.log(`Installed and configured ${item.launcher} for tenant ${config.tenantId}.`);
+    }
+  }
+
+  // Match explicit install setup without penalizing repeat opens: this helper
+  // only runs when the zero-network fast path has detected drift or first use.
+  const paths = appPaths(homeDir, config.tenantId, { tenantName: config.tenantName });
+  const gatewayUrl = resolveSkillsGateway(config.gatewayUrl);
+  for (const item of installed) {
+    const { client, env, label } = appSkillTarget(item.target, paths);
+    await io.syncSkills({ client, gatewayUrl, env, label });
+    if (item.target === "chatgpt") io.secureCodexHome(paths.chatgpt.codexHome);
+  }
+  await io.syncAgents({
+    profiles: installed.map((item) => appAgentProfile(item.target, paths)),
+    gatewayUrl: config.gatewayUrl,
+    credential: config.pat,
+    tenantId: config.tenantId,
+  });
+  for (const item of installed) await io.openLauncher(item.launcher);
+  return installed;
 }
 
 const REFRESH_TTL_MS = 6 * 60 * 60 * 1000;
@@ -552,6 +659,12 @@ async function refreshApps(targets, { staleOnly = false, tenantId = null } = {})
     await syncSkillsSafe({ client, gatewayUrl, env, label });
     if (status.target === "chatgpt") secureManagedCodexHome(tenantPaths.chatgpt.codexHome);
   }
+  await syncAgentProfilesSafe({
+    profiles: installedTargets.map((status) => appAgentProfile(status.target, tenantPaths)),
+    gatewayUrl: config.gatewayUrl,
+    credential: config.pat,
+    tenantId: config.tenantId,
+  });
   // Keep the update-notice cache warm from the same background slot.
   try {
     refreshUpdateCache();

package/src/commands/launch.js

@@ -5,6 +5,7 @@ import {
   ensureImpelClaudeProfile,
   ensureImpelCodexProfile,
 } from "../cliProfiles.js";
+import { syncAgentProfilesSafe } from "../agents.js";
 import {
   crossAppModelsEnabled,
   loadConfig,
@@ -134,9 +135,11 @@ export async function cmdLaunch(tool, argv) {
   const gatewayCredential = tenantCredential(config.pat, tenantId);
   const environment = { ...process.env };
   environment.IMPEL_TENANT_ID = tenantId;
+  let agentProfile;
 
   if (tool === "claude") {
     const profile = ensureImpelClaudeProfile(gatewayUrl, tenantId, { crossAppModels });
+    agentProfile = { client: "claude", root: profile.configDir, label: "Impel isolated Claude (impel claude)" };
     deleteEnvironmentKeys(environment, CLAUDE_DIRECT_AUTH_ENV);
     delete environment.CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY;
     environment.CLAUDE_CONFIG_DIR = profile.configDir;
@@ -150,12 +153,23 @@ export async function cmdLaunch(tool, argv) {
     environment.ANTHROPIC_AUTH_TOKEN = gatewayCredential;
   } else if (tool === "codex") {
     const profile = ensureImpelCodexProfile(gatewayUrl, tenantId);
+    agentProfile = { client: "codex", root: profile.codexHome, label: "Impel isolated Codex (impel codex)" };
     deleteEnvironmentKeys(environment, CODEX_DIRECT_AUTH_ENV);
     environment.CODEX_HOME = profile.codexHome;
   } else {
     throw new Error(`unsupported CLI launcher: ${tool}`);
   }
 
+  // Refresh at most every six hours. A network/catalog failure must not block
+  // the isolated client; the last successfully generated agents remain usable.
+  await syncAgentProfilesSafe({
+    profiles: [agentProfile],
+    gatewayUrl,
+    credential: gatewayCredential,
+    tenantId,
+    staleOnly: true,
+  });
+
   const exitCode = await runNativeCli(tool, impelLaunchArguments(tool, argv), environment);
   if (exitCode !== 0) process.exitCode = exitCode;
 }

package/src/commands/update.js

@@ -1,6 +1,6 @@
 // `impel update` — bring everything current in one command: the CLI itself
 // (npm reinstall from the public package), then the managed desktop apps/profiles, then
-// skills. The app step re-executes the freshly installed CLI so the new code
+// skills and native tenant agents. The app step re-executes the freshly installed CLI so the new code
 // performs it.
 
 import fs from "node:fs";
@@ -29,11 +29,11 @@ const HELP = `impel update - update everything Impel in one command
 
 Reinstalls impel-cli from npm, then cascades with the NEW build:
 \`impel app update all\` (update the platform's vendor apps and managed app
-profiles) when Impel apps are installed, then \`impel skills sync all\` across
-every managed profile.
+profiles) when Impel apps are installed, then \`impel skills sync all\` and
+\`impel agents sync all\` across every managed profile.
 
 Usage:
-  impel update              Update the CLI, then cascade to apps and skills
+  impel update              Update the CLI, then cascade to apps, skills, and agents
   impel update --check      Report whether an update is available; change nothing
   impel update --skip-apps  Skip the desktop-app step of the cascade
 `;
@@ -102,6 +102,13 @@ function defaultRunSkillsSync() {
   return result.status === 0;
 }
 
+function defaultRunAgentsSync() {
+  const result = spawnSync(process.execPath, [CLI_BIN, "agents", "sync", "all"], {
+    stdio: "inherit",
+  });
+  return result.status === 0;
+}
+
 function anyAppInstalled(homeDir = os.homedir()) {
   const config = loadConfig();
   const claudeUserData = process.platform === "win32"
@@ -136,6 +143,7 @@ export async function cmdUpdate(argv, overrides = {}) {
     selfUpdate: defaultSelfUpdate,
     runAppsUpdate: defaultRunAppsUpdate,
     runSkillsSync: defaultRunSkillsSync,
+    runAgentsSync: defaultRunAgentsSync,
     appsInstalled: anyAppInstalled,
     platform: process.platform,
     ...overrides,
@@ -213,6 +221,12 @@ export async function cmdUpdate(argv, overrides = {}) {
     cascadeFailed = true;
   }
 
+  console.log("Agents: syncing the selected tenant into every managed profile…");
+  if (!io.runAgentsSync()) {
+    console.error("impel update: agent sync failed; re-run `impel agents sync` after fixing the issue.");
+    cascadeFailed = true;
+  }
+
   if (cascadeFailed) {
     process.exitCode = 1;
     return;

package/src/commands/use.js

@@ -8,12 +8,15 @@
 // model_provider) into the impel config, so turning it OFF restores exactly
 // that — never a guess.
 
-import { loadConfig, saveConfig, resolveDefaultGateway } from "../config.js";
+import { loadConfig, saveConfig, redactSecretText, resolveDefaultGateway } from "../config.js";
+import { syncAgentProfilesSafe } from "../agents.js";
+import { ensureTenantSelection, tenantCredential } from "../tenants.js";
 import {
   applyClaudeGateway,
   revertClaudeGateway,
   isImpelApiKeyHelper,
   isImpelClaudeBaseUrl,
+  CLAUDE_DIR,
 } from "../claudeSetup.js";
 import {
   applyCodexGateway,
@@ -110,6 +113,25 @@ async function useGateway({ target, app }) {
   if (wantsCodex(target)) {
     await syncSkillsSafe({ client: "codex", gatewayUrl, env: { CODEX_HOME }, label: "Codex CLI (gateway)" });
   }
+  try {
+    const selected = await ensureTenantSelection(config);
+    const agentProfiles = [
+      ...(wantsClaude(target)
+        ? [{ client: "claude", root: CLAUDE_DIR, label: "Claude Code (gateway)" }]
+        : []),
+      ...(wantsCodex(target)
+        ? [{ client: "codex", root: CODEX_HOME, label: "Codex CLI (gateway)" }]
+        : []),
+    ];
+    await syncAgentProfilesSafe({
+      profiles: agentProfiles,
+      gatewayUrl,
+      credential: tenantCredential(config.pat, selected.tenantId),
+      tenantId: selected.tenantId,
+    });
+  } catch (error) {
+    console.warn(`impel: agent sync could not resolve the selected tenant (${redactSecretText(error?.message || error)}); continuing.`);
+  }
 
   console.log("");
   printGatewayNextSteps({ target, app });