Built in shell tool does not emit terminal content with exitCode on tool.execution_complete

[anthonykim1]

I’m trying to get the exit code for shell tool execution completion from the SDK tool.execution_complete event.

The SDK types suggest this should be available through terminal content on the tool result:

// node_modules/@github/copilot-sdk/dist/generated/session-events.d.ts

export interface ToolExecutionCompleteEvent {
  data: ToolExecutionCompleteData;
  type: "tool.execution_complete";
}

export interface ToolExecutionCompleteData {
  result?: ToolExecutionCompleteResult;
  success: boolean;
  toolCallId: string;
}

export interface ToolExecutionCompleteResult {
  content: string;
  contents?: ToolExecutionCompleteContent[];
  detailedContent?: string;
  structuredContent?: {
    [k: string]: unknown | undefined;
  };
}

export interface ToolExecutionCompleteContentTerminal {
  cwd?: string;
  exitCode?: number;
  text: string;
  type: "terminal";
}

Given that shape, I expected the shell command exit code to be available from the completed tool event payload like this:

session.on("tool.execution_complete", event => {
  const terminalContent = event.data.result?.contents?.find(
    content => content.type === "terminal"
  );

  const exitCode = terminalContent?.exitCode;
});

In other wordsL event.data.result?.contents?.find(c => c.type === "terminal")?.exitCode

Actual behavior seems to be tool.execution_complete just returning flattened text in event.data.result

event.data.result = {
  content: "...<shellId: 0 completed with exit code 0>",
  detailedContent: "...<shellId: 0 completed with exit code 0>"
}

Should the built-in shell/bash tool populate ToolExecutionCompleteResult.contents with a ToolExecutionCompleteContentTerminal block containing exitCode and cwd?

[github-actions]

Investigation Results: Confirmed Bug 🐛

Thanks for the detailed report. I investigated the codebase and confirmed this is a genuine bug.

What I looked at

• nodejs/src/generated/session-events.ts — the TypeScript types generated from the CLI schema
• test/snapshots/builtin_tools/should_capture_exit_code_in_output.yaml — actual snapshot of shell tool output
• nodejs/test/e2e/ — all E2E tests that check tool.execution_complete events
• All other language SDKs (Python, Java) for consistency

What I found

The schema explicitly defines ToolExecutionCompleteContentTerminal for this purpose:

/**
 * Terminal/shell output content block with optional exit code and working directory
 */
export interface ToolExecutionCompleteContentTerminal {
  cwd?: string;       // Working directory where the command was executed
  exitCode?: number;  // Process exit code, if the command has completed
  text: string;       // Terminal/shell output text
  type: "terminal";
}

And ToolExecutionCompleteResult.contents is documented as "Structured content blocks (text, images, audio, resources) returned by the tool in their native format".

However, looking at the actual snapshot data, the CLI's built-in shell tool does not populate contents. Instead, it embeds the exit code as plain text inside the content string:

content: "hello\nworld\n<exited with exit code 0>"

The contents array is absent entirely, meaning the pattern you attempted:

event.data.result?.contents?.find(c => c.type === "terminal")?.exitCode

will always be undefined for built-in shell tool results.

Root cause

The ToolExecutionCompleteContentTerminal type was clearly designed for the built-in shell tool (it's the only tool type for which it makes sense), but the CLI doesn't actually populate contents with a terminal block on shell tool completion. There are no tests enforcing this contract.

Workaround (until fixed)

You can parse the exit code from the content string:

session.on("tool.execution_complete", event => {
  const content = event.data.result?.content ?? "";
  const match = content.match(/<exited with exit code (\d+)>/);
  const exitCode = match ? parseInt(match[1]!, 10) : undefined;
});

This is fragile but works with the current CLI behavior. The proper fix is for the CLI to populate contents with a ToolExecutionCompleteContentTerminal block for shell tool results.

Generated by Bug Handler for issue #1803 · sonnet46 4.2M · ◷

[MRayermannMSFT]

Happy to work with @anthonykim1 on getting this sorted!

[anthonykim1]

Thanks!
As mentioned by @MRayermannMSFT earlier, the text: string is a bit ambiguous, since the output may be a preview, partial read, rather than always guaranteed full output of the command.

We wouldn't want people to think the text field is always guaranteed to be "complete"

Was thinking along the lines of:

export type ToolExecutionCompleteContent =
	| ToolExecutionCompleteContentText
	| ToolExecutionCompleteContentTerminal
	| ToolExecutionCompleteContentShellExit
	| ToolExecutionCompleteContentImage
	| ToolExecutionCompleteContentAudio
	| ToolExecutionCompleteContentResourceLink
	| ToolExecutionCompleteContentResource;


/**
 * Shell command exit metadata with optional output preview.
 */
export interface ToolExecutionCompleteContentShellExit {
    /**
     * Working directory where the shell command was executed
     */
    cwd?: string;
    /**
     * Exit code from the completed shell command
     */
    exitCode: number;
    /**
     * Output associated with this shell command, if available. May be partial,
     * truncated, or a preview; not guaranteed to be full output.
     */
    outputPreview?: string;
    /**
     * Whether outputPreview is known to be incomplete or truncated
     */
    outputTruncated?: boolean;
    /**
     * Shell id, as assigned by Copilot runtime 
     */
    shellId: string;
    /**
     * Content block type discriminator
     */
    type: "shell_exit";
}