docs(migration): add Sprint 2 Phase B — Backend invocation + MCP tool API diff#64
Merged
Conversation
… API diff
Replaces the Phase B placeholders under stable anchors `{#backend-invocation-diff}`
and `{#mcp-tool-api-diff}` with substantive content (en + zh-TW pair).
Section 4 — Backend invocation diff covers:
- TS-vs-Rust invocation models (tmux shell-string vs static BackendPreset / PTY)
- per-backend invocation matrix (Claude / OpenCode / Codex / Gemini / Kiro)
- resume strategy diff (TS session-id vs Rust ResumeMode {ContinueInCwd, Fixed,
NotSupported})
- nativeInstructionsMechanism → BackendPreset mapping with three behavior
changes flagged (OpenCode AGENTS.md, Kiro per-workdir naming, Kiro
inject-on-Ready)
- signal/ESC byte semantics with the `pending` capability-matrix markers per
protocol §3.5.8 (Sprint 11 verification deferred)
- migration call-outs for tooling that scripts the binary directly
Section 5 — MCP tool API diff covers:
- three-track coordination model (work / comms / scope freeze) with rationale
drawn from FLEET-DEV-PROTOCOL-v1.md §1, §2
- per-tool schema diff for the 30+ tools shared between daemons
- the 11 Rust-only tools grouped by track (inbox, describe_message,
describe_thread, set_waiting_on, clear_blocked_reason, report_health,
interrupt, tool_kill, move_pane, watch_ci, unwatch_ci)
- end-to-end TS-vs-Rust send_to_instance walkthrough as the deepest-friction
example, with five concrete prompt/runbook changes
- TS AGEND_TOOL_SET profiles vs Rust full-toolbox observation, marked
`pending` for Sprint 11
Authored under Sprint 2 Phase B role-swap (ts-reviewer drafts, ts-impl audits)
per General D5. Surrogate authority d-20260427025246010573-0.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…sion)
Addresses dev-reviewer-2's 2 LOW findings (Rust source pointers) and ts-impl's
3 informational observations (TS-side citation precision + clarity):
§4.2 Claude Code spawn_flags (F1, dev-reviewer-2):
- src/backend.rs:401-426 → src/backend.rs:411-426. The `:401-426` range
included the close of `name()` at L401, a blank line, and the doc-comment
block; tightening to `:411-426` covers exactly the `pub fn spawn_flags`
signature through closing brace. EN + zh-TW updated.
§4.5 capability matrix Claude row (F2, dev-reviewer-2):
- The previous citation `src/backend_harness.rs:51` landed on gemini's seed
row, not Claude's, and the framing "initial value" was misleading because
every backend's initial transport_verified is `Unverified` at L56. The
`False` value is set later by an explicit Claude branch in
`record_transport_results`. Reworded to cite L71-74 (the branch) plus
L50 (note text) and L56 (initial Unverified). EN + zh-TW updated.
§4.4 Kiro inject-on-Ready rationale (O1, ts-impl):
- TS `src/backend/kiro.ts:81` carries a comment claiming `.kiro/steering/`
is auto-loaded by Kiro CLI; Phase B asserts the opposite (IDE-only). The
Rust team's empirical investigation drove `inject_instructions_on_ready
= true`; clarified the discrepancy and added a fallback note that the
migration outcome is identical even if the TS comment turns out correct.
EN + zh-TW updated.
§5.2 list_instances `tags` filter hedge (O3, ts-impl):
- Removed "verify with dev-impl-1/2" hedge — dev-reviewer-2's audit confirmed
Rust `src/mcp/tools.rs` `list_instances` has `inputSchema.properties: {}`
(no parameters). Replaced with definite TS source pointer
(`src/outbound-schemas.ts:146-148`) + concrete migration guidance (drop
filter or switch to `team`-based routing). EN + zh-TW updated.
ts-impl's O2 (off-by-one on `claude-code.ts:17-45` and `opencode.ts:14-73`)
re-checked against the worktree source: line 17 IS `buildCommand(...)` and
line 14 IS `buildCommand(...)`; the original citations are correct as
written. No change.
Both reviewers' substantive Rust + TS claims passed; these changes are
citation polish only.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced Apr 27, 2026
suzuke
added a commit
that referenced
this pull request
Apr 27, 2026
… + Known incompatibilities (#66) Final phase of TS→Rust migration guide. 7-section guide complete. Verdicts: ts-reviewer full_review VERIFIED + dev-reviewer-2 scope_conformance VERIFIED at head 9638d5e. Polish revision 1fc19d4 (M1 medium Sprint 11 timeline reframe + L1 LOW portable-pty crate caveat + O1 LOW busy-gate note for delegate_task smoke test) + micro-fix a9509de (Rust PR #197/#199 → #149/#161 citation correction per dev-reviewer-2 cross-team git-blame). Polish + micro-fix inspected by ts-lead as surgical mechanical, no substantive change. Sprint 2 ledger now complete: Phase A (#63 + #65 follow-up) + Phase B (#64) + Phase C (#66) = 4 PRs landing 7-section migration guide ready for agend-terminal Sprint 24 input.
suzuke
added a commit
that referenced
this pull request
Apr 27, 2026
#67) Sprint 2 outcome: 4 PRs (#63, #64, #65, #66) ship the canonical TS→Rust migration guide as docs/migration-to-agend-terminal.md (+ zh-TW pair). Cross-team coordination with dev-team (agend-terminal Rust) operationalised general's D3 single-hop dispatch pattern; 7-section guide complete with stable anchors ready for agend-terminal Sprint 24 input. Wall time ~1h40m for full pipeline including all phases, audits, polish cycles, cross-team merge-ordering, and architectural side-fix routing (F-NEW-OUTBOUND-DROP-LOG-SEVERITY-1 routed to dev-team Sprint 22 P1).
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
1 participant
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
Phase B of the Sprint 2 migration guide. Fills in the two placeholder sections Phase A (#63) reserved with stable anchors:
{#backend-invocation-diff}) — TS vs Rust spawn surface, resume strategy,nativeInstructionsMechanism→BackendPresetmapping, signal/ESC byte capability matrix.{#mcp-tool-api-diff}) — three-track coordination model, per-tool schema diff for shared tools, the 11 Rust-only tools, end-to-end cross-instance comms walkthrough as the deepest-friction migration example.en + zh-TW pair. Anchors stable across both files in section order:
{#why-migrate}(Phase C, Phase A placeholder) ·{#cli-flag-mapping}(Phase A) ·{#fleet-yaml-schema-diff}(Phase A) ·{#backend-invocation-diff}(Phase B) ·{#mcp-tool-api-diff}(Phase B) ·{#migration-steps}(Phase C, Phase A placeholder) ·{#known-incompatibilities}(Phase C, Phase A placeholder).Source-of-truth pointers used
src/backend.rs(BackendPreset, ResumeMode, spawn_flags, has_resumable_session)src/backend_harness.rs:51(capability matrix initial state —claudetransport_verified=False with note "LLM context not tied to PTY buffer")src/process.rs(kill_process_tree SIGTERM → 500ms → SIGKILL)src/mcp/tools.rs(full tool definitions)src/mcp/handlers.rs:584(inbox),:969-991(interrupt),:994-1031(tool_kill),:1033-1063(set_waiting_on)FLEET-DEV-PROTOCOL-v1.md§1, §2 (three-track rationale)src/backend/{claude-code,opencode,codex,gemini-cli,kiro}.ts(per-backend invocation)src/daemon.ts:1022-1039(Bug Duplicate Fleet Context Injection in Gemini Backend (gemini.md vs MCP server instructions) #55 daemon-side gate after PR fix(#55): generalize fleet context dual-injection fix across backends #56)src/channel/mcp-tools.ts:120-126(AGEND_TOOL_SET profiles)src/outbound-handlers.ts(cross-instance comms routing)src/outbound-schemas.ts(TaskBoardArgs, BroadcastArgs, etc.)Pending markers (Sprint 11)
§4.5 capability matrix uses
pendingper protocol §3.5.8 for every cell where Sprint 11 real-CLI verification has not yet run:interruptsemantics (ESC stops LLM turn) — all 4 backends pendingtool_killsemantics (SIGINT to fg pgid) — all 4 backends pendingpending§5.5 marks Rust tool-set profile mechanism as
pending(Sprint 11) — TS exposesstandard/minimalviaAGEND_TOOL_SET; Rust currently exposes all 45 tools.Test plan
git diff --name-only origin/main..HEAD— only the two migration doc filesgrep -n '{#[a-z-]*}' docs/migration-to-agend-terminal.md docs/migration-to-agend-terminal.zh-TW.md— all 7 stable anchors present in both files in identical orderpendingcapability claim made withoutpendingmarker (all unverified Rust ESC/SIGINT semantics gated)i64,serde, tool names, file paths, GitHub URLs) in English; body translatedAuto-merge
Not auto-merged. Awaiting parallel review verdicts:
audit_mode: full_review)nativeInstructionsMechanismtranslation / capability-matrixpendingmarkers / MCP three-track separation / 11 Rust-only tools (audit_mode: scope_conformance)dev-lead / ts-lead holds the merge gate per protocol §10.3.
🤖 Generated with Claude Code