docs: clarify malformed plugin tool guards

src/agents/anthropic-transport-stream.ts

@@ -396,6 +396,8 @@ function convertAnthropicTools(tools: Context["tools"], isOAuthToken: boolean) {
     return [];
   }
   return tools.flatMap((tool) => {
+    // Main quarantine happens when plugin tools materialize; this keeps Anthropic
+    // safe for direct/custom tool arrays that bypass the plugin registry.
     const parameters =
       tool.parameters && typeof tool.parameters === "object" && !Array.isArray(tool.parameters)
         ? (tool.parameters as Record<string, unknown>)

src/plugins/tools.ts

@@ -66,6 +66,7 @@ function readPluginToolName(tool: unknown): string {
   if (!isRecord(tool)) {
     return "";
   }
+  // Optional-tool allowlists need a best-effort name before full shape validation.
   return typeof tool.name === "string" ? tool.name.trim() : "";
 }
 
@@ -189,6 +190,8 @@ export function resolvePluginTools(params: {
     }
     const nameSet = new Set<string>();
     for (const toolRaw of list) {
+      // Plugin factories run at request time and can return arbitrary values; isolate
+      // malformed tools here so one bad plugin tool cannot poison every provider.
       const malformedReason = describeMalformedPluginTool(toolRaw);
       if (malformedReason) {
         const message = `plugin tool is malformed (${entry.pluginId}): ${malformedReason}`;