impel-cli 0.10.0 → 0.11.1

package/README.md

@@ -148,7 +148,7 @@ 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 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
@@ -591,15 +591,17 @@ 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
+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:
+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 specialist `agentId` and
-`scopeParam`. It verifies that specialist is still available, starts one
+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
@@ -627,11 +629,12 @@ Invocation uses the clients' native agent behavior:
 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.
+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`
+load the generated standalone definitions directly from `$CODEX_HOME/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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "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

@@ -1,7 +1,8 @@
-// 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.
+// 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";
@@ -15,17 +16,17 @@ 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 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 SPECIALIST_TOOL_NAMES = [
-  SPECIALIST_LIST_TOOL,
-  SPECIALIST_START_TOOL,
-  SPECIALIST_READ_TOOL,
+const NATIVE_AGENT_TOOL_NAMES = [
+  NATIVE_AGENT_LIST_TOOL,
+  NATIVE_AGENT_START_TOOL,
+  NATIVE_AGENT_READ_TOOL,
 ];
-const SAFE_SPECIALIST_ID_RE = /^[A-Za-z0-9_.:-]{1,160}$/u;
+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;
 
@@ -63,61 +64,73 @@ function atomicPrivateWrite(filePath, contents) {
 
 function boundedString(value, field, { max = 1024, pattern = null } = {}) {
   if (typeof value !== "string" || !value.trim()) {
-    throw new Error(`specialist catalog returned an invalid ${field}`);
+    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(`specialist catalog returned an invalid ${field}`);
+    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(`specialist catalog returned an invalid ${field}`);
+    throw new Error(`native-agent catalog returned an invalid ${field}`);
   }
   return value.map((item) => boundedString(item, field, { max: 512 }));
 }
 
-export function normalizeSpecialistCatalog(payload, expectedTenantId) {
+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("specialist catalog returned an invalid response");
+    throw new Error("native-agent catalog returned an invalid response");
   }
   if (normalizeTenantId(payload.orgId) !== tenantId) {
-    throw new Error("specialist catalog returned the wrong organization");
+    throw new Error("native-agent 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");
+  if (!Array.isArray(payload.agents) || payload.agents.length > MAX_CATALOG_ITEMS) {
+    throw new Error("native-agent catalog returned an invalid agents 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 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(specialist.agentId, "agentId", {
+    const agentId = boundedString(agent.agentId, "agentId", {
       max: 160,
-      pattern: SAFE_SPECIALIST_ID_RE,
+      pattern: SAFE_AGENT_ID_RE,
     });
-    if (seenIds.has(agentId)) throw new Error(`specialist catalog returned duplicate agentId ${agentId}`);
-    seenIds.add(agentId);
+    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(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 }),
+      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, specialists };
+  return { orgId: tenantId, agents };
 }
 
 function decodeMcpResponse(contentType, body) {
@@ -151,13 +164,13 @@ async function postMcp({ endpoint, credential, sessionId, message, fetchImpl, ti
     });
   } catch (error) {
     const detail = error?.name === "AbortError" ? "request timed out" : error?.message || error;
-    throw new Error(`specialist MCP request failed: ${redactSecretText(detail)}`);
+    throw new Error(`native-agent 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}`);
+    throw new Error(`native-agent MCP returned HTTP ${response.status}`);
   }
   return {
     sessionId: response.headers.get("mcp-session-id") || sessionId || null,
@@ -169,26 +182,26 @@ 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");
+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 || "specialist MCP tool failed"));
+    throw new Error(redactSecretText(message.error.message || "native-agent MCP tool failed"));
   }
   const result = message.result;
-  if (result?.isError) throw new Error("specialist MCP list tool returned an error");
+  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("specialist MCP list tool returned no catalog");
+  if (!text) throw new Error("native-agent MCP list tool returned no catalog");
   try {
     return JSON.parse(text);
   } catch {
-    throw new Error("specialist MCP list tool returned invalid JSON");
+    throw new Error("native-agent MCP list tool returned invalid JSON");
   }
 }
 
-export async function fetchSpecialistCatalog({
+export async function fetchNativeAgentCatalog({
   gatewayUrl,
   credential,
   tenantId,
@@ -218,7 +231,7 @@ export async function fetchSpecialistCatalog({
   sessionId = initialized.sessionId;
   const initializeMessage = responseForId(initialized.messages, 1);
   if (initializeMessage?.error || !initializeMessage?.result) {
-    throw new Error("specialist MCP initialization failed");
+    throw new Error("native-agent MCP initialization failed");
   }
 
   const ready = await postMcp({
@@ -240,11 +253,11 @@ export async function fetchSpecialistCatalog({
       jsonrpc: "2.0",
       id: 2,
       method: "tools/call",
-      params: { name: SPECIALIST_LIST_TOOL, arguments: {} },
+      params: { name: NATIVE_AGENT_LIST_TOOL, arguments: {} },
     },
   });
-  return normalizeSpecialistCatalog(
-    specialistPayloadFromToolResult(responseForId(listed.messages, 2)),
+  return normalizeNativeAgentCatalog(
+    nativeAgentPayloadFromToolResult(responseForId(listed.messages, 2)),
     tenantId,
   );
 }
@@ -257,29 +270,36 @@ function slug(value) {
     .slice(0, 48) || "agent";
 }
 
-function generatedAgentNames(tenantId, specialists) {
+function generatedAgentNames(tenantId, agents) {
   const used = new Map();
-  return specialists.map((specialist) => {
-    const base = `impel-${slug(tenantId)}-${slug(specialist.agentId)}`.slice(0, 63).replace(/-+$/u, "");
+  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(specialist.agentId).digest("hex").slice(0, 8);
+    const suffix = crypto.createHash("sha256")
+      .update(`${agent.scopeParam}:${agent.agentId}`)
+      .digest("hex")
+      .slice(0, 8);
     return `${base.slice(0, 54)}-${suffix}`;
   });
 }
 
-function adapterInstructions(tenantId, specialist) {
+function adapterInstructions(tenantId, agent) {
   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.`
+  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 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.`,
+    `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(" ");
 }
@@ -288,15 +308,15 @@ 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);
+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:",
-    ...SPECIALIST_TOOL_NAMES.map((tool) => `  - ${JSON.stringify(nativeToolName(tool))}`),
+    ...NATIVE_AGENT_TOOL_NAMES.map((tool) => `  - ${JSON.stringify(nativeToolName(tool))}`),
     "mcpServers:",
     `  - ${MANAGED_AGENT_MCP_SERVER}:`,
     "      type: stdio",
@@ -307,14 +327,14 @@ function renderClaudeAgent({ tenantId, specialist, name, invocation }) {
     ...Object.entries(invocation.env || {}).map(([key, value]) => `        ${key}: ${JSON.stringify(value)}`),
     "---",
     "",
-    adapterInstructions(tenantId, specialist),
+    adapterInstructions(tenantId, agent),
     "",
   ];
   return lines.join("\n");
 }
 
-function renderCodexAgent({ tenantId, specialist, name, invocation }) {
-  const description = `Runs ${specialist.title} for Impel tenant ${tenantId}: ${specialist.description}`.slice(0, 900);
+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(", ");
@@ -322,32 +342,32 @@ function renderCodexAgent({ tenantId, specialist, name, invocation }) {
     `name = ${JSON.stringify(name)}`,
     `description = ${JSON.stringify(description)}`,
     'sandbox_mode = "read-only"',
-    `developer_instructions = ${JSON.stringify(adapterInstructions(tenantId, specialist))}`,
+    `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 = [${SPECIALIST_TOOL_NAMES.map((tool) => JSON.stringify(tool)).join(", ")}]`,
+    `enabled_tools = [${NATIVE_AGENT_TOOL_NAMES.map((tool) => JSON.stringify(tool)).join(", ")}]`,
     ...(envEntries ? [`env = { ${envEntries} }`] : []),
     "",
   ];
-  for (const tool of SPECIALIST_TOOL_NAMES) {
+  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, specialists, invocation = impelMcpInvocation(["--tenant", tenantId])) {
+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, specialists);
-  return specialists.map((specialist, index) => {
+  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, specialist, name, invocation })
-      : renderCodexAgent({ tenantId: normalizedTenant, specialist, name, invocation });
-    return { agentId: specialist.agentId, name, fileName: `${name}${extension}`, contents };
+      ? renderClaudeAgent({ tenantId: normalizedTenant, agent, name, invocation })
+      : renderCodexAgent({ tenantId: normalizedTenant, agent, name, invocation });
+    return { agentId: agent.agentId, name, fileName: `${name}${extension}`, contents };
   });
 }
 
@@ -378,17 +398,17 @@ function readManifest(manifestPath) {
 
 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;
+  if (!manifest || manifest.version !== 2 || 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))
+    && fs.existsSync(path.join(profile.root, "agents", fileName))
   );
 }
 
-export function syncAgentProfile({ client, root, label, tenantId, specialists, now = Date.now() }) {
+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()) {
@@ -399,10 +419,26 @@ export function syncAgentProfile({ client, root, label, tenantId, specialists, n
   privateDirectory(managedDir);
   const manifestPath = path.join(managedDir, MANAGED_AGENT_MANIFEST);
   const prior = readManifest(manifestPath);
-  const rendered = renderManagedAgents(client, tenantId, specialists);
+  const rendered = renderManagedAgents(client, tenantId, agents);
+  const priorFiles = new Set(prior?.files || []);
+  const priorUsesDiscoveryRoot = prior?.version === 2;
 
+  // Native clients discover standalone definitions directly under `agents/`.
+  // Preflight every destination before writing so an unmanaged file with the
+  // same generated name is never overwritten.
   for (const agent of rendered) {
-    atomicPrivateWrite(path.join(managedDir, agent.fileName), agent.contents);
+    const destination = path.join(agentsDir, agent.fileName);
+    if (fs.existsSync(destination)) {
+      if (!priorUsesDiscoveryRoot || !priorFiles.has(agent.fileName)) {
+        throw new Error(`refusing to overwrite unmanaged native-agent file ${destination}`);
+      }
+      if (fs.lstatSync(destination).isSymbolicLink()) {
+        throw new Error(`refusing to overwrite symlinked native-agent file ${destination}`);
+      }
+    }
+  }
+  for (const agent of rendered) {
+    atomicPrivateWrite(path.join(agentsDir, agent.fileName), agent.contents);
   }
   const currentFiles = new Set(rendered.map((agent) => agent.fileName));
   for (const stale of prior?.files || []) {
@@ -412,16 +448,31 @@ export function syncAgentProfile({ client, root, label, tenantId, specialists, n
       && !currentFiles.has(stale)
       && (stale.endsWith(".md") || stale.endsWith(".toml"))
     ) {
-      fs.rmSync(path.join(managedDir, stale), { force: true });
+      fs.rmSync(path.join(priorUsesDiscoveryRoot ? agentsDir : managedDir, stale), { force: true });
+    }
+  }
+  if (!priorUsesDiscoveryRoot) {
+    for (const legacy of prior?.files || []) {
+      if (
+        typeof legacy === "string"
+        && path.basename(legacy) === legacy
+        && (legacy.endsWith(".md") || legacy.endsWith(".toml"))
+      ) {
+        fs.rmSync(path.join(managedDir, legacy), { force: true });
+      }
     }
   }
   atomicPrivateWrite(manifestPath, `${JSON.stringify({
-    version: 1,
+    version: 2,
     tenantId,
     client,
     syncedAt: new Date(now).toISOString(),
     files: [...currentFiles].sort(),
-    agents: rendered.map(({ agentId, name }) => ({ agentId, name })),
+    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] };
 }
@@ -434,7 +485,7 @@ export async function syncAgentProfiles({
   staleOnly = false,
   ttlMs = AGENT_SYNC_TTL_MS,
   now = Date.now(),
-  fetchCatalog = fetchSpecialistCatalog,
+  fetchCatalog = fetchNativeAgentCatalog,
   logger = console,
 }) {
   if (process.env.IMPEL_SKIP_AGENT_SYNC === "1" || process.env.IMPEL_SKIP_AGENT_SYNC === "true") {
@@ -455,10 +506,10 @@ export async function syncAgentProfiles({
     const result = syncAgentProfile({
       ...profile,
       tenantId: normalizedTenant,
-      specialists: catalog.specialists,
+      agents: catalog.agents,
       now,
     });
-    logger.log(`Agents: ${profile.label || profile.client} up to date (${result.count} tenant specialist${result.count === 1 ? "" : "s"}).`);
+    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];

package/src/cli.js

@@ -44,7 +44,7 @@ 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
+  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)

package/src/commands/agents.js

@@ -1,5 +1,5 @@
 // `impel agents sync [claude|codex|all]` — synchronize the selected tenant's
-// opted-in Impel specialists into every managed native custom-agent registry.
+// explicitly invocable Impel agents into every managed native registry.
 
 import os from "node:os";
 
@@ -8,13 +8,14 @@ import { loadConfig, normalizeGatewayUrl, redactSecretText, resolveDefaultGatewa
 import { ensureTenantSelection, tenantCredential } from "../tenants.js";
 import { managedSkillProfiles } from "./skills.js";
 
-const HELP = `impel agents - sync tenant specialists as native custom agents
+const HELP = `impel agents - sync explicit tenant agents into native clients
 
 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.`;
+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";