fix: enforce role tool whitelist

hub/src/agent/models.ts

@@ -17,10 +17,11 @@
  *
  * A role bundles everything that distinguishes one agent persona from another:
  * model, system prompt, and the tool surface (files / cph / feishu / skills /
- * mcps). Per-run tool whitelisting is enforced by {@link ToolRegistry.subset};
- * the model never sees tools outside its role's whitelist, even if it tries to
- * call them — security does not rely on the system prompt.
+ * mcps). Per-run tool whitelisting is enforced by the Claude SDK runner and
+ * the cph_hub MCP server builder; security does not rely on the system prompt.
  */
+import { assertSupportedRoleTools } from "./roleTools.js";
+
 export interface RoleEntry {
   readonly id: string;
   /** Human label for the teacher-side switcher UX. */
@@ -36,7 +37,7 @@ export interface RoleEntry {
   /**
    * Tool names this role may use (whitelist). `undefined` ⇒ the full registered
    * set (back-compat / unrestricted roles). An empty array ⇒ no tools at all.
-   * Names not present in the registry are silently dropped at run setup.
+   * Invalid names fail fast when settings are loaded or the run is set up.
    */
   readonly tools?: readonly string[] | undefined;
 }
@@ -72,6 +73,9 @@ export class InMemoryModelRegistry implements ModelRegistry {
 
   constructor(models: readonly ModelEntry[], roles: readonly RoleEntry[] = []) {
     this.models = models;
+    for (const role of roles) {
+      if (role.tools !== undefined) assertSupportedRoleTools(role.tools);
+    }
     this.roles = new Map(roles.map((r) => [r.id, r]));
   }
 

hub/src/agent/roleTools.ts

@@ -0,0 +1,110 @@
+export const DEFAULT_CLAUDE_BUILT_IN_TOOLS = ["Read", "Write", "Bash", "Glob", "Grep"] as const;
+
+export const CPH_HUB_MCP_SERVER_NAME = "cph_hub";
+export const CPH_HUB_MCP_TOOL_IDS = ["send_file", "feishu_read_context", "request_approval"] as const;
+
+export type CphHubMcpToolId = (typeof CPH_HUB_MCP_TOOL_IDS)[number];
+
+export interface ClaudeSdkToolConfig {
+  readonly tools: readonly string[];
+  readonly allowedTools: readonly string[];
+}
+
+const ROLE_TOOL_TO_CLAUDE_BUILT_INS = new Map<string, readonly string[]>([
+  ["read_file", ["Read"]],
+  ["write_file", ["Write"]],
+  ["list_files", ["Glob"]],
+  ["search_files", ["Grep"]],
+  ["bash", ["Bash"]],
+  // ADR-0017 replaced cph custom tools with Bash commands. Granting either
+  // cph role tool therefore exposes the SDK Bash tool; cph-only Bash narrowing
+  // would need a separate command-policy layer.
+  ["cph_check", ["Bash"]],
+  ["cph_build", ["Bash"]],
+  ["Read", ["Read"]],
+  ["Write", ["Write"]],
+  ["Bash", ["Bash"]],
+  ["Glob", ["Glob"]],
+  ["Grep", ["Grep"]],
+]);
+
+const ROLE_TOOL_TO_CPH_HUB_MCP_TOOL = new Map<string, CphHubMcpToolId>([
+  ["send_file", "send_file"],
+  ["feishu_read_context", "feishu_read_context"],
+  ["request_approval", "request_approval"],
+  ["mcp__cph_hub__send_file", "send_file"],
+  ["mcp__cph_hub__feishu_read_context", "feishu_read_context"],
+  ["mcp__cph_hub__request_approval", "request_approval"],
+]);
+
+const SUPPORTED_ROLE_TOOLS = new Set([
+  ...ROLE_TOOL_TO_CLAUDE_BUILT_INS.keys(),
+  ...ROLE_TOOL_TO_CPH_HUB_MCP_TOOL.keys(),
+]);
+
+export function claudeSdkToolConfigForRole(roleTools: readonly string[] | undefined): ClaudeSdkToolConfig {
+  if (roleTools === undefined) {
+    const mcpTools = CPH_HUB_MCP_TOOL_IDS.map(claudeMcpToolName);
+    return {
+      tools: [...DEFAULT_CLAUDE_BUILT_IN_TOOLS],
+      allowedTools: [...DEFAULT_CLAUDE_BUILT_IN_TOOLS, ...mcpTools],
+    };
+  }
+
+  const builtIns: string[] = [];
+  const allowedTools: string[] = [];
+  for (const roleTool of roleTools) {
+    assertSupportedRoleTool(roleTool);
+    for (const tool of ROLE_TOOL_TO_CLAUDE_BUILT_INS.get(roleTool) ?? []) {
+      pushUnique(builtIns, tool);
+      pushUnique(allowedTools, tool);
+    }
+
+    const mcpTool = ROLE_TOOL_TO_CPH_HUB_MCP_TOOL.get(roleTool);
+    if (mcpTool !== undefined) {
+      pushUnique(allowedTools, claudeMcpToolName(mcpTool));
+    }
+  }
+
+  return { tools: builtIns, allowedTools };
+}
+
+export function cphHubMcpToolsForRole(roleTools: readonly string[] | undefined): readonly CphHubMcpToolId[] {
+  if (roleTools === undefined) return [...CPH_HUB_MCP_TOOL_IDS];
+
+  const tools: CphHubMcpToolId[] = [];
+  for (const roleTool of roleTools) {
+    assertSupportedRoleTool(roleTool);
+    const mcpTool = ROLE_TOOL_TO_CPH_HUB_MCP_TOOL.get(roleTool);
+    if (mcpTool !== undefined) pushUnique(tools, mcpTool);
+  }
+  return tools;
+}
+
+export function roleToolsAllow(roleTools: readonly string[] | undefined, roleTool: string): boolean {
+  if (roleTools === undefined) return true;
+  for (const configured of roleTools) {
+    assertSupportedRoleTool(configured);
+    if (configured === roleTool) return true;
+    if (ROLE_TOOL_TO_CPH_HUB_MCP_TOOL.get(configured) === roleTool) return true;
+  }
+  return false;
+}
+
+export function assertSupportedRoleTools(roleTools: readonly string[]): void {
+  for (const roleTool of roleTools) assertSupportedRoleTool(roleTool);
+}
+
+function claudeMcpToolName(tool: CphHubMcpToolId): string {
+  return `mcp__${CPH_HUB_MCP_SERVER_NAME}__${tool}`;
+}
+
+function assertSupportedRoleTool(roleTool: string): void {
+  if (!SUPPORTED_ROLE_TOOLS.has(roleTool)) {
+    throw new Error(`unknown role tool id: ${roleTool}`);
+  }
+}
+
+function pushUnique<T>(items: T[], item: T): void {
+  if (!items.includes(item)) items.push(item);
+}

hub/src/agent/runner.ts

@@ -30,6 +30,7 @@
 import { homedir } from "node:os";
 import { query, type McpServerConfig, type SDKMessage, type SDKAssistantMessage, type SDKUserMessage, type SDKResultMessage, type SDKPartialAssistantMessage } from "@anthropic-ai/claude-agent-sdk";
 import type { PrismaClient } from "@prisma/client";
+import { claudeSdkToolConfigForRole } from "./roleTools.js";
 
 export interface ProjectContext {
   readonly projectId: string;
@@ -54,6 +55,13 @@ export interface RunRequest {
   readonly systemPrompt: string | undefined;
   readonly providerEnv?: Record<string, string | undefined> | undefined;
   readonly resumeSessionId?: string | undefined;
+  /**
+   * RoleEntry.tools from admin/runtime settings. Values are Hub role tool ids
+   * (for example read_file/cph_check/send_file), mapped to Claude SDK tool
+   * names at run setup. `undefined` means the full supported tool surface; []
+   * means no tools.
+   */
+  readonly tools?: readonly string[] | undefined;
   readonly mcpServers?: Record<string, McpServerConfig> | undefined;
   readonly maxTurns?: number;
   readonly runId: string;
@@ -131,10 +139,12 @@ export async function runAgent(req: RunRequest): Promise<RunResult> {
   let error: string | undefined;
   try {
     await persistAgentMessage(req, "user", req.prompt);
+    const toolConfig = claudeSdkToolConfigForRole(req.tools);
 
     const options: Parameters<typeof query>[0]["options"] = {
       cwd: req.project.workspaceDir,
-      allowedTools: ["Read", "Write", "Bash", "Glob", "Grep"],
+      tools: [...toolConfig.tools],
+      allowedTools: [...toolConfig.allowedTools],
       maxTurns: cap,
       includePartialMessages: true,
       // ADR-0018: bypass interactive prompts (headless server); the sandbox