feat: add optional plugin tools

src/plugins/registry.ts

@@ -27,6 +27,7 @@ export type PluginToolRegistration = {
   pluginId: string;
   factory: ClawdbotPluginToolFactory;
   names: string[];
+  optional: boolean;
   source: string;
 };
 
@@ -125,9 +126,10 @@ export function createPluginRegistry(registryParams: PluginRegistryParams) {
   const registerTool = (
     record: PluginRecord,
     tool: AnyAgentTool | ClawdbotPluginToolFactory,
-    opts?: { name?: string; names?: string[] },
+    opts?: { name?: string; names?: string[]; optional?: boolean },
   ) => {
     const names = opts?.names ?? (opts?.name ? [opts.name] : []);
+    const optional = opts?.optional === true;
     const factory: ClawdbotPluginToolFactory =
       typeof tool === "function" ? tool : (_ctx: ClawdbotPluginToolContext) => tool;
 
@@ -143,6 +145,7 @@ export function createPluginRegistry(registryParams: PluginRegistryParams) {
       pluginId: record.id,
       factory,
       names: normalized,
+      optional,
       source: record.source,
     });
   };

src/plugins/tools.optional.test.ts

@@ -0,0 +1,177 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { resolvePluginTools } from "./tools.js";
+
+type TempPlugin = { dir: string; file: string; id: string };
+
+const tempDirs: string[] = [];
+
+function makeTempDir() {
+  const dir = path.join(os.tmpdir(), `clawdbot-plugin-tools-${randomUUID()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  tempDirs.push(dir);
+  return dir;
+}
+
+function writePlugin(params: { id: string; body: string }): TempPlugin {
+  const dir = makeTempDir();
+  const file = path.join(dir, `${params.id}.js`);
+  fs.writeFileSync(file, params.body, "utf-8");
+  return { dir, file, id: params.id };
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    try {
+      fs.rmSync(dir, { recursive: true, force: true });
+    } catch {
+      // ignore cleanup failures
+    }
+  }
+});
+
+describe("resolvePluginTools optional tools", () => {
+  const pluginBody = `
+export default function (api) {
+  api.registerTool(
+    {
+      name: "optional_tool",
+      description: "optional tool",
+      parameters: { type: "object", properties: {} },
+      async execute() {
+        return { content: [{ type: "text", text: "ok" }] };
+      },
+    },
+    { optional: true },
+  );
+}
+`;
+
+  it("skips optional tools without explicit allowlist", () => {
+    const plugin = writePlugin({ id: "optional-demo", body: pluginBody });
+    const tools = resolvePluginTools({
+      context: {
+        config: {
+          plugins: {
+            load: { paths: [plugin.file] },
+            allow: [plugin.id],
+          },
+        },
+        workspaceDir: plugin.dir,
+      },
+    });
+    expect(tools).toHaveLength(0);
+  });
+
+  it("allows optional tools by name", () => {
+    const plugin = writePlugin({ id: "optional-demo", body: pluginBody });
+    const tools = resolvePluginTools({
+      context: {
+        config: {
+          plugins: {
+            load: { paths: [plugin.file] },
+            allow: [plugin.id],
+          },
+        },
+        workspaceDir: plugin.dir,
+      },
+      toolAllowlist: ["optional_tool"],
+    });
+    expect(tools.map((tool) => tool.name)).toContain("optional_tool");
+  });
+
+  it("allows optional tools via plugin groups", () => {
+    const plugin = writePlugin({ id: "optional-demo", body: pluginBody });
+    const toolsAll = resolvePluginTools({
+      context: {
+        config: {
+          plugins: {
+            load: { paths: [plugin.file] },
+            allow: [plugin.id],
+          },
+        },
+        workspaceDir: plugin.dir,
+      },
+      toolAllowlist: ["group:plugins"],
+    });
+    expect(toolsAll.map((tool) => tool.name)).toContain("optional_tool");
+
+    const toolsPlugin = resolvePluginTools({
+      context: {
+        config: {
+          plugins: {
+            load: { paths: [plugin.file] },
+            allow: [plugin.id],
+          },
+        },
+        workspaceDir: plugin.dir,
+      },
+      toolAllowlist: ["optional-demo"],
+    });
+    expect(toolsPlugin.map((tool) => tool.name)).toContain("optional_tool");
+  });
+
+  it("rejects plugin id collisions with core tool names", () => {
+    const plugin = writePlugin({ id: "message", body: pluginBody });
+    const tools = resolvePluginTools({
+      context: {
+        config: {
+          plugins: {
+            load: { paths: [plugin.file] },
+            allow: [plugin.id],
+          },
+        },
+        workspaceDir: plugin.dir,
+      },
+      existingToolNames: new Set(["message"]),
+      toolAllowlist: ["message"],
+    });
+    expect(tools).toHaveLength(0);
+  });
+
+  it("skips conflicting tool names but keeps other tools", () => {
+    const plugin = writePlugin({
+      id: "multi",
+      body: `
+export default function (api) {
+  api.registerTool({
+    name: "message",
+    description: "conflict",
+    parameters: { type: "object", properties: {} },
+    async execute() {
+      return { content: [{ type: "text", text: "nope" }] };
+    },
+  });
+  api.registerTool({
+    name: "other_tool",
+    description: "ok",
+    parameters: { type: "object", properties: {} },
+    async execute() {
+      return { content: [{ type: "text", text: "ok" }] };
+    },
+  });
+}
+`,
+    });
+
+    const tools = resolvePluginTools({
+      context: {
+        config: {
+          plugins: {
+            load: { paths: [plugin.file] },
+            allow: [plugin.id],
+          },
+        },
+        workspaceDir: plugin.dir,
+      },
+      existingToolNames: new Set(["message"]),
+    });
+
+    expect(tools.map((tool) => tool.name)).toEqual(["other_tool"]);
+  });
+});

src/plugins/tools.ts

@@ -1,13 +1,43 @@
 import type { AnyAgentTool } from "../agents/tools/common.js";
+import { normalizeToolName } from "../agents/tool-policy.js";
 import { createSubsystemLogger } from "../logging.js";
 import { loadClawdbotPlugins } from "./loader.js";
 import type { ClawdbotPluginToolContext } from "./types.js";
 
 const log = createSubsystemLogger("plugins");
 
+type PluginToolMeta = {
+  pluginId: string;
+  optional: boolean;
+};
+
+const pluginToolMeta = new WeakMap<AnyAgentTool, PluginToolMeta>();
+
+export function getPluginToolMeta(tool: AnyAgentTool): PluginToolMeta | undefined {
+  return pluginToolMeta.get(tool);
+}
+
+function normalizeAllowlist(list?: string[]) {
+  return new Set((list ?? []).map(normalizeToolName).filter(Boolean));
+}
+
+function isOptionalToolAllowed(params: {
+  toolName: string;
+  pluginId: string;
+  allowlist: Set<string>;
+}): boolean {
+  if (params.allowlist.size === 0) return false;
+  const toolName = normalizeToolName(params.toolName);
+  if (params.allowlist.has(toolName)) return true;
+  const pluginKey = normalizeToolName(params.pluginId);
+  if (params.allowlist.has(pluginKey)) return true;
+  return params.allowlist.has("group:plugins");
+}
+
 export function resolvePluginTools(params: {
   context: ClawdbotPluginToolContext;
   existingToolNames?: Set<string>;
+  toolAllowlist?: string[];
 }): AnyAgentTool[] {
   const registry = loadClawdbotPlugins({
     config: params.context.config,
@@ -22,8 +52,27 @@ export function resolvePluginTools(params: {
 
   const tools: AnyAgentTool[] = [];
   const existing = params.existingToolNames ?? new Set<string>();
+  const existingNormalized = new Set(
+    Array.from(existing, (tool) => normalizeToolName(tool)),
+  );
+  const allowlist = normalizeAllowlist(params.toolAllowlist);
+  const blockedPlugins = new Set<string>();
 
   for (const entry of registry.tools) {
+    if (blockedPlugins.has(entry.pluginId)) continue;
+    const pluginIdKey = normalizeToolName(entry.pluginId);
+    if (existingNormalized.has(pluginIdKey)) {
+      const message = `plugin id conflicts with core tool name (${entry.pluginId})`;
+      log.error(message);
+      registry.diagnostics.push({
+        level: "error",
+        pluginId: entry.pluginId,
+        source: entry.source,
+        message,
+      });
+      blockedPlugins.add(entry.pluginId);
+      continue;
+    }
     let resolved: AnyAgentTool | AnyAgentTool[] | null | undefined = null;
     try {
       resolved = entry.factory(params.context);
@@ -32,13 +81,36 @@ export function resolvePluginTools(params: {
       continue;
     }
     if (!resolved) continue;
-    const list = Array.isArray(resolved) ? resolved : [resolved];
+    const listRaw = Array.isArray(resolved) ? resolved : [resolved];
+    const list = entry.optional
+      ? listRaw.filter((tool) =>
+          isOptionalToolAllowed({
+            toolName: tool.name,
+            pluginId: entry.pluginId,
+            allowlist,
+          }),
+        )
+      : listRaw;
+    if (list.length === 0) continue;
+    const nameSet = new Set<string>();
     for (const tool of list) {
-      if (existing.has(tool.name)) {
-        log.warn(`plugin tool name conflict (${entry.pluginId}): ${tool.name}`);
+      if (nameSet.has(tool.name) || existing.has(tool.name)) {
+        const message = `plugin tool name conflict (${entry.pluginId}): ${tool.name}`;
+        log.error(message);
+        registry.diagnostics.push({
+          level: "error",
+          pluginId: entry.pluginId,
+          source: entry.source,
+          message,
+        });
         continue;
       }
+      nameSet.add(tool.name);
       existing.add(tool.name);
+      pluginToolMeta.set(tool, {
+        pluginId: entry.pluginId,
+        optional: entry.optional,
+      });
       tools.push(tool);
     }
   }

src/plugins/types.ts

@@ -65,6 +65,12 @@ export type ClawdbotPluginToolFactory = (
   ctx: ClawdbotPluginToolContext,
 ) => AnyAgentTool | AnyAgentTool[] | null | undefined;
 
+export type ClawdbotPluginToolOptions = {
+  name?: string;
+  names?: string[];
+  optional?: boolean;
+};
+
 export type ProviderAuthKind = "oauth" | "api_key" | "token" | "device_code" | "custom";
 
 export type ProviderAuthResult = {
@@ -171,7 +177,7 @@ export type ClawdbotPluginApi = {
   logger: PluginLogger;
   registerTool: (
     tool: AnyAgentTool | ClawdbotPluginToolFactory,
-    opts?: { name?: string; names?: string[] },
+    opts?: ClawdbotPluginToolOptions,
   ) => void;
   registerHttpHandler: (handler: ClawdbotPluginHttpHandler) => void;
   registerChannel: (registration: ClawdbotPluginChannelRegistration | ChannelPlugin) => void;