impel-cli 0.9.2 → 0.11.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,11 +148,12 @@ 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 explicit tenant agents into native clients
 
 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>]     Install/configure a tenant on first use, then launch
@@ -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`)
 
@@ -389,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
 
@@ -584,6 +589,55 @@ 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 explicit native-agent catalog through the
+authenticated Impel MCP endpoint, then generates native custom-agent files for
+every managed profile. This catalog is separate from automatic specialists: it
+may include truthfully declared write-capable agents, but those agents require
+explicit user selection before the server will start a run.
+
+- 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 `agentId` and
+`scopeParam`. It verifies that the exact agent 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
+Explicitly use the configured impel-acme-research-agent 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
@@ -675,7 +729,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.2",
+  "version": "0.11.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,504 @@
+// Synchronizes explicitly invocable tenant-scoped Impel agents into the native
+// custom-agent registries used by Claude Code and Codex. Unlike the public
+// shared-skill marketplace, the native-agent catalog is authenticated and
+// organization specific, so it is fetched through the selected tenant's MCP
+// session. Automatic read-only specialists remain a separate catalog.
+
+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 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 MANAGED_AGENT_MCP_SERVER = "impel_agent";
+
+const NATIVE_AGENT_TOOL_NAMES = [
+  NATIVE_AGENT_LIST_TOOL,
+  NATIVE_AGENT_START_TOOL,
+  NATIVE_AGENT_READ_TOOL,
+];
+const SAFE_AGENT_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(`native-agent catalog returned an invalid ${field}`);
+  }
+  const normalized = value.trim();
+  if (normalized.length > max || (pattern && !pattern.test(normalized))) {
+    throw new Error(`native-agent catalog returned an invalid ${field}`);
+  }
+  return normalized;
+}
+
+function stringList(value, field) {
+  if (!Array.isArray(value) || value.length > 100) {
+    throw new Error(`native-agent catalog returned an invalid ${field}`);
+  }
+  return value.map((item) => boundedString(item, field, { max: 512 }));
+}
+
+function enumString(value, field, allowed) {
+  const normalized = boundedString(value, field, { max: 80 });
+  if (!allowed.includes(normalized)) {
+    throw new Error(`native-agent catalog returned an invalid ${field}`);
+  }
+  return normalized;
+}
+
+export function normalizeNativeAgentCatalog(payload, expectedTenantId) {
+  const tenantId = normalizeTenantId(expectedTenantId);
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("native-agent catalog returned an invalid response");
+  }
+  if (normalizeTenantId(payload.orgId) !== tenantId) {
+    throw new Error("native-agent catalog returned the wrong organization");
+  }
+  if (!Array.isArray(payload.agents) || payload.agents.length > MAX_CATALOG_ITEMS) {
+    throw new Error("native-agent catalog returned an invalid agents list");
+  }
+
+  const seenBindings = new Set();
+  const agents = payload.agents.map((agent) => {
+    if (!agent || typeof agent !== "object" || Array.isArray(agent)) {
+      throw new Error("native-agent catalog returned an invalid agent");
+    }
+    const agentId = boundedString(agent.agentId, "agentId", {
+      max: 160,
+      pattern: SAFE_AGENT_ID_RE,
+    });
+    const scopeParam = boundedString(agent.scopeParam, "scopeParam", {
+      max: 160,
+      pattern: SAFE_SCOPE_PARAM_RE,
+    });
+    const binding = `${scopeParam}:${agentId}`;
+    if (seenBindings.has(binding)) {
+      throw new Error(`native-agent catalog returned duplicate binding ${binding}`);
+    }
+    seenBindings.add(binding);
+    return {
+      agentId,
+      title: boundedString(agent.title, "title", { max: 160 }),
+      description: boundedString(agent.description, "description", { max: 1024 }),
+      scopeParam,
+      provider: enumString(agent.provider, "provider", ["claude_code", "codex"]),
+      capabilities: stringList(agent.capabilities, "capabilities"),
+      exclusions: stringList(agent.exclusions, "exclusions"),
+      requiredContext: stringList(agent.requiredContext, "requiredContext"),
+      sideEffects: enumString(agent.sideEffects, "sideEffects", ["read-only", "writes"]),
+    };
+  });
+  return { orgId: tenantId, agents };
+}
+
+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(`native-agent MCP request failed: ${redactSecretText(detail)}`);
+  } finally {
+    clearTimeout(timeout);
+  }
+  const body = await response.text();
+  if (!response.ok) {
+    throw new Error(`native-agent 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 nativeAgentPayloadFromToolResult(message) {
+  if (!message) throw new Error("native-agent MCP returned no tool result");
+  if (message.error) {
+    throw new Error(redactSecretText(message.error.message || "native-agent MCP tool failed"));
+  }
+  const result = message.result;
+  if (result?.isError) throw new Error("native-agent 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("native-agent MCP list tool returned no catalog");
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error("native-agent MCP list tool returned invalid JSON");
+  }
+}
+
+export async function fetchNativeAgentCatalog({
+  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("native-agent 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: NATIVE_AGENT_LIST_TOOL, arguments: {} },
+    },
+  });
+  return normalizeNativeAgentCatalog(
+    nativeAgentPayloadFromToolResult(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, agents) {
+  const used = new Map();
+  return agents.map((agent) => {
+    const base = `impel-${slug(tenantId)}-${slug(agent.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(`${agent.scopeParam}:${agent.agentId}`)
+      .digest("hex")
+      .slice(0, 8);
+    return `${base.slice(0, 54)}-${suffix}`;
+  });
+}
+
+function adapterInstructions(tenantId, agent) {
+  const toolName = nativeToolName;
+  const contextRequirement = agent.requiredContext.length
+    ? ` Required context keys are ${JSON.stringify(agent.requiredContext)}; if any are absent, ask for them before starting the run.`
+    : "";
+  const sideEffectInstruction = agent.sideEffects === "writes"
+    ? `The catalog 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; that explicit selection is the required side-effect confirmation, so pass confirmedSideEffects true. If the agent was chosen automatically or the selection is ambiguous, do not start it and ask the user to select it explicitly.`
+    : `The catalog declares that this agent is read-only; omit confirmedSideEffects.`;
+  return [
+    `You are a thin transport adapter for the exact Impel native agent ${JSON.stringify(agent.agentId)} in tenant ${JSON.stringify(tenantId)}.`,
+    `Do not perform the assigned task yourself and do not delegate to any other agent.`,
+    `First call ${toolName(NATIVE_AGENT_LIST_TOOL)} and verify that the exact agentId is still available with sideEffects ${JSON.stringify(agent.sideEffects)}. If it is unavailable or its policy excludes the request, stop with that explicit error.`,
+    sideEffectInstruction,
+    `Call ${toolName(NATIVE_AGENT_START_TOOL)} exactly once with agentId ${JSON.stringify(agent.agentId)}, scopeParam ${JSON.stringify(agent.scopeParam)}, task set to the complete assigned task, context and contextKeys containing all supplied context, confirmedSideEffects as directed above, and one stable idempotencyKey that you reuse for this logical task.${contextRequirement}`,
+    `Then call ${toolName(NATIVE_AGENT_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, agent, name, invocation }) {
+  const description = `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 lines = [
+    "---",
+    `name: ${JSON.stringify(name)}`,
+    `description: ${JSON.stringify(description)}`,
+    "model: inherit",
+    "tools:",
+    ...NATIVE_AGENT_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, agent),
+    "",
+  ];
+  return lines.join("\n");
+}
+
+function renderCodexAgent({ tenantId, agent, name, invocation }) {
+  const description = `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 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, agent))}`,
+    "",
+    `[mcp_servers.${MANAGED_AGENT_MCP_SERVER}]`,
+    `command = ${JSON.stringify(invocation.command)}`,
+    `args = [${invocation.args.map((argument) => JSON.stringify(argument)).join(", ")}]`,
+    `enabled_tools = [${NATIVE_AGENT_TOOL_NAMES.map((tool) => JSON.stringify(tool)).join(", ")}]`,
+    ...(envEntries ? [`env = { ${envEntries} }`] : []),
+    "",
+  ];
+  for (const tool of NATIVE_AGENT_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, agents, invocation = impelMcpInvocation(["--tenant", tenantId])) {
+  if (client !== "claude" && client !== "codex") throw new Error(`unknown agent client ${client}`);
+  const normalizedTenant = normalizeTenantId(tenantId);
+  const names = generatedAgentNames(normalizedTenant, agents);
+  return agents.map((agent, index) => {
+    const name = names[index];
+    const extension = client === "claude" ? ".md" : ".toml";
+    const contents = client === "claude"
+      ? renderClaudeAgent({ tenantId: normalizedTenant, agent, name, invocation })
+      : renderCodexAgent({ tenantId: normalizedTenant, agent, name, invocation });
+    return { agentId: agent.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, agents, 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, agents);
+
+  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 }, index) => ({
+      agentId,
+      scopeParam: agents[index].scopeParam,
+      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 = fetchNativeAgentCatalog,
+  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,
+      agents: catalog.agents,
+      now,
+    });
+    logger.log(`Agents: ${profile.label || profile.client} up to date (${result.count} explicit tenant agent${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,7 +25,7 @@ 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
@@ -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 explicit tenant agents into native clients
 
 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,97 @@
+// `impel agents sync [claude|codex|all]` — synchronize the selected tenant's
+// explicitly invocable Impel agents into every managed native 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 explicit tenant agents into native clients
+
+Usage:
+  impel agents sync [claude|codex|all]
+
+The selected tenant's authenticated explicit-agent catalog is written into
+every managed native profile. Write-capable agents require explicit user
+selection before a run can start. 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,
   };
@@ -277,6 +286,12 @@ export async function cmdWindowsApps(argv, overrides = {}) {
         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") {
@@ -379,7 +394,7 @@ export async function cmdApps(argv, overrides = {}) {
       targets,
       statuses,
       homeDir: os.homedir(),
-    });
+    }, overrides);
     return;
   }
   if (action !== "install" && action !== "update") {
@@ -428,6 +443,13 @@ 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,
+  });
 }
 
 /**
@@ -450,6 +472,7 @@ export async function provisionAndOpenManagedApps({
     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),
@@ -519,6 +542,12 @@ export async function provisionAndOpenManagedApps({
     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;
 }
@@ -630,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 });