Custom SDK tools (defineTool) not available to sub-agents via CustomAgentConfig.tools whitelist

[dt-benedict]

Bug

When a CustomAgentConfig specifies custom SDK tool names (registered via defineTool()) in its tools whitelist, the sub-agent does not receive those tools at runtime. Only built-in CLI tools (like view) survive the filtering. The custom tool names are silently ignored.

This is the same class of issue as #860 (MCP tool names not expanded), but affects custom tools registered through the SDK's defineTool() API.

Versions

• SDK: @github/copilot-sdk 0.2.0
• Runtime: Node.js 22

Expected Behavior

When a session registers custom tools via defineTool() and a custom agent's tools array references those tool names, the sub-agent should have access to those custom tools.

const myTool = defineTool("run_bash", {
  description: "Execute a bash command",
  parameters: z.object({ command: z.string() }),
  handler: async ({ command }) => { /* ... */ },
});

const session = await client.createSession({
  tools: [myTool],
  customAgents: [
    {
      name: "investigator",
      description: "Investigates problems using shell commands",
      tools: ["run_bash"],  // Should give this agent access to the custom tool
      prompt: "You are an investigator...",
    },
  ],
  onPermissionRequest: async () => ({ kind: "approved" }),
});

The investigator agent should have run_bash available.

Actual Behavior

The sub-agent reports it does not have run_bash available — it only sees built-in tools like view. The custom tool name "run_bash" in the agent's tools array is not matched against the session's registered custom tools.

The agent correctly reports "I do not have a run_bash tool available" — this is not a hallucination, the tool genuinely isn't injected into the sub-agent's context.

Reproduction

1. Register a custom tool via defineTool("my_custom_tool", { ... })
2. Pass it in tools when creating a session
3. Define a custom agent with tools: ["my_custom_tool"]
4. Send a prompt that triggers the sub-agent
5. Ask the sub-agent to use my_custom_tool
6. Sub-agent reports the tool is not available

Workaround

Setting tools: null (all tools) on the custom agent config does give the sub-agent access to custom tools. The issue is specifically with the whitelist filtering — it only matches built-in CLI tool names, not custom SDK tool names.

We work around this by removing the tools whitelist entirely and encoding tool restrictions in the agent's prompt instead. This loses the SDK-level enforcement of tool scoping.

Notes

• The SDK documentation (docs/features/custom-agents.md) only shows built-in tool names (grep, glob, view, edit, bash) in the tools examples — there are no examples with custom defineTool() names
• Issue AI: Agent Tools with bare MCP server name not expanded — agent sees zero MCP tools #860 documents the same pattern for MCP server tool names not being expanded
• The tools whitelist is a key feature for enforcing least-privilege on sub-agents — without it working for custom tools, there's no way to restrict which custom tools a sub-agent can use at the SDK level