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

[ductrung-nguyen]

Indeed we need to support/enhance this feature.

Current behavior

1. SessionConfig.CustomAgents[].Tools = ["my_tool"]
   -> CLI tells the LLM the subagent can use "my_tool"

2. LLM generates a tool call
   -> CLI sends `tool.call` RPC with sessionId: "<child-session-id>"

3. SDK looks up c.sessions["<child-session-id>"]
   -> NOT FOUND → returns error -32602: "unknown session"

1. Tool dispatch is per-session

// handleToolCallRequest handles a tool call request from the CLI server.
func (c *Client) handleToolCallRequest(req toolCallRequest) (*toolCallResponse, *jsonrpc2.Error) {
    // ...
    c.sessionsMux.Lock()
    session, ok := c.sessions[req.SessionID]    // <-- KEY: lookup by session ID
    c.sessionsMux.Unlock()
    if !ok {
        return nil, &jsonrpc2.Error{Code: -32602, Message: fmt.Sprintf("unknown session %s", req.SessionID)}
    }

    handler, ok := session.getToolHandler(req.ToolName)  // <-- tools are on the session object
    if !ok {
        return &toolCallResponse{Result: buildUnsupportedToolResult(req.ToolName)}, nil
    }
    // ...
}

The toolCallRequest contains a SessionID field. The SDK resolves the tool handler by:

1. Looking up c.sessions[req.SessionID] — a map only populated by CreateSession() and ResumeSessionWithOptions()
2. Calling session.getToolHandler(req.ToolName) on the found session

2. Sessions are only registered by explicit API calls

The c.sessions map is populated in exactlytwo places:

• CreateSession(): c.sessions[response.SessionID] = session
• ResumeSessionWithOptions(): c.sessions[response.SessionID] = session

There is no mechanism for the SDK to automatically register child sessions created by the CLI for subagents.

3. Tools are registered per-session

func (s *Session) registerTools(tools []Tool) {
    s.toolHandlersM.Lock()
    defer s.toolHandlersM.Unlock()
    s.toolHandlers = make(map[string]ToolHandler)
    for _, tool := range tools {
        if tool.Name == "" || tool.Handler == nil {
            continue
        }
        s.toolHandlers[tool.Name] = tool.Handler
    }
}

Tool handlers are stored in a per-session map[string]ToolHandler. Only the parent session (created via CreateSession()) has these handlers registered.

4. Lifecycle events do NOT register sessions

The handleLifecycleEvent function only dispatches events to registered callback handlers — it does NOT create Session objects or add entries to c.sessions. The subagent events (subagent.started, subagent.completed, etc.) are informational only.

5. CustomAgentConfig.Tools is RPC-only

type createSessionRequest struct {
    // ...
    CustomAgents []CustomAgentConfig `json:"customAgents,omitempty"`
    // ...
}

The CustomAgentConfig.Tools field determines which tool names the CLI exposes to the subagent's LLM context. However, when the subagent actually calls one of these tools, the CLI sends a tool.call RPC request with the child session ID — which the SDK cannot resolve.

The flow is:

1. SessionConfig.CustomAgents[].Tools = ["my_tool"] → CLI tells the LLM the subagent can use my_tool
2. LLM generates a tool call → CLI sends tool.call RPC with sessionId: "<child-session-id>"
3. SDK looks up c.sessions["<child-session-id>"] → not found → returns error -32602: unknown session

[ductrung-nguyen]

Proposal:

Protocol-level specification for resolving child session IDs created by subagents
and dispatching tool calls, permission requests, hooks, and user-input requests
back to the parent session that owns the handlers.

Problem

When a user configures custom agents (subagents) on a session, the Copilot CLI
creates a child session for each agent invocation. The child session has its own
session ID that is not in the SDK's session registry — only parent sessions are
registered by createSession().

All four request types (tool.call, permission.request, hooks.invoke,
userInput.request) may arrive with a child session ID. Without resolution logic
the SDK returns "unknown session", breaking the entire subagent feature.

Request Flow diagram

(with help of copilot)

┌──────────┐                  ┌──────────┐                   ┌──────────┐
│  Parent   │  createSession   │   SDK    │   JSON-RPC init   │ Copilot  │
│  App      │ ───────────────▶ │  Client  │ ────────────────▶ │  CLI     │
│           │  (tools, agents) │          │                   │          │
└──────────┘                   └────┬─────┘                   └────┬─────┘
                                    │                              │
           1. session.event ◀───────┼──────────────────────────────┤
              type: subagent.started │                              │
              data.remoteSessionId   │                              │
              data.toolCallId        │                              │
              data.agentName         │                              │
                                    │                              │
           2. SDK maps              │                              │
              child → parent        │                              │
              child → agentName     │                              │
                                    │                              │
           3. tool.call  ◀─────────┼──────────────────────────────┤
              sessionId = CHILD_ID  │                              │
              toolName, arguments   │                              │
                                    │                              │
           4. resolveSession(CHILD) │                              │
              → parent session      │                              │
              + allowlist check     │                              │
                                    │                              │
           5. invoke tool handler   │                              │
              return result ────────┼─────────────────────────────▶│
                                    │                              │
           6. session.event ◀───────┼──────────────────────────────┤
              type: subagent.completed                             │
              data.toolCallId       │                              │
                                    ▼                              ▼

Steps 3–5 repeat for permission.request, hooks.invoke, and userInput.request.

Protocol Contract

Session Events (parent session's event stream)

All subagent events arrive as session.event notifications keyed by the
parent session's sessionEventRequest.sessionId.

Event type	Key data fields	Purpose
subagent.started	remoteSessionId (child ID), toolCallId, agentName, agentDisplayName	Register child → parent mapping
subagent.completed	toolCallId, agentName	Cleanup instance tracking
subagent.failed	toolCallId, agentName, error	Cleanup instance tracking

Ordering guarantee: The CLI emits subagent.started before the first
request that uses the child session ID.

Request Types Requiring Resolution

JSON-RPC method	Params include sessionId	Child sessions possible?
tool.call	ok	ok
permission.request	OK	OK
hooks.invoke	OK	OK
userInput.request	OK	OK

Data Model

All SDKs must maintain three maps on the client instance. Names below are
language-agnostic; adapt casing to each language's conventions.

childToParent:      Map<childSessionId, parentSessionId>
childToAgent:       Map<childSessionId, agentName>
subagentInstances:  Map<parentSessionId, Map<toolCallId, SubagentInstance>>

SubagentInstance fields:

Field	Type	Description
agentName	string	Custom agent name from subagent.started
toolCallId	string	Unique tool call ID for this launch
childSessionId	string	Child session ID (from remoteSessionId)
startedAt	datetime	Timestamp of the subagent.started event

All maps must be protected by appropriate synchronization primitives to have thread-safe.

Required Behavior

Session Resolution

Every request handler must resolve the incoming sessionId through a single
shared function:

resolveSession(sessionId) → (session, isChild, error)

Algorithm:

1. Direct lookup: if sessions[sessionId] exists → return (session, false, nil)
2. Child lookup: if childToParent[sessionId] exists:
   • let parentId = childToParent[sessionId]
   • if sessions[parentId] exists → return (parentSession, true, nil)
   • else → error: "parent session {parentId} for child {sessionId} not found"
3. Unknown → error: "unknown session {sessionId}"

Handler Dispatch

Each handler follows the same pattern:

(session, isChild, err) = resolveSession(params.sessionId)
if err → return error response
// For tool.call ONLY: enforce allowlist
if isChild AND handler == tool.call:
    if not isToolAllowedForChild(params.sessionId, params.toolName):
        return error: "Tool '{toolName}' is not supported by this client instance."
// Dispatch to the resolved session's handler
return session.handle(params)

Allowlist Enforcement

The CustomAgentConfig.tools field controls which parent tools a subagent can
invoke.

tools value	Meaning
null / nil / None / not set	All parent tools accessible
[] (empty list)	No tools accessible
["a", "b"]	Only tools a and b accessible

Rules:

• Allowlist check applies only to tool.call requests (not
  permission.request, hooks.invoke, or userInput.request).
• A denied tool returns "Tool '{name}' is not supported by this client instance."
  — never "unknown session".
• The check algorithm:
  1. Look up agentName = childToAgent[childSessionId]
  2. Look up CustomAgentConfig for agentName on the parent session
  3. If tools is null/unset → allow
  4. If toolName is in tools list → allow
  5. Otherwise → deny

Cleanup Contract

Trigger	childToParent	childToAgent	subagentInstances
Client stop() / shutdown	Clear all	Clear all	Clear all
Delete single session (parent)	Remove children of that parent	Remove children of that parent	Remove parent entry
Destroy session (parent)	Remove children of that parent	Remove children of that parent	Remove parent entry, fire cleanup callback
subagent.completed / failed	Preserve	Preserve	Remove instance only

Why preserve on subagent end? Requests may still be in-flight after the
completed/failed event. Keeping childToParent and childToAgent ensures
those late-arriving requests resolve correctly.

Error Types

Error message	Condition
unknown session {id}	sessionId not found as direct session or child mapping
parent session {parentId} for child {childId} not found	Child mapping exists but parent session was deleted/destroyed
Tool '{name}' is not supported by this client instance.	Tool not in agent's allowlist, or tool not registered

Concurrency Requirements

• All map access (childToParent, childToAgent, subagentInstances) must be
  synchronized.
• The lock must not be held during handler execution (tool handler calls,
  permission callbacks, hook invocations). This prevents deadlocks when a handler
  triggers further session operations.
• Lock is acquired only for map reads/writes, then released before callback
  dispatch.

lock()
(session, isChild, err) = read maps
unlock()
// handler runs WITHOUT lock
result = session.handle(params)

[stephentoub]

I believe this is a duplicate of #959, which was fixed in the runtime a few days ago.