Repository navigation
Run background bash commands as MCP tasks - #164
Merged
Merged
Conversation
v1.5.0 speaks MCP protocol revision 2026-07-28 (server/discover, per-request _meta capabilities), which Claude Code's v2 MCP runtime negotiates and which its MCP tasks support requires. Groundwork for surfacing background bash commands as MCP tasks. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BqmpXXbY9uL5rUYrAjCnKg
A run_in_background bash call from a client that declares the MCP tasks extension (io.modelcontextprotocol/tasks, protocol 2026-07-28) is now answered with a task: the client follows it, is told when it finishes with its exit code, output file, and the end of its output, and stops it with tasks/cancel. Claude Code shows such commands in /tasks and wakes the agent when they end. kill_shell and list_shells are hidden from such a client; every other client keeps the shell id reply and those tools. mcp-go does not release the extension yet, so go.mod replaces it with the gartnera/mcp-go fork (upstream main + mark3labs/mcp-go#987 + server.WithTaskDecision, which keeps foreground calls synchronous). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BqmpXXbY9uL5rUYrAjCnKg
…1.319 TestBackgroundCommands runs a background command through each agent and follows it with list_shells: none of the non-interactive runs gets MCP tasks, so each must keep the shell id reply and the control tools. Claude Code 2.1.319 (which has MCP tasks) turns on tool search behind an ANTHROPIC_BASE_URL gateway, so a user's MCP server that launch does not mark always-load is announced as a deferred tool rather than offered outright; the layering test accepts either. The Agent SDK used by the real-model suite is bumped to 0.2.179, which bundles the same CLI. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BqmpXXbY9uL5rUYrAjCnKg
test_background_task_e2e runs a background command through Claude Code with MCP tasks on and checks that it runs as a task: the session is not offered kill_shell or list_shells, the call is not answered with a shell id, and Claude reports the output once the task completes. conftest now also clears the variables a surrounding Claude Code cloud session sets, which would otherwise keep the CLI under test from using MCP tasks. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BqmpXXbY9uL5rUYrAjCnKg
…dary - The real-model task test now requires output Claude can only know from the task's result: the command computes it, and only text after the completion notification counts. It catches asyncio.TimeoutError, which is not the builtin TimeoutError on Python 3.10. - The mocked background test no longer races list_shells against the background echo finishing. - OutputTail starts a single long line on a character boundary, and avoids copying the buffer to find a newline. - Document that subagents in a task session aren't offered the control tools, and that refused commands fail on the task's first poll. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BqmpXXbY9uL5rUYrAjCnKg
gartnera
added
the
release:major
Claude
gartnera
enabled auto-merge (squash)
November 7, 2026 00:22
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A
run_in_backgroundbash call from a client that declares the MCP tasks extension (io.modelcontextprotocol/tasks, protocol revision 2026-07-28) is now answered with a task instead of a shell id. Claude Code (2.1.304+) then shows the command in/tasks, lets the user stop it there, and wakes Claude with the result when it finishes, as it does for its own backgroundBash.tasks/cancelkills the command.kill_shellandlist_shellsare neither listed for nor callable by a client that runs tasks. Every other client keeps the shell-id reply and those tools.Breaking: MCP clients that declare the tasks extension no longer see
kill_shell/list_shells, and they get a task handle where they used to get a shell id.Dependency: mcp-go fork
go.modreplaces it withgartnera/mcp-gomain.main, plus feat: add SEP-2663 Tasks Extension mark3labs/mcp-go#987 (the extension, still unmerged upstream), plusserver.WithTaskDecision. That option lets the server keep a call synchronous; without it, everybashcall would become a task once the client declares the extension.go.modsays to drop the fork once upstream supports both.Known limitations (documented in
docs/background-processes.md)CLAUDE_AUTO_BACKGROUND_TASKS=1). Never for one-shotclaude -pruns or for subagents.Tests
go test ./...passes.cmd/serve_tasks_test.gocovers the control-tool filter, the task result, foreground calls, plain clients, and cancellation.OutputTailhas its own test.LITE_SANDBOX_E2E=1 go test ./e2e/mockedserver/): passes, with a newTestBackgroundCommands. Every agent tested (Claude Code-p, Codex, Crush, Grok, opencode v1, pi) gets the shell-id path and can calllist_shells. opencode v2 is not covered.ANTHROPIC_BASE_URLgateway, so the launch layering test now also accepts a user's MCP server announced as a deferred tool.e2e/claude): passes, with a newtest_background_task_e2e.py. Claude Code runs the command as a task, has no control tools, and reports output it can only learn from the task's result. The Agent SDK is bumped to 0.2.179, which bundles CLI 2.1.319.OS_SANDBOX_TESTS=1, and the docs link check (lycheewasn't available).Generated by Claude Code