Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
6.1 KiB
id, title, status, wave, depends_on, plan, spec, design, requirements, acceptance_criteria
| id | title | status | wave | depends_on | plan | spec | design | requirements | acceptance_criteria | |||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 01-split-claude-mcp-budgets | Split the Claude ACP MCP startup and tool-call budgets | done | 1 | plan.md | ../../specs/agents/requirements/mcp-timeout-budgets.md | ../../specs/agents/system-design/mcp-timeout-budgets.md |
|
|
Task 01: Split the Claude ACP MCP startup and tool-call budgets
Outcome
ClaudeACP.Runtime().Env declares MCP_TIMEOUT and MCP_TOOL_TIMEOUT as two
independent values, and a test asserts both, so the CLI's first-turn wait costs
bounded startup latency while Kandev's blocking MCP tools keep a two-hour
budget.
In scope
apps/backend/internal/agent/agents/claude_acp.go: replace the singleMCP_TIMEOUT: "7200000"entry withMCP_TIMEOUT: "30000"andMCP_TOOL_TIMEOUT: "7200000", with a comment naming what each budget governs and why they are separate. The comment must state the correct mechanism:MCP_TIMEOUTbounds both the MCP connect deadline and the CLI's first-turn wait onsubscriptions/listen, which a conformant server holds open, so the CLI waitsMCP_TIMEOUT - 5000ms before its first turn. Citeanthropics/claude-code#91414. Do not describe this as a slow, broken, or stalling MCP server, and do not name any MCP server.apps/backend/internal/agent/agents/claude_acp_test.go: add the regression test.apps/backend/internal/mcp/handlers/handlers.go:3782: correct the comment that currently attributes the two-hour wait toMCP_TIMEOUT. It isMCP_TOOL_TIMEOUTthat keeps this call open.
Out of scope
- Other agent runtimes. Task 02 owns that audit.
MCP_PROTOCOL_NEGOTIATION. Rejected in the ADR.- Stall detection and orchestrator cancellation.
Acceptance
ClaudeACP.Runtime().Envcontains both keys with distinct values, andMCP_TIMEOUTparses as exactly 30000 (asserted no greater than 60000 as a bound) whileMCP_TOOL_TIMEOUTparses as an integer no less than 7200000.- The test fails before the change with a message that names the coupled value, not only a count mismatch.
- An agent profile value for either key still replaces the managed agent
default without an environment conflict, proven by an existing or added test
over
appendAgentRuntimeDefaults.
Verification
make -C apps/backend test(new regression:TestClaudeACPSeparatesMCPStartupAndToolBudgetsininternal/agent/agents)make -C apps/backend lint
Write the test first. Confirm it fails because MCP_TOOL_TIMEOUT is absent and
MCP_TIMEOUT is 7200000, then make it pass.
Manual acceptance evidence
Launch a Claude session with at least one MCP server configured and record time
to first token. Expect roughly the no-MCP baseline plus 25 s
(MCP_TIMEOUT - 5000), against roughly 1h 59m 55s before the change.
Then verify the risk named in the plan: hold an
ask_user_question_kandev call open past 5 minutes without answering and
confirm the agent is still waiting. If it is not, record the observed bound and
raise it as separate work. Do not widen this task.
Files likely touched
apps/backend/internal/agent/agents/claude_acp.goapps/backend/internal/agent/agents/claude_acp_test.goapps/backend/internal/mcp/handlers/handlers.go
Dependencies
None.
Inputs
- Plan section
Confirmed root causefor the CLI semantics of each key. - System design section
Data and contractsfor the values and their bounds. appendAgentRuntimeDefaultsinapps/backend/internal/agent/runtime/lifecycle/environment_resolution.goand the tier table inapps/backend/internal/agent/runtime/environment/tier.gofor the override behavior.
Output contract
Report the failing assertion before the change, the exact test output after,
the files changed, the manual latency measurement, the idle-timeout finding,
and any blocker. The commit message and the test name must describe the split
of the two budgets. Neither may attribute the defect to a slow, broken, or
stalling MCP server, and neither may name a specific MCP server. Mark this
work order done and update plan.md in the same conversation.
Results
Implemented 2026-09-05.
ClaudeACP.Runtime().Envnow setsMCP_TIMEOUT: "30000"andMCP_TOOL_TIMEOUT: "7200000"with a comment citinganthropics/claude-code#91414.- New test
TestClaudeACPSeparatesMCPStartupAndToolBudgetsinclaude_acp_test.go. Confirmed failing before the change:MCP_TIMEOUT = 7200000, want <= 60000andRuntime().Env missing "MCP_TOOL_TIMEOUT". Passes after. handlers.go:3782comment corrected to referenceMCP_TOOL_TIMEOUT.- "Agent profile still overrides managed default" acceptance criterion is
satisfied by the existing generic test
TestAppendAgentRuntimeDefaultsFillsOnlyMissingKeys(environment_resolution_defaults_test.go), which picks an arbitrary key out ofclaude-acp'sRuntime().Envmap and asserts override behavior; ran with-count=5to confirm it exercises bothMCP_TIMEOUTandMCP_TOOL_TIMEOUTacross map-iteration orders. No new test added — would have duplicated existing generic coverage. make -C apps/backend test: the only two packages this change touches at the unit level (internal/agent/agents,internal/mcp/handlers) are green. A full-suite run turned up 67 pre-existing failing tests across unrelated packages (worktree/socket/docker/config plumbing); confirmed byte-identical failing-test-name and failing-package sets against merge-basec51ec0a2in a scratch worktree — environmental, not caused by this change.make -C apps/backend lint: 0 issues.- Manual acceptance evidence (live session latency measurement, idle-timeout probe) not performed in this automated build step — requires launching a real Claude session with a configured MCP server, which is outside what this session can safely/meaningfully do unattended. Left as an operator follow-up; does not block the code/test acceptance criteria above.