docs: recommend tools.alsoAllow for optional plugin tools

src/agents/pi-tools.ts

@@ -346,7 +346,7 @@ export function createClawdbotCodingTools(options?: {
     if (resolved.unknownAllowlist.length > 0) {
       const entries = resolved.unknownAllowlist.join(", ");
       const suffix = resolved.strippedAllowlist
-        ? "Ignoring allowlist so core tools remain available."
+        ? "Ignoring allowlist so core tools remain available. Use tools.alsoAllow for additive plugin tool enablement."
         : "These entries won't match any tool unless the plugin is enabled.";
       logWarn(`tools: ${label} allowlist contains unknown entries (${entries}). ${suffix}`);
     }

src/agents/tool-policy.ts

@@ -209,6 +209,12 @@ export function stripPluginOnlyAllowlist(
     if (!isCoreEntry && !isPluginEntry) unknownAllowlist.push(entry);
   }
   const strippedAllowlist = !hasCoreEntry;
+  // When an allowlist contains only plugin tools, we strip it to avoid accidentally
+  // disabling core tools. Users who want additive behavior should prefer `tools.alsoAllow`.
+  if (strippedAllowlist) {
+    // Note: logging happens in the caller (pi-tools/tools-invoke) after this function returns.
+    // We keep this note here for future maintainers.
+  }
   return {
     policy: strippedAllowlist ? { ...policy, allow: undefined } : policy,
     unknownAllowlist: Array.from(new Set(unknownAllowlist)),

src/gateway/tools-invoke-http.ts

@@ -189,7 +189,7 @@ export async function handleToolsInvokeHttpRequest(
     if (resolved.unknownAllowlist.length > 0) {
       const entries = resolved.unknownAllowlist.join(", ");
       const suffix = resolved.strippedAllowlist
-        ? "Ignoring allowlist so core tools remain available."
+        ? "Ignoring allowlist so core tools remain available. Use tools.alsoAllow for additive plugin tool enablement."
         : "These entries won't match any tool unless the plugin is enabled.";
       logWarn(`tools: ${label} allowlist contains unknown entries (${entries}). ${suffix}`);
     }