feat(core,tools,docs): tool execution context contract in tracker adapters, per-tool documentation, and Docker E2E for host-side tools

[hojinzs]

Parent: #673 (Epic #651) · ADR docs/adr/2026-08-28_agent-tool-isolation.md Phase 2
리포트 항목: A13 구현 — Phase 2, E2, A16(툴)

병합 게이트(공통): 각 조각은 host-side 경로를 추가만 하므로 독립 병합 가능. 단 #700(1b, MCP subprocess 비활성화)은 A·B 모두 병합된 뒤에만 진행.

#673 분할 3/3 — 공통 계약·문서·E2E.

범위

• 어댑터 계약: agentToolSpecs() / executeAgentTool(name, args, context={issue})(스펙 §10.5 hooks)를 core 계약으로 정식화하고 GitHub/Linear 어댑터가 구현 — A/B가 임시로 둔 호출 경로를 계약으로 수렴
• 툴 문서(§10.5 MUST): 이름·입력 스키마, mutation 가능 여부, scope 제한(§15.5), 결과/오류 형태, rate-limit 기대치 — docs/trackers/<kind>.md(#674와 조율)
• Docker E2E: Codex/Claude 워커가 host-side 툴로 트래커 전이·코멘트 수행(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 시나리오), child env/파일에 토큰 없음 단언
• AGENT_TEST.md 시나리오 표, ADR "conformance" 절 갱신

완료 기준

• 계약 단위테스트, Docker E2E 통과, 문서 병합

Blocked by: #730, #731

[hojinzs]

Backlog → Ready (프로젝트 상태 관리) — 블로커 해소(#720/#730/#731 완료), In review 3(<5), WIP 캡(8) 내 픽업. main의 resolveProviderEnvironmentValues(#728)·core normalization.ts(#729)는 재사용만, 제거/재구현 금지.

[moncher-dev]

Workpad — #732 — Cycle 1

Type: fresh pickup
Branch: feat/732-tool-execution-context
Draft PR: #754
Cycle opened: 2026-08-29T08:57:44Z · Trigger: Ready pickup after dependencies #730 and #731 merged

Status Transitions

• 2026-08-29T09:03:52Z · Ready → In progress · implementation cycle opened after dependency resolution (cycle 1 open)

Plan

• 1. Formalize the agent-tool execution context contract and adapter implementations with unit coverage.
• 2. Document GitHub and Linear agent tools, then add the Docker host-side tool E2E scenario and ADR/test-guide updates.
• 3. Wrap-up: re-verify the original issue · pass the Completion Bar · changeset (if needed) · PR ready · transition to In review

Rework / PR Feedback

N/A — fresh pickup.

Completion Bar

• In-scope requirements implemented
• pnpm lint
• pnpm test
• pnpm typecheck
• pnpm build
• Docker E2E (if integration behavior changed)
• Tests for new functionality (or justified N/A)
• Code conventions (CLAUDE.md)
• Inline review comments answered (rework only; N/A fresh pickup)

Validation

• pnpm lint — pass.
• pnpm test — pass.
• pnpm typecheck — pass.
• pnpm build — pass.
• pnpm --filter @gh-symphony/worker test — pass (186 tests), including host-process adapter execution.
• Docker Codex host tool: docker compose --project-name symphony-e2e-584c5ba46035 -f docker-compose.e2e.yml exec -T symphony-e2e node /app/e2e/host-dynamic-tool-e2e.mjs — pass (host_dynamic_tool_e2e=pass).
• Docker Claude host MCP: pnpm e2e:claude — pass (5 tests).
• Changeset: .changeset/agent-tool-contract-docs.md.
• Docker E2E evidence: e2e/scenarios/19-host-side-tracker-tools.md.
• Upstream conformance: docs/symphony-spec.md remains unchanged; the generic GraphQL scope limitation is explicitly documented in the ADR and per-tool contracts.

Delegation (out-of-scope / human / post-merge)

• None.

Progress Log

• 2026-08-29T08:57:44Z: Classified the work as Coordination, Execution, and Integration layers; opened the feature branch and cycle plan.
• 2026-08-29T09:03:00Z: Formalized adapter-owned tool specifications and host execution, routed Codex calls through the selected adapter, committed d0922edd, and opened Draft PR feat(trackers): add agent tool execution contract #754.
• 2026-08-29T09:15:00Z: Documented GitHub and Linear host tools, added TC-19 and the required changeset, fixed the Docker harness to use the worker host environment, and completed Codex/Claude Docker verification.
• 2026-08-29T09:16:00Z: Re-verified every issue requirement against the adapter contract/tests, per-tool docs, ADR, and TC-19; refreshed PR feat(trackers): add agent tool execution contract #754 for human review. Handoff reason: implementation and required validation completed. Intended transition body: 🔁 Status: In progress → In review / Reason: implementation and required validation completed / Cycle: 1 close.

Blockers

None