Feature request: Plumb AbortSignal through ToolInvocation so session.abort() can cancel in-flight tool handlers

[Ljosmann]

Feature request: Plumb AbortSignal through ToolInvocation so session.abort() can cancel in-flight tool handlers

Summary

session.abort() cancels the agentic loop (no further tool calls scheduled) but does not propagate cancellation into a currently-executing tool handler. The handler runs to completion regardless. This forces SDK consumers building wedge-recovery to implement OS-level process tree kills at their own layer, when the cooperative cancellation primitive could live in the SDK.

Verified state at @github/copilot-sdk (dist/)

1. ToolInvocation interface (types.d.ts:224-233):

export interface ToolInvocation {
    sessionId: string;
    toolCallId: string;
    toolName: string;
    arguments: unknown;
    /** W3C Trace Context traceparent from the CLI's execute_tool span. */
    traceparent?: string;
    /** W3C Trace Context tracestate from the CLI's execute_tool span. */
    tracestate?: string;
}

No signal, no abortSignal, no cancellation handle.

2. _executeToolAndRespond (session.js:278-309):

async _executeToolAndRespond(requestId, toolName, toolCallId, args, handler, traceparent, tracestate) {
  try {
    const rawResult = await handler(args, { sessionId, toolCallId, toolName, arguments: args, traceparent, tracestate });
    ...
  } catch (error) { ... }
}

Handler is awaited synchronously; no signal threaded through; no race against an abort source.

3. session.abort() (session.js:765-769):

async abort() {
  await this.connection.sendRequest("session.abort", { sessionId: this.sessionId });
}

JSDoc: "and can continue to be used for new messages" + "resolves when the abort request is acknowledged." Confirms scope is the agentic loop, not the handler.

4. Searched node_modules/@github/copilot-sdk/dist/ for AbortSignal|AbortController|signal:|cancel\(|cancellation: zero matches.

Proposed API

Add an optional AbortSignal to ToolInvocation that aborts when session.abort() (or a new session.cancelToolCall(toolCallId)) is called:

export interface ToolInvocation {
    sessionId: string;
    toolCallId: string;
    toolName: string;
    arguments: unknown;
    /** Aborts when session.abort() or session.cancelToolCall(toolCallId) is invoked. */
    signal: AbortSignal;
    traceparent?: string;
    tracestate?: string;
}

Optional addition: a more granular session.cancelToolCall(toolCallId) that cancels a specific in-flight handler without aborting the broader agentic loop.

Why it matters

Without handler-level cancellation, consumers building wedge-recovery (long-running shell handlers, network calls, file I/O on large files) must:

1. Track child PIDs at handler-spawn or via shell tool event streams,
2. Issue OS-level kills (Windows taskkill /F /T /PID, POSIX SIGKILL fan-out across descendant tree),
3. Re-probe survivors with bounded wait,
4. Manage orphan-leak edge cases.

That's ~125 lines of code per consumer plus cross-platform paths. A cooperative AbortSignal in the SDK lets handlers self-terminate cleanly — fetch(url, { signal }), await sleep(ms, { signal }), child_process.spawn(...).on(signal.aborted, kill) — which is the well-trodden Node.js cancellation idiom.

Backwards compatibility

AbortSignal is non-required for handlers that don't consume it (existing handlers continue to work). Handlers that opt in get cooperative cancellation; the SDK keeps its existing process-isolation guarantees.

Concrete consumer evidence

Parley (multi-agent orchestration system built on @github/copilot-sdk) ships at present a 313-line wedge-kill primitive in our orchestrator (Windows taskkill /F /T /PID + POSIX SIGKILL fan-out + bounded post-kill verify + tracker reset) that exists specifically because session.abort() doesn't propagate. With this feature, that primitive would be ~30 lines of if (signal.aborted) cleanup() in the consumer's tool handlers.

Workaround until landed

OS-level process tree kill via tracked child PIDs from tool start events, gated by a bounded post-kill verify. Functional but not durable. Issue tracks the durable layer.

Affected versions

Verified against @github/copilot-sdk shipped in current Parley node_modules snapshot (May 2026). Please confirm whether the proposed API has been considered or is on the roadmap.

[Ljosmann]

Cross-vantage probe finding — built-in tools don't route through SDK shell namespace

Following up on the original issue with concrete probe evidence from two independent vantages (different ships, different agents, different probe approaches) converging on the same finding.

Live runtime probe (probe script scripts/probe-shell-kill.ts)

Built-in powershell tool invoked via SDK; observed tool.execution_start event stream:

• tool.execution_start event payload: NO pid, processId, or shellPid field present.
• ShellCommandStateTracker.parseShellRootPid returned null for the rootPid.
• session.shell.kill({ processId: null }) could not be invoked because no processId was available.

Bonus control test (confirmed shell.kill works on its intended lane):

• session.shell.exec({ cwd: "." }) → returned { processId: "<UUID>" }
• session.shell.kill({ processId: "<UUID>" }) → returned { killed: true }

SDK type-source trace

ToolExecutionStartData interface (@github/copilot-sdk/dist/generated/session-events.d.ts:2094-2122) has NO typed processId field. ToolExecutionCompleteData (:2218-2252) likewise lacks one. The built-in tool event payload type does not encode a process identifier that would be compatible with session.shell.kill's input shape.

Conclusion

The proposed AbortSignal (or any cancellation handle) in ToolInvocation remains the right shape for the durable fix. session.shell.kill is functional but limited to processes spawned via session.shell.exec; built-in tool processes (which consumers actually need to cancel for wedge-recovery) are out of scope for the existing kill primitive.

Workaround in production: OS-level process-tree kill via tracked PIDs captured from shell tool event metadata (when available) or external tracking (when not). Functional but not durable; consumers must reimplement cross-platform process management at their layer.