impel-cli 0.20.37 → 0.20.38

package/README.md

@@ -180,24 +180,35 @@ impel claude --model opus
 impel codex exec "review this repository"
 ```
 
-To run one explicitly selected tenant agent in a single Codex thread, select
+To run one explicitly selected tenant agent in a single native thread, select
 it by exact agent ID (preferred) or unique exact title:
 
 ```sh
+impel claude --agent research-agent --print "answer this question"
 impel codex --agent research-agent exec "answer this question"
 ```
 
-This path loads a generated, tenant-bound profile with the ultra-fast Codex
-Spark model at low reasoning for the thin adapter turns, a read-only local
-sandbox, the exact fixed MCP binding, and only that binding's answer/run,
-resume, and recovery tools. It omits unrelated local repository, app,
-collaboration, permission, environment, and skill-catalog prompt context; the
-selected Eve agent still performs the substantive work. The path also omits
-the normal parent specialist instructions, so there is no parent spawn, parent
-wait, or relay turn. Model, profile, developer-instruction, MCP, approval,
-sandbox, and feature overrides are rejected with `--agent`. The selected
-tenant and profile integrity must match before Codex starts. Ordinary `impel
-codex` passthrough is unchanged.
+Both managed paths verify the selected tenant manifest and generated adapter
+bytes, resolve the canonical native agent name, and omit the normal parent
+specialist instructions. Claude Code receives the explicit 2.1.220 opt-in and
+session permission mode required to run only that adapter's fixed MCP
+allowlist. Impel re-declares the verified adapter under a random per-launch
+name and loads only the isolated user settings source, so project, user, plugin,
+and fixed organization agent names cannot replace it. User-authored Claude
+agents that are absent from the Impel manifest keep Claude's ordinary
+permission behavior. Model, prompt, agent-definition, tool, MCP, settings,
+plugin, worktree, and permission overrides are rejected for a verified managed
+Claude selection.
+
+Codex loads a generated, tenant-bound profile with the ultra-fast Codex Spark
+model at low reasoning for the thin adapter turns, a read-only local sandbox,
+the exact fixed MCP binding, and only that binding's answer/run, resume, and
+recovery tools. It omits unrelated local repository, app, collaboration,
+permission, environment, and skill-catalog prompt context; the selected Eve
+agent still performs the substantive work. Model, profile,
+developer-instruction, MCP, approval, sandbox, and feature overrides are
+rejected for its managed path. Ordinary `impel claude`, user-authored Claude
+agent, and `impel codex` passthrough are unchanged.
 
 ## Remote Fargate sessions
 
@@ -518,6 +529,7 @@ must remain explicit and destructive-state aware.
 impel setup
 impel update
 impel claude
+impel claude --agent <id|exact-title> ...
 impel codex
 impel codex --agent <id|exact-title> ...
 impel tenant list|current|use

package/RELEASE_NOTES.md

@@ -1,5 +1,17 @@
 # Release notes
 
+## 0.20.38 — Restore managed Claude agent permissions
+
+- Verifies an exact synchronized Claude agent and its generated file digest
+  before enabling Claude Code 2.1.220's required bypass-permission opt-in and
+  session mode for that fixed MCP-only adapter.
+- Resolves exact agent IDs and titles to a byte-verified definition, declares
+  it under a random per-launch name with user-only setting sources, omits the
+  parent delegation prompt, and rejects model, prompt, tool, MCP, settings,
+  plugin, worktree, and permission overrides on the managed path.
+- Leaves ordinary Claude launches, user-authored Claude agents, and every
+  Codex launch path unchanged.
+
 ## 0.20.37 — Resume ambiguous native answers
 
 - Retries Next's typed ambiguous direct-answer response with the exact persisted

package/docs/native-agent-host-capability-matrix.md

@@ -6,7 +6,7 @@ is treated as an eager host.
 
 | Surface | Pinned build | Exact selected tools | Selected path | Host behavior |
 | --- | --- | --- | --- | --- |
-| Claude Code | 2.1.220 | Yes, agent frontmatter `tools` | Eager | The bound run/answer, resume, and recovery tools are direct child tools. No catalog discovery or code-cell polling is required. |
+| Claude Code | 2.1.220 | Yes, agent frontmatter `tools` | Eager; optional single-thread selection | The bound run/answer, resume, and recovery tools are direct child tools. `impel claude --agent` verifies the exact managed adapter before enabling 2.1.220's bypass-permission opt-in and mode. |
 | Claude Desktop | 1.26832.0 (embedded Code 2.1.222) | Yes, agent frontmatter `tools` | Eager | Same direct-tool contract as Claude Code. |
 | Codex CLI through `impel codex` | 0.147.0 | Yes, with `features.code_mode.direct_only_tool_namespaces = ["mcp__impel_agent"]` | Eager; optional single-thread profile | Existing `@Agent` children call the fixed MCP namespace directly. `impel codex --agent` also removes the parent spawn/wait/relay thread. |
 | ChatGPT desktop Codex | 26.803.41515 (embedded Codex 0.147.0-alpha.6.5) | Yes, with the same exact native namespace | Eager child, compatible parent | Keeps the app's supported `@Agent` parent/child route, but the child no longer needs code cells or code-mode waits. |
@@ -16,6 +16,17 @@ is treated as an eager host.
 - Eager profiles expose only the exact fixed binding's answer/run, resume, and
   recovery tools. `IMPEL_NATIVE_EAGER_TRANSPORT=0` independently restores the
   legacy host-visible tool configuration without deleting profiles or runs.
+- A top-level Claude selection receives `--allow-dangerously-skip-permissions`
+  plus `--permission-mode bypassPermissions` only after its manifest record,
+  canonical definition, fixed MCP binding, and generated file bytes have been
+  verified. User-authored agents keep native Claude behavior.
+- The verified definition is passed through `--agents` under a random
+  per-launch name while `--setting-sources user` excludes project/local
+  definitions. This outranks user and plugin names and makes collisions with a
+  fixed organization-managed agent name impractical.
+- Verified Claude selections reject model, prompt, agent-definition, tool,
+  MCP, settings, plugin, worktree, and permission-policy overrides before
+  native launch.
 - Every local composite keeps one upstream MCP session for its process lifetime,
   validates the exact binding once, and persists the authoritative run handle
   before ambiguous retries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.20.37",
+  "version": "0.20.38",
   "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
   "bin": {

package/src/agents.js

@@ -17,6 +17,7 @@ import {
 } from "./config.js";
 import {
   CODEX_NATIVE_AGENT_ATTACHMENT_WINDOW_MS,
+  IMPEL_MANAGED_MCP_ENV,
   IMPEL_NATIVE_AGENT_ATTACHMENT_WINDOW_ENV,
   IMPEL_NATIVE_AGENT_TELEMETRY_ENV_NAMES,
   IMPEL_NATIVE_AGENT_MCP_TARGET,
@@ -55,7 +56,7 @@ export const NATIVE_AGENT_RESUME_TOOL = "resume_native_agent_run";
 export const NATIVE_AGENT_RECOVER_TOOL = "recover_native_agent_runs";
 export const NATIVE_AGENT_CONTINUATION_SCHEMA = "impel.native-agent-continuation.v1";
 export const MANAGED_AGENT_MCP_SERVER = "impel_agent";
-export const MANAGED_AGENT_MANIFEST_VERSION = 19;
+export const MANAGED_AGENT_MANIFEST_VERSION = 20;
 
 // The host model only selects the fixed MCP tool and faithfully returns its
 // result. Spark minimizes those transport-only turns while the selected Eve
@@ -82,6 +83,7 @@ const TERMINAL_NATIVE_AGENT_STATUSES = new Set(["succeeded", "failed", "cancelle
 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;
+const MAX_CLAUDE_INLINE_AGENT_JSON_BYTES = 12 * 1024;
 const RETRYABLE_AGENT_CATALOG_ERROR = /request timed out|fetch failed|ECONNRESET|ETIMEDOUT|EAI_AGAIN|network error/iu;
 const RESERVED_AGENT_NAMES = Object.freeze({
   claude: new Set(["explore", "general-purpose", "plan"]),
@@ -711,44 +713,73 @@ function customAgentDescription(tenantId, agent) {
   ).slice(0, 900);
 }
 
-function renderClaudeAgent({ tenantId, agent, name, invocation, recoveryOnly = false }) {
+function claudeAgentDefinition({ tenantId, agent, invocation, recoveryOnly = false }) {
   const description = recoveryOnly
     ? `Recovery-only access to pending runs for retired Impel binding ${agent.agentId} in tenant ${tenantId}.`
     : customAgentDescription(tenantId, agent);
   const toolNames = recoveryOnly ? NATIVE_AGENT_RECOVERY_TOOL_NAMES : nativeAgentToolNames(agent);
   const eager = eagerNativeAgentTransportEnabled();
+  return {
+    description,
+    prompt: recoveryOnly ? retiredAdapterInstructions(tenantId, agent) : claudeAdapterInstructions(tenantId, agent),
+    model: "haiku",
+    ...(eager ? {
+      permissionMode: "bypassPermissions",
+      tools: toolNames.map((tool) => nativeToolName(tool)),
+    } : {}),
+    mcpServers: [{
+      [MANAGED_AGENT_MCP_SERVER]: {
+        type: "stdio",
+        command: invocation.command,
+        args: [...invocation.args],
+        env: { ...(invocation.env || {}) },
+      },
+    }],
+  };
+}
+
+function renderClaudeAgentDefinition(name, definition) {
+  const server = definition.mcpServers[0][MANAGED_AGENT_MCP_SERVER];
   const lines = [
     "---",
     `name: ${JSON.stringify(name)}`,
-    `description: ${JSON.stringify(description)}`,
-    "model: haiku",
-    ...(eager
+    `description: ${JSON.stringify(definition.description)}`,
+    `model: ${definition.model}`,
+    ...(definition.permissionMode
       ? [
         // This agent receives only the exact fixed-binding MCP allowlist below,
         // so bypassing prompts cannot grant filesystem, shell, connector, or
         // arbitrary MCP access. It lets non-interactive/dontAsk hosts execute
         // the selected managed adapter instead of auto-denying its sole call.
-        "permissionMode: bypassPermissions",
+        `permissionMode: ${definition.permissionMode}`,
         "tools:",
-        ...toolNames.map((tool) => `  - ${JSON.stringify(nativeToolName(tool))}`),
+        ...definition.tools.map((tool) => `  - ${JSON.stringify(tool)}`),
       ]
       : []),
     "mcpServers:",
     `  - ${MANAGED_AGENT_MCP_SERVER}:`,
     "      type: stdio",
-    `      command: ${JSON.stringify(invocation.command)}`,
+    `      command: ${JSON.stringify(server.command)}`,
     "      args:",
-    ...invocation.args.map((argument) => `        - ${JSON.stringify(argument)}`),
+    ...server.args.map((argument) => `        - ${JSON.stringify(argument)}`),
     "      env:",
-    ...Object.entries(invocation.env || {}).map(([key, value]) => `        ${key}: ${JSON.stringify(value)}`),
+    ...Object.entries(server.env).map(([key, value]) => `        ${key}: ${JSON.stringify(value)}`),
     "---",
     "",
-    recoveryOnly ? retiredAdapterInstructions(tenantId, agent) : claudeAdapterInstructions(tenantId, agent),
+    definition.prompt,
     "",
   ];
   return lines.join("\n");
 }
 
+function renderClaudeAgent({ tenantId, agent, name, invocation, recoveryOnly = false }) {
+  const definition = claudeAgentDefinition({ tenantId, agent, invocation, recoveryOnly });
+  return {
+    contents: renderClaudeAgentDefinition(name, definition),
+    launchDefinition: definition,
+  };
+}
+
 function codexInvocationEnvironment(invocation, { durableProfile = false } = {}) {
   const entries = Object.entries(invocation.env || {});
   const transient = new Set(IMPEL_NATIVE_AGENT_TELEMETRY_ENV_NAMES);
@@ -871,9 +902,11 @@ export function renderManagedAgents(client, tenantId, agents, invocation = null,
     // collision-safe, filesystem-safe identifiers, so use them as filenames.
     const fileStem = client === "claude" ? name : fileStems[index];
     const boundInvocation = boundNativeAgentInvocation(normalizedTenant, agent, invocation);
-    const contents = client === "claude"
+    const claudeRendered = client === "claude"
       ? renderClaudeAgent({ tenantId: normalizedTenant, agent, name, invocation: boundInvocation })
-      : renderCodexAgent({ tenantId: normalizedTenant, agent, name, invocation: boundInvocation, directCodeMode });
+      : null;
+    const contents = claudeRendered?.contents
+      ?? renderCodexAgent({ tenantId: normalizedTenant, agent, name, invocation: boundInvocation, directCodeMode });
     const profileName = client === "codex" ? fileStem : null;
     return {
       agentId: agent.agentId,
@@ -885,6 +918,7 @@ export function renderManagedAgents(client, tenantId, agents, invocation = null,
       name,
       fileName: `${fileStem}${extension}`,
       contents,
+      ...(claudeRendered ? { launchDefinition: claudeRendered.launchDefinition } : {}),
       ...(profileName ? {
         profileName,
         profileFileName: `${profileName}.config.toml`,
@@ -939,9 +973,11 @@ function renderRetiredManagedAgents(client, tenantId, bindings, active, invocati
       policyFingerprint: binding.policyFingerprint,
       mode: "recovery",
     });
-    const contents = client === "claude"
+    const claudeRendered = client === "claude"
       ? renderClaudeAgent({ tenantId, agent, name, invocation: boundInvocation, recoveryOnly: true })
-      : renderCodexAgent({ tenantId, agent, name, invocation: boundInvocation, recoveryOnly: true, directCodeMode });
+      : null;
+    const contents = claudeRendered?.contents
+      ?? renderCodexAgent({ tenantId, agent, name, invocation: boundInvocation, recoveryOnly: true, directCodeMode });
     const profileName = client === "codex" ? path.basename(fileName, extension) : null;
     return {
       agentId: binding.agentId,
@@ -953,6 +989,7 @@ function renderRetiredManagedAgents(client, tenantId, bindings, active, invocati
       name,
       fileName,
       contents,
+      ...(claudeRendered ? { launchDefinition: claudeRendered.launchDefinition } : {}),
       ...(profileName ? {
         profileName,
         profileFileName: `${profileName}.config.toml`,
@@ -999,7 +1036,8 @@ function managedManifestPath(root) {
 }
 
 function contentDigest(contents) {
-  return crypto.createHash("sha256").update(contents, "utf8").digest("hex");
+  const bytes = Buffer.isBuffer(contents) ? contents : Buffer.from(contents, "utf8");
+  return crypto.createHash("sha256").update(bytes).digest("hex");
 }
 
 function managedArtifactIsCurrent(root, relativePath, expectedDigest) {
@@ -1009,8 +1047,9 @@ function managedArtifactIsCurrent(root, relativePath, expectedDigest) {
   if (!/^[a-f0-9]{64}$/u.test(expectedDigest || "")) return false;
   const artifactPath = path.join(root, ...segments);
   try {
-    if (fs.lstatSync(artifactPath).isSymbolicLink()) return false;
-    return contentDigest(fs.readFileSync(artifactPath, "utf8")) === expectedDigest;
+    const stat = fs.lstatSync(artifactPath);
+    if (stat.isSymbolicLink() || !stat.isFile()) return false;
+    return contentDigest(fs.readFileSync(artifactPath)) === expectedDigest;
   } catch {
     return false;
   }
@@ -1033,6 +1072,156 @@ export function readManagedAgentManifest(root) {
   return readManifest(managedManifestPath(root));
 }
 
+function exactObjectKeys(value, keys) {
+  return value
+    && typeof value === "object"
+    && !Array.isArray(value)
+    && JSON.stringify(Object.keys(value).sort()) === JSON.stringify([...keys].sort());
+}
+
+function validateClaudeLaunchDefinition(record, tenantId) {
+  const definition = record.launchDefinition;
+  if (!exactObjectKeys(definition, [
+    "description", "prompt", "model", "permissionMode", "tools", "mcpServers",
+  ])
+    || typeof definition.description !== "string"
+    || !definition.description
+    || definition.description.length > 900
+    || typeof definition.prompt !== "string"
+    || !definition.prompt
+    || Buffer.byteLength(definition.prompt, "utf8") > 256 * 1024
+    || definition.model !== "haiku"
+    || definition.permissionMode !== "bypassPermissions"
+    || !Array.isArray(definition.tools)
+    || definition.tools.length < 2
+    || definition.tools.length > 3
+    || new Set(definition.tools).size !== definition.tools.length
+    || !definition.tools.every((tool) => [
+      NATIVE_AGENT_ANSWER_TOOL,
+      NATIVE_AGENT_RUN_TOOL,
+      NATIVE_AGENT_RESUME_TOOL,
+      NATIVE_AGENT_RECOVER_TOOL,
+    ].map((name) => nativeToolName(name)).includes(tool))
+    || !Array.isArray(definition.mcpServers)
+    || definition.mcpServers.length !== 1
+    || !exactObjectKeys(definition.mcpServers[0], [MANAGED_AGENT_MCP_SERVER])) {
+    throw new Error("the managed Claude launch definition is invalid; run `impel agents sync claude`");
+  }
+  const server = definition.mcpServers[0][MANAGED_AGENT_MCP_SERVER];
+  const allowedEnvironment = new Set([IMPEL_MANAGED_MCP_ENV, ...IMPEL_NATIVE_AGENT_TELEMETRY_ENV_NAMES]);
+  if (!exactObjectKeys(server, ["type", "command", "args", "env"])
+    || server.type !== "stdio"
+    || typeof server.command !== "string"
+    || !server.command
+    || !Array.isArray(server.args)
+    || !server.args.every((argument) => typeof argument === "string")
+    || !server.env
+    || typeof server.env !== "object"
+    || Array.isArray(server.env)
+    || server.env[IMPEL_MANAGED_MCP_ENV] !== "1"
+    || !Object.entries(server.env).every(([key, value]) =>
+      allowedEnvironment.has(key)
+      && typeof value === "string"
+      && value.length <= 4096
+      && redactCredentialText(value) === value
+    )) {
+    throw new Error("the managed Claude MCP definition is invalid; run `impel agents sync claude`");
+  }
+  const answerOnly = server.args.at(-1) === "--answer-only";
+  const trustedInvocation = impelNativeAgentMcpInvocation({
+    tenantId,
+    agentId: record.agentId,
+    scopeParam: record.scopeParam,
+    policyFingerprint: record.policyFingerprint,
+    mode: answerOnly ? "answer" : "durable",
+  });
+  const expectedTools = (answerOnly
+    ? [NATIVE_AGENT_ANSWER_TOOL, NATIVE_AGENT_RESUME_TOOL]
+    : NATIVE_AGENT_TOOL_NAMES
+  ).map((name) => nativeToolName(name));
+  if (server.command !== trustedInvocation.command
+    || JSON.stringify(server.args) !== JSON.stringify(trustedInvocation.args)
+    || JSON.stringify(definition.tools) !== JSON.stringify(expectedTools)) {
+    throw new Error("the managed Claude binding is invalid; run `impel agents sync claude`");
+  }
+  return definition;
+}
+
+// A selector absent from the Impel manifest remains Claude-native. A matching
+// record is integrity checked, then re-declared under a random per-launch name
+// through Claude's higher-priority --agents source. This prevents project,
+// user, plugin, and fixed managed-settings names from replacing the adapter.
+export function resolveManagedClaudeAgent(root, tenantId, selector) {
+  const normalizedTenant = normalizeTenantId(tenantId);
+  if (typeof selector !== "string" || !selector || selector.length > 512) return null;
+  const manifest = readManagedAgentManifest(root);
+  if (!manifest
+    || manifest.version !== MANAGED_AGENT_MANIFEST_VERSION
+    || manifest.client !== "claude"
+    || manifest.tenantId !== normalizedTenant
+    || !Array.isArray(manifest.agents)) {
+    return null;
+  }
+  const records = manifest.agents.filter((record) => record
+    && typeof record === "object"
+    && typeof record.name === "string");
+  const active = records.filter((record) => !record.retired);
+  let matches = active.filter((record) => record.agentId === selector);
+  if (matches.length === 0) matches = active.filter((record) => record.title === selector);
+  if (matches.length === 0) matches = active.filter((record) => record.name === selector);
+  if (matches.length === 0 && records.some((record) => record.retired && [
+    record.agentId,
+    record.title,
+    record.name,
+  ].includes(selector))) {
+    throw new Error(`managed Claude agent ${JSON.stringify(selector)} is retired and cannot start new work`);
+  }
+  if (matches.length === 0) return null;
+  if (matches.length !== 1) {
+    throw new Error(
+      `managed Claude agent ${JSON.stringify(selector)} is ambiguous for tenant ${JSON.stringify(normalizedTenant)}`,
+    );
+  }
+  const [record] = matches;
+  if (typeof record.agentId !== "string"
+    || !SAFE_AGENT_ID_RE.test(record.agentId)
+    || typeof record.scopeParam !== "string"
+    || !SAFE_SCOPE_PARAM_RE.test(record.scopeParam)
+    || !/^[a-f0-9]{64}$/u.test(record.policyFingerprint || "")) {
+    throw new Error("the managed Claude binding metadata is invalid; run `impel agents sync claude`");
+  }
+  const fileName = `${record.name}.md`;
+  if (path.basename(fileName) !== fileName || !manifest.files.includes(fileName)) {
+    throw new Error("the managed Claude agent mapping is invalid; run `impel agents sync claude`");
+  }
+  const relativePath = `agents/${fileName}`;
+  if (!managedArtifactIsCurrent(root, relativePath, manifest.contentDigests?.[relativePath])) {
+    throw new Error("the managed Claude agent failed its integrity check; run `impel agents sync claude`");
+  }
+  const launchDefinition = validateClaudeLaunchDefinition(record, normalizedTenant);
+  if (contentDigest(renderClaudeAgentDefinition(record.name, launchDefinition))
+    !== manifest.contentDigests?.[relativePath]) {
+    throw new Error("the managed Claude launch definition does not match its agent file; run `impel agents sync claude`");
+  }
+  const suffix = crypto.randomBytes(12).toString("hex");
+  const prefix = `impel-${record.name}`.slice(0, 63 - suffix.length - 1).replace(/-+$/u, "");
+  const launchName = `${prefix}-${suffix}`;
+  const launchAgentsJson = JSON.stringify({ [launchName]: launchDefinition });
+  if (Buffer.byteLength(launchAgentsJson, "utf8") > MAX_CLAUDE_INLINE_AGENT_JSON_BYTES) {
+    throw new Error(
+      `managed Claude agent ${JSON.stringify(selector)} is too large for a safe cross-platform direct launch; shorten its synchronized catalog policy`,
+    );
+  }
+  return {
+    ...record,
+    fileName,
+    path: path.join(root, "agents", fileName),
+    launchName,
+    launchDefinition,
+    launchAgentsJson,
+  };
+}
+
 export function resolveManagedCodexAgentProfile(root, tenantId, selector) {
   const normalizedTenant = normalizeTenantId(tenantId);
   const normalizedSelector = boundedString(selector, "agent selector", { max: 512 });
@@ -1236,6 +1425,9 @@ export function syncAgentProfile({
       policyFingerprint: agent.policyFingerprint,
       retired: agent.retired,
       name: agent.name,
+      ...(client === "claude" ? {
+        launchDefinition: agent.launchDefinition,
+      } : {}),
       ...(client === "codex" && directProfiles ? {
         profileName: agent.profileName,
         profileFileName: agent.profileFileName,

package/src/cli.js

@@ -34,6 +34,7 @@ Get started:
 
 Work:
   impel claude [args...]                      Launch Claude Code with an isolated Impel profile
+  impel claude --agent <id|exact-title> ...   Run one fixed tenant agent without a parent hop
   impel codex [args...]                       Launch Codex with an isolated Impel profile
   impel codex --agent <id|exact-title> ...    Run one fixed tenant agent without a parent hop
   impel remote handoff|dispatch|handback      Move or control provider-native sessions remotely

package/src/commands/launch.js

@@ -6,7 +6,11 @@ import {
   ensureImpelClaudeProfile,
   ensureImpelCodexProfile,
 } from "../cliProfiles.js";
-import { resolveManagedCodexAgentProfile, syncAgentProfilesSafe } from "../agents.js";
+import {
+  resolveManagedClaudeAgent,
+  resolveManagedCodexAgentProfile,
+  syncAgentProfilesSafe,
+} from "../agents.js";
 import {
   crossAppModelsEnabled,
   loadConfig,
@@ -77,10 +81,43 @@ const IMPEL_CODEX_RUNTIME_OVERRIDES = [
 ];
 
 const IMPEL_CODEX_UNRESTRICTED_ARGUMENT = "--dangerously-bypass-approvals-and-sandbox";
+const IMPEL_CLAUDE_MANAGED_AGENT_ARGUMENTS = [
+  "--allow-dangerously-skip-permissions",
+  "--permission-mode",
+  "bypassPermissions",
+  // Pinned Claude 2.1.220 treats agents, skills, commands, and settings as
+  // source-scoped. Load only the isolated user profile so project/local agent
+  // definitions cannot replace the integrity-verified adapter after launch.
+  "--setting-sources",
+  "user",
+];
 
-export function impelLaunchArguments(tool, argv, { codexAgentProfile = null } = {}) {
+export function impelLaunchArguments(tool, argv, {
+  claudeManagedAgent = null,
+  codexAgentProfile = null,
+} = {}) {
   if (!RUNTIME_BRAND.features.agents) return [...argv];
   if (tool === "claude") {
+    if (claudeManagedAgent) {
+      const { launchName, launchAgentsJson } = claudeManagedAgent;
+      if (typeof launchName !== "string"
+        || !launchName
+        || typeof launchAgentsJson !== "string"
+        || !launchAgentsJson) {
+        throw new Error("managed Claude launch configuration is invalid");
+      }
+      if (Buffer.byteLength(launchAgentsJson, "utf8") > 12 * 1024) {
+        throw new Error("managed Claude launch configuration is too large");
+      }
+      return [
+        ...IMPEL_CLAUDE_MANAGED_AGENT_ARGUMENTS,
+        "--agents",
+        launchAgentsJson,
+        "--agent",
+        launchName,
+        ...argv,
+      ];
+    }
     return ["--append-system-prompt", IMPEL_CLAUDE_PARENT_DELEGATION_INSTRUCTIONS, ...argv];
   }
   if (tool === "codex") {
@@ -99,6 +136,113 @@ export function impelLaunchArguments(tool, argv, { codexAgentProfile = null } =
   throw new Error(`unsupported CLI launcher: ${tool}`);
 }
 
+const CLAUDE_MANAGED_AGENT_LOCKED_OPTIONS = new Set([
+  "--add-dir",
+  "--agents",
+  "--allow-tools",
+  "--allow-dangerously-skip-permissions",
+  "--allowedTools",
+  "--allowed-tools",
+  "--append-subagent-system-prompt",
+  "--append-system-prompt",
+  "--append-system-prompt-file",
+  "--bare",
+  "--brief",
+  "--chrome",
+  "--dangerously-skip-permissions",
+  "--disable-slash-commands",
+  "--disallowedTools",
+  "--disallowed-tools",
+  "--effort",
+  "--exclude-dynamic-system-prompt-sections",
+  "--fallback-model",
+  "--file",
+  "--ide",
+  "--managed-settings",
+  "--mcp-config",
+  "--model",
+  "--no-chrome",
+  "--permission-mode",
+  "--permission-prompt-tool",
+  "--plugin-dir",
+  "--plugin-dir-no-mcp",
+  "--plugin-url",
+  "--safe-mode",
+  "--setting-sources",
+  "--settings",
+  "--strict-mcp-config",
+  "--system-prompt",
+  "--system-prompt-file",
+  "--tmux",
+  "--tools",
+  "--worktree",
+]);
+
+function claudeManagedAgentLockedOption(argument) {
+  if (argument === "-w" || (argument.startsWith("-w") && argument.length > 2)) return "-w";
+  if (CLAUDE_MANAGED_AGENT_LOCKED_OPTIONS.has(argument)) return argument;
+  return [...CLAUDE_MANAGED_AGENT_LOCKED_OPTIONS].find((option) =>
+    argument.startsWith(`${option}=`)
+  ) || null;
+}
+
+export function parseClaudeAgentLaunchArguments(argv) {
+  const passthrough = [];
+  const selectors = [];
+  let literal = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (literal) {
+      passthrough.push(argument);
+      continue;
+    }
+    if (argument === "--") {
+      literal = true;
+      passthrough.push(argument);
+      continue;
+    }
+    if (argument === "--agent") {
+      const value = argv[index += 1];
+      selectors.push(typeof value === "string" && value && !value.startsWith("-") ? value : null);
+      continue;
+    }
+    if (argument.startsWith("--agent=")) {
+      const value = argument.slice("--agent=".length);
+      selectors.push(value && !value.startsWith("-") ? value : null);
+      continue;
+    }
+    passthrough.push(argument);
+  }
+  const selector = selectors.length === 1 ? selectors[0] : null;
+  return {
+    selector,
+    argv: selector === null ? [...argv] : passthrough,
+  };
+}
+
+export function assertManagedClaudeAgentLaunchArguments(argv) {
+  let literal = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (literal) continue;
+    if (argument === "--") {
+      literal = true;
+      continue;
+    }
+    if (argument === "--agent") {
+      index += 1;
+      continue;
+    }
+    if (argument.startsWith("--agent=")) continue;
+    const locked = claudeManagedAgentLockedOption(argument);
+    if (locked) {
+      throw new Error(
+        `${locked} cannot be used with a verified managed Claude agent; Impel locks model, instructions, tools, MCP, settings, and permission policy`,
+      );
+    }
+  }
+}
+
 const CODEX_AGENT_LOCKED_OPTIONS = new Set([
   "-c",
   "--config",
@@ -264,8 +408,11 @@ function runNativeCli(tool, argv, environment) {
 
 export async function cmdLaunch(tool, argv) {
   let nativeArgv = [...argv];
+  let claudeAgentSelector = null;
   let codexAgentSelector = null;
-  if (tool === "codex") {
+  if (tool === "claude" && RUNTIME_BRAND.features.agents) {
+    ({ selector: claudeAgentSelector, argv: nativeArgv } = parseClaudeAgentLaunchArguments(argv));
+  } else if (tool === "codex") {
     try {
       ({ selector: codexAgentSelector, argv: nativeArgv } = parseCodexAgentLaunchArguments(argv));
     } catch (error) {
@@ -356,6 +503,29 @@ export async function cmdLaunch(tool, argv) {
     });
   }
 
+  let claudeManagedAgent = null;
+  if (RUNTIME_BRAND.features.agents && claudeAgentSelector !== null) {
+    try {
+      claudeManagedAgent = resolveManagedClaudeAgent(
+        agentProfile.root,
+        tenantId,
+        claudeAgentSelector,
+      );
+      if (claudeManagedAgent) {
+        assertManagedClaudeAgentLaunchArguments(nativeArgv);
+      } else {
+        // `--agent` is also Claude's native user-agent selector. If the exact
+        // value is not in the integrity-tracked Impel manifest, preserve the
+        // user's original argv and ordinary permission behavior byte-for-byte.
+        nativeArgv = [...argv];
+      }
+    } catch (error) {
+      console.error(`impel claude: ${redactSecretText(error?.message || error)}`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   let codexAgentProfile = null;
   if (codexAgentSelector !== null) {
     try {
@@ -377,7 +547,10 @@ export async function cmdLaunch(tool, argv) {
   const { env: launchEnvironment } = withGitEnvironment(environment, { baseEnvironment: environment });
   const exitCode = await runNativeCli(
     tool,
-    impelLaunchArguments(tool, nativeArgv, { codexAgentProfile }),
+    impelLaunchArguments(tool, nativeArgv, {
+      claudeManagedAgent,
+      codexAgentProfile,
+    }),
     launchEnvironment,
   );
   if (exitCode !== 0) process.exitCode = exitCode;

package/src/selfInvocation.js

@@ -5,8 +5,18 @@ import { environmentValue } from "./nativeProcess.js";
 import { brandedEnvironmentName, RUNTIME_BRAND } from "./runtimeBrand.js";
 
 /** The running package's own bin script, used directly for live child spawns. */
-export const IMPEL_CLI_ENTRYPOINT = process.env.IMPEL_CLI_EXTENSION_ENTRYPOINT
-  || fileURLToPath(new URL("../bin/impel.js", import.meta.url));
+const PACKAGE_CLI_ENTRYPOINT = fileURLToPath(new URL("../bin/impel.js", import.meta.url));
+const extensionEntrypoint = process.env.IMPEL_CLI_EXTENSION_ENTRYPOINT;
+// The public Impel package never delegates its trusted MCP command prefix to
+// inherited process state. First-party extension wrappers install a validated
+// non-Impel runtime brand before import, must actually be executing the named
+// entrypoint, and then prove that same path in createImpelCliExtension.
+export const IMPEL_CLI_ENTRYPOINT = RUNTIME_BRAND.cli.packageName === "impel-cli"
+  || typeof extensionEntrypoint !== "string"
+  || !path.isAbsolute(extensionEntrypoint)
+  || path.resolve(process.argv[1] || "") !== path.resolve(extensionEntrypoint)
+  ? PACKAGE_CLI_ENTRYPOINT
+  : extensionEntrypoint;
 
 // Matches a real package install (npm/pnpm/volta all place the package under
 // node_modules/impel-cli; an unsupported project-local install matches too,