@tencentcloudadp/cli 0.1.4 → 0.1.5

package/dist/cli.js

@@ -153,12 +153,12 @@ var CommandRegistry = class {
     };
   }
   schemaHint(tokens) {
-    const path14 = [];
+    const path18 = [];
     for (const token of tokens) {
-      if (!this.knownTokensAt(path14).has(token)) break;
-      path14.push(token);
+      if (!this.knownTokensAt(path18).has(token)) break;
+      path18.push(token);
     }
-    return path14.length > 0 ? `Run: adp schema --command "${path14.join(" ")}" --format json` : "Run: adp schema --compact --format json";
+    return path18.length > 0 ? `Run: adp schema --command "${path18.join(" ")}" --format json` : "Run: adp schema --compact --format json";
   }
   /**
    * Resolves argv's command tokens against the real command tree, returning a
@@ -191,26 +191,26 @@ var CommandRegistry = class {
     return void 0;
   }
   /** True when `path` is a group, i.e. something must follow it. */
-  isGroupPath(path14) {
-    const prefix = path14.join(" ");
+  isGroupPath(path18) {
+    const prefix = path18.join(" ");
     return this.commands.some((definition) => {
       const parts = literalTokens(definition.command);
-      return parts.length > path14.length && parts.slice(0, path14.length).join(" ") === prefix;
+      return parts.length > path18.length && parts.slice(0, path18.length).join(" ") === prefix;
     });
   }
   /** Every valid next token at a command path: leaf names and group names. */
-  knownTokensAt(path14) {
-    const prefix = path14.join(" ");
+  knownTokensAt(path18) {
+    const prefix = path18.join(" ");
     const tokens = /* @__PURE__ */ new Set();
     for (const definition of this.commands) {
       const parts = literalTokens(definition.command);
-      if (parts.length <= path14.length) {
+      if (parts.length <= path18.length) {
         continue;
       }
-      if (parts.slice(0, path14.length).join(" ") !== prefix) {
+      if (parts.slice(0, path18.length).join(" ") !== prefix) {
         continue;
       }
-      const next = parts[path14.length];
+      const next = parts[path18.length];
       if (next !== void 0) {
         tokens.add(next);
       }
@@ -583,7 +583,7 @@ function fitsRegisteredCommand(command, definitions) {
 }
 
 // src/infrastructure/logging/logger.ts
-var SECRET_RE = /secret[_-]?id|secret[_-]?key|secret[_-]?token|tmp[_-]?secret|app[_-]?key|x-cos-security-token|TENCENTCLOUD_/gi;
+var SECRET_RE = /secret[_-]?id|secret[_-]?key|secret[_-]?token|tmp[_-]?secret|app[_-]?key|tool[_-]?key|x-cos-security-token|TENCENTCLOUD_/gi;
 var SECRET_ID_RE = /\bAKID[0-9A-Za-z]+\b/g;
 function redact(value) {
   return value.replace(SECRET_ID_RE, "[redacted-secret-id]").replace(SECRET_RE, "[redacted]");
@@ -1145,24 +1145,11 @@ function assertNumericId(value, name, listCommand) {
   }
   return trimmed;
 }
-function canonicalizeLocalPath(input, cwd) {
+function assertLocalPath(input) {
   if (!input || hasControlChars(input)) {
     throw usageError("Invalid local path", "Pass a filesystem path without control characters");
   }
-  const { resolve, normalize } = pathFromNode();
-  return normalize(resolve(cwd, input));
-}
-function pathFromNode() {
-  const posixJoin = (left, right) => {
-    if (right.startsWith("/") || /^[A-Za-z]:[\\/]/.test(right)) {
-      return right;
-    }
-    return `${left.replace(/[/\\]+$/, "")}/${right.replace(/^[/\\]+/, "")}`;
-  };
-  return {
-    resolve: (...parts) => parts.reduce((acc, part) => posixJoin(acc, part)),
-    normalize: (p) => p.replace(/\\/g, "/").replace(/\/{2,}/g, "/")
-  };
+  return input;
 }
 
 // src/interfaces/cli/core/id-flags.ts
@@ -1890,13 +1877,15 @@ ${input.error ? `<p class="err">${escapeHtml(input.error)}</p>` : ""}
 
 // src/infrastructure/child-process/detached-login.ts
 import { spawn } from "child_process";
+import { win32 } from "path";
 var DETACHED_LOGIN_ENV = "ADP_WEB_LOGIN_IPC";
 async function launchDetachedLogin(input) {
-  const entry = process.argv[1];
+  const entry = input.entry ?? process.argv[1];
   if (!entry) {
     throw new DomainError("Cannot locate the adp entry script", "upstream", "DetachFailed");
   }
-  const child = spawn(process.execPath, [...process.execArgv, entry, ...input.args], {
+  const child = (input.spawnImpl ?? spawn)(input.execPath ?? process.execPath, [...input.execArgv ?? process.execArgv, entry, ...input.args], {
+    shell: false,
     detached: true,
     stdio: ["ignore", "ignore", "ignore", "ipc"],
     env: { ...input.env, [DETACHED_LOGIN_ENV]: "1" },
@@ -1909,9 +1898,10 @@ async function launchDetachedLogin(input) {
     }, input.handshakeTimeoutMs ?? 15e3);
     child.once("message", (message) => {
       clearTimeout(timer);
-      const parsed = message;
-      if (parsed.type !== "auth_url" || !parsed.url || !parsed.expiresAt) {
-        reject(new DomainError(parsed.error ?? "The login server failed to start", "upstream", "DetachFailed"));
+      const parsed = message && typeof message === "object" ? message : {};
+      if (parsed.type !== "auth_url" || typeof parsed.url !== "string" || typeof parsed.expiresAt !== "string" || !parsed.url || !parsed.expiresAt) {
+        child.kill();
+        reject(new DomainError(typeof parsed.error === "string" ? parsed.error : "The login server failed to start", "upstream", "DetachFailed"));
         return;
       }
       child.disconnect();
@@ -1928,10 +1918,27 @@ async function launchDetachedLogin(input) {
     });
   });
 }
-function openInBrowser(url) {
-  const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+function openInBrowser(url, options = {}) {
+  let target;
+  try {
+    target = new URL(url);
+  } catch {
+    throw new DomainError("Browser URL must be an absolute HTTP(S) URL", "usage", "InvalidBrowserUrl");
+  }
+  if (!["http:", "https:"].includes(target.protocol) || [...url].some((char) => char.charCodeAt(0) < 32)) {
+    throw new DomainError("Browser URL must use HTTP(S) without control characters", "usage", "InvalidBrowserUrl");
+  }
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const systemRoot = Object.entries(env).find(([key]) => key.toLowerCase() === "systemroot")?.[1] ?? "C:\\Windows";
+  const [command, args] = platform === "darwin" ? ["open", [target.href]] : platform === "win32" ? [win32.join(systemRoot, "System32", "rundll32.exe"), [`${win32.join(systemRoot, "System32", "url.dll")},FileProtocolHandler`, target.href]] : ["xdg-open", [target.href]];
   try {
-    const child = spawn(command, args, { detached: true, stdio: "ignore", windowsHide: true });
+    const child = (options.spawnImpl ?? spawn)(command, args, {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+      shell: false
+    });
     child.on("error", () => void 0);
     child.unref();
   } catch {
@@ -2007,27 +2014,51 @@ async function resolveIdentity(deps, input) {
 }
 
 // src/infrastructure/fs/profile-file-store.ts
-import { mkdir, readFile, readdir, rm, writeFile, chmod } from "fs/promises";
-import { homedir } from "os";
+import { readFile, readdir, rm } from "fs/promises";
+
+// src/infrastructure/fs/private-file.ts
+import { chmod, mkdir, writeFile } from "fs/promises";
 import path from "path";
+async function writePrivateFile(filePath, contents, options = {}) {
+  const fs = { mkdir, writeFile, chmod, ...options.fs };
+  const posix = (options.platform ?? process.platform) !== "win32";
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  if (posix) {
+    try {
+      await fs.chmod(filePath, 384);
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+  await fs.writeFile(filePath, contents, { encoding: "utf8", ...posix ? { mode: 384 } : {} });
+  if (posix) {
+    await fs.chmod(filePath, 384);
+  }
+}
+
+// src/infrastructure/fs/profile-file-store.ts
+import { homedir } from "os";
+import path2 from "path";
 function adpProfilesDir(home = homedir()) {
-  return path.join(home, ".adp", "profiles");
+  return path2.join(home, ".adp", "profiles");
 }
 function adpActiveProfilePath(home = homedir()) {
-  return path.join(home, ".adp", "active");
+  return path2.join(home, ".adp", "active");
 }
 function profileFileName(name) {
-  if (!name || name !== path.basename(name) || name.startsWith(".")) {
+  if (!name || name.startsWith(".") || /[<>:"/\\|?*]/u.test(name) || [...name].some((character) => character.charCodeAt(0) < 32) || /[. ]$/u.test(name) || /^(?:con|prn|aux|nul|conin\$|conout\$|com[1-9¹²³]|lpt[1-9¹²³]) *(?:\.|$)/iu.test(name)) {
     throw new Error(`Invalid profile name: ${name}`);
   }
   return `${name}.json`;
 }
-function createProfileStore(dir = adpProfilesDir(), activePath = adpActiveProfilePath()) {
+function createProfileStore(dir = adpProfilesDir(), activePath = adpActiveProfilePath(), privateFileOptions = {}) {
   return {
     async load(name) {
       let text13;
       try {
-        text13 = await readFile(path.join(dir, profileFileName(name)), "utf8");
+        text13 = await readFile(path2.join(dir, profileFileName(name)), "utf8");
       } catch (error) {
         if (error.code === "ENOENT") {
           return void 0;
@@ -2037,17 +2068,12 @@ function createProfileStore(dir = adpProfilesDir(), activePath = adpActiveProfil
       return parseProfile(name, text13);
     },
     async save(profile) {
-      await mkdir(dir, { recursive: true });
-      const target = path.join(dir, profileFileName(profile.name));
-      await writeFile(target, `${JSON.stringify(profile, null, 2)}
-`, {
-        encoding: "utf8",
-        mode: 384
-      });
-      await chmod(target, 384);
+      const target = path2.join(dir, profileFileName(profile.name));
+      await writePrivateFile(target, `${JSON.stringify(profile, null, 2)}
+`, privateFileOptions);
     },
     async remove(name) {
-      await rm(path.join(dir, profileFileName(name)), { force: true });
+      await rm(path2.join(dir, profileFileName(name)), { force: true });
     },
     async list() {
       let entries;
@@ -2082,15 +2108,13 @@ function createProfileStore(dir = adpProfilesDir(), activePath = adpActiveProfil
         }
         throw error;
       }
-      const name = text13.trim();
-      return name.length > 0 ? name : void 0;
+      const name = text13.replace(/[\r\n]+$/u, "");
+      return name.trim().length > 0 ? name : void 0;
     },
     async setActive(name) {
       profileFileName(name);
-      await mkdir(path.dirname(activePath), { recursive: true });
-      await writeFile(activePath, `${name}
-`, { encoding: "utf8", mode: 384 });
-      await chmod(activePath, 384);
+      await writePrivateFile(activePath, `${name}
+`, privateFileOptions);
     }
   };
 }
@@ -2401,7 +2425,7 @@ function mapSdkError(error) {
   if (/SecretIdNotFound/i.test(blob)) {
     return new DomainError(message, "auth", code, {
       ...options,
-      hint: "This SecretId is not a Tencent Cloud CAM key. Doc import (SaveDoc / RetryDocParse) and workflow canvas commands authenticate as LKE 2023-11-30. Independent-site OneID keys only work if the ADP endpoint proxies that LKE version; otherwise use a cloud profile (`adp login --site cloud`).",
+      hint: "This SecretId was not found on the host that received it. SaveDoc, RetryDocParse, and workflow canvas use the same LKE 2023-11-30 actions on every site: public cloud calls lke.tencentcloudapi.com, and an independent or custom profile sends them to its ADP host. Log in with the site that issued the key.",
       retryable: false
     });
   }
@@ -3096,11 +3120,11 @@ function mergePluginBindings(spec) {
       byId.set(tool.pluginId, { pluginId: tool.pluginId });
     }
   }
-  for (const pluginId2 of spec.pluginIds) {
-    byId.set(pluginId2, { pluginId: pluginId2 });
+  for (const pluginId3 of spec.pluginIds) {
+    byId.set(pluginId3, { pluginId: pluginId3 });
   }
-  for (const pluginId2 of spec.connectorIds ?? []) {
-    byId.set(pluginId2, { pluginId: pluginId2 });
+  for (const pluginId3 of spec.connectorIds ?? []) {
+    byId.set(pluginId3, { pluginId: pluginId3 });
   }
   for (const plugin of spec.plugins ?? []) {
     byId.set(plugin.pluginId, plugin);
@@ -3208,7 +3232,9 @@ function toSummary5(raw) {
   return {
     agentId: String(raw.AgentId ?? raw.agentId ?? ""),
     name: optionalString3(raw.Name ?? raw.name ?? profile.Name) ?? "",
-    description: optionalString3(raw.Description ?? raw.description ?? profile.Description)
+    description: optionalString3(raw.Description ?? raw.description ?? profile.Description),
+    role: roleOf(raw.Role ?? profile.Role),
+    parentAgentId: optionalString3(raw.ParentAgentId ?? profile.ParentAgentId)
   };
 }
 function toDetail3(response, fallbackId) {
@@ -3255,9 +3281,14 @@ function toDetail3(response, fallbackId) {
     agentId: String(response.AgentId ?? agent.AgentId ?? fallbackId),
     name: optionalString3(profile.Name),
     description: optionalString3(profile.Description),
+    role: roleOf(profile.Role),
+    parentAgentId: optionalString3(profile.ParentAgentId),
     spec
   };
 }
+function roleOf(value) {
+  return typeof value === "number" ? value : void 0;
+}
 function optionalString3(value) {
   return typeof value === "string" ? value : void 0;
 }
@@ -3463,14 +3494,14 @@ function isApiCreate(input) {
   return "spec" in input;
 }
 function createPluginGateway(client) {
-  async function describeRaw(pluginId2, spaceId) {
+  async function describeRaw(pluginId3, spaceId) {
     const response = await callSdk(
-      () => client.request("DescribePlugin", compact({ PluginId: pluginId2, SpaceId: spaceId }))
+      () => client.request("DescribePlugin", compact({ PluginId: pluginId3, SpaceId: spaceId }))
     );
     return asRecord2(response.Plugin ?? response);
   }
-  async function describePlugin2(pluginId2, spaceId) {
-    return toSummary7(await describeRaw(pluginId2, spaceId));
+  async function describePlugin2(pluginId3, spaceId) {
+    return toSummary7(await describeRaw(pluginId3, spaceId));
   }
   return {
     async list(input) {
@@ -4540,6 +4571,376 @@ function createPluginAccessGateway(client) {
   };
 }
 
+// src/infrastructure/tencent/tool-key-gateway.ts
+function asText(value) {
+  if (typeof value === "string" && value) {
+    return value;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(value);
+  }
+  return void 0;
+}
+function toRecord(raw) {
+  const record = asRecord2(raw);
+  const apiKeyId = asText(record.ApiKeyId);
+  if (!apiKeyId) {
+    return void 0;
+  }
+  const status = Number(record.Status);
+  return {
+    apiKeyId,
+    apiKey: asText(record.ApiKey) ?? "",
+    description: asText(record.Description) ?? "",
+    ...Number.isFinite(status) ? { status } : {},
+    ...asText(record.CreateTime) ? { createTime: asText(record.CreateTime) } : {},
+    ...asText(record.LastAccessTime) ? { lastAccessTime: asText(record.LastAccessTime) } : {}
+  };
+}
+function createToolKeyGateway(client) {
+  return {
+    async create() {
+      const response = await callSdk(() => client.request("CreateApiKey", {}));
+      return { apiKey: String(response.ApiKey ?? ""), apiKeyId: String(response.ApiKeyId ?? "") };
+    },
+    async list() {
+      const response = await callSdk(() => client.request("DescribeApiKeyList", {}));
+      const items = Array.isArray(response.ApiKeyList) ? response.ApiKeyList : [];
+      return items.map(toRecord).filter((item) => item !== void 0);
+    },
+    async update(input) {
+      await callSdk(
+        () => client.request("ModifyApiKey", { ApiKeyId: input.apiKeyId, Description: input.description })
+      );
+    },
+    async setStatus(input) {
+      await callSdk(
+        () => client.request("ModifyApiKeyStatus", { ApiKeyId: input.apiKeyId, Status: input.status })
+      );
+    },
+    async delete(input) {
+      await callSdk(() => client.request("DeleteApiKey", { ApiKeyId: input.apiKeyId }));
+    }
+  };
+}
+
+// src/domain/plugin/mcp-url.ts
+var PLUGIN_MCP_URL_PREFIX = "https://adp.cloud.tencent.com/";
+var PLUGIN_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+function pluginMcpUrl(pluginId3) {
+  if (!PLUGIN_ID.test(pluginId3)) {
+    throw usageError(
+      "Invalid plugin-id for an MCP URL",
+      "Pass the plugin id from adp plugin list. It must be one path segment, without slashes."
+    );
+  }
+  return `${PLUGIN_MCP_URL_PREFIX}plugin/mcp/${pluginId3}/mcp`;
+}
+function assertPluginMcpUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw mcpUrlRejected();
+  }
+  const allowed = new URL(PLUGIN_MCP_URL_PREFIX);
+  if (parsed.origin !== allowed.origin || parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw mcpUrlRejected();
+  }
+  if (!/^\/plugin\/mcp\/[A-Za-z0-9][A-Za-z0-9_-]{0,127}\/mcp$/.test(parsed.pathname)) {
+    throw mcpUrlRejected();
+  }
+}
+function mcpUrlRejected() {
+  return new DomainError(
+    "Refusing to send a tool key to a URL outside the plugin MCP allowlist",
+    "usage",
+    "McpUrlNotAllowed",
+    {
+      hint: "Calls only go to https://adp.cloud.tencent.com/plugin/mcp/<pluginId>/mcp",
+      retryable: false
+    }
+  );
+}
+
+// src/infrastructure/mcp/plugin-mcp-client.ts
+var PROTOCOL_VERSION = "2024-11-05";
+var CLIENT_INFO = { name: "adp-cli", version: "0.0.0" };
+var ERROR_BODY_PREVIEW = 400;
+function createPluginMcpGateway(options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  async function open(input) {
+    const url = pluginMcpUrl(input.pluginId);
+    assertPluginMcpUrl(url);
+    const session = createSession({ url, apiKey: input.apiKey, fetchImpl, timeoutMs: input.timeoutMs });
+    await session.initialize();
+    return session;
+  }
+  return {
+    async listTools(input) {
+      const session = await open(input);
+      return readTools(await session.sendRequest("tools/list", {}));
+    },
+    async callTool(input) {
+      const session = await open(input);
+      return unwrapToolPayload(
+        await session.sendRequest("tools/call", { name: input.toolName, arguments: input.arguments }),
+        input.apiKey
+      );
+    }
+  };
+}
+function createSession(options) {
+  let sessionId = "";
+  let nextId = 1;
+  async function post(payload) {
+    assertPluginMcpUrl(options.url);
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json, text/event-stream",
+      Authorization: `Bearer ${options.apiKey}`
+    };
+    if (sessionId) {
+      headers["Mcp-Session-Id"] = sessionId;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+    let response;
+    try {
+      response = await options.fetchImpl(options.url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: controller.signal,
+        redirect: "error"
+      });
+    } catch (cause) {
+      const aborted = cause instanceof Error && cause.name === "AbortError";
+      throw new DomainError(
+        aborted ? `MCP request timed out after ${options.timeoutMs}ms` : "MCP request failed",
+        "upstream",
+        aborted ? "Timeout" : "McpTransport",
+        { retryable: true, cause }
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+    const seen = response.headers.get("Mcp-Session-Id");
+    if (seen) {
+      sessionId = seen;
+    }
+    const body = await response.text();
+    if (response.status === 401 || response.status === 403) {
+      throw new DomainError(`MCP plugin rejected the tool key (HTTP ${response.status})`, "auth", "ToolKeyRejected", {
+        hint: "The key in ADP_API_KEY, --api-key-env, or ~/.adp/tool-key was rejected. Create a new one with adp plugin key create.",
+        retryable: false,
+        nextActions: [
+          { command: "adp plugin key create --format json", reason: "issue a new tool key and save it" }
+        ]
+      });
+    }
+    if (response.status >= 400) {
+      throw new DomainError(
+        `MCP request failed (HTTP ${response.status}): ${scrub(body, options.apiKey) || "(empty)"}`,
+        "upstream",
+        "McpTransport",
+        { retryable: response.status >= 500 }
+      );
+    }
+    return { status: response.status, body };
+  }
+  function unwrap(raw) {
+    if (!raw || typeof raw !== "object") {
+      return raw;
+    }
+    const frame = raw;
+    if (frame.error) {
+      throw new DomainError(
+        `MCP error: ${scrub(JSON.stringify(frame.error), options.apiKey)}`,
+        "upstream",
+        "McpServerError",
+        { retryable: false }
+      );
+    }
+    return frame.result ?? raw;
+  }
+  async function sendRequest(method, params) {
+    const id = nextId;
+    nextId += 1;
+    const { body } = await post({ jsonrpc: "2.0", id, method, params });
+    if (!body.trim()) {
+      throw new DomainError("MCP response was empty", "upstream", "McpProtocol", { retryable: true });
+    }
+    return unwrap(parseMcpBody(body));
+  }
+  return {
+    async initialize() {
+      await sendRequest("initialize", {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: CLIENT_INFO
+      });
+      await post({ jsonrpc: "2.0", method: "notifications/initialized", params: {} });
+    },
+    sendRequest
+  };
+}
+function parseMcpBody(body) {
+  try {
+    return JSON.parse(body);
+  } catch {
+  }
+  let lastData = [];
+  for (const chunk of body.split("\n\n")) {
+    const dataLines = chunk.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart());
+    if (dataLines.length > 0) {
+      lastData = dataLines;
+    }
+  }
+  if (lastData.length === 0) {
+    throw new DomainError("MCP response was neither JSON nor SSE", "upstream", "McpProtocol", { retryable: true });
+  }
+  try {
+    return JSON.parse(lastData.join("\n").trim());
+  } catch (cause) {
+    throw new DomainError("MCP response frame is not valid JSON", "upstream", "McpProtocol", {
+      retryable: true,
+      cause
+    });
+  }
+}
+function unwrapToolPayload(result, secret = "") {
+  if (!result || typeof result !== "object") {
+    return result;
+  }
+  const payload = result;
+  if (payload.isError) {
+    const parts = [];
+    if (Array.isArray(payload.content)) {
+      for (const item of payload.content) {
+        const text13 = item ?? {};
+        if (text13.type === "text") {
+          parts.push(String(text13.text ?? ""));
+        }
+      }
+    }
+    const message = scrub(parts.join("\n").trim(), secret);
+    throw new DomainError(`MCP tool failed: ${message || "(no text)"}`, "upstream", "McpToolError", { retryable: false });
+  }
+  if (Array.isArray(payload.content)) {
+    for (const item of payload.content) {
+      const text13 = item ?? {};
+      if (text13.type !== "text") {
+        continue;
+      }
+      const raw = String(text13.text ?? "");
+      try {
+        return JSON.parse(raw);
+      } catch {
+        return raw;
+      }
+    }
+  }
+  return result;
+}
+function readTools(result) {
+  const record = result && typeof result === "object" ? result : {};
+  const tools = Array.isArray(record.tools) ? record.tools : [];
+  return tools.flatMap((item) => {
+    if (!item || typeof item !== "object") {
+      return [];
+    }
+    const tool = item;
+    if (typeof tool.name !== "string" || !tool.name) {
+      return [];
+    }
+    const inputSchema = tool.inputSchema && typeof tool.inputSchema === "object" && !Array.isArray(tool.inputSchema) ? tool.inputSchema : void 0;
+    return [
+      {
+        name: tool.name,
+        ...typeof tool.description === "string" ? { description: tool.description } : {},
+        ...inputSchema ? { inputSchema } : {}
+      }
+    ];
+  });
+}
+function scrub(text13, secret) {
+  let out = text13;
+  const trimmed = secret.trim();
+  if (trimmed.length >= 4) {
+    out = out.split(trimmed).join("[redacted]");
+  }
+  return out.replace(/Bearer\s+\S+/gi, "Bearer [redacted]").slice(0, ERROR_BODY_PREVIEW);
+}
+
+// src/infrastructure/fs/tool-key-file-store.ts
+import { readFile as readFile2, rm as rm2 } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import path3 from "path";
+
+// src/infrastructure/fs/ini-credentials.ts
+function parseIni(text13) {
+  const result = {};
+  for (const rawLine of text13.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#") || line.startsWith(";") || line.startsWith("[")) {
+      continue;
+    }
+    const eq = line.indexOf("=");
+    if (eq < 0) {
+      continue;
+    }
+    const key = line.slice(0, eq).trim().toLowerCase();
+    const value = line.slice(eq + 1).trim();
+    if (key) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function renderIni(section, entries) {
+  const body = entries.filter((entry) => entry[1] !== void 0 && entry[1] !== "").map(([key, value]) => `${key} = ${value}`);
+  return [`[${section}]`, ...body, ""].join("\n");
+}
+
+// src/infrastructure/fs/tool-key-file-store.ts
+function adpToolKeyPath(home = homedir2()) {
+  return path3.join(home, ".adp", "tool-key");
+}
+function createToolKeyFileStore(filePath, privateFileOptions = {}) {
+  return {
+    async load() {
+      try {
+        const parsed = parseIni(await readFile2(filePath, "utf8"));
+        const value = (parsed.tool_key ?? parsed.api_key ?? "").trim();
+        if (!value) {
+          return void 0;
+        }
+        const apiKeyId = (parsed.api_key_id ?? "").trim();
+        return { value, ...apiKeyId ? { apiKeyId } : {} };
+      } catch (error) {
+        if (error.code === "ENOENT") {
+          return void 0;
+        }
+        throw error;
+      }
+    },
+    async save(input) {
+      await writePrivateFile(
+        filePath,
+        renderIni("default", [
+          ["tool_key", input.value],
+          ["api_key_id", input.apiKeyId]
+        ]),
+        privateFileOptions
+      );
+    },
+    async clear() {
+      await rm2(filePath, { force: true });
+    }
+  };
+}
+
 // src/infrastructure/tencent/skill-gateway.ts
 var CREATE_TYPE_FILE_UPLOAD = 1;
 function createSkillGateway(client) {
@@ -5060,7 +5461,7 @@ var DEFAULT_TIMEOUT_MS = 18e4;
 function createSseChatGateway(client, options = {}) {
   const chatUrl = options.chatUrl ?? DEFAULT_ADP_CHAT_SSE_URL;
   const fetchImpl = options.fetchImpl ?? fetch;
-  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const timeoutMs2 = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   return {
     async createSession(input) {
       if (input.conversationId && !isValidConversationId(input.conversationId)) {
@@ -5094,13 +5495,13 @@ function createSseChatGateway(client, options = {}) {
       };
     },
     async sendMessage(session, input, onEvent) {
-      await postSseChat(fetchImpl, chatUrl, session, input, onEvent, timeoutMs);
+      await postSseChat(fetchImpl, chatUrl, session, input, onEvent, timeoutMs2);
     },
     async close() {
     }
   };
 }
-async function postSseChat(fetchImpl, chatUrl, session, input, onEvent, timeoutMs) {
+async function postSseChat(fetchImpl, chatUrl, session, input, onEvent, timeoutMs2) {
   const body = buildChatRequest({
     conversationId: session.conversationId,
     appKey: session.appKey,
@@ -5110,7 +5511,7 @@ async function postSseChat(fetchImpl, chatUrl, session, input, onEvent, timeoutM
     attachments: input.attachments
   });
   const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const timer = setTimeout(() => controller.abort(), timeoutMs2);
   let response;
   try {
     response = await fetchImpl(chatUrl, {
@@ -5148,7 +5549,7 @@ async function postSseChat(fetchImpl, chatUrl, session, input, onEvent, timeoutM
     await readSseStream(stream, onEvent, seen);
   } catch (error) {
     if (isAbortError(error)) {
-      throw chatTimeoutError(timeoutMs, seen);
+      throw chatTimeoutError(timeoutMs2, seen);
     }
     if (error instanceof DomainError) {
       throw error;
@@ -5162,8 +5563,8 @@ async function postSseChat(fetchImpl, chatUrl, session, input, onEvent, timeoutM
   }
 }
 var MISSING_TOOL = /(mcp__[\w.-]*?(\w+)) not found/;
-function chatTimeoutError(timeoutMs, seen) {
-  const seconds2 = Math.round(timeoutMs / 1e3);
+function chatTimeoutError(timeoutMs2, seen) {
+  const seconds2 = Math.round(timeoutMs2 / 1e3);
   if (seen.missingTool) {
     return new DomainError(
       `Chat timed out after ${seconds2}s; the agent's tool ${seen.missingTool} was not found by the runtime`,
@@ -5573,12 +5974,12 @@ function toTask2(raw) {
 }
 function toMcpApp(raw) {
   const mcp = {};
-  const pluginId2 = optionalString8(raw.PluginId);
+  const pluginId3 = optionalString8(raw.PluginId);
   const resourceUri = optionalString8(raw.ResourceUri);
   const threadId = optionalString8(raw.ThreadId);
   const toolResult = optionalString8(raw.ToolResult);
-  if (pluginId2) {
-    mcp.pluginId = pluginId2;
+  if (pluginId3) {
+    mcp.pluginId = pluginId3;
   }
   if (resourceUri) {
     mcp.resourceUri = resourceUri;
@@ -6705,8 +7106,8 @@ function hmacSha1Hex(key, value) {
 }
 
 // src/infrastructure/fs/local-document-reader.ts
-import { readFile as readFile2 } from "fs/promises";
-import path2 from "path";
+import { readFile as readFile3 } from "fs/promises";
+import path4 from "path";
 
 // src/domain/knowledge/doc.ts
 var DOC_ENABLE_SCOPE_BOTH = 4;
@@ -6769,7 +7170,7 @@ function createFsLocalDocumentReader() {
     async read(absolutePath) {
       let bytes;
       try {
-        bytes = await readFile2(absolutePath);
+        bytes = await readFile3(absolutePath);
       } catch (error) {
         const code = error.code;
         throw usageError(
@@ -6777,7 +7178,7 @@ function createFsLocalDocumentReader() {
           code === "ENOENT" ? "Check --file points at an existing document" : "Check file permissions"
         );
       }
-      const fileName = path2.basename(absolutePath);
+      const fileName = path4.basename(absolutePath);
       return {
         fileName,
         fileType: fileTypeFromName(fileName),
@@ -6788,38 +7189,11 @@ function createFsLocalDocumentReader() {
 }
 
 // src/infrastructure/fs/credential-file-store.ts
-import { homedir as homedir2 } from "os";
-import { chmod as chmod2, mkdir as mkdir2, readFile as readFile3, rm as rm2, writeFile as writeFile2 } from "fs/promises";
-import path3 from "path";
-
-// src/infrastructure/fs/ini-credentials.ts
-function parseIni(text13) {
-  const result = {};
-  for (const rawLine of text13.split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (!line || line.startsWith("#") || line.startsWith(";") || line.startsWith("[")) {
-      continue;
-    }
-    const eq = line.indexOf("=");
-    if (eq < 0) {
-      continue;
-    }
-    const key = line.slice(0, eq).trim().toLowerCase();
-    const value = line.slice(eq + 1).trim();
-    if (key) {
-      result[key] = value;
-    }
-  }
-  return result;
-}
-function renderIni(section, entries) {
-  const body = entries.filter((entry) => entry[1] !== void 0 && entry[1] !== "").map(([key, value]) => `${key} = ${value}`);
-  return [`[${section}]`, ...body, ""].join("\n");
-}
-
-// src/infrastructure/fs/credential-file-store.ts
-function tencentCloudCredentialsPath(home = homedir2()) {
-  return path3.join(home, ".tencentcloud", "credentials");
+import { homedir as homedir3 } from "os";
+import { readFile as readFile4, rm as rm3 } from "fs/promises";
+import path5 from "path";
+function tencentCloudCredentialsPath(home = homedir3()) {
+  return path5.join(home, ".tencentcloud", "credentials");
 }
 function createEnvCredentialReader(env = process.env) {
   return {
@@ -6833,11 +7207,11 @@ function createEnvCredentialReader(env = process.env) {
     }
   };
 }
-function createCredentialFileStore(filePath, source2) {
+function createCredentialFileStore(filePath, source2, privateFileOptions = {}) {
   return {
     async load() {
       try {
-        const text13 = await readFile3(filePath, "utf8");
+        const text13 = await readFile4(filePath, "utf8");
         const parsed = parseIni(text13);
         const secretId = parsed.secret_id ?? parsed.secretid;
         const secretKey = parsed.secret_key ?? parsed.secretkey;
@@ -6853,26 +7227,30 @@ function createCredentialFileStore(filePath, source2) {
       }
     },
     async save(input) {
-      await mkdir2(path3.dirname(filePath), { recursive: true });
       const body = renderIni("default", [
         ["secret_id", input.secretId],
         ["secret_key", input.secretKey],
         ["token", input.token]
       ]);
-      await writeFile2(filePath, body, { encoding: "utf8", mode: 384 });
-      await chmod2(filePath, 384);
+      await writePrivateFile(filePath, body, privateFileOptions);
     },
     async clear() {
-      await rm2(filePath, { force: true });
+      await rm3(filePath, { force: true });
     }
   };
 }
 
 // src/infrastructure/fs/jsonc-config-store.ts
-import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
-import path4 from "path";
+import { mkdir as mkdir2, readFile as readFile5, writeFile as writeFile2 } from "fs/promises";
+import path7 from "path";
 import { parse as parseJsonc } from "jsonc-parser";
 
+// src/infrastructure/fs/local-path.ts
+import path6 from "path";
+function canonicalizeLocalPath(input, cwd, paths = path6) {
+  return paths.resolve(cwd, assertLocalPath(input));
+}
+
 // src/domain/project-config/env-overlay.ts
 function mergeEnvOverlay(base, overlay) {
   return {
@@ -7263,27 +7641,27 @@ function createJsoncConfigStore() {
   return {
     async load(options) {
       const cwd = options.cwd;
-      const configPath = path4.resolve(cwd, options.configPath ?? "adp.jsonc");
+      const configPath = canonicalizeLocalPath(options.configPath ?? "adp.jsonc", cwd);
       const { config: base, warnings } = await readConfigFile(configPath);
       const extra = warnings.length > 0 ? { warnings } : {};
       if (!options.envName) {
         return { config: base, configPath, ...extra };
       }
-      const overlayPath = path4.resolve(cwd, `adp.env.${options.envName}.jsonc`);
+      const overlayPath = canonicalizeLocalPath(`adp.env.${options.envName}.jsonc`, cwd);
       const overlay = await readOptionalConfig(overlayPath);
       return { config: overlay ? mergeEnvOverlay(base, overlay) : base, configPath, ...extra };
     },
     async write(configPath, config2) {
-      await mkdir3(path4.dirname(configPath), { recursive: true });
+      await mkdir2(path7.dirname(configPath), { recursive: true });
       const body = `${JSON.stringify(adpConfigToFile(config2), null, 2)}
 `;
-      await writeFile3(configPath, body, "utf8");
+      await writeFile2(configPath, body, "utf8");
     },
     async writeSidecar(cwd, relativePath, contents, options) {
       const resolved2 = canonicalizeLocalPath(relativePath, cwd);
-      await mkdir3(path4.dirname(resolved2), { recursive: true });
+      await mkdir2(path7.dirname(resolved2), { recursive: true });
       try {
-        await writeFile3(resolved2, contents, { encoding: "utf8", flag: options?.overwrite === false ? "wx" : "w" });
+        await writeFile2(resolved2, contents, { encoding: "utf8", flag: options?.overwrite === false ? "wx" : "w" });
       } catch (error) {
         if (error.code === "EEXIST") {
           return false;
@@ -7295,7 +7673,7 @@ function createJsoncConfigStore() {
     async readInstructions(cwd, relativePath) {
       const resolved2 = canonicalizeLocalPath(relativePath, cwd);
       try {
-        return await readFile4(resolved2, "utf8");
+        return await readFile5(resolved2, "utf8");
       } catch {
         throw new DomainError(`instructions file not found: ${relativePath} (resolved to ${resolved2})`, "usage", "InstructionsFileMissing", {
           hint: `Create ${resolved2} with the agent's system prompt, or replace agent.instructions_file with inline agent.instructions in adp.jsonc`,
@@ -7322,7 +7700,7 @@ function unknownConfigFields(parsed) {
 async function readConfigFile(configPath) {
   let text13;
   try {
-    text13 = await readFile4(configPath, "utf8");
+    text13 = await readFile5(configPath, "utf8");
   } catch {
     throw new DomainError(`Config not found: ${configPath}`, "usage", "UsageError", {
       hint: "Run: adp init   or pass --config path/to/adp.jsonc",
@@ -7356,7 +7734,7 @@ async function readConfigFile(configPath) {
 async function readOptionalConfig(configPath) {
   let text13;
   try {
-    text13 = await readFile4(configPath, "utf8");
+    text13 = await readFile5(configPath, "utf8");
   } catch (error) {
     if (error.code === "ENOENT") {
       return void 0;
@@ -7375,8 +7753,8 @@ async function readOptionalConfig(configPath) {
 }
 
 // src/infrastructure/fs/companion-skill-pack.ts
-import { cp, readFile as readFile5, stat } from "fs/promises";
-import path6 from "path";
+import { cp, readFile as readFile6, stat } from "fs/promises";
+import path9 from "path";
 import { existsSync as existsSync2 } from "fs";
 
 // src/domain/companion-skills/companion-skill.ts
@@ -7412,13 +7790,13 @@ function parseAgentKinds(value) {
 
 // src/infrastructure/fs/package-root.ts
 import { existsSync, readFileSync } from "fs";
-import path5 from "path";
+import path8 from "path";
 import { fileURLToPath } from "url";
 var CLI_PACKAGE_NAME = "@tencentcloudadp/cli";
-function resolvePackageRoot(startDir = path5.dirname(fileURLToPath(import.meta.url))) {
+function resolvePackageRoot(startDir = path8.dirname(fileURLToPath(import.meta.url))) {
   let dir = startDir;
   for (let i = 0; i < 10; i += 1) {
-    const pkgPath = path5.join(dir, "package.json");
+    const pkgPath = path8.join(dir, "package.json");
     if (existsSync(pkgPath)) {
       try {
         const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
@@ -7428,7 +7806,7 @@ function resolvePackageRoot(startDir = path5.dirname(fileURLToPath(import.meta.u
       } catch {
       }
     }
-    const parent = path5.dirname(dir);
+    const parent = path8.dirname(dir);
     if (parent === dir) {
       break;
     }
@@ -7439,9 +7817,9 @@ function resolvePackageRoot(startDir = path5.dirname(fileURLToPath(import.meta.u
     "Run adp from the installed npm package or the adp-cli repository"
   );
 }
-function readCliPackageIdentity(startDir = path5.dirname(fileURLToPath(import.meta.url))) {
+function readCliPackageIdentity(startDir = path8.dirname(fileURLToPath(import.meta.url))) {
   const root = resolvePackageRoot(startDir);
-  const pkgPath = path5.join(root, "package.json");
+  const pkgPath = path8.join(root, "package.json");
   const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
   if (typeof pkg.version !== "string" || pkg.version.trim().length === 0) {
     throw usageError(
@@ -7455,12 +7833,12 @@ function readCliPackageIdentity(startDir = path5.dirname(fileURLToPath(import.me
 // src/infrastructure/fs/companion-skill-pack.ts
 function createFsCompanionSkillPack(options = {}) {
   const packageRoot = options.packageRoot ?? resolvePackageRoot();
-  const skillsRoot = path6.join(packageRoot, "skills");
+  const skillsRoot = path9.join(packageRoot, "skills");
   return {
     async listSkillIds() {
       const ids4 = [];
       for (const name of COMPANION_SKILL_IDS) {
-        if (existsSync2(path6.join(skillsRoot, name, "SKILL.md"))) {
+        if (existsSync2(path9.join(skillsRoot, name, "SKILL.md"))) {
           ids4.push(name);
         }
       }
@@ -7473,18 +7851,18 @@ function createFsCompanionSkillPack(options = {}) {
       return ids4;
     },
     async skillSourceDir(skillId) {
-      const dir = path6.join(skillsRoot, skillId);
-      const skillFile = path6.join(dir, "SKILL.md");
+      const dir = path9.join(skillsRoot, skillId);
+      const skillFile = path9.join(dir, "SKILL.md");
       if (!existsSync2(skillFile)) {
         throw usageError(`Companion skill not found: ${skillId}`, `Looked for ${skillFile}`);
       }
       return dir;
     },
     async readDescription(sourceDir) {
-      const file = path6.join(sourceDir, "SKILL.md");
+      const file = path9.join(sourceDir, "SKILL.md");
       let raw;
       try {
-        raw = await readFile5(file, "utf8");
+        raw = await readFile6(file, "utf8");
       } catch {
         return "";
       }
@@ -7499,11 +7877,11 @@ function createFsCompanionSkillPack(options = {}) {
       }
     },
     joinPath(...parts) {
-      return path6.join(...parts);
+      return path9.join(...parts);
     },
     async copySkill(sourceDir, destDir, dryRun) {
-      const skillId = path6.basename(sourceDir);
-      if (path6.resolve(sourceDir) === path6.resolve(destDir)) {
+      const skillId = path9.basename(sourceDir);
+      if (path9.resolve(sourceDir) === path9.resolve(destDir)) {
         return { skillId, destDir, copied: false };
       }
       if (dryRun) {
@@ -7534,12 +7912,12 @@ function parseFrontmatterDescription(raw) {
 
 // src/infrastructure/fs/config-schema-locator.ts
 import { existsSync as existsSync3 } from "fs";
-import path7 from "path";
+import path10 from "path";
 function createFsConfigSchemaLocator(options = {}) {
   return {
     async resolvePath() {
       const root = options.packageRoot ?? resolvePackageRoot();
-      const schemaPath = path7.join(root, "config-schema.json");
+      const schemaPath = path10.join(root, "config-schema.json");
       if (!existsSync3(schemaPath)) {
         throw usageError(
           `config-schema.json not found at ${schemaPath}`,
@@ -7559,7 +7937,7 @@ var NETWORK_HINT = `Check network access to ${NPM_REGISTRY_ORIGIN}`;
 function createNpmRegistryGateway(options = {}) {
   const origin = options.origin?.trim() || NPM_REGISTRY_ORIGIN;
   const fetchImpl = options.fetchImpl ?? fetch;
-  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
+  const timeoutMs2 = options.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
   return {
     async getRelease(request) {
       const packageName = request.packageName.trim();
@@ -7573,7 +7951,7 @@ function createNpmRegistryGateway(options = {}) {
         response = await fetchImpl(url, {
           method: "GET",
           headers: { accept: "application/json", "user-agent": NPM_USER_AGENT },
-          signal: AbortSignal.timeout(timeoutMs)
+          signal: AbortSignal.timeout(timeoutMs2)
         });
       } catch (error) {
         throw registryError(
@@ -7625,12 +8003,83 @@ function trimTrailingSlash(origin) {
 
 // src/infrastructure/child-process/spawn-command-runner.ts
 import { spawn as spawn2 } from "child_process";
-function createSpawnCommandRunner(options = {}) {
-  const stdio = options.stdio ?? "inherit";
-  return (request) => new Promise((resolve, reject) => {
-    const child = spawn2(request.command, request.args, { stdio });
-    child.on("error", reject);
-    child.on("close", (code, signal) => {
+
+// src/infrastructure/child-process/windows-command.ts
+import { statSync } from "fs";
+import { win32 as win322 } from "path";
+function isFile(path18) {
+  try {
+    return statSync(path18).isFile();
+  } catch {
+    return false;
+  }
+}
+function envValue(env, name) {
+  const key = Object.keys(env).find((key2) => key2.toLowerCase() === name.toLowerCase());
+  return key === void 0 ? void 0 : env[key];
+}
+function windowsCommand(command, args, options = {}) {
+  const env = options.env ?? process.env;
+  const fileExists = options.isFile ?? isFile;
+  const cwd = options.cwd ?? process.cwd();
+  const extensions = [".exe", ".com", ".cmd", ".bat"];
+  const configured = (envValue(env, "PATHEXT") ?? ".COM;.EXE;.BAT;.CMD").split(";").map((ext) => ext.toLowerCase()).filter((ext) => extensions.includes(ext));
+  const suffixes = win322.extname(command) ? [""] : configured;
+  const dirs = /[\\/]/.test(command) ? [""] : [cwd, ...(envValue(env, "PATH") ?? "").split(";")];
+  let resolved2;
+  for (const dir of dirs) {
+    for (const suffix of suffixes) {
+      const candidate = win322.resolve(cwd, dir.replace(/^"|"$/g, ""), command + suffix);
+      if (fileExists(candidate)) {
+        resolved2 = candidate;
+        break;
+      }
+    }
+    if (resolved2) break;
+  }
+  const executable = resolved2 ?? command;
+  if (!/\.(cmd|bat)$/i.test(executable)) {
+    return { command: executable, args: [...args], windowsVerbatimArguments: false };
+  }
+  const manager = win322.basename(executable).replace(/\.(cmd|bat)$/i, "").toLowerCase();
+  if (resolved2 && ["npm", "pnpm", "yarn"].includes(manager)) {
+    const root = win322.dirname(executable);
+    const entries = manager === "npm" ? ["node_modules/npm/bin/npm-cli.js"] : manager === "pnpm" ? ["node_modules/pnpm/bin/pnpm.cjs", "node_modules/pnpm/bin/pnpm.js"] : ["node_modules/yarn/bin/yarn.js"];
+    entries.push(`node_modules/corepack/dist/${manager}.js`);
+    const entry = entries.map((path18) => win322.join(root, path18)).find(fileExists);
+    if (entry) {
+      return { command: options.execPath ?? process.execPath, args: [entry, ...args], windowsVerbatimArguments: false };
+    }
+  }
+  const quote = (value) => {
+    if ([...value].some((char) => char.charCodeAt(0) < 32) || /["%!?^&|<>()]/.test(value) || value.endsWith("\\")) {
+      throw new Error("Unsupported character in Windows batch command; use a Node.js entry or executable instead");
+    }
+    return `"${value}"`;
+  };
+  const line = `"${[executable, ...args].map(quote).join(" ")}"`;
+  if (line.length > 8e3) throw new Error("Windows batch command is too long");
+  if (!resolved2) throw Object.assign(new Error(`Executable not found: ${command}`), { code: "ENOENT" });
+  return {
+    command: win322.join(envValue(env, "SystemRoot") ?? "C:\\Windows", "System32", "cmd.exe"),
+    args: ["/d", "/s", "/v:off", "/c", line],
+    windowsVerbatimArguments: true
+  };
+}
+
+// src/infrastructure/child-process/spawn-command-runner.ts
+function createSpawnCommandRunner(options = {}) {
+  const stdio = options.stdio ?? "inherit";
+  return (request) => new Promise((resolve, reject) => {
+    const invocation = (options.platform ?? process.platform) === "win32" ? windowsCommand(request.command, request.args, options.windows) : { command: request.command, args: request.args, windowsVerbatimArguments: false };
+    const child = (options.spawnImpl ?? spawn2)(invocation.command, invocation.args, {
+      stdio,
+      shell: false,
+      windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+      ...options.windows?.env ? { env: options.windows.env } : {}
+    });
+    child.on("error", reject);
+    child.on("close", (code, signal) => {
       if (code === null) {
         reject(new Error(`${request.command} exited via signal ${signal ?? "unknown"}`));
         return;
@@ -7641,17 +8090,17 @@ function createSpawnCommandRunner(options = {}) {
 }
 
 // src/infrastructure/fs/update-check-store.ts
-import { homedir as homedir3 } from "os";
-import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile4 } from "fs/promises";
-import path8 from "path";
-function adpUpdateCheckPath(home = homedir3()) {
-  return path8.join(home, ".adp", "update-check.json");
+import { homedir as homedir4 } from "os";
+import { readFile as readFile7 } from "fs/promises";
+import path11 from "path";
+function adpUpdateCheckPath(home = homedir4()) {
+  return path11.join(home, ".adp", "update-check.json");
 }
-function createUpdateCheckStore(filePath = adpUpdateCheckPath()) {
+function createUpdateCheckStore(filePath = adpUpdateCheckPath(), privateFileOptions = {}) {
   return {
     async load() {
       try {
-        const record = JSON.parse(await readFile6(filePath, "utf8"));
+        const record = JSON.parse(await readFile7(filePath, "utf8"));
         if (typeof record?.latestVersion !== "string" || record.latestVersion.length === 0) {
           return void 0;
         }
@@ -7672,23 +8121,16 @@ function createUpdateCheckStore(filePath = adpUpdateCheckPath()) {
       }
     },
     async save(record) {
-      try {
-        await mkdir4(path8.dirname(filePath), { recursive: true });
-        await writeFile4(filePath, `${JSON.stringify(record, null, 2)}
-`, {
-          encoding: "utf8",
-          mode: 384
-        });
-      } catch {
-      }
+      await writePrivateFile(filePath, `${JSON.stringify(record, null, 2)}
+`, privateFileOptions);
     }
   };
 }
 
 // src/infrastructure/fs/install-source-probe.ts
-import { homedir as homedir4 } from "os";
-import { readFile as readFile7, realpath, writeFile as writeFile5 } from "fs/promises";
-import path9 from "path";
+import { homedir as homedir5 } from "os";
+import { readFile as readFile8, realpath, writeFile as writeFile3 } from "fs/promises";
+import path12 from "path";
 
 // src/domain/update/install-source.ts
 var INSTALL_SOURCES = ["npm", "workbuddy"];
@@ -7724,7 +8166,7 @@ function createInstallSourceProbe(options) {
           return fromEnv;
         }
         const resolved2 = await realpath(root).catch(() => root);
-        const prefix = workbuddyConnectorPrefix(options.env, options.homeDir ?? homedir4());
+        const prefix = workbuddyConnectorPrefix(options.env, options.homeDir ?? homedir5());
         const resolvedPrefix = await realpath(prefix).catch(() => prefix);
         return isWithin(resolved2, resolvedPrefix, platform) ? "workbuddy" : "npm";
       } catch {
@@ -7732,8 +8174,8 @@ function createInstallSourceProbe(options) {
       }
     },
     async mark(source2) {
-      const filePath = path9.join(packageRoot(), INSTALL_SOURCE_MARKER);
-      await writeFile5(
+      const filePath = path12.join(packageRoot(), INSTALL_SOURCE_MARKER);
+      await writeFile3(
         filePath,
         `${JSON.stringify({ source: source2, markedAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2)}
 `,
@@ -7745,23 +8187,23 @@ function createInstallSourceProbe(options) {
 }
 async function readMarker(root) {
   try {
-    const parsed = JSON.parse(await readFile7(path9.join(root, INSTALL_SOURCE_MARKER), "utf8"));
+    const parsed = JSON.parse(await readFile8(path12.join(root, INSTALL_SOURCE_MARKER), "utf8"));
     return isInstallSource(parsed.source) ? parsed.source : void 0;
   } catch {
     return void 0;
   }
 }
 function workbuddyConnectorPrefix(env, homeDir) {
-  const configDir = env.WORKBUDDY_CONFIG_DIR?.trim() || env.CODEBUDDY_CONFIG_DIR?.trim() || path9.join(homeDir, ".workbuddy");
-  return path9.join(configDir, "binaries", "node", "cli-connector-packages");
+  const configDir = env.WORKBUDDY_CONFIG_DIR?.trim() || env.CODEBUDDY_CONFIG_DIR?.trim() || path12.join(homeDir, ".workbuddy");
+  return path12.join(configDir, "binaries", "node", "cli-connector-packages");
 }
 function isWithin(target, prefix, platform) {
   const normalize = (value) => {
-    const resolved2 = path9.resolve(value);
+    const resolved2 = path12.resolve(value);
     return platform === "win32" ? resolved2.toLowerCase() : resolved2;
   };
-  const relative = path9.relative(normalize(prefix), normalize(target));
-  return relative.length > 0 && !relative.startsWith("..") && !path9.isAbsolute(relative);
+  const relative = path12.relative(normalize(prefix), normalize(target));
+  return relative.length > 0 && !relative.startsWith("..") && !path12.isAbsolute(relative);
 }
 
 // src/infrastructure/tencent/workflow-gateway.ts
@@ -8274,10 +8716,10 @@ function createMemoryGateway(clients) {
       ];
       const patch = {};
       const paths = [];
-      for (const [key, field, path14] of fields) {
+      for (const [key, field, path18] of fields) {
         if (input.patch[key] !== void 0 && (rich || key === "type" || key === "content")) {
           patch[field] = input.patch[key];
-          paths.push(`entry_patch.${branch}.${path14}`);
+          paths.push(`entry_patch.${branch}.${path18}`);
         }
       }
       await request("ModifyMemoryEntry", {
@@ -9499,8 +9941,8 @@ function createKbShareGateway(client) {
 }
 
 // src/infrastructure/tencent/volume-gateway.ts
-import { mkdir as mkdir5, readFile as readFile8, writeFile as writeFile6 } from "fs/promises";
-import path10 from "path";
+import { mkdir as mkdir3, readFile as readFile9, writeFile as writeFile4 } from "fs/promises";
+import path13 from "path";
 
 // src/domain/volume/volume.ts
 var VOLUME_STATUS_LABELS = { 1: "creating", 2: "ready", 3: "failed", 4: "deleting" };
@@ -9511,14 +9953,14 @@ function normalizeVolumePath(input, options = {}) {
   if (segments.some((segment) => segment === "..")) {
     throw new DomainError("Volume paths cannot contain '..'", "usage", "UsageError");
   }
-  const path14 = segments.join("/");
-  if (!path14 && !options.allowRoot) {
+  const path18 = segments.join("/");
+  if (!path18 && !options.allowRoot) {
     throw new DomainError("Pass a path inside the volume, e.g. docs/report.pdf", "usage", "UsageError");
   }
-  return path14;
+  return path18;
 }
-function baseName(path14) {
-  return path14.slice(path14.lastIndexOf("/") + 1);
+function baseName(path18) {
+  return path18.slice(path18.lastIndexOf("/") + 1);
 }
 
 // src/infrastructure/tencent/volume-gateway.ts
@@ -9658,7 +10100,7 @@ function createVolumeGateway(client, options = {}) {
       await request("DeleteFileVolumeEntry", { ...ref3(input), RelativePath: input.path, ExpectedType: ENTRY_TYPES[input.type] });
     },
     async upload(input) {
-      const body = await readFile8(input.localPath).catch((error) => {
+      const body = await readFile9(input.localPath).catch((error) => {
         throw new DomainError(`Cannot read ${input.localPath}`, "usage", "LocalFileUnreadable", {
           hint: error.code === "ENOENT" ? "Check the --file path" : error.message
         });
@@ -9681,8 +10123,8 @@ function createVolumeGateway(client, options = {}) {
         throw await transferError(response, "download");
       }
       const bytes = new Uint8Array(await response.arrayBuffer());
-      await mkdir5(path10.dirname(input.localPath), { recursive: true });
-      await writeFile6(input.localPath, bytes);
+      await mkdir3(path13.dirname(input.localPath), { recursive: true });
+      await writeFile4(input.localPath, bytes);
       return { bytes: bytes.byteLength };
     },
     async previewUrl(input) {
@@ -10071,8 +10513,8 @@ function positive3(value) {
 }
 
 // src/infrastructure/cos/package-downloader.ts
-import { mkdir as mkdir6, readFile as readFile9, writeFile as writeFile7 } from "fs/promises";
-import path11 from "path";
+import { mkdir as mkdir4, readFile as readFile10, writeFile as writeFile5 } from "fs/promises";
+import path14 from "path";
 function createPackageDownloader(options = {}) {
   const fetchImpl = options.fetchImpl ?? globalThis.fetch;
   return {
@@ -10085,12 +10527,12 @@ function createPackageDownloader(options = {}) {
         });
       }
       const bytes = new Uint8Array(await response.arrayBuffer());
-      await mkdir6(path11.dirname(absolutePath), { recursive: true });
-      await writeFile7(absolutePath, bytes);
+      await mkdir4(path14.dirname(absolutePath), { recursive: true });
+      await writeFile5(absolutePath, bytes);
       return { bytes: bytes.byteLength };
     },
     async upload(url, absolutePath) {
-      const body = await readFile9(absolutePath).catch((error) => {
+      const body = await readFile10(absolutePath).catch((error) => {
         throw new DomainError(`Cannot read package file ${absolutePath}`, "usage", "PackageFileUnreadable", {
           hint: error.code === "ENOENT" ? "Check the --file path" : error.message
         });
@@ -10201,7 +10643,7 @@ var PAGE_NOT_EXIST = "Generic.PageNotExist";
 function createTencentDocsPortal(options = {}) {
   const origin = options.origin ?? DOCS_PORTAL_ORIGIN;
   const fetchImpl = options.fetchImpl ?? fetch;
-  const timeoutMs = options.timeoutMs ?? DEFAULT_DOCS_TIMEOUT_MS;
+  const timeoutMs2 = options.timeoutMs ?? DEFAULT_DOCS_TIMEOUT_MS;
   return {
     async search(input) {
       if (!input.keyword.trim()) {
@@ -10212,7 +10654,7 @@ function createTencentDocsPortal(options = {}) {
       url.searchParams.set("keyword", input.keyword.trim());
       url.searchParams.set("page", "1");
       url.searchParams.set("pagesize", String(pagesize));
-      const payload = await requestJson(fetchImpl, url, { method: "GET" }, timeoutMs, origin);
+      const payload = await requestJson(fetchImpl, url, { method: "GET" }, timeoutMs2, origin);
       return parseSearchHits(payload, origin);
     },
     async listPages(input) {
@@ -10225,7 +10667,7 @@ function createTencentDocsPortal(options = {}) {
           isPreview: false
         }
       };
-      const payload = await postCgi(fetchImpl, origin, LIST_MENU_ACTION, body, timeoutMs);
+      const payload = await postCgi(fetchImpl, origin, LIST_MENU_ACTION, body, timeoutMs2);
       const nodes = extractMenuNodes(payload);
       const pages = flattenMenu(nodes, productId);
       if (!input.docType) {
@@ -10249,12 +10691,12 @@ function createTencentDocsPortal(options = {}) {
           catId: Number(productId) || productId
         }
       };
-      const payload = await postCgi(fetchImpl, origin, GET_DOC_ACTION, body, timeoutMs);
+      const payload = await postCgi(fetchImpl, origin, GET_DOC_ACTION, body, timeoutMs2);
       return parseDocContent(payload, documentId, productId);
     }
   };
 }
-async function postCgi(fetchImpl, origin, action, body, timeoutMs) {
+async function postCgi(fetchImpl, origin, action, body, timeoutMs2) {
   const url = new URL(`${DOCS_CGI_PREFIX}/${action}`, origin);
   return requestJson(
     fetchImpl,
@@ -10264,11 +10706,11 @@ async function postCgi(fetchImpl, origin, action, body, timeoutMs) {
       headers: { "content-type": "application/json" },
       body: JSON.stringify(body)
     },
-    timeoutMs,
+    timeoutMs2,
     origin
   );
 }
-async function requestJson(fetchImpl, url, init, timeoutMs, origin) {
+async function requestJson(fetchImpl, url, init, timeoutMs2, origin) {
   const referer = productDocsUrl(DEFAULT_DOCS_PRODUCT_ID);
   let response;
   try {
@@ -10280,7 +10722,7 @@ async function requestJson(fetchImpl, url, init, timeoutMs, origin) {
         referer,
         ...init.headers
       },
-      signal: AbortSignal.timeout(timeoutMs)
+      signal: AbortSignal.timeout(timeoutMs2)
     });
   } catch (error) {
     throw portalError(
@@ -10564,7 +11006,7 @@ function normalizedChoiceName(value) {
 
 // src/interfaces/cli/prompter.ts
 var PROMPT_TIMEOUT_MS = 6e4;
-async function readSecret(message, timeoutMs) {
+async function readSecret(message, timeoutMs2) {
   const stdin = process.stdin;
   process.stdout.write(message);
   if (!stdin.isTTY) {
@@ -10583,7 +11025,7 @@ async function readSecret(message, timeoutMs) {
       process.stdout.write("\n");
       resolve(result);
     };
-    const timer = setTimeout(() => finish(value), timeoutMs);
+    const timer = setTimeout(() => finish(value), timeoutMs2);
     const onData = (chunk) => {
       for (const char of chunk.toString("utf8")) {
         if (char === "\r" || char === "\n") {
@@ -10607,9 +11049,9 @@ async function readSecret(message, timeoutMs) {
     stdin.on("data", onData);
   });
 }
-async function readLine(message, timeoutMs) {
+async function readLine(message, timeoutMs2) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const timer = setTimeout(() => rl.close(), timeoutMs);
+  const timer = setTimeout(() => rl.close(), timeoutMs2);
   try {
     return await rl.question(message);
   } catch (error) {
@@ -10727,6 +11169,8 @@ async function createProductionDeps(env = process.env) {
     launchDetachedLogin,
     openBrowser: openInBrowser,
     env,
+    toolKeyStore: createToolKeyFileStore(adpToolKeyPath()),
+    pluginMcp: createPluginMcpGateway(),
     resolveIdentity: (flags) => resolveIdentityFor(flags),
     async resolveGateways(flags) {
       const identity = await resolveIdentityFor(flags);
@@ -10748,6 +11192,7 @@ async function createProductionDeps(env = process.env) {
         release: createReleaseGateway(client),
         plugin: createPluginGateway(client),
         pluginAccess: createPluginAccessGateway(client),
+        toolKey: createToolKeyGateway(lke),
         skillLifecycle: createSkillLifecycleGateway(client),
         workflowRunControl: createWorkflowRunControlGateway(client),
         agentTool: createAgentToolGateway(client),
@@ -10782,25 +11227,13 @@ async function createProductionDeps(env = process.env) {
         usage: createUsageGateway(client),
         objectStore: createPlatformObjectStore(),
         packageDownloader: createPackageDownloader(),
-        knowledge: independent ? unsupportedGateway(
-          "adp kb doc is not supported by the independent-site profile",
-          "Knowledge document transport uses the public-cloud LKE and platform COS planes"
-        ) : createKnowledgeGateway({ adp: client, lke }),
+        knowledge: createKnowledgeGateway({ adp: client, lke }),
         kb: createKbGateway(client),
         channel: createChannelGateway(client)
       };
     }
   };
 }
-function unsupportedGateway(message, hint) {
-  return new Proxy({}, {
-    get() {
-      return async () => {
-        throw usageError(message, hint);
-      };
-    }
-  });
-}
 function canPrompt(deps) {
   return deps.stdinIsTTY && !deps.agentName;
 }
@@ -11364,7 +11797,7 @@ function registerIdentityCommands(registry, ctx) {
 }
 
 // src/interfaces/cli/commands/init.ts
-import path12 from "path";
+import path15 from "path";
 
 // src/domain/project-config/adp-config.ts
 var APP_MODES = {
@@ -11682,7 +12115,7 @@ function registerInitCommand(registry, ctx) {
             plugins: []
           }
         };
-        const configPath = path12.resolve(ctx.flags.cwd, ctx.flags.config ?? "adp.jsonc");
+        const configPath = path15.resolve(ctx.flags.cwd, ctx.flags.config ?? "adp.jsonc");
         const createRemote = Boolean(args["create-remote"]);
         const gateways = createRemote && !ctx.flags.dryRun ? await ctx.deps.resolveGateways(ctx.flags) : void 0;
         const previewModels = createRemote && ctx.flags.dryRun && config2.appMode === APP_MODES.claw && modelId === PLACEHOLDER_MODEL_ID ? await ctx.deps.resolveGateways(ctx.flags).then((resolved2) => resolved2.model).catch(() => void 0) : void 0;
@@ -13646,7 +14079,7 @@ function registerSpaceCommands(registry, ctx) {
 }
 
 // src/infrastructure/fs/app-package-reader.ts
-import { readFile as readFile10 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 import { inflateRawSync } from "zlib";
 var END_OF_CENTRAL_DIRECTORY = 101010256;
 var CENTRAL_FILE_HEADER = 33639248;
@@ -13727,7 +14160,7 @@ function createAppPackageReader() {
 }
 async function readInventory(file) {
   try {
-    const zip = await readFile10(file);
+    const zip = await readFile11(file);
     const entries = listEntries(zip);
     if (entries.length === 0 && zip.length > 0 && !looksLikeZip(zip)) {
       return EMPTY_INVENTORY;
@@ -15430,28 +15863,126 @@ function afterAppCreate(payload) {
   };
 }
 
+// src/interfaces/cli/commands/agent/index.ts
+import { readFile as readFile12 } from "fs/promises";
+import path16 from "path";
+
 // src/application/agent/agent-use-cases.ts
+var CLAW_AGENT_LIMIT = 20;
 async function listAgents(gateway, input) {
   return collectPages(
     (page3, pageSize) => gateway.list({ appId: input.appId, limit: pageSize, page: page3 }),
     { limit: input.limit, page: input.page, firstPage: 0 }
   );
 }
-function agentAlreadyExists(appId3, agentId) {
+function specForAgentCreate(config2, projectInstructions, overrides) {
+  const subViaFlags = overrides.subAgent === true || overrides.role === 1;
+  const role = subViaFlags ? 1 : overrides.role ?? config2?.agent.profile.role ?? 0;
+  if (role !== 0 && role !== 1) {
+    throw usageError(
+      `Agent role must be 0 (main) or 1 (sub-agent); got ${role}`,
+      "Pass --role 0 or --role 1 (or --sub-agent)"
+    );
+  }
+  if (subViaFlags && !overrides.name?.trim()) {
+    throw usageError(
+      "A Claw sub-agent needs --name",
+      "Pass --name. adp.jsonc agent.profile.name is the main agent and is not reused for --role 1"
+    );
+  }
+  const name = (overrides.name ?? config2?.agent.profile.name ?? "").trim();
+  if (!name) {
+    throw usageError("Agent name is required", "Pass --name, or set agent.profile.name in adp.jsonc");
+  }
+  const description = overrides.description !== void 0 ? overrides.description : subViaFlags ? name : config2?.agent.profile.description;
+  const configuredModel = overrides.modelId ?? config2?.agent.model.modelId ?? "";
+  const modelId = configuredModel === PLACEHOLDER_MODEL_ID ? "" : configuredModel;
+  return {
+    profile: {
+      name,
+      description,
+      iconUrl: subViaFlags ? void 0 : config2?.agent.profile.iconUrl,
+      role
+    },
+    instructions: instructionsForCreate(name, description, subViaFlags, config2, projectInstructions, overrides.instructions),
+    model: {
+      modelId,
+      ...subViaFlags ? {} : {
+        alias: config2?.agent.model.alias,
+        contextWordsLimit: config2?.agent.model.contextWordsLimit,
+        instructionsWordsLimit: config2?.agent.model.instructionsWordsLimit
+      }
+    },
+    skillIds: overrides.skillIds ?? (subViaFlags ? [] : config2?.agent.skillIds ?? []),
+    pluginIds: subViaFlags ? [] : config2?.agent.pluginIds ?? [],
+    connectorIds: subViaFlags ? void 0 : config2?.agent.connectorIds,
+    tools: subViaFlags ? [{ ...KNOWLEDGE_RETRIEVAL_TOOL }] : config2?.agent.tools ?? [],
+    plugins: subViaFlags ? void 0 : config2?.agent.plugins,
+    maxReasoningRound: subViaFlags ? void 0 : config2?.agent.maxReasoningRound
+  };
+}
+function instructionsForCreate(name, description, subViaFlags, config2, projectInstructions, explicit) {
+  if (explicit !== void 0) {
+    return explicit;
+  }
+  if (subViaFlags) {
+    return defaultSubAgentInstructions(name, description);
+  }
+  if (projectInstructions !== void 0) {
+    return projectInstructions;
+  }
+  if (config2?.agent.instructions) {
+    return config2.agent.instructions;
+  }
+  if (!config2) {
+    return defaultSubAgentInstructions(name, description);
+  }
+  return "";
+}
+function defaultSubAgentInstructions(name, description) {
+  if (description && description !== name) {
+    return `You are ${name}. ${description}`;
+  }
+  return `You are ${name}.`;
+}
+function shellWord4(value) {
+  return /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
+}
+function subAgentCreateCommand(appId3, name) {
+  const shown = name?.trim() ? name.trim() : "sub-agent";
+  return `adp agent create --app-id ${appId3} --role 1 --name ${shellWord4(shown)} --dry-run --format json`;
+}
+function agentAlreadyExists(appId3, agentId, name) {
   return new DomainError(
-    `App ${appId3} already has agent ${agentId}; a Claw app cannot get a second agent from CreateAgent`,
+    `App ${appId3} already has main agent ${agentId}. CreateAgent with role 0 returns that agent instead of creating another one`,
     "conflict",
     "AgentAlreadyExists",
     {
-      hint: "A Claw app (app_mode 4) has exactly one config-side agent. Change it with adp agent update, or create another app for a second agent",
+      hint: "A Claw app (app_mode 4) has one main agent (role 0) and up to 19 sub-agents (role 1). Edit the main agent with adp agent update, or pass --role 1 (or --sub-agent) on adp agent create to add a sub-agent",
       nextActions: [
         {
           command: `adp agent update --app-id ${appId3} --agent-id ${agentId} --format json`,
-          reason: "edit the existing agent from the same adp.jsonc instead of creating one (this writes the agent draft); do not re-run agent create"
+          reason: "edit the existing main agent (role 0) instead of creating another one"
         },
         {
-          command: `adp agent update --app-id ${appId3} --agent-id ${agentId} --dry-run --format json`,
-          reason: "or preview that update first"
+          command: subAgentCreateCommand(appId3, name),
+          reason: "add a Claw sub-agent (role 1); set --description to when the main agent should delegate, and --instructions for how the sub-agent works"
+        }
+      ]
+    }
+  );
+}
+function agentLimitReached(appId3) {
+  return new DomainError(
+    `App ${appId3} already has ${CLAW_AGENT_LIMIT} agents. A Claw app allows 1 main agent and 19 sub-agents`,
+    "conflict",
+    "AgentLimitExceeded",
+    {
+      hint: "Delete a sub-agent before creating another. Keep the main agent (role 0).",
+      nextActions: [
+        {
+          command: `adp agent list --app-id ${appId3} --format json`,
+          reason: "list agents and their roles before deleting a sub-agent"
         }
       ]
     }
@@ -15472,7 +16003,7 @@ async function describeAgent(gateway, input) {
     throw error;
   }
 }
-async function createAgent(gateway, input, apps2) {
+async function createAgent(gateway, input, apps2, models) {
   const app = await apps2.describe({ appId: input.appId });
   if (app.appMode !== void 0 && app.appMode !== APP_MODES.claw) {
     throw usageError(
@@ -15480,26 +16011,110 @@ async function createAgent(gateway, input, apps2) {
       app.appMode === APP_MODES.standard ? "A Standard app has no extra agents: edit its settings in adp.jsonc and run adp deploy" : "Edit the existing agents with adp agent update, or create a Claw app (adp init --app-mode 4) for a separate agent"
     );
   }
+  const role = input.spec.profile?.role ?? 0;
+  if (role !== 0 && role !== 1) {
+    throw usageError(
+      `Agent role must be 0 (main) or 1 (sub-agent); got ${role}`,
+      "Pass --role 0 or --role 1 (or --sub-agent)"
+    );
+  }
   const before = await gateway.list({ appId: input.appId, limit: 100, page: 0 });
+  const main2 = before.items.find((agent) => (agent.role ?? 0) === 0);
+  if (role === 0 && main2) {
+    throw agentAlreadyExists(input.appId, main2.agentId, input.spec.profile?.name);
+  }
+  if (before.items.length >= CLAW_AGENT_LIMIT) {
+    throw agentLimitReached(input.appId);
+  }
+  const spec = await withInheritedModel(gateway, models, {
+    appId: input.appId,
+    spaceId: input.spaceId,
+    spec: input.spec,
+    agents: before.items
+  });
   if (input.dryRun) {
-    const existing = before.items[0];
-    if (app.appMode === APP_MODES.claw && existing) {
-      throw agentAlreadyExists(input.appId, existing.agentId);
+    if (role === 1) {
+      return { dryRun: true, appId: input.appId, role: 1, name: spec.profile.name, modelId: spec.model.modelId };
     }
     return { dryRun: true, appId: input.appId };
   }
-  const created = await gateway.create(input);
+  const created = await gateway.create({ appId: input.appId, spec });
   if (before.items.some((agent) => agent.agentId === created.agentId)) {
-    throw agentAlreadyExists(input.appId, created.agentId);
+    throw agentAlreadyExists(input.appId, created.agentId, spec.profile.name);
+  }
+  if (role === 1) {
+    return { dryRun: false, ...created, role: 1, name: spec.profile.name, modelId: spec.model.modelId };
   }
   return { dryRun: false, ...created };
 }
+async function withInheritedModel(gateway, models, input) {
+  const current = input.spec.model.modelId;
+  if (current && current !== PLACEHOLDER_MODEL_ID) {
+    return input.spec;
+  }
+  const main2 = input.agents.find((agent) => (agent.role ?? 0) === 0);
+  if (main2) {
+    try {
+      const detail = await gateway.describe({ appId: input.appId, agentId: main2.agentId });
+      const modelId = detail.spec?.model.modelId;
+      if (modelId && modelId !== PLACEHOLDER_MODEL_ID) {
+        return { ...input.spec, model: { ...input.spec.model, modelId } };
+      }
+    } catch {
+    }
+  }
+  if (models && input.spaceId) {
+    try {
+      const listed = await models.list({ limit: 1, page: 0, scene: MODEL_SCENE_CLAW, spaceId: input.spaceId });
+      const modelId = listed.items[0]?.modelId;
+      if (modelId) {
+        return { ...input.spec, model: { ...input.spec.model, modelId } };
+      }
+    } catch {
+    }
+  }
+  return { ...input.spec, model: { ...input.spec.model, modelId: "Auto/auto" } };
+}
+function hasPatch(patch) {
+  return Boolean(patch && Object.values(patch).some((value) => value !== void 0));
+}
+function applyAgentPatch(spec, patch) {
+  return {
+    ...spec,
+    profile: {
+      ...spec.profile,
+      ...patch.name !== void 0 ? { name: patch.name } : {},
+      ...patch.description !== void 0 ? { description: patch.description } : {}
+    },
+    ...patch.instructions !== void 0 ? { instructions: patch.instructions } : {},
+    model: patch.modelId !== void 0 ? { ...spec.model, modelId: patch.modelId } : spec.model
+  };
+}
 async function modifyAgent(gateway, input) {
+  const patching = hasPatch(input.patch);
+  let spec = input.spec;
+  if (patching || !spec) {
+    if (!patching) {
+      throw usageError(
+        "Agent update needs adp.jsonc or a field to change",
+        "Pass --name, --description, --instructions, --instructions-file, or --model-id"
+      );
+    }
+    const current = await describeAgent(gateway, { appId: input.appId, agentId: input.agentId });
+    if (!current.spec) {
+      throw usageError(
+        `Agent ${input.agentId} has no config to update`,
+        "Run adp agent get and pass --name, --description, --instructions, or --model-id"
+      );
+    }
+    spec = applyAgentPatch(current.spec, input.patch ?? {});
+  }
+  const patched = patching ? { name: spec.profile.name, description: spec.profile.description, modelId: spec.model.modelId } : {};
   if (input.dryRun) {
-    return { dryRun: true, agentId: input.agentId };
+    return { dryRun: true, agentId: input.agentId, ...patched };
   }
-  await gateway.modify({ ...input, updateMask: defaultUpdateMask() });
-  return { dryRun: false, agentId: input.agentId };
+  await gateway.modify({ appId: input.appId, agentId: input.agentId, spec, updateMask: defaultUpdateMask() });
+  return { dryRun: false, agentId: input.agentId, ...patched };
 }
 async function deleteAgent(gateway, input) {
   await assertExisting([input.agentId], async (agentId) => (await describeAgent(gateway, { appId: input.appId, agentId })).agentId, {
@@ -15570,28 +16185,82 @@ function registerAgentCommands(registry, ctx) {
   registry.define(
     createCommand({
       command: "agent create",
-      describe: "Create an agent from the local spec",
+      describe: "Create a Claw agent (role 0 main, or role 1 sub-agent)",
       effects: "non_idempotent",
       outputKind: "data",
       examples: [
         "adp agent create --app-id app-1 --format json",
-        "adp agent create --app-id app-1 --dry-run"
+        "adp agent create --app-id app-1 --dry-run",
+        "adp agent create --app-id app-1 --role 1 --name ray\u7684\u6D4B\u8BD5agent --description delegates-ray-tests --dry-run --format json",
+        "adp agent create --app-id app-1 --sub-agent --name ray\u7684\u6D4B\u8BD5agent --instructions You-are-ray --model-id m1 --dry-run --format json"
+      ],
+      flags: [
+        { name: "app-id", type: "string", describe: "App ID (default: adp.jsonc app_id)" },
+        {
+          name: "name",
+          type: "string",
+          describe: "Agent name. Overrides adp.jsonc agent.profile.name. Required when adp.jsonc is absent, and required with --role 1 or --sub-agent"
+        },
+        {
+          name: "description",
+          type: "string",
+          describe: "Routing description: the main agent uses it to decide when to delegate. Overrides adp.jsonc agent.profile.description"
+        },
+        {
+          name: "role",
+          type: "number",
+          describe: "0 = main agent (default), 1 = Claw sub-agent. A second role 0 fails with AgentAlreadyExists; role 1 adds a sub-agent (up to 19)"
+        },
+        {
+          name: "sub-agent",
+          type: "boolean",
+          describe: "Create a Claw sub-agent (same as --role 1). Does not copy the main agent's instructions.md, skill_ids, or plugin_ids"
+        },
+        {
+          name: "instructions",
+          type: "string",
+          describe: "System prompt. With --role 1 this is the sub-agent prompt; instructions.md is not copied unless you pass it here or via --instructions-file"
+        },
+        {
+          name: "instructions-file",
+          type: "string",
+          describe: "Read the system prompt from this file instead of --instructions or instructions.md"
+        },
+        {
+          name: "model-id",
+          type: "string",
+          describe: "Model ID. Default: a real adp.jsonc agent.model.model_id, else the main agent's model, else the first ModelScene=18 model, else Auto/auto"
+        },
+        {
+          name: "skill-id",
+          type: "string",
+          list: true,
+          describe: "Skill ID to mount (repeatable). With --role 1, defaults to none instead of copying the main agent"
+        }
       ],
-      flags: [{ name: "app-id", type: "string", describe: "App ID (default: adp.jsonc app_id)" }],
       async handler(args) {
-        const loaded = await ctx.deps.configStore.load({
+        const instructionsFlag = await readInstructionsFlag(ctx, args);
+        const overrides = readCreateOverrides(args, instructionsFlag);
+        const loaded = await tryLoadConfig(ctx.deps.configStore, {
           cwd: ctx.flags.cwd,
           configPath: ctx.flags.config,
           envName: ctx.flags.env
         });
-        const instructions = await resolveInstructions(ctx.deps.configStore, ctx.flags.cwd, loaded.config);
+        const projectInstructions = loaded && !overrides.subAgent && !instructionsFlag.explicit ? await resolveInstructions(ctx.deps.configStore, ctx.flags.cwd, loaded.config) : void 0;
+        const spec = specForAgentCreate(loaded?.config, projectInstructions, overrides);
         const gateways = await ctx.deps.resolveGateways(ctx.flags);
         return mutationPayload(
-          await createAgent(gateways.agent, {
-            appId: await agentAppId(ctx, args),
-            spec: toAgentSpec(loaded.config, instructions),
-            dryRun: ctx.flags.dryRun
-          }, gateways.app),
+          await createAgent(
+            gateways.agent,
+            {
+              appId: await agentAppId(ctx, args),
+              spec,
+              dryRun: ctx.flags.dryRun,
+              spaceId: loaded?.config.spaceId
+            },
+            gateways.app,
+            gateways.model
+          ),
           "create",
           "agent"
         );
@@ -15601,28 +16270,50 @@ function registerAgentCommands(registry, ctx) {
   registry.define(
     createCommand({
       command: "agent update",
-      describe: "Modify an agent from the local spec",
+      describe: "Modify an agent from adp.jsonc, or patch fields passed as flags",
       effects: "idempotent",
       outputKind: "data",
       examples: [
         "adp agent update --app-id app-1 --agent-id agt-1 --format json",
-        "adp agent update --app-id app-1 --agent-id agt-1 --dry-run"
+        "adp agent update --app-id app-1 --agent-id agt-1 --dry-run",
+        "adp agent update --app-id app-1 --agent-id agt-1 --name ray\u7684\u6D4B\u8BD5agent --description delegates-ray-tests --dry-run --format json"
       ],
       flags: [
         { name: "app-id", type: "string", describe: "App ID (default: adp.jsonc app_id)" },
-        { name: "agent-id", type: "string", describe: "Agent ID (default: adp.jsonc agent_id when the app is the bound one)" }
+        { name: "agent-id", type: "string", describe: "Agent ID (default: adp.jsonc agent_id when the app is the bound one)" },
+        { name: "name", type: "string", describe: "New agent name. With any field flag, other fields stay as they are on the agent" },
+        { name: "description", type: "string", describe: "New routing description. With any field flag, other fields stay as they are on the agent" },
+        { name: "instructions", type: "string", describe: "New system prompt" },
+        { name: "instructions-file", type: "string", describe: "Read the new system prompt from this file" },
+        { name: "model-id", type: "string", describe: "New model ID" }
       ],
       async handler(args) {
-        const loaded = await ctx.deps.configStore.load({
+        const instructionsFlag = await readInstructionsFlag(ctx, args);
+        const patch = readUpdatePatch(args, instructionsFlag);
+        const loaded = await tryLoadConfig(ctx.deps.configStore, {
           cwd: ctx.flags.cwd,
           configPath: ctx.flags.config,
           envName: ctx.flags.env
         });
-        const instructions = await resolveInstructions(ctx.deps.configStore, ctx.flags.cwd, loaded.config);
         const gateways = await ctx.deps.resolveGateways(ctx.flags);
+        const ids4 = await agentIds(ctx, args, "agent update modifies one agent");
+        if (patch) {
+          return mutationPayload(
+            await modifyAgent(gateways.agent, { ...ids4, patch, dryRun: ctx.flags.dryRun }),
+            "update",
+            "agent"
+          );
+        }
+        if (!loaded) {
+          throw usageError(
+            "Agent update needs adp.jsonc or a field to change",
+            "Pass --name, --description, --instructions, --instructions-file, or --model-id"
+          );
+        }
+        const instructions = await resolveInstructions(ctx.deps.configStore, ctx.flags.cwd, loaded.config);
         return mutationPayload(
           await modifyAgent(gateways.agent, {
-            ...await agentIds(ctx, args, "agent update modifies one agent"),
+            ...ids4,
             spec: toAgentSpec(loaded.config, instructions),
             dryRun: ctx.flags.dryRun
           }),
@@ -15663,6 +16354,72 @@ function registerAgentCommands(registry, ctx) {
     })
   );
 }
+async function readInstructionsFlag(ctx, args) {
+  const inline = typeof args.instructions === "string" ? args.instructions : void 0;
+  const file = typeof args["instructions-file"] === "string" ? args["instructions-file"] : void 0;
+  if (inline !== void 0 && file !== void 0) {
+    throw usageError("Pass only one of --instructions and --instructions-file", "One system prompt is enough");
+  }
+  if (file !== void 0) {
+    const filePath = path16.resolve(ctx.flags.cwd, file);
+    try {
+      return { text: await readFile12(filePath, "utf8"), explicit: true };
+    } catch {
+      throw usageError(`Cannot read --instructions-file ${file}`, "Pass a path to a text file, or use --instructions");
+    }
+  }
+  if (inline !== void 0) {
+    return { text: inline, explicit: true };
+  }
+  return { explicit: false };
+}
+function readCreateOverrides(args, instructions) {
+  const subFlag = args["sub-agent"] === true;
+  let role;
+  if (args.role !== void 0) {
+    const parsed = typeof args.role === "number" ? args.role : Number(args.role);
+    if (parsed !== 0 && parsed !== 1) {
+      throw usageError("`--role` must be 0 (main agent) or 1 (sub-agent)", "Pass --role 0, --role 1, or --sub-agent");
+    }
+    role = parsed;
+  }
+  if (subFlag && role === 0) {
+    throw usageError("`--sub-agent` is role 1", "Drop --role 0, or drop --sub-agent");
+  }
+  const subAgent = subFlag || role === 1;
+  return {
+    name: optionalText3(args.name),
+    description: optionalText3(args.description),
+    role: subAgent ? 1 : role,
+    subAgent,
+    instructions: instructions.explicit ? instructions.text ?? "" : void 0,
+    modelId: optionalText3(args["model-id"]),
+    skillIds: args["skill-id"] === void 0 ? void 0 : stringList2(args["skill-id"])
+  };
+}
+function readUpdatePatch(args, instructions) {
+  const patch = {};
+  if (typeof args.name === "string") {
+    patch.name = args.name;
+  }
+  if (typeof args.description === "string") {
+    patch.description = args.description;
+  }
+  if (instructions.explicit) {
+    patch.instructions = instructions.text ?? "";
+  }
+  if (typeof args["model-id"] === "string") {
+    patch.modelId = args["model-id"];
+  }
+  return Object.values(patch).some((value) => value !== void 0) ? patch : void 0;
+}
+function optionalText3(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function stringList2(value) {
+  const raw = Array.isArray(value) ? value : value === void 0 || value === null ? [] : [value];
+  return raw.flatMap((item) => String(item).split(",")).map((item) => item.trim()).filter((item) => item.length > 0);
+}
 
 // src/application/agent/agent-tool-use-cases.ts
 function explainAgentToolError(error) {
@@ -17386,7 +18143,7 @@ async function modifyPlugin(gateway, input) {
 async function deletePlugin(gateway, input) {
   const scope = input.spaceId;
   if (scope) {
-    await assertExisting([input.pluginId], async (pluginId2) => (await gateway.describe({ pluginId: pluginId2, spaceId: scope })).pluginId, {
+    await assertExisting([input.pluginId], async (pluginId3) => (await gateway.describe({ pluginId: pluginId3, spaceId: scope })).pluginId, {
       code: "PluginNotFound",
       noun: "plugin",
       listCommand: `adp plugin list --space-id ${scope} --fields pluginId,name --format json`
@@ -17402,7 +18159,7 @@ async function deletePlugin(gateway, input) {
       throw error;
     }
     const spaceId = input.spaceId;
-    const missing = spaceId ? await missingIds([input.pluginId], async (pluginId2) => (await gateway.describe({ pluginId: pluginId2, spaceId })).pluginId).catch(() => []) : [input.pluginId];
+    const missing = spaceId ? await missingIds([input.pluginId], async (pluginId3) => (await gateway.describe({ pluginId: pluginId3, spaceId })).pluginId).catch(() => []) : [input.pluginId];
     if (missing.length === 0) {
       throw error;
     }
@@ -17419,8 +18176,8 @@ async function deletePlugin(gateway, input) {
 }
 
 // src/infrastructure/fs/plugin-spec-file.ts
-import { readFile as readFile11 } from "fs/promises";
-import path13 from "path";
+import { readFile as readFile13 } from "fs/promises";
+import path17 from "path";
 import { parse as parseJsonc2 } from "jsonc-parser";
 import { z as z2 } from "zod";
 var paramTypeSchema = z2.enum(Object.keys(PARAM_TYPES));
@@ -17544,10 +18301,10 @@ function parsePluginSpec(text13, sourcePath, env = process.env) {
   };
 }
 async function loadPluginSpec(cwd, relativePath) {
-  const resolved2 = path13.resolve(cwd, relativePath);
+  const resolved2 = path17.resolve(cwd, relativePath);
   let text13;
   try {
-    text13 = await readFile11(resolved2, "utf8");
+    text13 = await readFile13(resolved2, "utf8");
   } catch {
     throw usageError(
       `Plugin spec not found: ${resolved2}`,
@@ -17603,22 +18360,28 @@ function registerPluginCommands(registry, ctx) {
       async handler(args) {
         const spaceId = await resolveSpaceId(ctx, args, "plugin get reads the plugin in a space");
         const gateways = await ctx.deps.resolveGateways(ctx.flags);
-        const pluginId2 = assertResourceId(String(args["plugin-id"]), "plugin-id");
-        const plugin = await describePlugin(gateways.plugin, { pluginId: pluginId2, spaceId: assertResourceId(spaceId, "space-id") });
-        const toolId = plugin.tools?.[0]?.toolId;
+        const pluginId3 = assertResourceId(String(args["plugin-id"]), "plugin-id");
+        const plugin = await describePlugin(gateways.plugin, { pluginId: pluginId3, spaceId: assertResourceId(spaceId, "space-id") });
+        const tool = plugin.tools?.[0];
+        const toolId = tool?.toolId;
+        const mcpCall = plugin.pluginKind === PLUGIN_KIND_MCP && toolId ? {
+          command: mcpCallCommand(pluginId3, { toolId, name: tool?.name }),
+          reason: "preview a direct MCP call; adp plugin key create saves the tool key that call reads"
+        } : void 0;
         return {
           result: plugin,
           nextActions: toolId ? [
             {
-              command: `adp agent tool bind --plugin-id ${pluginId2} --tool-id ${toolId} --format json`,
-              reason: `bind ${plugin.tools[0].name ?? "the first tool"} to an agent (pick another toolId from tools[] for a different tool); also add {"plugin_id":"${pluginId2}","tool_id":"${toolId}"} to agent.tools in adp.jsonc, or the next adp deploy removes it`,
+              command: `adp agent tool bind --plugin-id ${pluginId3} --tool-id ${toolId} --format json`,
+              reason: `bind ${tool?.name ?? "the first tool"} to an agent (pick another toolId from tools[] for a different tool); also add {"plugin_id":"${pluginId3}","tool_id":"${toolId}"} to agent.tools in adp.jsonc, or the next adp deploy removes it`,
               needs_input: { flag: "agent-id", question: "Agent ID to bind the tool to (adp agent list)" }
             },
             {
               command: "adp deploy --dry-run --format json",
-              reason: `the project-file route: add {"plugin_id":"${pluginId2}","tool_id":"${toolId}"} to agent.tools in adp.jsonc, then preview the release`,
+              reason: `the project-file route: add {"plugin_id":"${pluginId3}","tool_id":"${toolId}"} to agent.tools in adp.jsonc, then preview the release`,
               needs_edit: { file: "adp.jsonc" }
-            }
+            },
+            ...mcpCall ? [mcpCall] : []
           ] : void 0
         };
       }
@@ -17830,17 +18593,24 @@ function registerPluginCommands(registry, ctx) {
     })
   );
 }
+function mcpCallCommand(pluginId3, tool) {
+  const name = tool.name?.trim();
+  if (name && /^[A-Za-z0-9_-]+$/.test(name)) {
+    return `adp plugin tool call --plugin-id ${pluginId3} --tool-name ${name} --dry-run --format json`;
+  }
+  return `adp plugin tool call --plugin-id ${pluginId3} --tool-id ${tool.toolId} --dry-run --format json`;
+}
 function afterPluginCreate(payload, spaceId) {
-  const pluginId2 = payload.result.pluginId;
-  if (payload.result.dryRun || !pluginId2) {
+  const pluginId3 = payload.result.pluginId;
+  if (payload.result.dryRun || !pluginId3) {
     return payload;
   }
   return {
     ...payload,
     nextActions: [
-      { command: `adp plugin get --plugin-id ${pluginId2} --space-id ${spaceId} --format json`, reason: "list the plugin's tool IDs" },
+      { command: `adp plugin get --plugin-id ${pluginId3} --space-id ${spaceId} --format json`, reason: "list the plugin's tool IDs" },
       {
-        command: `adp agent tool bind --plugin-id ${pluginId2} --format json`,
+        command: `adp agent tool bind --plugin-id ${pluginId3} --format json`,
         reason: "bind one of those tools to an agent's draft, then adp deploy",
         needs_input: { flag: "tool-id", question: "Tool ID from adp plugin get" }
       }
@@ -17986,76 +18756,481 @@ function strings6(value) {
 function pluginId(args) {
   return assertResourceId(String(args["plugin-id"]), "plugin-id");
 }
-function registerPluginAccessCommands(registry, ctx) {
+function registerPluginAccessCommands(registry, ctx) {
+  registry.define(
+    createCommand({
+      command: "plugin share get",
+      describe: "Show who may use a plugin across spaces (active config, or --pending for the one awaiting approval)",
+      effects: "read_only",
+      outputKind: "data",
+      flags: [pluginIdFlag, { name: "pending", type: "boolean", describe: "Show the config awaiting approval" }],
+      examples: ["adp plugin share get --plugin-id plg-1 --format json"],
+      async handler(args) {
+        const gateways = await ctx.deps.resolveGateways(ctx.flags);
+        if (args.pending === true) {
+          return { result: await describePendingPluginShare(gateways.pluginAccess, { pluginId: pluginId(args) }) };
+        }
+        return { result: await describePluginShare(gateways.pluginAccess, { pluginId: pluginId(args), pending: false }) };
+      }
+    })
+  );
+  registry.define(
+    createCommand({
+      command: "plugin share set",
+      describe: "Change plugin or credential share scope; may need approval, and is blocked while apps use what it removes",
+      effects: "idempotent",
+      outputKind: "data",
+      flags: [
+        pluginIdFlag,
+        { name: "scope", type: "string", describe: "Plugin scope: none | all | spaces" },
+        { name: "space", type: "string", describe: "Target space ID for --scope spaces (repeatable)" },
+        { name: "credential", type: "string", describe: "<credential-id>=none|all|spaces:<id>,<id> (repeatable)" },
+        { name: "remark", type: "string", describe: "Note for the approver" },
+        { name: "force", type: "boolean", describe: "Admin only: apply even though referrers lose access" },
+        { name: "confirm-name", type: "string", describe: "Plugin name, required with --force" }
+      ],
+      examples: [
+        "adp plugin share set --plugin-id plg-1 --scope spaces --space sp-2 --yes",
+        "adp plugin share set --plugin-id plg-1 --credential cred-1=all --yes --format json"
+      ],
+      async handler(args) {
+        const id = pluginId(args);
+        let plugin;
+        if (args.scope !== void 0) {
+          const scope = String(args.scope);
+          if (!SCOPES.includes(scope)) {
+            throw usageError(`--scope must be one of ${SCOPES.join(", ")}`);
+          }
+          plugin = { scope, spaceIds: [...new Set(strings6(args.space).map((s) => assertResourceId(s, "space")))] };
+        } else if (args.space !== void 0) {
+          throw usageError("--space needs --scope spaces");
+        }
+        const credentials = strings6(args.credential).map(parseCredentialShare);
+        await requireYes(ctx, `change share settings of plugin ${id}`);
+        if (ctx.flags.dryRun) {
+          return { result: { dryRun: true, pluginId: id, plugin, credentials }, message: `Would change share settings of plugin ${id}.` };
+        }
+        const gateways = await ctx.deps.resolveGateways(ctx.flags);
+        const result = await setPluginShare(gateways.pluginAccess, {
+          pluginId: id,
+          plugin,
+          credentials,
+          remark: typeof args.remark === "string" ? args.remark : void 0,
+          force: args.force === true,
+          confirmedName: typeof args["confirm-name"] === "string" ? args["confirm-name"] : void 0
+        });
+        return {
+          result,
+          message: result.status === "pending_approval" ? `Submitted for approval: plugin ${id}.` : `Share settings applied: plugin ${id}.`,
+          nextActions: [
+            {
+              command: `adp plugin share get --plugin-id ${id}${result.status === "pending_approval" ? " --pending" : ""}`,
+              reason: result.status === "pending_approval" ? "Review the config awaiting approval" : "Confirm the active config"
+            }
+          ]
+        };
+      }
+    })
+  );
+  registry.define(
+    createCommand({
+      command: "plugin share approval",
+      describe: "Show a plugin share approval (scope and credential changes)",
+      effects: "read_only",
+      outputKind: "data",
+      flags: [pluginIdFlag, { name: "approval-id", type: "string", describe: "Approval ID", required: true }],
+      examples: ["adp plugin share approval --plugin-id plg-1 --approval-id 2096851869377474240 --format json"],
+      async handler(args) {
+        const gateways = await ctx.deps.resolveGateways(ctx.flags);
+        return {
+          result: await describePluginShareApproval(gateways.pluginAccess, {
+            pluginId: pluginId(args),
+            approvalId: assertResourceId(String(args["approval-id"]), "approval-id")
+          })
+        };
+      }
+    })
+  );
+  registry.define(
+    createCommand({
+      command: "plugin tool get",
+      describe: "Show one plugin tool with its input/output schema",
+      effects: "read_only",
+      outputKind: "data",
+      flags: [
+        pluginIdFlag,
+        { name: "tool-id", type: "string", describe: "Tool ID (see adp plugin get)", required: true },
+        { name: "space-id", type: "string", describe: "Space ID (defaults to adp.jsonc)" }
+      ],
+      examples: ["adp plugin tool get --plugin-id plg-1 --tool-id tool-1 --format json"],
+      async handler(args) {
+        const spaceId = await optionalSpaceId(ctx, args);
+        const gateways = await ctx.deps.resolveGateways(ctx.flags);
+        const id = pluginId(args);
+        const toolId = assertResourceId(String(args["tool-id"]), "tool-id");
+        const tool = await describePluginTool(gateways.pluginAccess, {
+          pluginId: id,
+          toolId,
+          ...spaceId ? { spaceId: assertResourceId(spaceId, "space-id") } : {}
+        });
+        const toolName = tool.name.trim();
+        return {
+          result: tool,
+          nextActions: [
+            {
+              command: /^[A-Za-z0-9_-]+$/.test(toolName) ? `adp plugin tool call --plugin-id ${id} --tool-name ${toolName} --dry-run --format json` : `adp plugin tool call --plugin-id ${id} --tool-id ${toolId} --dry-run --format json`,
+              reason: "preview a direct MCP call when this plugin is pluginKind=2; adp plugin key create saves the tool key"
+            }
+          ]
+        };
+      }
+    })
+  );
+  registry.define(
+    createCommand({
+      command: "plugin auth check",
+      describe: "Check whether the caller has authorized OAuth plugins",
+      effects: "read_only",
+      outputKind: "data",
+      flags: [
+        { name: "plugin-id", type: "string", describe: "Plugin ID (repeatable)", required: true, list: true },
+        { name: "credential-id", type: "string", describe: "OAuth credential ID, paired by position with --plugin-id" }
+      ],
+      examples: ["adp plugin auth check --plugin-id plg-1 --credential-id cred-1 --format json"],
+      async handler(args) {
+        const pluginIds = strings6(args["plugin-id"]).map((id) => assertResourceId(id, "plugin-id"));
+        const credentialIds = strings6(args["credential-id"]);
+        const gateways = await ctx.deps.resolveGateways(ctx.flags);
+        const items = await checkPluginAuth(gateways.pluginAccess, {
+          items: pluginIds.map((id, i) => ({ pluginId: id, ...credentialIds[i] ? { credentialId: credentialIds[i] } : {} }))
+        });
+        return { result: { items } };
+      }
+    })
+  );
+  registry.define(
+    createCommand({
+      command: "plugin oauth-url",
+      describe: "Create an OAuth consent link for an OAuth plugin credential; open it in a browser",
+      effects: "non_idempotent",
+      outputKind: "data",
+      flags: [pluginIdFlag, { name: "credential-id", type: "string", describe: "OAuth credential ID", required: true }],
+      examples: ["adp plugin oauth-url --plugin-id plg-1 --credential-id cred-1"],
+      async handler(args) {
+        const input = { pluginId: pluginId(args), credentialId: assertResourceId(String(args["credential-id"]), "credential-id") };
+        if (ctx.flags.dryRun) {
+          return { result: { dryRun: true, ...input }, message: `Would create an OAuth consent link for credential ${input.credentialId}.` };
+        }
+        const gateways = await ctx.deps.resolveGateways(ctx.flags);
+        const { url } = await pluginOAuthUrl(gateways.pluginAccess, input);
+        return { result: { url }, message: url };
+      }
+    })
+  );
+}
+
+// src/domain/plugin/tool-key.ts
+function maskToolKey(value) {
+  if (value.includes("*")) {
+    return value;
+  }
+  if (value.length <= 8) {
+    return "****";
+  }
+  return `${value.slice(0, 4)}****${value.slice(-4)}`;
+}
+
+// src/application/plugin/tool-key-use-cases.ts
+var CREATE_COMMAND = {
+  command: "adp plugin key create --format json",
+  reason: "create a tool key and save it for adp plugin tool call"
+};
+var LIST_COMMAND = {
+  command: "adp plugin key list --format json",
+  reason: "list tool key ids; the plaintext is only returned when a key is created"
+};
+function toolKeyLimitReached(error) {
+  const message = error instanceof Error ? error.message : "";
+  if (!message.includes("4509400")) {
+    return void 0;
+  }
+  return new DomainError("This account already has the maximum of 2 tool keys (4509400)", "conflict", "ToolKeyLimitReached", {
+    hint: "An existing key's plaintext cannot be read back. Run adp plugin key list. A lastAccessTime of 0 has never been used. After you confirm which key to drop, disable it, then delete it, and create again. Or set a plaintext you already hold as ADP_API_KEY.",
+    retryable: false,
+    requestId: error instanceof DomainError ? error.requestId : void 0,
+    cause: error,
+    nextActions: [
+      {
+        command: "adp plugin key list --format json",
+        reason: "see key ids and lastAccessTime; 0 means unused. Confirm with the user before disabling one"
+      },
+      {
+        command: "adp plugin key disable --format json",
+        reason: "disable the confirmed key first; delete rejects a key that is still enabled",
+        needs_input: { flag: "key-id", question: "Tool key ID from adp plugin key list" }
+      },
+      {
+        command: "adp plugin key delete --yes --format json",
+        reason: "after disable succeeds, pass the same --key-id, then adp plugin key create",
+        needs_input: { flag: "key-id", question: "Tool key ID from adp plugin key list" }
+      }
+    ]
+  });
+}
+function toolKeyNotDisabled(error, apiKeyId) {
+  const message = error instanceof Error ? error.message : "";
+  if (!message.includes("4509404")) {
+    return void 0;
+  }
+  return new DomainError(`Tool key ${apiKeyId} must be disabled before it can be deleted (4509404)`, "conflict", "ToolKeyNotDisabled", {
+    hint: "Disable the key, then delete it. Disabling stops clients that use this key.",
+    retryable: false,
+    requestId: error instanceof DomainError ? error.requestId : void 0,
+    cause: error,
+    nextActions: [
+      {
+        command: `adp plugin key disable --key-id ${apiKeyId} --format json`,
+        reason: "disable the key; DeleteApiKey rejects a key that is still enabled"
+      },
+      {
+        command: `adp plugin key delete --key-id ${apiKeyId} --yes --format json`,
+        reason: "delete the key after it is disabled"
+      }
+    ]
+  });
+}
+function toolKeyMissingError() {
+  return new DomainError("MCP plugin calls need an ADP API Key (tool key)", "auth", "ToolKeyMissing", {
+    hint: "Create one with adp plugin key create (it is saved to ~/.adp/tool-key), set ADP_API_KEY, or pass --api-key-env. Do not put the secret on the command line.",
+    retryable: false,
+    nextActions: [CREATE_COMMAND, LIST_COMMAND]
+  });
+}
+async function resolveToolKey(input) {
+  if (input.envName) {
+    const value = (input.env[input.envName] ?? "").trim();
+    if (!value) {
+      throw new DomainError(`Environment variable ${input.envName} is empty`, "usage", "UsageError", {
+        hint: "Export the ADP API Key in that variable, or omit --api-key-env to use ADP_API_KEY or ~/.adp/tool-key",
+        retryable: false
+      });
+    }
+    return { value, source: "api-key-env", envName: input.envName };
+  }
+  const fromEnv = (input.env.ADP_API_KEY ?? "").trim();
+  if (fromEnv) {
+    return { value: fromEnv, source: "env", envName: "ADP_API_KEY" };
+  }
+  const stored = await input.store.load();
+  if (!stored?.value.trim()) {
+    return void 0;
+  }
+  return { value: stored.value.trim(), source: "file", ...stored.apiKeyId ? { apiKeyId: stored.apiKeyId } : {} };
+}
+function viewOf(record) {
+  return {
+    apiKeyId: record.apiKeyId,
+    apiKey: maskToolKey(record.apiKey),
+    masked: true,
+    description: record.description,
+    ...record.status !== void 0 ? { status: record.status, enabled: record.status === 1 } : {},
+    ...record.createTime ? { createTime: record.createTime } : {},
+    ...record.lastAccessTime ? { lastAccessTime: record.lastAccessTime } : {}
+  };
+}
+async function listToolKeys(gateway) {
+  const records20 = await gateway.list();
+  return records20.map(viewOf);
+}
+async function requireKey(gateway, apiKeyId) {
+  const found = (await listToolKeys(gateway)).find((item) => item.apiKeyId === apiKeyId);
+  if (!found) {
+    throw new DomainError(`No tool key with ID ${apiKeyId}`, "not_found", "ToolKeyNotFound", {
+      hint: "List ids with adp plugin key list. The plaintext cannot be recovered from the list.",
+      retryable: false,
+      nextActions: [LIST_COMMAND]
+    });
+  }
+  return found;
+}
+async function createToolKey(gateway, store, input) {
+  const description = input.description?.trim() || void 0;
+  if (input.dryRun) {
+    return { dryRun: true, save: input.save, ...description ? { description } : {} };
+  }
+  let created;
+  try {
+    created = await gateway.create();
+  } catch (error) {
+    const limit = toolKeyLimitReached(error);
+    if (limit) {
+      throw limit;
+    }
+    throw error;
+  }
+  if (!created.apiKey || !created.apiKeyId) {
+    throw new DomainError("CreateApiKey did not return a tool key", "upstream", "ToolKeyNotCreated", {
+      hint: "Nothing was saved locally. Retry adp plugin key create.",
+      retryable: true,
+      nextActions: [CREATE_COMMAND]
+    });
+  }
+  if (input.save) {
+    await store.save({ value: created.apiKey, apiKeyId: created.apiKeyId });
+  }
+  if (description) {
+    try {
+      await gateway.update({ apiKeyId: created.apiKeyId, description });
+    } catch (error) {
+      throw new DomainError(
+        input.save ? `Tool key ${created.apiKeyId} was saved locally, but the description was not updated` : `Tool key ${created.apiKeyId} was created, but the description was not updated. Plaintext: ${created.apiKey}`,
+        "upstream",
+        "ToolKeyDescriptionFailed",
+        {
+          cause: error,
+          hint: input.save ? "The key is in ~/.adp/tool-key. Set the description with adp plugin key update." : "This is the only time the plaintext is available.",
+          retryable: false,
+          nextActions: [
+            {
+              command: `adp plugin key update --key-id ${created.apiKeyId} --format json`,
+              reason: "retry the description",
+              needs_input: { flag: "description", question: "Description for this tool key" }
+            }
+          ]
+        }
+      );
+    }
+  }
+  return {
+    dryRun: false,
+    apiKeyId: created.apiKeyId,
+    apiKey: input.reveal ? created.apiKey : maskToolKey(created.apiKey),
+    masked: !input.reveal,
+    saved: input.save,
+    ...description ? { description } : {},
+    ...input.keepSecret ? { secret: created.apiKey } : {}
+  };
+}
+async function setToolKeyStatus(gateway, input) {
+  await requireKey(gateway, input.apiKeyId);
+  if (!input.dryRun) {
+    await gateway.setStatus({ apiKeyId: input.apiKeyId, status: input.status });
+  }
+  return { dryRun: input.dryRun, apiKeyId: input.apiKeyId, status: input.status, enabled: input.status === 1 };
+}
+async function updateToolKey(gateway, input) {
+  await requireKey(gateway, input.apiKeyId);
+  if (!input.dryRun) {
+    await gateway.update({ apiKeyId: input.apiKeyId, description: input.description });
+  }
+  return { dryRun: input.dryRun, apiKeyId: input.apiKeyId, description: input.description };
+}
+async function deleteToolKey(gateway, store, input) {
+  await requireKey(gateway, input.apiKeyId);
+  if (input.dryRun) {
+    return { dryRun: true, apiKeyId: input.apiKeyId, localKeyCleared: false };
+  }
+  try {
+    await gateway.delete({ apiKeyId: input.apiKeyId });
+  } catch (error) {
+    const notDisabled = toolKeyNotDisabled(error, input.apiKeyId);
+    if (notDisabled) {
+      throw notDisabled;
+    }
+    throw error;
+  }
+  const stored = await store.load();
+  const localKeyCleared = stored?.apiKeyId === input.apiKeyId;
+  if (localKeyCleared) {
+    await store.clear();
+  }
+  return { dryRun: false, apiKeyId: input.apiKeyId, localKeyCleared };
+}
+
+// src/interfaces/cli/commands/plugin/key.ts
+var keyIdFlag = { name: "key-id", type: "string", describe: "Tool key ID (adp plugin key list)", required: true };
+var revealFlag4 = {
+  name: "reveal",
+  type: "boolean",
+  describe: "Print the plaintext tool key. Otherwise it is masked. The plaintext is only available at creation."
+};
+function storeOf(ctx) {
+  return ctx.deps.toolKeyStore ?? createToolKeyFileStore(adpToolKeyPath());
+}
+function savedNote(saved) {
+  return saved ? " Saved to ~/.adp/tool-key for later adp plugin tool call." : "";
+}
+function registerPluginKeyCommands(registry, ctx) {
   registry.define(
     createCommand({
-      command: "plugin share get",
-      describe: "Show who may use a plugin across spaces (active config, or --pending for the one awaiting approval)",
+      command: "plugin key list",
+      describe: "List ADP API keys (tool keys). Values are masked; plaintext exists only at creation.",
       effects: "read_only",
       outputKind: "data",
-      flags: [pluginIdFlag, { name: "pending", type: "boolean", describe: "Show the config awaiting approval" }],
-      examples: ["adp plugin share get --plugin-id plg-1 --format json"],
-      async handler(args) {
+      flags: [],
+      examples: ["adp plugin key list --format json"],
+      async handler() {
         const gateways = await ctx.deps.resolveGateways(ctx.flags);
-        if (args.pending === true) {
-          return { result: await describePendingPluginShare(gateways.pluginAccess, { pluginId: pluginId(args) }) };
-        }
-        return { result: await describePluginShare(gateways.pluginAccess, { pluginId: pluginId(args), pending: false }) };
+        const items = await listToolKeys(gateways.toolKey);
+        return applyListShape(
+          ctx,
+          sliceResult(items, { limit: ctx.flags.limit, page: ctx.flags.page }),
+          "adp plugin key list"
+        );
       }
     })
   );
   registry.define(
     createCommand({
-      command: "plugin share set",
-      describe: "Change plugin or credential share scope; may need approval, and is blocked while apps use what it removes",
-      effects: "idempotent",
+      command: "plugin key create",
+      describe: "Create an ADP API key (tool key) and save it to ~/.adp/tool-key so adp plugin tool call can use it",
+      effects: "non_idempotent",
       outputKind: "data",
       flags: [
-        pluginIdFlag,
-        { name: "scope", type: "string", describe: "Plugin scope: none | all | spaces" },
-        { name: "space", type: "string", describe: "Target space ID for --scope spaces (repeatable)" },
-        { name: "credential", type: "string", describe: "<credential-id>=none|all|spaces:<id>,<id> (repeatable)" },
-        { name: "remark", type: "string", describe: "Note for the approver" },
-        { name: "force", type: "boolean", describe: "Admin only: apply even though referrers lose access" },
-        { name: "confirm-name", type: "string", describe: "Plugin name, required with --force" }
+        { name: "description", type: "string", describe: "Note stored on the key (ModifyApiKey)" },
+        revealFlag4,
+        {
+          name: "save",
+          type: "boolean",
+          default: true,
+          describe: "Save the new key to ~/.adp/tool-key (mode 0600). Pass --no-save to skip; then --reveal is required, because the plaintext is returned only once."
+        }
       ],
       examples: [
-        "adp plugin share set --plugin-id plg-1 --scope spaces --space sp-2 --yes",
-        "adp plugin share set --plugin-id plg-1 --credential cred-1=all --yes --format json"
+        "adp plugin key create --format json",
+        "adp plugin key create --description kling --reveal --format json",
+        "adp plugin key create --no-save --reveal --format json"
       ],
       async handler(args) {
-        const id = pluginId(args);
-        let plugin;
-        if (args.scope !== void 0) {
-          const scope = String(args.scope);
-          if (!SCOPES.includes(scope)) {
-            throw usageError(`--scope must be one of ${SCOPES.join(", ")}`);
-          }
-          plugin = { scope, spaceIds: [...new Set(strings6(args.space).map((s) => assertResourceId(s, "space")))] };
-        } else if (args.space !== void 0) {
-          throw usageError("--space needs --scope spaces");
+        const save = args.save !== false;
+        const reveal = args.reveal === true;
+        if (!save && !reveal) {
+          throw usageError(
+            "Refusing to create a tool key that cannot be recovered",
+            "The plaintext is returned only once. Omit --no-save to store it in ~/.adp/tool-key, or pass --reveal to print it."
+          );
         }
-        const credentials = strings6(args.credential).map(parseCredentialShare);
-        await requireYes(ctx, `change share settings of plugin ${id}`);
-        if (ctx.flags.dryRun) {
-          return { result: { dryRun: true, pluginId: id, plugin, credentials }, message: `Would change share settings of plugin ${id}.` };
+        const description = typeof args.description === "string" ? args.description : void 0;
+        const created = await createToolKey(
+          (await ctx.deps.resolveGateways(ctx.flags)).toolKey,
+          storeOf(ctx),
+          { description, reveal, save, dryRun: ctx.flags.dryRun }
+        );
+        if (created.dryRun) {
+          return {
+            result: created,
+            message: save ? "Would create a tool key and save it to ~/.adp/tool-key." : "Would create a tool key and print it. Nothing is saved."
+          };
         }
-        const gateways = await ctx.deps.resolveGateways(ctx.flags);
-        const result = await setPluginShare(gateways.pluginAccess, {
-          pluginId: id,
-          plugin,
-          credentials,
-          remark: typeof args.remark === "string" ? args.remark : void 0,
-          force: args.force === true,
-          confirmedName: typeof args["confirm-name"] === "string" ? args["confirm-name"] : void 0
-        });
+        const { secret: _secret, ...result } = created;
         return {
           result,
-          message: result.status === "pending_approval" ? `Submitted for approval: plugin ${id}.` : `Share settings applied: plugin ${id}.`,
+          message: `Created tool key ${result.apiKey}.${savedNote(result.saved)}`,
           nextActions: [
+            { command: "adp plugin key list --format json", reason: "confirm the new key id; the list stays masked" },
             {
-              command: `adp plugin share get --plugin-id ${id}${result.status === "pending_approval" ? " --pending" : ""}`,
-              reason: result.status === "pending_approval" ? "Review the config awaiting approval" : "Confirm the active config"
+              command: "adp plugin list --fields pluginId,name,pluginKind --format json",
+              reason: "pick a pluginKind=2 plugin, then adp plugin tool call"
             }
           ]
         };
@@ -18064,86 +19239,397 @@ function registerPluginAccessCommands(registry, ctx) {
   );
   registry.define(
     createCommand({
-      command: "plugin share approval",
-      describe: "Show a plugin share approval (scope and credential changes)",
-      effects: "read_only",
+      command: "plugin key update",
+      describe: "Change an ADP API key's description",
+      effects: "idempotent",
       outputKind: "data",
-      flags: [pluginIdFlag, { name: "approval-id", type: "string", describe: "Approval ID", required: true }],
-      examples: ["adp plugin share approval --plugin-id plg-1 --approval-id 2096851869377474240 --format json"],
+      flags: [
+        keyIdFlag,
+        { name: "description", type: "string", describe: "New note", required: true }
+      ],
+      examples: ["adp plugin key update --key-id key-1 --description kling --format json"],
       async handler(args) {
+        const apiKeyId = assertResourceId(String(args["key-id"]), "key-id");
+        const description = String(args.description ?? "").trim();
+        if (!description) {
+          throw usageError("Missing --description", "Pass the note to store on this tool key");
+        }
         const gateways = await ctx.deps.resolveGateways(ctx.flags);
+        const result = await updateToolKey(gateways.toolKey, { apiKeyId, description, dryRun: ctx.flags.dryRun });
         return {
-          result: await describePluginShareApproval(gateways.pluginAccess, {
-            pluginId: pluginId(args),
-            approvalId: assertResourceId(String(args["approval-id"]), "approval-id")
-          })
+          result,
+          message: ctx.flags.dryRun ? `Would update the description of tool key ${apiKeyId}.` : `Updated tool key ${apiKeyId}.`
         };
       }
     })
   );
+  for (const enabled of [true, false]) {
+    const verb = enabled ? "enable" : "disable";
+    const status = enabled ? 1 : 2;
+    registry.define(
+      createCommand({
+        command: `plugin key ${verb}`,
+        describe: enabled ? "Enable an ADP API key (status 1). A disabled key cannot call MCP plugins." : "Disable an ADP API key (status 2). Delete requires the key to be disabled first.",
+        effects: "idempotent",
+        outputKind: "data",
+        flags: [keyIdFlag],
+        examples: [`adp plugin key ${verb} --key-id key-1 --format json`],
+        async handler(args) {
+          const apiKeyId = assertResourceId(String(args["key-id"]), "key-id");
+          const gateways = await ctx.deps.resolveGateways(ctx.flags);
+          const result = await setToolKeyStatus(gateways.toolKey, { apiKeyId, status, dryRun: ctx.flags.dryRun });
+          if (ctx.flags.dryRun) {
+            return { result, message: `Would ${verb} tool key ${apiKeyId}.` };
+          }
+          return { result, message: `${enabled ? "Enabled" : "Disabled"} tool key ${apiKeyId}.` };
+        }
+      })
+    );
+  }
   registry.define(
     createCommand({
-      command: "plugin tool get",
-      describe: "Show one plugin tool with its input/output schema",
-      effects: "read_only",
+      command: "plugin key delete",
+      describe: "Delete an ADP API key. Clients using it stop working. A matching ~/.adp/tool-key is removed.",
+      effects: "non_idempotent",
       outputKind: "data",
-      flags: [
-        pluginIdFlag,
-        { name: "tool-id", type: "string", describe: "Tool ID (see adp plugin get)", required: true },
-        { name: "space-id", type: "string", describe: "Space ID (defaults to adp.jsonc)" }
-      ],
-      examples: ["adp plugin tool get --plugin-id plg-1 --tool-id tool-1 --format json"],
+      flags: [keyIdFlag],
+      examples: ["adp plugin key delete --key-id key-1 --yes"],
       async handler(args) {
-        const spaceId = await optionalSpaceId(ctx, args);
+        const apiKeyId = assertResourceId(String(args["key-id"]), "key-id");
+        await requireYes(ctx, `delete tool key ${apiKeyId}`);
         const gateways = await ctx.deps.resolveGateways(ctx.flags);
+        const result = await deleteToolKey(gateways.toolKey, storeOf(ctx), { apiKeyId, dryRun: ctx.flags.dryRun });
         return {
-          result: await describePluginTool(gateways.pluginAccess, {
-            pluginId: pluginId(args),
-            toolId: assertResourceId(String(args["tool-id"]), "tool-id"),
-            ...spaceId ? { spaceId: assertResourceId(spaceId, "space-id") } : {}
-          })
+          result,
+          message: ctx.flags.dryRun ? `Would delete tool key ${apiKeyId}.` : `Deleted tool key ${apiKeyId}.`
         };
       }
     })
   );
+}
+
+// src/application/plugin/plugin-mcp-use-cases.ts
+async function prepareToolKey(gateway, store, input) {
+  const existing = await resolveToolKey({ env: input.env, envName: input.envName, store });
+  if (existing) {
+    return {
+      value: existing.value,
+      source: existing.source,
+      ...existing.apiKeyId ? { apiKeyId: existing.apiKeyId } : {},
+      created: false,
+      wouldCreate: false,
+      hasKey: true
+    };
+  }
+  if (!input.autoCreate) {
+    if (input.dryRun) {
+      return { created: false, wouldCreate: false, hasKey: false };
+    }
+    throw toolKeyMissingError();
+  }
+  if (input.dryRun) {
+    return { created: false, wouldCreate: true, hasKey: false };
+  }
+  if (!gateway) {
+    throw new DomainError("Creating a tool key needs cloud credentials", "auth", "ToolKeyMissing", {
+      hint: "Run adp auth status, then retry with --auto-create-key, or create a key with adp plugin key create.",
+      retryable: false,
+      nextActions: [
+        { command: "adp auth status --format json", reason: "check the CAM credential used to call CreateApiKey" },
+        { command: "adp plugin key create --format json", reason: "create and save a tool key" }
+      ]
+    });
+  }
+  const created = await createToolKey(gateway, store, { reveal: false, save: true, dryRun: false, keepSecret: true });
+  if (created.dryRun || !created.secret) {
+    throw new DomainError("CreateApiKey did not return a tool key", "upstream", "ToolKeyNotCreated", { retryable: true });
+  }
+  return { value: created.secret, source: "created", apiKeyId: created.apiKeyId, created: true, wouldCreate: false, hasKey: true };
+}
+async function resolveToolName(tools, input) {
+  const name = input.toolName?.trim() || void 0;
+  if (!input.toolId) {
+    if (!name) {
+      throw new DomainError("Pass --tool-name or --tool-id", "usage", "UsageError", {
+        hint: "Tool names are on adp plugin get. --tool-id is resolved to that name.",
+        retryable: false,
+        nextActions: [
+          {
+            command: "adp plugin list --fields pluginId,name,pluginKind --format json",
+            reason: "find a pluginKind=2 plugin, then read its tools"
+          }
+        ]
+      });
+    }
+    return name;
+  }
+  if (!tools) {
+    throw new DomainError("--tool-id needs cloud credentials to look up the tool name", "auth", "AuthFailure", {
+      hint: "Pass --tool-name to skip the lookup, or run adp auth status and retry.",
+      retryable: false,
+      nextActions: [{ command: "adp auth status --format json", reason: "check the CAM credential used to describe the tool" }]
+    });
+  }
+  const detail = await describePluginTool(tools, {
+    pluginId: input.pluginId,
+    toolId: input.toolId,
+    ...input.spaceId ? { spaceId: input.spaceId } : {}
+  });
+  if (name && detail.name !== name) {
+    throw new DomainError(
+      `--tool-name ${name} does not match tool ${input.toolId} (${detail.name})`,
+      "usage",
+      "UsageError",
+      { hint: "Omit one of the two flags, or pass the name adp plugin tool get prints.", retryable: false }
+    );
+  }
+  if (!detail.name) {
+    throw new DomainError(`Tool ${input.toolId} has no name`, "not_found", "PluginToolNotFound", { retryable: false });
+  }
+  return detail.name;
+}
+async function callPluginMcpTool(deps, input) {
+  const url = pluginMcpUrl(input.pluginId);
+  const toolName = await resolveToolName(deps.tools, input);
+  const key = await prepareToolKey(deps.toolKeys, deps.store, input);
+  const base = {
+    dryRun: input.dryRun,
+    url,
+    pluginId: input.pluginId,
+    toolName,
+    ...input.toolId ? { toolId: input.toolId } : {},
+    arguments: input.arguments,
+    ...key.source ? { apiKeySource: key.source } : {},
+    ...key.apiKeyId ? { apiKeyId: key.apiKeyId } : {},
+    apiKeyCreated: key.created,
+    wouldCreateKey: key.wouldCreate,
+    hasKey: key.hasKey
+  };
+  if (input.dryRun || !key.value) {
+    return base;
+  }
+  const output = await deps.mcp.callTool({
+    pluginId: input.pluginId,
+    apiKey: key.value,
+    toolName,
+    arguments: input.arguments,
+    timeoutMs: input.timeoutMs
+  });
+  return { ...base, output };
+}
+async function listPluginMcpTools(deps, input) {
+  const url = pluginMcpUrl(input.pluginId);
+  const key = await prepareToolKey(deps.toolKeys, deps.store, input);
+  const base = {
+    dryRun: input.dryRun,
+    url,
+    pluginId: input.pluginId,
+    ...key.source ? { apiKeySource: key.source } : {},
+    ...key.apiKeyId ? { apiKeyId: key.apiKeyId } : {},
+    apiKeyCreated: key.created,
+    wouldCreateKey: key.wouldCreate,
+    hasKey: key.hasKey
+  };
+  if (input.dryRun || !key.value) {
+    return base;
+  }
+  const tools = await deps.mcp.listTools({ pluginId: input.pluginId, apiKey: key.value, timeoutMs: input.timeoutMs });
+  return { ...base, tools };
+}
+
+// src/interfaces/cli/commands/plugin/tool-call.ts
+var ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var DEFAULT_TIMEOUT_MS3 = 6e4;
+var MAX_TIMEOUT_MS = 6e5;
+var pluginIdFlag2 = {
+  name: "plugin-id",
+  type: "string",
+  describe: "Plugin ID. The call goes to https://adp.cloud.tencent.com/plugin/mcp/<pluginId>/mcp",
+  required: true
+};
+var apiKeyEnvFlag = {
+  name: "api-key-env",
+  type: "string",
+  describe: "Environment variable holding the ADP API Key. Default: ADP_API_KEY, then ~/.adp/tool-key. The secret is never a flag."
+};
+var autoCreateFlag = {
+  name: "auto-create-key",
+  type: "boolean",
+  describe: "When no tool key is available, create one, save it to ~/.adp/tool-key, and use it. The plaintext is not printed."
+};
+var timeoutFlag = {
+  name: "timeout-ms",
+  type: "number",
+  default: DEFAULT_TIMEOUT_MS3,
+  describe: "MCP HTTP timeout in milliseconds"
+};
+function dryRunMessage(result, preview, done) {
+  if (!result.dryRun) {
+    return done;
+  }
+  if (result.wouldCreateKey) {
+    return `Would create a tool key and ${preview}.`;
+  }
+  if (!result.hasKey) {
+    return `Would ${preview}. No tool key is loaded; create one or pass --auto-create-key before the real call.`;
+  }
+  return `Would ${preview}.`;
+}
+function keyNeeded(result) {
+  if (!result.dryRun || result.hasKey || result.wouldCreateKey) {
+    return void 0;
+  }
+  return [
+    {
+      command: "adp plugin key create --format json",
+      reason: "save a tool key before the real call, or rerun with --auto-create-key"
+    }
+  ];
+}
+function storeOf2(ctx) {
+  return ctx.deps.toolKeyStore ?? createToolKeyFileStore(adpToolKeyPath());
+}
+function mcpOf(ctx) {
+  return ctx.deps.pluginMcp ?? createPluginMcpGateway();
+}
+function envName(value) {
+  if (typeof value !== "string" || !value.trim()) {
+    return void 0;
+  }
+  const name = value.trim();
+  if (!ENV_NAME.test(name)) {
+    throw usageError("--api-key-env must be an environment variable name", "Example: --api-key-env ADP_API_KEY");
+  }
+  return name;
+}
+function timeoutMs(value) {
+  const parsed = value === void 0 ? DEFAULT_TIMEOUT_MS3 : Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > MAX_TIMEOUT_MS) {
+    throw usageError("--timeout-ms must be an integer from 1 to 600000");
+  }
+  return parsed;
+}
+function toolArguments(args) {
+  const input = args.input;
+  const alias = args.args;
+  if (typeof input === "string" && typeof alias === "string" && input !== alias) {
+    throw usageError("Pass only one of --input or --args", "Both are the JSON object sent as the tool arguments");
+  }
+  const raw = typeof input === "string" ? input : typeof alias === "string" ? alias : void 0;
+  if (raw === void 0 || !raw.trim()) {
+    return {};
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw usageError("--input must be a JSON object", `Example: --input '{"prompt":"a cat"}'`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw usageError("--input must be a JSON object", "Arrays and scalars are rejected. Pass {} for no arguments.");
+  }
+  return parsed;
+}
+function pluginId2(args) {
+  return assertResourceId(String(args["plugin-id"]), "plugin-id");
+}
+function registerPluginToolCallCommands(registry, ctx) {
   registry.define(
     createCommand({
-      command: "plugin auth check",
-      describe: "Check whether the caller has authorized OAuth plugins",
+      command: "plugin tool list",
+      describe: "List tools on a platform MCP plugin over Streamable HTTP (not the catalog from plugin get)",
       effects: "read_only",
       outputKind: "data",
-      flags: [
-        { name: "plugin-id", type: "string", describe: "Plugin ID (repeatable)", required: true, list: true },
-        { name: "credential-id", type: "string", describe: "OAuth credential ID, paired by position with --plugin-id" }
-      ],
-      examples: ["adp plugin auth check --plugin-id plg-1 --credential-id cred-1 --format json"],
-      async handler(args) {
-        const pluginIds = strings6(args["plugin-id"]).map((id) => assertResourceId(id, "plugin-id"));
-        const credentialIds = strings6(args["credential-id"]);
-        const gateways = await ctx.deps.resolveGateways(ctx.flags);
-        const items = await checkPluginAuth(gateways.pluginAccess, {
-          items: pluginIds.map((id, i) => ({ pluginId: id, ...credentialIds[i] ? { credentialId: credentialIds[i] } : {} }))
-        });
-        return { result: { items } };
+      flags: [pluginIdFlag2, apiKeyEnvFlag, autoCreateFlag, timeoutFlag],
+      examples: ["adp plugin tool list --plugin-id plg-1 --format json"],
+      async handler(args) {
+        const id = pluginId2(args);
+        const name = envName(args["api-key-env"]);
+        const store = storeOf2(ctx);
+        const autoCreate = args["auto-create-key"] === true;
+        const existing = await resolveToolKey({ env: ctx.deps.env, envName: name, store });
+        const gateways = autoCreate && !existing && !ctx.flags.dryRun ? await ctx.deps.resolveGateways(ctx.flags) : void 0;
+        const result = await listPluginMcpTools(
+          { mcp: mcpOf(ctx), store, ...gateways ? { toolKeys: gateways.toolKey } : {} },
+          {
+            pluginId: id,
+            env: ctx.deps.env,
+            ...name ? { envName: name } : {},
+            autoCreate,
+            timeoutMs: timeoutMs(args["timeout-ms"]),
+            dryRun: ctx.flags.dryRun
+          }
+        );
+        return {
+          result,
+          message: dryRunMessage(result, `list tools at ${result.url}`, `Listed tools at ${result.url}.`),
+          nextActions: keyNeeded(result)
+        };
       }
     })
   );
   registry.define(
     createCommand({
-      command: "plugin oauth-url",
-      describe: "Create an OAuth consent link for an OAuth plugin credential; open it in a browser",
+      command: "plugin tool call",
+      describe: "Call one tool on a platform MCP plugin (pluginKind=2). Auth is a tool key, not a command-line secret.",
       effects: "non_idempotent",
       outputKind: "data",
-      flags: [pluginIdFlag, { name: "credential-id", type: "string", describe: "OAuth credential ID", required: true }],
-      examples: ["adp plugin oauth-url --plugin-id plg-1 --credential-id cred-1"],
+      flags: [
+        pluginIdFlag2,
+        { name: "tool-name", type: "string", describe: "Tool name, such as SubmitKlingTextToVideoJob. Required unless --tool-id is set." },
+        { name: "tool-id", type: "string", describe: "Tool ID from adp plugin get. Resolved to the tool name when --tool-name is omitted." },
+        { name: "input", type: "string", describe: "JSON object of tool arguments. Default {}." },
+        { name: "args", type: "string", describe: "Alias of --input" },
+        { name: "space-id", type: "string", describe: "Space ID used only to resolve --tool-id (defaults to adp.jsonc)" },
+        apiKeyEnvFlag,
+        autoCreateFlag,
+        timeoutFlag
+      ],
+      examples: [
+        "adp plugin tool call --plugin-id plg-1 --tool-name SubmitJob --input '{}' --format json",
+        "adp plugin tool call --plugin-id plg-1 --tool-id tool-1 --dry-run --format json",
+        "adp plugin tool call --plugin-id plg-1 --tool-name SubmitJob --auto-create-key --format json"
+      ],
       async handler(args) {
-        const input = { pluginId: pluginId(args), credentialId: assertResourceId(String(args["credential-id"]), "credential-id") };
-        if (ctx.flags.dryRun) {
-          return { result: { dryRun: true, ...input }, message: `Would create an OAuth consent link for credential ${input.credentialId}.` };
-        }
-        const gateways = await ctx.deps.resolveGateways(ctx.flags);
-        const { url } = await pluginOAuthUrl(gateways.pluginAccess, input);
-        return { result: { url }, message: url };
+        const id = pluginId2(args);
+        const toolName = typeof args["tool-name"] === "string" && args["tool-name"].trim() ? args["tool-name"].trim() : void 0;
+        const toolId = typeof args["tool-id"] === "string" && args["tool-id"].trim() ? assertResourceId(args["tool-id"].trim(), "tool-id") : void 0;
+        const name = envName(args["api-key-env"]);
+        const store = storeOf2(ctx);
+        const autoCreate = args["auto-create-key"] === true;
+        const spaceId = await optionalSpaceId(ctx, args);
+        const existing = await resolveToolKey({ env: ctx.deps.env, envName: name, store });
+        const needCloud = Boolean(toolId) || autoCreate && !existing && !ctx.flags.dryRun;
+        const gateways = needCloud ? await ctx.deps.resolveGateways(ctx.flags) : void 0;
+        const result = await callPluginMcpTool(
+          {
+            mcp: mcpOf(ctx),
+            store,
+            ...gateways ? { tools: gateways.pluginAccess, toolKeys: gateways.toolKey } : {}
+          },
+          {
+            pluginId: id,
+            ...toolName ? { toolName } : {},
+            ...toolId ? { toolId } : {},
+            ...spaceId ? { spaceId: assertResourceId(spaceId, "space-id") } : {},
+            arguments: toolArguments(args),
+            env: ctx.deps.env,
+            ...name ? { envName: name } : {},
+            autoCreate,
+            timeoutMs: timeoutMs(args["timeout-ms"]),
+            dryRun: ctx.flags.dryRun
+          }
+        );
+        return {
+          result,
+          message: dryRunMessage(result, `call ${result.toolName} at ${result.url}`, `Called ${result.toolName}.`),
+          nextActions: keyNeeded(result) ?? (!result.dryRun && result.toolName.startsWith("Submit") ? [
+            {
+              command: `adp plugin get --plugin-id ${id} --format json`,
+              reason: "find the matching Query tool and call it with the task id in output"
+            }
+          ] : void 0)
+        };
       }
     })
   );
@@ -18685,7 +20171,7 @@ function registerEnvCommands(registry, ctx) {
 }
 
 // src/interfaces/cli/commands/skills-install.ts
-import { homedir as homedir5 } from "os";
+import { homedir as homedir6 } from "os";
 
 // src/application/companion-skills/discover-companion-skills.ts
 async function discoverCompanionSkills(pack, input) {
@@ -18830,7 +20316,7 @@ function registerCompanionSkillCommands(registry, ctx) {
           await requireYes(ctx, `install companion skills (${scope})`);
         }
         const result = await installCompanionSkills(ctx.deps.companionSkills, {
-          homeDir: homedir5(),
+          homeDir: homedir6(),
           cwd: ctx.flags.cwd,
           scope,
           agents: typeof args.agent === "string" ? args.agent : void 0,
@@ -18862,7 +20348,7 @@ function registerCompanionSkillCommands(registry, ctx) {
       ],
       async handler() {
         const result = await discoverCompanionSkills(ctx.deps.companionSkills, {
-          homeDir: homedir5(),
+          homeDir: homedir6(),
           cwd: ctx.flags.cwd
         });
         if (isManagedInstall(await detectInstallSource(ctx.deps))) {
@@ -22071,7 +23557,7 @@ async function modifyChannel(deps, input) {
   if (paths.length === 0) {
     throw usageError("Nothing to update", `Pass --description or --spec-json. Updatable paths: ${allowed.join(", ")}`);
   }
-  const rejected = paths.filter((path14) => !allowed.includes(path14));
+  const rejected = paths.filter((path18) => !allowed.includes(path18));
   if (rejected.length > 0) {
     throw usageError(
       `ModifyChannel cannot change ${rejected.join(", ")}`,
@@ -22357,7 +23843,7 @@ function registerModelCommands(registry, ctx) {
 }
 
 // src/interfaces/cli/commands/workflow/index.ts
-import { readFile as readFile13 } from "fs/promises";
+import { readFile as readFile15 } from "fs/promises";
 
 // src/domain/workflow/canvas.ts
 var WORKFLOW_NODE_TYPES = [
@@ -22615,17 +24101,17 @@ function checkReferences(nodes, problems) {
       const ref3 = isRecord(value.Reference) ? value.Reference : !root && "JsonPath" in value && text4(value.NodeID) ? value : void 0;
       if (ref3 && text4(ref3.NodeID)) {
         const target = byId.get(text4(ref3.NodeID));
-        const path14 = text4(ref3.JsonPath);
+        const path18 = text4(ref3.JsonPath);
         if (!target) {
           problems.push(
             `node ${id}: "${here}" references node "${text4(ref3.NodeID)}", which does not exist; point Reference.NodeID at one of ${[...byId.keys()].join(", ")}`
           );
         } else {
-          const field = /^Output\.([^.[\]]+)/.exec(path14)?.[1];
+          const field = /^Output\.([^.[\]]+)/.exec(path18)?.[1];
           const declared = declaredOutputs(target);
           if (field && declared && !declared.includes(field)) {
             problems.push(
-              `node ${id}: "${here}" reads ${text4(ref3.NodeID)}.${path14}, but ${text4(ref3.NodeID)} (${text4(target.NodeType)}) declares only ${declared.map((name) => `Output.${name}`).join(", ")}; rename the reference or the ${text4(target.NodeType) === "PARAMETER_EXTRACTOR" ? "parameter" : "output"}`
+              `node ${id}: "${here}" reads ${text4(ref3.NodeID)}.${path18}, but ${text4(ref3.NodeID)} (${text4(target.NodeType)}) declares only ${declared.map((name) => `Output.${name}`).join(", ")}; rename the reference or the ${text4(target.NodeType) === "PARAMETER_EXTRACTOR" ? "parameter" : "output"}`
             );
           }
         }
@@ -22883,18 +24369,18 @@ var COMPARISON_OPERATORS = /* @__PURE__ */ new Set([
   "NOT_SET"
 ]);
 var NUMERIC_OPERATORS = /* @__PURE__ */ new Set(["LT", "LE", "GT", "GE"]);
-function checkLogical(logical, path14, fixes, problems) {
+function checkLogical(logical, path18, fixes, problems) {
   const compound = Array.isArray(logical.Compound) ? logical.Compound.filter(isRecord) : [];
   const combined = logical.LogicalOperator === "AND" || logical.LogicalOperator === "OR";
   if (combined) {
     if (compound.length === 0) {
-      problems.push(`${path14}: LogicalOperator ${text4(logical.LogicalOperator)} needs conditions in Compound[]`);
+      problems.push(`${path18}: LogicalOperator ${text4(logical.LogicalOperator)} needs conditions in Compound[]`);
     }
     if ("Comparison" in logical) {
       delete logical.Comparison;
-      fixes.push(`removed ${path14}.Comparison (an ${text4(logical.LogicalOperator)} group uses Compound only)`);
+      fixes.push(`removed ${path18}.Comparison (an ${text4(logical.LogicalOperator)} group uses Compound only)`);
     }
-    compound.forEach((child, index) => checkLogical(child, `${path14}.Compound[${index}]`, fixes, problems));
+    compound.forEach((child, index) => checkLogical(child, `${path18}.Compound[${index}]`, fixes, problems));
     return;
   }
   const comparison = isRecord(logical.Comparison) ? logical.Comparison : void 0;
@@ -22904,10 +24390,10 @@ function checkLogical(logical, path14, fixes, problems) {
   const operator = text4(comparison.Operator);
   if (!COMPARISON_OPERATORS.has(operator)) {
     problems.push(
-      `${path14}.Comparison: Operator "${operator || "none"}" is not supported; use one of ${[...COMPARISON_OPERATORS].join(", ")}`
+      `${path18}.Comparison: Operator "${operator || "none"}" is not supported; use one of ${[...COMPARISON_OPERATORS].join(", ")}`
     );
   } else if (NUMERIC_OPERATORS.has(operator) && !["INT", "FLOAT"].includes(text4(comparison.LeftType))) {
-    problems.push(`${path14}.Comparison: ${operator} compares numbers; LeftType must be INT or FLOAT, got ${text4(comparison.LeftType) || "none"}`);
+    problems.push(`${path18}.Comparison: ${operator} compares numbers; LeftType must be INT or FLOAT, got ${text4(comparison.LeftType) || "none"}`);
   }
 }
 function dynamicCard(node) {
@@ -23049,9 +24535,9 @@ function rewriteEndReferences(node, fixes) {
       const value = isRecord(property.Value) ? property.Value : void 0;
       if (value?.InputType === "INPUT_REF" && isRecord(value.InputRef)) {
         const ref3 = value.InputRef;
-        const path14 = text4(ref3.JsonPath) || `Output.${text4(ref3.Name)}`;
-        property.Value = { InputType: "REFERENCE_OUTPUT", Reference: { NodeID: text4(ref3.NodeID), JsonPath: path14 } };
-        fixes.push(`END ${text4(node.NodeID)}: output ${text4(property.Title)} INPUT_REF -> REFERENCE_OUTPUT ${path14}`);
+        const path18 = text4(ref3.JsonPath) || `Output.${text4(ref3.Name)}`;
+        property.Value = { InputType: "REFERENCE_OUTPUT", Reference: { NodeID: text4(ref3.NodeID), JsonPath: path18 } };
+        fixes.push(`END ${text4(node.NodeID)}: output ${text4(property.Title)} INPUT_REF -> REFERENCE_OUTPUT ${path18}`);
       }
       visit(property.Properties);
     }
@@ -23254,7 +24740,7 @@ function recheckAction(input) {
     };
   }
   return {
-    command: rerunOf(input, "dry-run") ?? `adp workflow deploy --app-id ${input.appId}${workflow} --canvas-file ${shellWord4(input.canvasFile)}${input.bind === false ? " --no-bind" : input.bind ? " --bind" : ""} --dry-run --format json`,
+    command: rerunOf(input, "dry-run") ?? `adp workflow deploy --app-id ${input.appId}${workflow} --canvas-file ${shellWord5(input.canvasFile)}${input.bind === false ? " --no-bind" : input.bind ? " --bind" : ""} --dry-run --format json`,
     reason: `after editing ${input.canvasFile} to fix the problems above, re-run this local check (no cloud write)`,
     needs_edit: { file: input.canvasFile }
   };
@@ -23347,7 +24833,7 @@ function platformRejectionActions(input, canvas, errors) {
   const workflow = input.workflowId ? ` --workflow-id ${input.workflowId}` : "";
   actions.push(
     input.canvasFile ? {
-      command: rerunOf(input, "yes") ?? `adp workflow deploy --app-id ${input.appId}${workflow} --canvas-file ${shellWord4(input.canvasFile)}${input.bind === false ? " --no-bind" : input.bind ? " --bind" : ""} --yes --format json`,
+      command: rerunOf(input, "yes") ?? `adp workflow deploy --app-id ${input.appId}${workflow} --canvas-file ${shellWord5(input.canvasFile)}${input.bind === false ? " --no-bind" : input.bind ? " --bind" : ""} --yes --format json`,
       reason: `after editing ${named ? `node ${named}` : "the canvas"} in ${input.canvasFile} as the platform message says, deploy again; this writes the workflow draft (the local --dry-run check already passes)`,
       needs_edit: { file: input.canvasFile }
     } : recheckAction(input)
@@ -23357,7 +24843,7 @@ function platformRejectionActions(input, canvas, errors) {
 function rerunOf(input, mode2) {
   return input.rerun?.(mode2);
 }
-function shellWord4(value) {
+function shellWord5(value) {
   return /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
 }
 async function withShellCleanup(error, gateway, appId3, workflowId2, name) {
@@ -23587,13 +25073,13 @@ function signatureExpiry2(url) {
 }
 
 // src/infrastructure/fs/workflow-canvas-extractor.ts
-import { readFile as readFile12, writeFile as writeFile8 } from "fs/promises";
+import { readFile as readFile14, writeFile as writeFile6 } from "fs/promises";
 import { basename, dirname, join } from "path";
 var CANVAS_ENTRY = /(?:^|\/)([^/]+_workflow\.json)$/;
 function createWorkflowCanvasExtractor() {
   return {
     async extractCanvases(zipPath) {
-      const zip = await readFile12(zipPath);
+      const zip = await readFile14(zipPath);
       const written = [];
       for (const entry of listEntries(zip)) {
         const match = CANVAS_ENTRY.exec(entry.name);
@@ -23602,7 +25088,7 @@ function createWorkflowCanvasExtractor() {
           continue;
         }
         const target = join(dirname(zipPath), basename(match[1]));
-        await writeFile8(target, body);
+        await writeFile6(target, body);
         written.push(target);
       }
       return written;
@@ -23913,7 +25399,7 @@ function parseTimeout(args) {
   }
   return timeout * 1e3;
 }
-function shellWord5(value) {
+function shellWord6(value) {
   return /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
 }
 function waitingActions(appId3, workflowRunId, question, options = []) {
@@ -23934,7 +25420,7 @@ function waitingActions(appId3, workflowRunId, question, options = []) {
   }
   return [
     {
-      command: `adp workflow run resume --app-id ${appId3} --run-id ${workflowRunId} --query ${shellWord5(options[0])} --format json`,
+      command: `adp workflow run resume --app-id ${appId3} --run-id ${workflowRunId} --query ${shellWord6(options[0])} --format json`,
       reason: `${ask}options: ${options.join(" / ")}; this picks the first, change --query to choose another`
     },
     get
@@ -23985,7 +25471,7 @@ function registerWorkflowRunCommands(registry, ctx) {
             message: `Would start a workflow run of app ${id}.`
           };
         }
-        const timeoutMs = parseTimeout(args);
+        const timeoutMs2 = parseTimeout(args);
         const gateways = await ctx.deps.resolveGateways(ctx.flags);
         const result = await runWorkflow(
           { runs: gateways.workflowRun, latestMessage: (ref3) => gateways.workflowRunControl.latestMessage(ref3) },
@@ -23996,7 +25482,7 @@ function registerWorkflowRunCommands(registry, ctx) {
             variables,
             visitorId: typeof args["visitor-id"] === "string" ? args["visitor-id"] : void 0,
             wait: args.wait !== false,
-            timeoutMs
+            timeoutMs: timeoutMs2
           }
         );
         if (result.status === "submitted") {
@@ -24168,7 +25654,7 @@ function registerWorkflowRunCommands(registry, ctx) {
         if (ctx.flags.dryRun) {
           return { result: { dryRun: true, ...input }, message: `Would resume workflow run ${input.workflowRunId}.` };
         }
-        const timeoutMs = parseTimeout(args);
+        const timeoutMs2 = parseTimeout(args);
         const gateways = await ctx.deps.resolveGateways(ctx.flags);
         if (args.wait !== false) {
           return waitedOutput(
@@ -24176,7 +25662,7 @@ function registerWorkflowRunCommands(registry, ctx) {
               gateways.workflowRunControl,
               await resumeWorkflowRunAndWait(
                 { runs: gateways.workflowRun, control: gateways.workflowRunControl },
-                { ...input, timeoutMs }
+                { ...input, timeoutMs: timeoutMs2 }
               )
             )
           );
@@ -24217,22 +25703,22 @@ function registerWorkflowRunCommands(registry, ctx) {
 }
 
 // src/interfaces/cli/commands/workflow/index.ts
-async function readCanvas(path14) {
+async function readCanvas(path18) {
   let raw;
   try {
-    raw = await readFile13(path14, "utf8");
+    raw = await readFile15(path18, "utf8");
   } catch {
-    throw usageError(`Cannot read canvas file ${path14}`, "Pass a readable JSON file via --canvas-file");
+    throw usageError(`Cannot read canvas file ${path18}`, "Pass a readable JSON file via --canvas-file");
   }
   try {
     const parsed = JSON.parse(raw);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-      throw usageError(`Canvas file ${path14} must contain a JSON object`, "Pass a workflow canvas object");
+      throw usageError(`Canvas file ${path18} must contain a JSON object`, "Pass a workflow canvas object");
     }
     return parsed;
   } catch (error) {
     if (error instanceof SyntaxError) {
-      throw usageError(`Canvas file ${path14} is not valid JSON`, "Fix the canvas JSON and retry");
+      throw usageError(`Canvas file ${path18} is not valid JSON`, "Fix the canvas JSON and retry");
     }
     throw error;
   }
@@ -25272,7 +26758,7 @@ function registerMemoryCommands(registry, ctx) {
       examples: ["adp memory export --space-id sp-1 --store-id rms_abc --output ./memory.csv"],
       async handler(args) {
         const ref3 = await storeRef(ctx, args);
-        const output = text5(args, "output") ? canonicalizeLocalPath(String(args.output), ctx.flags.cwd) : void 0;
+        const output = typeof args.output === "string" ? canonicalizeLocalPath(args.output, ctx.flags.cwd) : void 0;
         if (ctx.flags.dryRun) {
           return { result: { dryRun: true, ...ref3, output }, message: `Would export memory store ${ref3.storeId}.` };
         }
@@ -25491,11 +26977,11 @@ async function credentialRef(ctx, args) {
   };
 }
 async function readToken(ctx, args, required3) {
-  const envName = text6(args, "token-env");
-  if (envName) {
-    const value = ctx.deps.env[envName]?.trim();
+  const envName2 = text6(args, "token-env");
+  if (envName2) {
+    const value = ctx.deps.env[envName2]?.trim();
     if (!value) {
-      throw new DomainError(`Environment variable ${envName} is empty or unset`, "usage", "UsageError");
+      throw new DomainError(`Environment variable ${envName2} is empty or unset`, "usage", "UsageError");
     }
     return value;
   }
@@ -25773,7 +27259,7 @@ ${auth.authorizationUrl}`);
 }
 
 // src/interfaces/cli/commands/timer/index.ts
-import { readFile as readFile14 } from "fs/promises";
+import { readFile as readFile16 } from "fs/promises";
 
 // src/application/timer/timer-use-cases.ts
 var RUN_POLL_MS = 3e3;
@@ -25905,7 +27391,7 @@ async function prompt(args) {
     return inline;
   }
   try {
-    const content = (await readFile14(file, "utf8")).trim();
+    const content = (await readFile16(file, "utf8")).trim();
     if (!content) {
       throw new Error("empty");
     }
@@ -26934,49 +28420,49 @@ async function deleteVolume(gateway, input) {
   return { volumeId: volume.volumeId, name: volume.name, deleted: true, referenceApps: volume.referenceApps };
 }
 function listVolumeEntries(gateway, input) {
-  const path14 = normalizeVolumePath(input.path, { allowRoot: true });
-  return guard10(gateway.listEntries({ ...input, path: path14 }), { ...input, path: path14 });
+  const path18 = normalizeVolumePath(input.path, { allowRoot: true });
+  return guard10(gateway.listEntries({ ...input, path: path18 }), { ...input, path: path18 });
 }
 function makeVolumeDirectory(gateway, input) {
-  const path14 = normalizeVolumePath(input.path);
-  return guard10(gateway.mkdir({ ...input, path: path14 }), { ...input, path: path14 });
+  const path18 = normalizeVolumePath(input.path);
+  return guard10(gateway.mkdir({ ...input, path: path18 }), { ...input, path: path18 });
 }
 async function renameVolumeFile(gateway, input) {
-  const path14 = normalizeVolumePath(input.path);
+  const path18 = normalizeVolumePath(input.path);
   const name = input.name.trim();
   if (!name || name.includes("/") || name === "." || name === "..") {
     throw new DomainError("--name is a single file name; files cannot move between directories", "usage", "UsageError");
   }
-  const renamed = await guard10(gateway.rename({ ...input, path: path14, name }), { ...input, path: path14, operation: "rename" });
+  const renamed = await guard10(gateway.rename({ ...input, path: path18, name }), { ...input, path: path18, operation: "rename" });
   if (renamed.sizeBytes > 0) {
     return renamed;
   }
-  const finalPath = renamed.path || [...path14.split("/").slice(0, -1), name].join("/");
+  const finalPath = renamed.path || [...path18.split("/").slice(0, -1), name].join("/");
   const parent = finalPath.split("/").slice(0, -1).join("/");
   const listing = await gateway.listEntries({ spaceId: input.spaceId, volumeId: input.volumeId, path: parent, query: baseName(finalPath), limit: 50 }).catch(() => void 0);
   const entry = listing?.items.find((item) => item.path === finalPath);
   return { path: finalPath, sizeBytes: entry?.sizeBytes ?? renamed.sizeBytes };
 }
 async function deleteVolumeEntry(gateway, input) {
-  const path14 = normalizeVolumePath(input.path);
+  const path18 = normalizeVolumePath(input.path);
   const type = input.recursive ? "directory" : "file";
-  await guard10(gateway.deleteEntry({ ...input, path: path14, type }), { ...input, path: path14, operation: "delete" });
-  return { volumeId: input.volumeId, path: path14, type, deleted: true };
+  await guard10(gateway.deleteEntry({ ...input, path: path18, type }), { ...input, path: path18, operation: "delete" });
+  return { volumeId: input.volumeId, path: path18, type, deleted: true };
 }
 function uploadToVolume(gateway, input) {
   const local = baseName(input.localPath.replace(/\\/g, "/"));
   const raw = input.to === void 0 || input.to === "" ? local : input.to.endsWith("/") ? `${input.to}${local}` : input.to;
-  const path14 = normalizeVolumePath(raw);
-  return guard10(gateway.upload({ ...input, path: path14 }), { ...input, path: path14 });
+  const path18 = normalizeVolumePath(raw);
+  return guard10(gateway.upload({ ...input, path: path18 }), { ...input, path: path18 });
 }
 async function downloadFromVolume(gateway, input) {
-  const path14 = normalizeVolumePath(input.path);
-  const result = await guard10(gateway.download({ ...input, path: path14 }), { ...input, path: path14 });
-  return { volumeId: input.volumeId, path: path14, output: input.localPath, ...result };
+  const path18 = normalizeVolumePath(input.path);
+  const result = await guard10(gateway.download({ ...input, path: path18 }), { ...input, path: path18 });
+  return { volumeId: input.volumeId, path: path18, output: input.localPath, ...result };
 }
 function volumePreviewUrl(gateway, input) {
-  const path14 = normalizeVolumePath(input.path);
-  return guard10(gateway.previewUrl({ ...input, path: path14 }), { ...input, path: path14 });
+  const path18 = normalizeVolumePath(input.path);
+  return guard10(gateway.previewUrl({ ...input, path: path18 }), { ...input, path: path18 });
 }
 
 // src/interfaces/cli/commands/volume/index.ts
@@ -27103,14 +28589,14 @@ function registerVolumeCommands(registry, ctx) {
       examples: ["adp volume ls --space-id sp-1 --volume-id v-1 --path docs --format json"],
       async handler(args) {
         const target = await ref2(ctx, args);
-        const path14 = text10(args.path) ?? "";
+        const path18 = text10(args.path) ?? "";
         const query = text10(args.query);
         const gateways = await ctx.deps.resolveGateways(ctx.flags);
-        const page3 = await listVolumeEntries(gateways.volume, { ...target, path: path14, query, limit: ctx.flags.limit, page: ctx.flags.page });
+        const page3 = await listVolumeEntries(gateways.volume, { ...target, path: path18, query, limit: ctx.flags.limit, page: ctx.flags.page });
         return applyListShape(
           ctx,
           pageResult(page3, { limit: ctx.flags.limit, page: ctx.flags.page }),
-          `adp volume ls --space-id ${target.spaceId} --volume-id ${target.volumeId}${path14 ? ` --path ${JSON.stringify(path14)}` : ""}`
+          `adp volume ls --space-id ${target.spaceId} --volume-id ${target.volumeId}${path18 ? ` --path ${JSON.stringify(path18)}` : ""}`
         );
       }
     })
@@ -27937,7 +29423,7 @@ function registerSynonymCommands(registry, ctx) {
       examples: ["adp synonym export --app-id app-1 --output ./synonyms.xlsx"],
       async handler(args) {
         const appId3 = await resolveAppId(ctx, args, WHY_APP7);
-        const output = text11(args, "output") ? canonicalizeLocalPath(String(args.output), ctx.flags.cwd) : void 0;
+        const output = typeof args.output === "string" ? canonicalizeLocalPath(args.output, ctx.flags.cwd) : void 0;
         const input = { appId: appId3, query: text11(args, "query"), categoryId: categoryId(args), unreleasedOnly: args.unreleased === true };
         if (ctx.flags.dryRun) {
           return { result: { dryRun: true, ...input, output }, message: "Would export synonyms." };
@@ -28166,7 +29652,7 @@ function registerUnsatisfiedCommands(registry, ctx) {
       examples: ["adp unsatisfied export --app-id app-1 --status pending --output ./unsatisfied.xlsx"],
       async handler(args) {
         const appId3 = await resolveAppId(ctx, args, WHY_APP8);
-        const output = text12(args, "output") ? canonicalizeLocalPath(String(args.output), ctx.flags.cwd) : void 0;
+        const output = typeof args.output === "string" ? canonicalizeLocalPath(args.output, ctx.flags.cwd) : void 0;
         const input = { appId: appId3, ...filters5(args), replyIds: list4(args, "reply-id").map((id) => assertResourceId(id, "reply-id")) };
         if (ctx.flags.dryRun) {
           return { result: { dryRun: true, ...input, output }, message: "Would export unsatisfied replies." };
@@ -29009,6 +30495,8 @@ async function runCli(options) {
   registerAppOpsCommands(registry, ctx);
   registerPluginCommands(registry, ctx);
   registerPluginAccessCommands(registry, ctx);
+  registerPluginKeyCommands(registry, ctx);
+  registerPluginToolCallCommands(registry, ctx);
   registerSkillCommands(registry, ctx);
   registerSkillLifecycleCommands(registry, ctx);
   registerEnvCommands(registry, ctx);