@checkstack/ai-backend 0.1.6 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @checkstack/ai-backend
 
+## 0.2.0
+
+### Minor Changes
+
+- 2428bfc: fix(ai): make AI tool names provider-safe (no "." in names)
+
+  LLM providers (and the MCP spec) require tool names to match
+  `^[a-zA-Z0-9_-]+$`, but our tool names are qualified as `<plugin>.<tool>`
+  (e.g. `incident.list`, `dependency.list`). The "." caused the model backend to
+  reject the tool list, so chat tool-calling failed after deploy.
+
+  Tool names are now normalized to a provider-safe form at the single
+  registration chokepoint (the tool registry) and in the projection-routing
+  table: the "." namespace separator is mapped to "\_" (so `incident.list`
+  becomes `incident_list`). The registry key, the name serialized out to the
+  model / MCP client, and the name the model echoes back in a tool call are all
+  the same normalized string, so the round-trip needs no reverse lookup. Any
+  other illegal character is an authoring mistake and is now rejected at
+  registration rather than silently rewritten.
+
+  BREAKING: AI tool names exposed over the MCP `tools/list` endpoint change from
+  the dotted form (`incident.list`) to the underscored form (`incident_list`).
+  MCP clients that referenced tools by their dotted names must update to the
+  underscored names. (Chat was already broken by the provider rejection, so this
+  only changes the working MCP surface.)
+
 ## 0.1.6
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/ai-backend",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -21,7 +21,7 @@
     "@checkstack/common": "0.15.0",
     "@checkstack/drizzle-helper": "0.0.5",
     "@checkstack/integration-backend": "0.4.5",
-    "@checkstack/sdk": "0.101.1",
+    "@checkstack/sdk": "0.102.0",
     "@orpc/client": "^1.14.4",
     "@orpc/contract": "^1.14.4",
     "@orpc/server": "^1.14.4",

package/src/agent-runner.test.ts

@@ -47,14 +47,14 @@ describe("createAgentRunner", () => {
     const registry = createAiToolRegistry();
     const calls: string[] = [];
     registry.register(
-      readTool("plugin.read", async () => {
-        calls.push("plugin.read");
+      readTool("plugin_read", async () => {
+        calls.push("plugin_read");
         return { ok: true };
       }),
     );
     // A destructive tool must NOT be offered.
     registry.register({
-      name: "plugin.delete",
+      name: "plugin_delete",
       description: "delete",
       effect: "destructive",
       input: z.object({}),
@@ -63,7 +63,7 @@ describe("createAgentRunner", () => {
     } as RegisteredAiTool);
     // A projected read (deferred sentinel) must NOT be offered in v1.
     registry.register({
-      name: "plugin.projected",
+      name: "plugin_projected",
       description: "projected",
       effect: "read",
       input: z.object({}),
@@ -77,7 +77,7 @@ describe("createAgentRunner", () => {
     const generateText = mock(async (args: { tools?: Record<string, unknown> }) => {
       offeredToolNames = Object.keys(args.tools ?? {});
       // Simulate the model calling the read tool once.
-      const t = (args.tools ?? {})["plugin.read"] as {
+      const t = (args.tools ?? {})["plugin_read"] as {
         execute: (i: unknown) => Promise<unknown>;
       };
       await t.execute({});
@@ -102,11 +102,11 @@ describe("createAgentRunner", () => {
       outputSchema: z.object({ severity: z.string() }),
     });
 
-    expect(offeredToolNames.sort()).toEqual(["plugin.read"]);
-    expect(calls).toEqual(["plugin.read"]);
+    expect(offeredToolNames.sort()).toEqual(["plugin_read"]);
+    expect(calls).toEqual(["plugin_read"]);
     expect(result.text).toBe("done");
     expect(result.object).toEqual({ severity: "high" });
-    expect(result.toolCalls).toEqual([{ tool: "plugin.read", ok: true }]);
+    expect(result.toolCalls).toEqual([{ tool: "plugin_read", ok: true }]);
   });
 
   it("hands the model a date-safe schema for tools with Date inputs (no throw)", async () => {
@@ -116,7 +116,7 @@ describe("createAgentRunner", () => {
     // chat. The runner must gate date inputs through dateSafeModelSchema too.
     const registry = createAiToolRegistry();
     registry.register({
-      name: "plugin.history",
+      name: "plugin_history",
       description: "history",
       effect: "read",
       input: z.object({ since: z.date() }),
@@ -130,7 +130,7 @@ describe("createAgentRunner", () => {
       async (args: {
         tools?: Record<string, { inputSchema: unknown }>;
       }) => {
-        const t = (args.tools ?? {})["plugin.history"];
+        const t = (args.tools ?? {})["plugin_history"];
         // Exactly what the SDK does internally to build the model request; this
         // threw before the fix.
         offeredSchema = await asSchema(t.inputSchema as never).jsonSchema;
@@ -161,7 +161,7 @@ describe("createAgentRunner", () => {
   it("offers a projected read tool and routes it through the principal's client", async () => {
     const registry = createAiToolRegistry();
     registry.register({
-      name: "incident.list",
+      name: "incident_list",
       description: "list incidents",
       effect: "read",
       input: z.object({}),
@@ -186,7 +186,7 @@ describe("createAgentRunner", () => {
     let offered: string[] = [];
     const generateText = mock(async (args: { tools?: Record<string, unknown> }) => {
       offered = Object.keys(args.tools ?? {});
-      const t = (args.tools ?? {})["incident.list"] as {
+      const t = (args.tools ?? {})["incident_list"] as {
         execute: (i: unknown) => Promise<unknown>;
       };
       await t.execute({ status: "open" });
@@ -197,7 +197,7 @@ describe("createAgentRunner", () => {
       resolver,
       resolveConnection: async () => connection,
       getProjectionRoute: (name) =>
-        name === "incident.list"
+        name === "incident_list"
           ? { pluginId: "incident", procedureKey: "listIncidents" }
           : undefined,
       modelFns: { generateText: generateText as never },
@@ -210,15 +210,15 @@ describe("createAgentRunner", () => {
       prompt: "go",
     });
 
-    expect(offered).toEqual(["incident.list"]);
+    expect(offered).toEqual(["incident_list"]);
     expect(procCalls).toEqual([{ status: "open" }]);
-    expect(result.toolCalls).toEqual([{ tool: "incident.list", ok: true }]);
+    expect(result.toolCalls).toEqual([{ tool: "incident_list", ok: true }]);
   });
 
   it("records a tool failure and surfaces it to the model instead of aborting", async () => {
     const registry = createAiToolRegistry();
     registry.register(
-      readTool("plugin.boom", async () => {
+      readTool("plugin_boom", async () => {
         throw new Error("missing access: plugin.read");
       }),
     );
@@ -226,7 +226,7 @@ describe("createAgentRunner", () => {
 
     let toolResult: unknown;
     const generateText = mock(async (args: { tools?: Record<string, unknown> }) => {
-      const t = (args.tools ?? {})["plugin.boom"] as {
+      const t = (args.tools ?? {})["plugin_boom"] as {
         execute: (i: unknown) => Promise<unknown>;
       };
       toolResult = await t.execute({});
@@ -247,15 +247,15 @@ describe("createAgentRunner", () => {
     });
 
     expect(toolResult).toEqual({ error: "missing access: plugin.read" });
-    expect(result.toolCalls).toEqual([{ tool: "plugin.boom", ok: false }]);
+    expect(result.toolCalls).toEqual([{ tool: "plugin_boom", ok: false }]);
     expect(result.object).toBeUndefined();
   });
 
   it("calls recordToolCall for each invocation (ok and failure)", async () => {
     const registry = createAiToolRegistry();
-    registry.register(readTool("plugin.ok", async () => ({ ok: true })));
+    registry.register(readTool("plugin_ok", async () => ({ ok: true })));
     registry.register(
-      readTool("plugin.boom", async () => {
+      readTool("plugin_boom", async () => {
         throw new Error("nope");
       }),
     );
@@ -273,8 +273,8 @@ describe("createAgentRunner", () => {
 
     const generateText = mock(async (args: { tools?: Record<string, unknown> }) => {
       const tools = args.tools ?? {};
-      await (tools["plugin.ok"] as { execute: (i: unknown) => Promise<unknown> }).execute({});
-      await (tools["plugin.boom"] as { execute: (i: unknown) => Promise<unknown> }).execute({});
+      await (tools["plugin_ok"] as { execute: (i: unknown) => Promise<unknown> }).execute({});
+      await (tools["plugin_boom"] as { execute: (i: unknown) => Promise<unknown> }).execute({});
       return { text: "x", usage: {} };
     });
 
@@ -287,12 +287,12 @@ describe("createAgentRunner", () => {
     await runner({ principal, rpcClient, connectionId: "c", prompt: "go" });
 
     expect(recorded).toContainEqual({
-      toolName: "plugin.ok",
+      toolName: "plugin_ok",
       ok: true,
       effect: "read",
     });
     expect(recorded).toContainEqual({
-      toolName: "plugin.boom",
+      toolName: "plugin_boom",
       ok: false,
       effect: "read",
     });

package/src/chat/agent-loop.test.ts

@@ -28,9 +28,9 @@ function tool(
 
 function setup() {
   const registry = createAiToolRegistry();
-  const read = tool("incident.list", "read", "incident.incident.read");
-  const mutate = tool("automation.propose", "mutate", "automation.automation.manage");
-  const destroy = tool("incident.delete", "destructive", "incident.incident.manage");
+  const read = tool("incident_list", "read", "incident.incident.read");
+  const mutate = tool("automation_propose", "mutate", "automation.automation.manage");
+  const destroy = tool("incident_delete", "destructive", "incident.incident.manage");
   registry.register(read);
   registry.register(mutate);
   registry.register(destroy);
@@ -57,15 +57,15 @@ describe("agent loop tool gating (matrix #14)", () => {
   test("the loop only offers resolver-allowed tools", () => {
     const { resolver } = setup();
     const offered = offeredTools({ principal: limited, resolver }).map((t) => t.name);
-    expect(offered).toEqual(["incident.list"]);
-    expect(offered).not.toContain("automation.propose");
-    expect(offered).not.toContain("incident.delete");
+    expect(offered).toEqual(["incident_list"]);
+    expect(offered).not.toContain("automation_propose");
+    expect(offered).not.toContain("incident_delete");
   });
 
   test("a model-requested tool OUTSIDE the principal's set is refused server-side", () => {
     const { resolver, registry } = setup();
     const d = disposeAgentTool({
-      toolName: "automation.propose",
+      toolName: "automation_propose",
       principal: limited,
       resolver,
       getTool: (n) => registry.getTool(n),
@@ -87,7 +87,7 @@ describe("agent loop tool gating (matrix #14)", () => {
   test("a read tool auto-runs", () => {
     const { resolver, registry } = setup();
     const d = disposeAgentTool({
-      toolName: "incident.list",
+      toolName: "incident_list",
       principal: limited,
       resolver,
       getTool: (n) => registry.getTool(n),
@@ -98,7 +98,7 @@ describe("agent loop tool gating (matrix #14)", () => {
   test("a mutate tool requires a confirm card (never silently mutates)", () => {
     const { resolver, registry } = setup();
     const d = disposeAgentTool({
-      toolName: "automation.propose",
+      toolName: "automation_propose",
       principal: power,
       resolver,
       getTool: (n) => registry.getTool(n),
@@ -109,7 +109,7 @@ describe("agent loop tool gating (matrix #14)", () => {
   test("a destructive tool requires a confirm card", () => {
     const { resolver, registry } = setup();
     const d = disposeAgentTool({
-      toolName: "incident.delete",
+      toolName: "incident_delete",
       principal: power,
       resolver,
       getTool: (n) => registry.getTool(n),

package/src/chat/auto-apply.test.ts

@@ -129,7 +129,7 @@ function mutatingTool(): {
     created: input.value,
   }));
   const tool: RegisteredAiTool<{ value: string }, { created: string }> = {
-    name: "demo.mutate",
+    name: "demo_mutate",
     description: "demo mutating tool",
     effect: "mutate",
     input: ManageInput,
@@ -208,7 +208,7 @@ describe("AUTO-mode mutate auto-apply path", () => {
     // proposed -> applied, with the applier stamped. Not a weaker/parallel path.
     const applied = [...store.rows.values()].filter((r) => r.status === "applied");
     expect(applied).toHaveLength(1);
-    expect(applied[0]?.toolName).toBe("demo.mutate");
+    expect(applied[0]?.toolName).toBe("demo_mutate");
     expect(applied[0]?.effect).toBe("mutate");
     expect(applied[0]?.appliedById).toBe("u1");
     expect(applied[0]?.id).toBe(result.toolCallId);

package/src/hardening/handler-authz.test.ts

@@ -154,7 +154,7 @@ describe("HARDENING: a misbehaving model cannot escape the resolver gate", () =>
   test("isAllowed refuses a tool whose rule the principal lacks", () => {
     const registry = createAiToolRegistry();
     let ran = false;
-    const adminTool = readTool("ai.secrets", "ai.tools.manage", () => {
+    const adminTool = readTool("ai_secrets", "ai.tools.manage", () => {
       ran = true;
     });
     registry.register(adminTool);
@@ -168,7 +168,7 @@ describe("HARDENING: a misbehaving model cannot escape the resolver gate", () =>
 
   test("a service principal (no access rules) is refused every tool", () => {
     const registry = createAiToolRegistry();
-    const tool = readTool("incident.list", "incident.incident.read", () => {});
+    const tool = readTool("incident_list", "incident.incident.read", () => {});
     registry.register(tool);
     const resolver = createAiToolResolver({ registry });
     const service: AuthUser = { type: "service", pluginId: "svc" };
@@ -181,7 +181,7 @@ describe("HARDENING: propose refuses a model-picked out-of-scope tool BEFORE dry
     const registry = createAiToolRegistry();
     let dryRan = false;
     let executed = false;
-    const tool = mutateTool("billing.refund", "billing.billing.manage", {
+    const tool = mutateTool("billing_refund", "billing.billing.manage", {
       onDryRun: () => {
         dryRan = true;
       },
@@ -200,7 +200,7 @@ describe("HARDENING: propose refuses a model-picked out-of-scope tool BEFORE dry
     await expect(
       service.propose({
         principal: limited, // lacks billing.billing.manage
-        toolName: "billing.refund",
+        toolName: "billing_refund",
         input: { amount: 100 },
         transport: "chat",
         rpcClient,
@@ -217,7 +217,7 @@ describe("HARDENING: bad model-supplied args are rejected (no execution on garba
   test("propose rejects args that fail the tool's own zod schema", async () => {
     const registry = createAiToolRegistry();
     let dryRan = false;
-    const tool = mutateTool("incident.escalate", "incident.incident.read", {
+    const tool = mutateTool("incident_escalate", "incident.incident.read", {
       onDryRun: () => {
         dryRan = true;
       },
@@ -237,7 +237,7 @@ describe("HARDENING: bad model-supplied args are rejected (no execution on garba
     await expect(
       service.propose({
         principal: limited,
-        toolName: "incident.escalate",
+        toolName: "incident_escalate",
         input: { amount: -5 },
         transport: "chat",
         rpcClient,
@@ -253,9 +253,9 @@ describe("HARDENING: scope-narrowing can never WIDEN the surfaced toolset", () =
   // only ever shrink the visible tools — never add one the principal lacks.
   test("narrowing the principal's rules monotonically shrinks the visible tools", () => {
     const registry = createAiToolRegistry();
-    registry.register(readTool("incident.list", "incident.incident.read", () => {}));
-    registry.register(readTool("hc.status", "healthcheck.config.read", () => {}));
-    registry.register(readTool("ai.secrets", "ai.tools.manage", () => {}));
+    registry.register(readTool("incident_list", "incident.incident.read", () => {}));
+    registry.register(readTool("hc_status", "healthcheck.config.read", () => {}));
+    registry.register(readTool("ai_secrets", "ai.tools.manage", () => {}));
     const resolver = createAiToolResolver({ registry });
 
     const wide: AuthUser = {
@@ -274,8 +274,8 @@ describe("HARDENING: scope-narrowing can never WIDEN the surfaced toolset", () =
 
     // Narrowed is a strict subset — never a superset.
     for (const name of narrowNames) expect(wideNames.has(name)).toBe(true);
-    expect(narrowNames.has("hc.status")).toBe(false);
-    expect(narrowNames.has("ai.secrets")).toBe(false);
+    expect(narrowNames.has("hc_status")).toBe(false);
+    expect(narrowNames.has("ai_secrets")).toBe(false);
     // And the narrowing never invented a tool outside the wide set.
     expect([...narrowNames].every((n) => wideNames.has(n))).toBe(true);
   });

package/src/mcp/server.test.ts

@@ -47,12 +47,12 @@ function buildHandler({
   }) => Promise<void>;
 }) {
   const registry = createAiToolRegistry();
-  const incidentTool = readTool("incident.list", "incident.incident.read");
-  const adminTool = readTool("ai.secrets", "ai.tools.manage");
+  const incidentTool = readTool("incident_list", "incident.incident.read");
+  const adminTool = readTool("ai_secrets", "ai.tools.manage");
   // A mutating tool the limited principal IS allowed for (same access rule as
   // incident.list). The ONLY thing that may refuse a bare tools/call for it is
   // the structural effect-gate, not the resolver.
-  const mutating = mutateTool("incident.close", "incident.incident.read");
+  const mutating = mutateTool("incident_close", "incident.incident.read");
   registry.register(incidentTool);
   registry.register(adminTool);
   registry.register(mutating);
@@ -121,8 +121,8 @@ describe("MCP server (read-only Streamable-HTTP)", () => {
     );
     const json = await res.json();
     const names = json.result.tools.map((t: { name: string }) => t.name);
-    expect(names).toEqual(["incident.list"]);
-    expect(names).not.toContain("ai.secrets");
+    expect(names).toEqual(["incident_list"]);
+    expect(names).not.toContain("ai_secrets");
   });
 
   test("tools/list returns 401 for an unauthenticated caller", async () => {
@@ -150,7 +150,7 @@ describe("MCP server (read-only Streamable-HTTP)", () => {
         jsonrpc: "2.0",
         id: 4,
         method: "tools/call",
-        params: { name: "ai.secrets", arguments: {} },
+        params: { name: "ai_secrets", arguments: {} },
       }),
     );
     expect(res.status).toBe(403);
@@ -175,7 +175,7 @@ describe("MCP server (read-only Streamable-HTTP)", () => {
           jsonrpc: "2.0",
           id: 5,
           method: "tools/call",
-          params: { name: "incident.list", arguments: { status: "open" } },
+          params: { name: "incident_list", arguments: { status: "open" } },
         },
         "tok-123",
       ),
@@ -205,7 +205,7 @@ describe("MCP server (read-only Streamable-HTTP)", () => {
         jsonrpc: "2.0",
         id: 7,
         method: "tools/call",
-        params: { name: "incident.close", arguments: {} },
+        params: { name: "incident_close", arguments: {} },
       }),
     );
     expect(res.status).toBe(403);
@@ -221,8 +221,8 @@ describe("MCP server (read-only Streamable-HTTP)", () => {
     );
     const json = await res.json();
     const names = json.result.tools.map((t: { name: string }) => t.name);
-    expect(names).toContain("incident.list");
-    expect(names).not.toContain("incident.close");
+    expect(names).toContain("incident_list");
+    expect(names).not.toContain("incident_close");
   });
 
   // §14.5: per-principal tool budget enforced on tools/call (shared-Postgres).
@@ -241,7 +241,7 @@ describe("MCP server (read-only Streamable-HTTP)", () => {
         jsonrpc: "2.0",
         id: 9,
         method: "tools/call",
-        params: { name: "incident.list", arguments: {} },
+        params: { name: "incident_list", arguments: {} },
       }),
     );
     expect(res.status).toBe(429);
@@ -264,12 +264,12 @@ describe("MCP server (read-only Streamable-HTTP)", () => {
         jsonrpc: "2.0",
         id: 10,
         method: "tools/call",
-        params: { name: "incident.list", arguments: { status: "open" } },
+        params: { name: "incident_list", arguments: { status: "open" } },
       }),
     );
     expect(res.status).toBe(200);
     expect(recorded).toHaveLength(1);
-    expect(recorded[0]?.toolName).toBe("incident.list");
+    expect(recorded[0]?.toolName).toBe("incident_list");
     // The args hash is a SHA-256 hex digest, never the raw args.
     expect(recorded[0]?.argsHash).toMatch(/^[0-9a-f]{64}$/);
   });

package/src/propose-apply/service.test.ts

@@ -135,7 +135,7 @@ function mutatingTool(
 ): RegisteredAiTool<{ value: string }, { created: string }> {
   let executed = 0;
   const tool: RegisteredAiTool<{ value: string }, { created: string }> = {
-    name: "demo.mutate",
+    name: "demo_mutate",
     description: "demo mutating tool",
     effect: "mutate",
     input: ManageInput,
@@ -200,7 +200,7 @@ describe("propose/apply lifecycle (matrix #11)", () => {
 
     const proposal = await service.propose({
       principal: allowed,
-      toolName: "demo.mutate",
+      toolName: "demo_mutate",
       input: { value: "alpha" },
       transport: "chat",
     });
@@ -222,7 +222,7 @@ describe("propose/apply lifecycle (matrix #11)", () => {
 
     const proposal = await service.propose({
       principal: allowed,
-      toolName: "demo.mutate",
+      toolName: "demo_mutate",
       input: { value: "beta" },
       transport: "chat",
     });
@@ -239,7 +239,7 @@ describe("propose/apply lifecycle (matrix #11)", () => {
     const { service } = setup(tool);
     const proposal = await service.propose({
       principal: allowed,
-      toolName: "demo.mutate",
+      toolName: "demo_mutate",
       input: { value: "gamma" },
       transport: "chat",
     });
@@ -265,7 +265,7 @@ describe("propose/apply authorization (matrix #11 / decision 5)", () => {
     await expect(
       service.propose({
         principal: notAllowed,
-        toolName: "demo.mutate",
+        toolName: "demo_mutate",
         input: { value: "x" },
         transport: "chat",
       }),
@@ -277,7 +277,7 @@ describe("propose/apply authorization (matrix #11 / decision 5)", () => {
     const { service } = setup(tool);
     const proposal = await service.propose({
       principal: allowed,
-      toolName: "demo.mutate",
+      toolName: "demo_mutate",
       input: { value: "x" },
       transport: "chat",
     });
@@ -294,7 +294,7 @@ describe("propose/apply authorization (matrix #11 / decision 5)", () => {
     await expect(
       service.propose({
         principal: allowed,
-        toolName: "demo.mutate",
+        toolName: "demo_mutate",
         input: { value: "x" },
         transport: "chat",
       }),
@@ -306,7 +306,7 @@ describe("propose/apply authorization (matrix #11 / decision 5)", () => {
     await expect(
       service.propose({
         principal: { type: "service", pluginId: "x" },
-        toolName: "demo.mutate",
+        toolName: "demo_mutate",
         input: { value: "x" },
         transport: "chat",
       }),
@@ -320,7 +320,7 @@ describe("propose does NOT mutate (matrix #12)", () => {
     const { service } = setup(tool);
     await service.propose({
       principal: allowed,
-      toolName: "demo.mutate",
+      toolName: "demo_mutate",
       input: { value: "x" },
       transport: "chat",
     });
@@ -334,7 +334,7 @@ describe("audit rows (matrix #13)", () => {
     const { service, store } = setup(tool);
     const proposal = await service.propose({
       principal: allowed,
-      toolName: "demo.mutate",
+      toolName: "demo_mutate",
       input: { value: "x" },
       transport: "chat",
     });
@@ -358,7 +358,7 @@ describe("audit rows (matrix #13)", () => {
     // Proposed by u1.
     const proposal = await service.propose({
       principal: allowed,
-      toolName: "demo.mutate",
+      toolName: "demo_mutate",
       input: { value: "x" },
       transport: "chat",
     });
@@ -386,7 +386,7 @@ describe("audit rows (matrix #13)", () => {
     const { service, store } = setup(tool);
     const proposal = await service.propose({
       principal: allowed,
-      toolName: "demo.mutate",
+      toolName: "demo_mutate",
       input: { value: "x" },
       transport: "chat",
     });
@@ -411,7 +411,7 @@ describe("audit rows (matrix #13)", () => {
     const { service, store } = setup(tool, () => current);
     const proposal = await service.propose({
       principal: allowed,
-      toolName: "demo.mutate",
+      toolName: "demo_mutate",
       input: { value: "x" },
       transport: "chat",
     });

package/src/registry-wiring.test.ts

@@ -30,7 +30,7 @@ function handAuthoredTool(): RegisteredAiTool {
 }
 
 describe("createRegistryExtensionPoints (end-to-end registration)", () => {
-  test("registerTool qualifies an unqualified name with the plugin id", () => {
+  test("registerTool qualifies an unqualified name, registered provider-safe", () => {
     const registry = createAiToolRegistry();
     const { toolExtensionPoint } = createRegistryExtensionPoints({ registry });
 
@@ -39,11 +39,15 @@ describe("createRegistryExtensionPoints (end-to-end registration)", () => {
       definePluginMetadata({ pluginId: "automation" }),
     );
 
-    expect(registry.hasTool("automation.propose")).toBe(true);
-    expect(registry.getTool("automation.propose")?.effect).toBe("mutate");
+    // Qualified to `automation.propose`, then normalized to the provider-safe
+    // name set (the "." the provider rejects becomes "_").
+    expect(registry.hasTool("automation_propose")).toBe(true);
+    expect(registry.getTool("automation_propose")?.effect).toBe("mutate");
+    // The dotted form is NOT a key (the provider would never send it).
+    expect(registry.hasTool("automation.propose")).toBe(false);
   });
 
-  test("registerTool leaves an already-qualified name unchanged", () => {
+  test("registerTool leaves an already-qualified name unchanged (modulo sanitization)", () => {
     const registry = createAiToolRegistry();
     const { toolExtensionPoint } = createRegistryExtensionPoints({ registry });
 
@@ -52,8 +56,10 @@ describe("createRegistryExtensionPoints (end-to-end registration)", () => {
       definePluginMetadata({ pluginId: "different" }),
     );
 
-    expect(registry.hasTool("automation.propose")).toBe(true);
-    expect(registry.hasTool("different.automation.propose")).toBe(false);
+    // Already qualified, so it is not re-prefixed with "different"; only "."
+    // is sanitized to "_".
+    expect(registry.hasTool("automation_propose")).toBe(true);
+    expect(registry.hasTool("different_automation_propose")).toBe(false);
   });
 
   test("expose builds and registers a projected tool from a contract procedure", () => {
@@ -72,7 +78,8 @@ describe("createRegistryExtensionPoints (end-to-end registration)", () => {
       execute: () => Promise.resolve({}),
     });
 
-    const tool = registry.getTool("incident.list");
+    // The authored name "incident.list" is normalized to the provider-safe key.
+    const tool = registry.getTool("incident_list");
     expect(tool).toBeDefined();
     // Access rules read verbatim from the source procedure, qualified.
     expect(tool?.requiredAccessRules).toEqual(["incident.incident.read"]);
@@ -98,9 +105,10 @@ describe("createRegistryExtensionPoints (end-to-end registration)", () => {
       execute: () => Promise.resolve({}),
     });
 
+    // Registry keys/names are the provider-safe form of each authored name.
     expect(registry.getTools().map((t) => t.name).sort()).toEqual([
-      "automation.propose",
-      "incident.list",
+      "automation_propose",
+      "incident_list",
     ]);
   });
 

package/src/registry-wiring.ts

@@ -4,6 +4,7 @@ import type {
   AiToolProjectionExtensionPoint,
 } from "./extension-points";
 import { buildProjectedTool } from "./projection";
+import { toProviderToolName } from "./tool-name";
 import type { AiToolRegistry } from "./tool-registry";
 
 /**
@@ -57,7 +58,10 @@ export function createRegistryExtensionPoints({
       const tool = buildProjectedTool(input);
       registry.register(tool);
       exposedProjections.push({
-        toolName: tool.name,
+        // Match the registry's canonical (provider-safe) key so the chat
+        // read-loop and MCP transport resolve this route by the same name the
+        // model is given and echoes back.
+        toolName: toProviderToolName(tool.name),
         pluginId: input.sourcePluginMetadata.pluginId,
         procedureKey: input.procedureKey,
       });

package/src/resolver.test.ts

@@ -26,24 +26,24 @@ describe("createAiToolResolver.resolveTools", () => {
   test("a principal lacking automation.manage never sees automation.propose", () => {
     const registry = createAiToolRegistry();
     registry.register(
-      tool("automation.propose", ["automation.automation.manage"]),
+      tool("automation_propose", ["automation.automation.manage"]),
     );
-    registry.register(tool("incident.list", ["incident.incident.read"]));
+    registry.register(tool("incident_list", ["incident.incident.read"]));
     const resolver = createAiToolResolver({ registry });
 
     const principal = userWith(["incident.incident.read"]);
     const names = resolver.resolveTools(principal).map((t) => t.name);
 
-    expect(names).toEqual(["incident.list"]);
-    expect(names).not.toContain("automation.propose");
+    expect(names).toEqual(["incident_list"]);
+    expect(names).not.toContain("automation_propose");
   });
 
   test("an admin (accessRules ['*']) sees all tools", () => {
     const registry = createAiToolRegistry();
     registry.register(
-      tool("automation.propose", ["automation.automation.manage"]),
+      tool("automation_propose", ["automation.automation.manage"]),
     );
-    registry.register(tool("incident.list", ["incident.incident.read"]));
+    registry.register(tool("incident_list", ["incident.incident.read"]));
     const resolver = createAiToolResolver({ registry });
 
     const names = resolver
@@ -51,12 +51,12 @@ describe("createAiToolResolver.resolveTools", () => {
       .map((t) => t.name)
       .sort();
 
-    expect(names).toEqual(["automation.propose", "incident.list"]);
+    expect(names).toEqual(["automation_propose", "incident_list"]);
   });
 
   test("a service principal (no access rules) sees no tools", () => {
     const registry = createAiToolRegistry();
-    registry.register(tool("incident.list", ["incident.incident.read"]));
+    registry.register(tool("incident_list", ["incident.incident.read"]));
     const resolver = createAiToolResolver({ registry });
 
     const service: AuthUser = { type: "service", pluginId: "automation" };

package/src/tool-name.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { PROVIDER_TOOL_NAME_PATTERN, toProviderToolName } from "./tool-name";
+
+describe("toProviderToolName", () => {
+  test("maps the '.' namespace separator to '_'", () => {
+    expect(toProviderToolName("incident.list")).toBe("incident_list");
+    expect(toProviderToolName("catalog.listSystems")).toBe(
+      "catalog_listSystems",
+    );
+    expect(toProviderToolName("dependency.list")).toBe("dependency_list");
+  });
+
+  test("maps every '.' in a multi-dot name", () => {
+    expect(toProviderToolName("a.b.c")).toBe("a_b_c");
+  });
+
+  test("leaves an already provider-safe name unchanged", () => {
+    expect(toProviderToolName("incident_list")).toBe("incident_list");
+    expect(toProviderToolName("get-status")).toBe("get-status");
+    expect(toProviderToolName("Tool_123")).toBe("Tool_123");
+  });
+
+  test("the result always matches the provider pattern", () => {
+    for (const name of ["incident.list", "a.b.c", "get-status", "x"]) {
+      expect(PROVIDER_TOOL_NAME_PATTERN.test(toProviderToolName(name))).toBe(
+        true,
+      );
+    }
+  });
+
+  test("throws on an illegal character rather than silently rewriting it", () => {
+    expect(() => toProviderToolName("foo$bar")).toThrow(/Invalid AI tool name/);
+    expect(() => toProviderToolName("with space")).toThrow(
+      /Invalid AI tool name/,
+    );
+    expect(() => toProviderToolName("emoji😀")).toThrow(/Invalid AI tool name/);
+  });
+
+  test("throws on an empty name", () => {
+    expect(() => toProviderToolName("")).toThrow(/Invalid AI tool name/);
+  });
+});

package/src/tool-name.ts

@@ -0,0 +1,37 @@
+/**
+ * Provider tool-name constraint.
+ *
+ * LLM providers (and the MCP spec) require tool names to match
+ * `^[a-zA-Z0-9_-]+$`.
+ */
+export const PROVIDER_TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+
+/**
+ * Convert a canonical tool name to its provider-safe form.
+ *
+ * Tool names are qualified as `<plugin>.<tool>` - the "." is the namespace
+ * separator of the naming convention, which the provider rejects. It is mapped
+ * deterministically to "_" (so `incident.list` -> `incident_list`).
+ *
+ * Any OTHER disallowed character is an authoring mistake in the tool
+ * definition, not stray input, so it is NOT silently rewritten: this throws so
+ * the bad name surfaces at registration (startup) instead of being masked.
+ *
+ * The mapping is applied at the single registration chokepoint (the tool
+ * registry) and the projection-routing table, so the registry key, the name
+ * sent to the model / MCP client, and the name the model echoes back in a tool
+ * call are all identical - the round-trip (name-out === name-in) holds without
+ * any reverse lookup.
+ */
+export function toProviderToolName(name: string): string {
+  const normalized = name.replaceAll(".", "_");
+  if (!PROVIDER_TOOL_NAME_PATTERN.test(normalized)) {
+    throw new Error(
+      `Invalid AI tool name "${name}": after normalizing the "." separator to ` +
+        `"_" it must match ${String(PROVIDER_TOOL_NAME_PATTERN)} (letters, ` +
+        `digits, "_" and "-" only). Rename the tool to use only those ` +
+        `characters, with "." reserved for the <plugin>.<tool> separator.`,
+    );
+  }
+  return normalized;
+}

package/src/tool-registry.ts

@@ -1,5 +1,6 @@
 import type { AuthUser, RpcClient } from "@checkstack/backend-api";
 import type { AiTool } from "@checkstack/ai-common";
+import { toProviderToolName } from "./tool-name";
 
 /**
  * A tool whose executors run with a Checkstack {@link AuthUser} principal and
@@ -21,7 +22,12 @@ export type RegisteredAiTool<TInput = unknown, TOutput = unknown> = AiTool<
  * registry, so no capability is implemented twice.
  *
  * Tool names are already fully qualified (`<plugin>.<tool>`) by the extension
- * points before they reach `register`.
+ * points before they reach `register`. `register` then maps the name to its
+ * provider-safe form (see {@link toProviderToolName}) and uses that as the
+ * canonical key, so every consumer (serializer, chat SDK tools, MCP
+ * `tools/list`, and the tool-call resolution path) sees and resolves the same
+ * provider-safe name. A name with an illegal character (beyond the "."
+ * separator) is rejected here rather than rewritten.
  */
 export interface AiToolRegistry {
   register(tool: RegisteredAiTool): void;
@@ -35,12 +41,16 @@ export function createAiToolRegistry(): AiToolRegistry {
 
   return {
     register(tool: RegisteredAiTool): void {
-      if (tools.has(tool.name)) {
+      // Map to the provider-safe name (e.g. `incident.list` -> `incident_list`)
+      // and key the registry on it, so the name sent to the model and the name
+      // it echoes back both match this entry. Throws on an illegal name.
+      const name = toProviderToolName(tool.name);
+      if (tools.has(name)) {
         throw new Error(
-          `AI tool ${tool.name} already registered — likely a duplicate registration.`,
+          `AI tool ${name} already registered — likely a duplicate registration.`,
         );
       }
-      tools.set(tool.name, tool);
+      tools.set(name, name === tool.name ? tool : { ...tool, name });
     },
 
     getTools(): RegisteredAiTool[] {

package/src/tools/docs-tools.test.ts

@@ -120,7 +120,7 @@ describe("docs tools registration + resolution", () => {
       .resolveTools(userWith(["ai.chat.read"]))
       .map((t) => t.name)
       .sort();
-    expect(names).toEqual(["ai.getDoc", "ai.searchDocs"]);
+    expect(names).toEqual(["ai_getDoc", "ai_searchDocs"]);
   });
 
   test("a principal without ai.chat.read sees neither docs tool", () => {

package/src/tools/tool-set.e2e.test.ts

@@ -38,7 +38,7 @@ describe("ai-backend's own platform tool set", () => {
   test("docs + probe tools are registered and qualified", () => {
     const registry = buildOwnRegistry();
     const names = registry.getTools().map((t) => t.name);
-    for (const expected of ["ai.searchDocs", "ai.getDoc", "ai.probeUrl"]) {
+    for (const expected of ["ai_searchDocs", "ai_getDoc", "ai_probeUrl"]) {
       expect(names).toContain(expected);
     }
   });