feat(tools,worker): pass the normalized issue (id, nativeRef) as tool execution context, remove the dead dynamic-tool path, document per-tool contracts

[moncher-dev]

Epic: #651
리포트 항목: A13 구현 — 2단계, E2, A16(툴) — docs/reports/2026-08-28-upstream-spec-drift-research.md (PR #650)

결정 반영 (2026-08-28)

#671에서 (a) host-side 실행, 2단계 확정. 이 이슈는 2단계: 툴을 호스트가 실행하고 정규화 issue 컨텍스트를 넘기며, dead dynamic-tool 경로를 실제 프로토콜로 교체한다.

병합 게이트 (2026-08-28, 트랜지션 전략)

• 이 이슈(Phase 2)는 Codex·Claude 두 런타임 모두에서 host-side 툴 실행이 완료돼야 한다. 한 런타임만 완료된 상태로 병합하지 않는다(다른 런타임 워커가 툴을 잃음).
• 1b(feat(runtimes,worker): complete ADR Phase 1 — disable agent-owned MCP exposure, host-side Git transport, isolated child HOME (merge only with #673) #700)는 이 이슈와 같은 릴리스에서 병합한다: 순서는 feat(tools,worker): pass the normalized issue (id, nativeRef) as tool execution context, remove the dead dynamic-tool path, document per-tool contracts #673 → feat(runtimes,worker): complete ADR Phase 1 — disable agent-owned MCP exposure, host-side Git transport, isolated child HOME (merge only with #673) #700(직후) 또는 동시. feat(runtimes,worker): complete ADR Phase 1 — disable agent-owned MCP exposure, host-side Git transport, isolated child HOME (merge only with #673) #700 없이 #673만 병합되는 것은 허용(툴이 host-side와 MCP 양쪽에 잠시 공존), 반대는 금지.
• 리뷰 편의를 위해 런타임별 PR 분할은 가능하나, 첫 PR 병합 전에 두 번째 PR이 approve 상태여야 한다.

문제

§10.5: 런타임은 툴 호출을 host-side로 실행하고(MUST), 정규화된 이슈(issue.id, native_ref)를 실행 컨텍스트로 전달하며(SHOULD), 각 어댑터는 툴 이름/스키마/변경 가능성/scope/오류·rate-limit 의미론을 문서화한다(MUST). 현재 툴은 에이전트가 spawn하는 MCP subprocess이고 GITHUB_PROJECT_ID만 받으며, 워커의 dynamic-tool 경로는 dead code다.

현재 상태 (증거)

• 툴 컨텍스트: tool-github-graphql/src/mcp-entry.ts:34-65(GITHUB_PROJECT_ID만), tool-linear-graphql/src/mcp-entry.ts:22-28; LINEAR_ISSUE_ID는 allowlist에서 걸러짐 runtime.ts:536-546
• dead 경로: dynamic_tool_call_request/response는 Codex v2 메서드가 아님(runtime.ts:131, index.ts:1255-1276); runToolProcess(index.ts:2176-2219)가 raw JSON을 JSON-RPC 기대 MCP 서버 stdin에 써서 항상 "{}"
• 툴 문서: packages/tracker-github/README.md(3줄), packages/tracker-linear/README.md(7줄), README.md:726 한 줄

할 일

• Codex: thread/start에서 dynamic tool spec advertise(config.mcp_servers 대신), item/tool/call 요청을 워커가 받아 tool-*-graphql의 executeTool()을 in-process 호출, 결과를 JSON-RPC 응답으로 반환; 미지원 툴 이름은 구조화 실패 + 세션 계속
• Claude: 워커가 MCP 서버를 host-side로 띄우고 HTTP/SSE transport로 노출, mcp.json에는 URL + 워커 발급 세션 토큰만 기록(세션 종료 시 폐기)
• 툴 실행 컨텍스트에 issue.id, issue.identifier, nativeRef(refactor(core,orchestrator,trackers): add nativeRef and remove provider-payload branching from service.ts #665) 전달 — 어댑터가 provider 식별자로 scope 제한(§15.5 narrowing) 가능하게
• dead dynamic_tool_call_* 경로와 runToolProcess 삭제
• docs/trackers/<kind>.md(docs(trackers): publish compact adapter profiles for github-project, linear, and file per spec §11.2 #674) 또는 툴 패키지 README에 §10.5 목록 문서화: 툴 이름·입력 스키마, mutation 가능 여부, scope 제한, 결과/오류 형태, rate-limit 기대치
• 툴 spec은 워커 시작 시 스냅샷에 고정(리로드가 in-flight 세션에 영향 없음 — 현재 동작 유지, 테스트로 고정)

완료 기준

• §17.5: 툴이 host-side에서 어댑터 auth로 실행되고 child env/파일에 토큰이 없으며, issue 컨텍스트가 툴에 도달하는 테스트(Codex, Claude)
• 미지원 툴 이름 → 구조화 실패 + 세션 계속 테스트
• Docker E2E: Codex/Claude 워커가 트래커 상태 전이·코멘트를 수행(Linear tracker: workers cannot write to the tracker — MCP server never receives auth, and the LINEAR_API_KEY path sends a malformed header (regression of #314) #634 시나리오)
• 문서 병합

Blocked by: #665, #671

[moncher-dev]

#671 scope confirmation — phase 2 host-side execution

#671 accepts #673 as the conformance-closing phase for the upstream §10.5/§15.3 tool boundary. #673 owns these outcomes:

• Codex advertises the selected adapter's snapshotted tool specs and handles app-server item/tool/call requests in the worker with host-side adapter credentials;
• Claude uses a worker/orchestrator-owned, loopback HTTP MCP service; generated mcp.json contains only its URL and a per-run session capability token, never a tracker credential;
• every tool call receives internal normalized context { issue: { id, identifier, nativeRef } }, allowing adapter-level scope narrowing;
• structured failures cover unsupported tool names, invalid arguments, missing auth, transport failures, and rate limits without stalling the session;
• the obsolete dynamic_tool_call_*/runToolProcess route is removed rather than adapted; and
• the host service owns session-token expiry/revocation, loopback-server teardown, and per-adapter tool-contract documentation.

#672 is the prerequisite that removes tracker secrets from coding-agent environments and files. #673 must not reintroduce them. For Linear, retain the credential in the worker by default; extend the host-side broker only if remote-worker deployment requires it. The authoritative rationale and temporary MCP-subprocess divergence are in ADR 2026-08-28.

[moncher-dev]

#671 scope correction — host enforcement is part of phase 2

The normalized { issue: { id, identifier, nativeRef } } context in the prior
scope confirmation is a host-enforced boundary, not advisory metadata. #673
must expose bounded, issue-aware adapter operations and enforce the selected
issue context for every call; moving the current arbitrary GraphQL forwarding
paths into the worker by itself is insufficient. nativeRef remains opaque to
the scheduler and is interpreted only by the selected adapter.