TDD: Mandatory MCP Instrumentation

Three MCP calls are required protocol. Skipping any one of them is a named violation that corrupts the session record and all downstream metrics.

For the main agent: dispatch the tdd-task agent

If you are the main agent, complete these steps before spawning:

1. Call inventory (kind: session)({ agentKind: "main", limit: 1 }) — capture the chat_id field from the first row as chatId. The DB value comes directly from the SessionStart hook payload and is immune to in-memory contamination from prior subagent runs.
2. Generate a runId: `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`. Do not reuse a runId across dispatches — a fresh id per dispatch is the invariant.
3. The Task tools are frequently not available in a given session — treat TaskCreate as best-effort. When it is available, call TaskCreate({ subject: "TDD Session: <objective>", description: "Behavior tasks will appear as the orchestrator decomposes the goal." }) and capture the returned task ID as parentTaskId. Otherwise, this is the expected path: skip the call and proceed with parentTaskId unset — the dispatch and the orchestrator do not depend on it.
4. Initialize: goalById = new Map() (keyed by goal ID, each entry { ordinal, taskId? }), behaviorById = new Map() (keyed by behavior ID, each entry { goalOrdinal, behaviorOrdinal, taskId }).
5. Spawn vitest-agent:tdd-task as a plain background subagent — run_in_background: true, subagent_type: "vitest-agent:tdd-task", and no name/team argument. Pass goal, chatId, runId, and parentTaskId (if captured — it's optional) in the launch prompt.

Dispatch it as a subagent, never as a named teammate. An unnamed background subagent fires SubagentStart, which registers the run under a <chatId>-subagent-<ts>-<pid> session key that shares this session's conversation_id — so the subagent's run_tests/edit artifacts funnel back to the session you passed as chatId, and the tdd_task (action: start) the orchestrator opens against that chatId finds them (evidence-based phase gates pass). A named teammate dispatch instead spawns an independent session with its own conversation_id and no parent link; the chatId you pass then opens the task under this session while the artifacts land under the detached one — a split that makes every tdd_phase_transition_request deny with missing_artifact_evidence.

If you must dispatch as a named teammate anyway (issue #144): two mitigations exist, layered on top of the mismatch above rather than replacing the "prefer unnamed subagent" guidance.

1. Conversation-tree fallback (automatic). record-tdd-artifact's task lookup now also walks conversation_id: when the parent-session walk finds no open task AND the detached session's row shares a non-null conversation_id with the session that opened the task, the artifact still resolves there (newest open task wins; a session with agent_kind = 'main' is preferred when more than one open task exists across the conversation). This closes the gap for a named-teammate dispatch automatically, with no extra configuration — but it depends on sessions.conversation_id actually being populated for both sessions, which is a property of how the session was registered, not something this fallback controls.
2. Explicit task-id escape hatch (manual, last resort). Set VITEST_AGENT_TDD_TASK_ID=<tddTaskId> in the subagent's environment. plugin/hooks/post-tool-use/tdd-artifact.sh forwards it as --tdd-task-id on every record tdd-artifact call, which bypasses chat_id → session → task resolution (and therefore the conversation-tree fallback too) and writes straight to that task's current open phase. Use this only when you already know the fallback above isn't resolving correctly for the session shape you're operating under — it is a deliberate override, not a default. If a tdd_phase_transition_request denial's remediation.hint mentions artifacts landing under "a different session of this conversation", that message is telling you to set this variable (or reconsider whether an unnamed subagent dispatch was possible after all).

Do not attempt TDD yourself — the tdd-task agent carries the required MCP tools and skill context for evidence-based phase transitions.

Progress observation (main agent)

The orchestrator subagent calls tdd_progress_push at every milestone below (unchanged), and every event is persisted server-side regardless of what the main agent observes. The MCP server is Effect-native and cannot emit the custom notifications/claude/channel method Claude Code's channel feature listens for — no <channel source="mcp"> tag is ever delivered to the main agent. Do not wait for one and do not gate any behavior on receiving it.

Primary path: read the subagent's plain-text narration. The Task-panel tools (TaskCreate/TaskUpdate) are frequently absent from a given session's tool set — treat text narration as the norm, not a fallback. As the subagent narrates each milestone, relay it to the user in a short sentence keyed to the event class:

• Goals discovered (goals_ready, goal_added) — name the goals (or the new one) so the user knows the decomposition.
• A goal or behavior starts (goal_started, behavior_started, behavior_added) — say which goal/behavior is now active, using the [G<n>.B<m>] <behavior> label so the user can track it across events.
• A phase transition (phase_transition) — mention the behavior and its new phase (red, green, refactor, etc.).
• A behavior or goal finishes (behavior_completed, goal_completed) — confirm completion; for goal_completed note the finished behaviors.
• A behavior or goal is abandoned (behavior_abandoned, goal_abandoned) — surface the reason.
• Blocked (blocked) — surface reason and failureSignatureHash prominently; this is the one event class worth calling out even mid-narration.
• Session complete (session_complete) — summarize the outcome (succeeded / blocked / abandoned) and the goals covered.

Secondary path: poll tdd_task (action: get)(id) whenever you need the current phase/goals state — for example when the subagent's narration is quiet for a stretch, or before reporting status to the user. It returns the full goal+behavior tree so you can rebuild the shape from a single read. (tdd_task (action: resume)(id) returns only a short status summary; reach for tdd_task (action: get) when you need the tree.) Between narration and polling, wait for the background completion notification to know the dispatch has finished.

Optional: mirror into a task panel (only when the host session has the Task tools — often it doesn't)

When TaskCreate/TaskUpdate are available, you may additionally render a task panel from the same channel events, in parallel with the narration above. The orchestrator's three-tier hierarchy (objective → goals → behaviors) renders flat in the task list — TaskCreate does not nest cleanly past one parent, so encode the goal index in the task label as [G<n>.B<m>] <behavior> rather than building a 3-level tree.

Maintain three pieces of state per session:

• parentTaskId — the parent TDD Session: {objective} task, if one was captured at dispatch (see step 3 above). Optional — leave unset otherwise.
• goalById: Map<goalId, { ordinal, taskId? }> — goal metadata. Goal-level events render as marker tasks (e.g. --- Goal 1 done ---) inserted between behavior groups; goal status is conveyed via the marker, not a real task.
• behaviorById: Map<behaviorId, { goalOrdinal, behaviorOrdinal, taskId }> — keyed lookup for behavior-level updates.

Event → action mapping:

type	Action
goals_ready	Record each {id, ordinal, goal} in goalById. No tasks yet — wait for behaviors_ready.
goal_added	Append the new goal to goalById.
goal_started	No-op.
behaviors_ready	Record each behavior's ordinals in behaviorById. No tasks yet — task creation is deferred to behavior_started so abandoned sessions don't leave orphaned pending tasks.
behavior_added	Append { goalOrdinal, behaviorOrdinal } to behaviorById. No task yet.
behavior_started	TaskCreate({ subject: "[G<n>.B<m>] <behavior>", description: "...", activeForm: "Running behavior" }) — store the returned task id in behaviorById, then TaskUpdate({ id: <taskId>, status: "in_progress" }).
phase_transition	TaskUpdate({ id: <behavior taskId>, content: "[G<n>.B<m>] <behavior> · <toPhase>" }).
behavior_completed	TaskUpdate({ id: <behavior taskId>, status: "completed" }).
behavior_abandoned	TaskUpdate({ id: <behavior taskId>, status: "cancelled" }); surface the reason.
goal_completed	Reconcile against behaviorIds[] (mark any still-pending child completed — catches dropped behavior_completed events). Then TaskCreate({ content: "--- Goal <goalOrdinal+1> done ---", status: "completed", parentTaskId }) as a marker.
goal_abandoned	Same reconcile but mark unfinished children cancelled. Insert marker --- Goal <goalOrdinal+1> abandoned: <reason> ---.
blocked	TaskUpdate({ id: <behavior taskId>, status: "blocked" }); surface reason and failureSignatureHash.
session_complete	Reconcile against goalIds[] (catch dropped goal_completed events). TaskUpdate({ id: parentTaskId, status: "completed" }) (or cancelled if outcome is abandoned).

Session hygiene (main agent)

When the run finishes — the background completion notification arrives, or tdd_task (action: get) shows the session ended — clean up the agent you dispatched. A plain background subagent completes on its own, but if you spawned a named or otherwise persistent agent, or you are ending the run early, stop it with TaskStop so it does not linger idle. Do not leave dispatched agents running once you have their result.

If your session has terminal-automation tools available (for example the it2 iTerm integration), you may use them to give the user a clean visual view of the run — dedicate a pane or window to the orchestrator and tidy it up when the run completes. This is optional and best-effort: reach for it only when those tools are present, and never let window management block or delay the TDD work itself.

---

Hard Gate 1 — tdd_task (action: start)

Skipping this gate is the UNREGISTERED SESSION violation. This is the first action. Before any file read or write toward the goal:

tdd_task (action: start)({ goal, chatId, runId })

Without a session ID there is no TDD session. Every phase artifact is homeless. RED-phase test failures are misclassified as flaky (the DB sees repeated failures with no session context and computes a low pass rate). acceptance_metrics returns 0% because zero evidence is bound to any session.

The chatId and runId are normally passed in your launch prompt. When they are, use both exactly as given — do not call inventory (kind: session) to derive chatId and do not generate a new runId; both come from the main agent and bind you to its session.

If your launch prompt has no chatId (a raw or programmatic dispatch that skipped the bootstrap), you are running as a detached session with no parent link. In that case only: recover your own chatId via inventory (kind: session)({ agentKind: "main", limit: 1 }) — the first row is your own just-registered session — and generate your own runId. Do not guess or borrow another session's chatId: opening the task against a session whose artifacts you do not produce splits attribution and makes every phase gate deny. Self-bootstrapping into your own session keeps the task and its artifacts co-located, so the gates work.

Hard Gate 2 — hypothesis (action: record) before every production edit

Skipping this gate is the UNCITED FIX violation.

REQUIRED SUB-SKILL: vitest-agent:record-hypothesis-before-fix

Before editing any non-test file, call:

hypothesis (action: record)({
  content: "<causal claim: why this edit will make the test pass>",
  citedTestErrorId: <id from test_errors output>,
  citedStackFrameId: <id from test_errors output>
})

Do not pass a sessionId here. The MCP server resolves the binding session automatically from the recovered host context (your running subagent session), so any sessionId you supply is ignored. Passing the tddTaskId under a sessionId key — an easy slip after the goal/behavior calls — would mis-attribute the hypothesis if it were honored; the server now prevents it.

Both citedTestErrorId and citedStackFrameId are required — they prove the hypothesis addresses a specific observed failure. A hypothesis without cited evidence is a guess.

• "Fix the validation" — not a hypothesis
• "The bounds check at line 42 runs after the index access, causing TypeError on index N" — is a hypothesis

After the fix: hypothesis (action: validate)({ id, outcome: "confirmed" | "refuted" | "abandoned" }).

Hard Gate 3 — tdd_phase_transition_request

Skipping this gate is the UNRECORDED PHASE CHANGE violation. At every RED→GREEN and GREEN→REFACTOR boundary:

tdd_phase_transition_request({
  tddTaskId: <id>,
  goalId: <id>,
  requestedPhase: "green" | "refactor",
  citedArtifactId: <tdd_artifacts.id>
})

Phase boundaries without MCP confirmation do not exist in the database. The validator enforces evidence-binding rules (D2): the cited artifact must itself have been recorded in the current phase (not replayed from an earlier, closed phase) and its test must have been authored in this session. A test first written and run before you requested red is fine — the artifact you cite just has to come from a run inside red. If the validator denies, read the remediation field and act on it before retrying. Do not advance the phase unilaterally.

Two cross-behavior moves are first-class — request each in one call with citedArtifactId omitted (auto-resolution finds the row):

• Triangulation. When one implementation satisfies several behaviors, enter red.triangulate (not red) for each. Later members' tests pass immediately (no own failing run) — request red.triangulate→green with the member's behaviorId; the batch's real failing run is accepted (phase-window and behavior-match are waived for this transition). Do not skip green with a red→refactor jump — the validator denies red→refactor, red.triangulate→refactor, and spike→refactor outright with denialReason: 'refactor_without_passing_run', even when a valid test_passed_run from another behavior is cited (issue #361). refactor is only reachable from green or green.fake-it.
• Next behavior. Cross a behavior boundary with a single refactor→red carrying the new behaviorId; the prior behavior's test_passed_run is accepted because refactor→red does not enforce behavior-match. No refactor→red-then-red→red rebind dance.

---

Observed Rationalizations (baseline session, 2026-05-04)

These are the exact behaviors from the previous orchestrator session. All four are violations:

What the orchestrator did	Named violation	Consequence
Fixed bugs without calling tdd_task (action: start)	UNREGISTERED SESSION	acceptance_metrics 0%; RED failures classified as flaky (67% pass rate)
Edited production code without hypothesis (action: record)	UNCITED FIX	No causal evidence bound to the fix; hypothesis audit is empty
Advanced phases without tdd_phase_transition_request	UNRECORDED PHASE CHANGE	DB has no phase record; evidence-based transitions cannot validate
Used pnpm vitest run via Bash instead of run_tests MCP	SESSION BYPASS	Results bypass persistence; test_history and phase artifacts are not written

Violating the letter of these rules IS violating the spirit of these rules.

---

Red Flags — STOP before continuing

If you are about to...	Required action
Write any file before tdd_task (action: start) returned a session ID	STOP — UNREGISTERED SESSION. Call tdd_task (action: start) first.
Edit any production file without a recorded hypothesis	STOP — UNCITED FIX. Call hypothesis (action: record) first.
Begin the next phase without tdd_phase_transition_request	STOP — UNRECORDED PHASE CHANGE. Request the transition first.
Run vitest, pnpm vitest, npx vitest, or any Bash test runner	STOP — SESSION BYPASS. Use run_tests MCP instead.
"Skip setup just this once, the goal is simple"	UNREGISTERED SESSION + UNCITED FIX combined. No exceptions.
Call inventory (kind: session) to find your chatId when one was passed	STOP — the chatId is in your launch prompt. Use it directly. (Only self-recover via inventory when the prompt genuinely has no chatId — see Gate 1.)