@vitest-agent/mcp 4.3.1 → 5.0.0

package/tools/hypothesis.js

@@ -1,9 +1,9 @@
 import { McpSession } from "../session.js";
 import { IdempotentReplayMarker } from "../utils/replay-marker.js";
+import { McpToolkit, ToolOutputSchema, ToolRefusal } from "@effected/mcp";
 import { Effect, Match, Option, Schema } from "effect";
 import { DataReader, DataStore } from "@vitest-agent/engine";
 import { Tool } from "effect/unstable/ai";
-import { DataStoreError } from "@vitest-agent/sdk";
 
 //#region src/tools/hypothesis.ts
 const HypothesisRowSchema = Schema.Struct({
@@ -32,11 +32,11 @@ const HypothesisListOk = Schema.Struct({
 	count: Schema.Number,
 	hypotheses: Schema.Array(HypothesisRowSchema)
 });
-const HypothesisResult = Schema.Union([
+const HypothesisResult = ToolOutputSchema.objectRooted(Schema.Union([
 	HypothesisRecordOk,
 	HypothesisValidateOk,
 	HypothesisListOk
-]).annotate({
+])).annotate({
 	identifier: "HypothesisResult",
 	title: "hypothesis result",
 	description: "Discriminate on `action`. record returns the new id; list returns the matching rows; validate returns an empty acknowledgement."
@@ -85,9 +85,11 @@ const HypothesisInput = Schema.Union([
 	ListVariant
 ]);
 /**
-* Handler for {@link hypothesisTool}. `record` fails (as a defect, so it
-* reaches the agent as the `UnexpectedToolError` envelope) when the
-* binding session cannot be resolved.
+* Handler for {@link hypothesisTool}. `record` fails with a
+* {@link ToolRefusal} (an `isError` result naming the fix) when the binding
+* session cannot be resolved: an unknown `tddTaskId`, an unknown fallback
+* `sessionId`, or no session at all; `validate` does for an unknown id. Any
+* other store failure is a defect.
 *
 * @public
 */
@@ -99,10 +101,13 @@ const handleHypothesis = (input) => Match.value(input).pipe(Match.discriminators
 		let resolvedSessionId;
 		if (variant.tddTaskId !== void 0) {
 			const bound = yield* reader.getSessionByTddTaskId(variant.tddTaskId);
-			if (Option.isNone(bound)) return yield* Effect.fail(new DataStoreError({
-				operation: "write",
-				table: "hypotheses",
-				reason: `unknown tddTaskId ${variant.tddTaskId}: no session found to attribute hypothesis`
+			if (Option.isNone(bound)) return yield* Effect.fail(ToolRefusal.refuse(`Unknown tddTaskId ${variant.tddTaskId}: no session to attribute the hypothesis to.`, {
+				hint: "Pass the tddTaskId returned by tdd_task action='start' (tdd_task action='get' confirms it exists).",
+				suggestedTool: "tdd_task",
+				suggestedArgs: {
+					action: "get",
+					tddTaskId: variant.tddTaskId
+				}
 			}));
 			resolvedSessionId = bound.value.id;
 		} else {
@@ -115,10 +120,15 @@ const handleHypothesis = (input) => Match.value(input).pipe(Match.discriminators
 					resolvedSessionId = Option.isSome(sub) ? sub.value.id : main.value.id;
 				}
 			}
-			if (resolvedSessionId === void 0) return yield* Effect.fail(new DataStoreError({
-				operation: "write",
-				table: "hypotheses",
-				reason: "no recovered session context: pass tddTaskId (the id returned by tdd_task action:start) to bind this hypothesis to your task's session — do not retry with a raw sessionId, and never pass tddTaskId under a sessionId key"
+			if (resolvedSessionId === void 0) return yield* Effect.fail(ToolRefusal.refuse("No session to attribute the hypothesis to: no host session context was recovered.", {
+				hint: "Pass tddTaskId (the id returned by tdd_task action='start') to bind this hypothesis to your task's session; do not retry with a raw sessionId, and never pass tddTaskId under a sessionId key.",
+				suggestedTool: "tdd_task",
+				suggestedArgs: { action: "start" }
+			}));
+			if (resolvedSessionId === variant.sessionId && Option.isNone(yield* reader.getSessionById(resolvedSessionId))) return yield* Effect.fail(ToolRefusal.refuse(`Unknown sessionId ${resolvedSessionId}.`, {
+				hint: "Pass tddTaskId (the id returned by tdd_task action='start') instead of a raw sessionId.",
+				suggestedTool: "tdd_task",
+				suggestedArgs: { action: "start" }
 			}));
 		}
 		return {
@@ -138,7 +148,11 @@ const handleHypothesis = (input) => Match.value(input).pipe(Match.discriminators
 			outcome: variant.outcome,
 			validatedAt: variant.validatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
 			...variant.validatedTurnId !== void 0 && { validatedTurnId: variant.validatedTurnId }
-		});
+		}).pipe(Effect.catchIf((error) => error.reason.startsWith("unknown hypothesis id"), () => Effect.fail(ToolRefusal.refuse(`Unknown hypothesis id ${variant.id}.`, {
+			hint: "Use the id hypothesis action='record' returned, or find it with hypothesis action='list'.",
+			suggestedTool: "hypothesis",
+			suggestedArgs: { action: "list" }
+		}))));
 		return { action: "validate" };
 	}),
 	list: (variant) => Effect.gen(function* () {
@@ -153,22 +167,18 @@ const handleHypothesis = (input) => Match.value(input).pipe(Match.discriminators
 			hypotheses: rows
 		};
 	})
-})).pipe(Effect.orDie);
+})).pipe(Effect.catchTag("DataStoreError", Effect.die));
 /**
 * The Effect-native `hypothesis` tool.
 *
 * @public
 */
-const hypothesisTool = Tool.make("hypothesis", {
+const hypothesisTool = McpToolkit.unionTool("hypothesis", {
 	description: "Use to manage debugging hypotheses, with a CRUD action discriminator: action='record' (content, tddTaskId?, optional citation ids) writes a hypothesis — the binding session is resolved server-side from the recovered host context (active TDD subagent, else main session); pass tddTaskId (returned by tdd_task action='start') to bind deterministically to that task's session, and do not pass sessionId when recording; action='validate' (id, outcome, validatedAt?) records a validation outcome — validatedAt is optional and defaults server-side to now when omitted, or is honored verbatim when supplied; action='list' (sessionId?, outcome?, limit?) returns matching hypotheses.",
 	parameters: HypothesisInput,
 	success: HypothesisResult,
-	dependencies: [
-		DataReader,
-		DataStore,
-		McpSession
-	]
-}).annotate(Tool.Title, "Hypothesis").annotate(Tool.Readonly, false).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, false);
+	failure: ToolRefusal
+}).addDependency(DataReader).addDependency(DataStore).addDependency(McpSession).annotate(Tool.Title, "Hypothesis").annotate(Tool.Readonly, false).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, false);
 
 //#endregion
 export { HypothesisInput, HypothesisResult, handleHypothesis, hypothesisTool };

package/tools/inventory.js

@@ -1,4 +1,5 @@
 import { collectProjectRows, resolveProjectTargets } from "./_project-groups.js";
+import { McpToolkit, ToolOutputSchema, ToolRefusal } from "@effected/mcp";
 import { Effect, Match, Option, Schema } from "effect";
 import { DataReader } from "@vitest-agent/engine";
 import { Tool } from "effect/unstable/ai";
@@ -114,7 +115,7 @@ const TagInventoryUnscoped = Schema.Struct({
 *
 * @public
 */
-const InventoryResult = Schema.Union([
+const InventoryResult = ToolOutputSchema.objectRooted(Schema.Union([
 	ProjectInventory,
 	ModuleInventory,
 	SuiteInventory,
@@ -123,7 +124,7 @@ const InventoryResult = Schema.Union([
 	SessionListInventory,
 	TagInventoryScoped,
 	TagInventoryUnscoped
-]).annotate({
+])).annotate({
 	identifier: "InventoryResult",
 	title: "inventory result",
 	description: "Discriminate on `inventoryKind`. project/module/suite carry counted lists; session_detail discriminates further on `found`; session_list returns the matching sessions; tag_scoped and tag_unscoped carry per-tag counts (the unscoped form also carries a `byProject` breakdown per tag)."
@@ -291,12 +292,12 @@ const handleInventory = (input) => Match.value(input).pipe(Match.discriminatorsE
 *
 * @public
 */
-const inventoryTool = Tool.make("inventory", {
+const inventoryTool = McpToolkit.unionTool("inventory", {
 	description: "Use to discover what exists in the workspace, with a kind discriminator: project / module / suite / session / tag. structuredContent discriminates on `inventoryKind` (project, module, suite, session_detail, session_list, tag_scoped, tag_unscoped) so callers can branch on the response shape without parsing markdown.",
 	parameters: InventoryInput,
 	success: InventoryResult,
-	dependencies: [DataReader]
-}).annotate(Tool.Title, "Inventory").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true);
+	failure: ToolRefusal
+}).addDependency(DataReader).annotate(Tool.Title, "Inventory").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true);
 
 //#endregion
 export { InventoryInput, InventoryResult, handleInventory, inventoryTool };

package/tools/note.js

@@ -1,3 +1,4 @@
+import { McpToolkit, ToolOutputSchema, ToolRefusal } from "@effected/mcp";
 import { Effect, Match, Option, Schema } from "effect";
 import { DataReader, DataStore } from "@vitest-agent/engine";
 import { Tool } from "effect/unstable/ai";
@@ -64,7 +65,7 @@ const NoteSearchOk = Schema.Struct({
 *
 * @public
 */
-const NoteResult = Schema.Union([
+const NoteResult = ToolOutputSchema.objectRooted(Schema.Union([
 	NoteCreateOk,
 	NoteListOk,
 	NoteGetFound,
@@ -72,7 +73,7 @@ const NoteResult = Schema.Union([
 	NoteUpdateOk,
 	NoteDeleteOk,
 	NoteSearchOk
-]).annotate({
+])).annotate({
 	identifier: "NoteResult",
 	title: "note result",
 	description: "Discriminate on `action`. `get` further discriminates on `found`."
@@ -210,12 +211,12 @@ const handleNote = (input) => Match.value(input).pipe(Match.discriminatorsExhaus
 *
 * @public
 */
-const noteTool = Tool.make("note", {
+const noteTool = McpToolkit.unionTool("note", {
 	description: "Use to manage notes, with a CRUD action discriminator: action='create' writes a scoped note; action='list' (scope?, project?, testFullName?) returns matching notes; action='get' (id) returns a structured note; action='update' (id, ...patch) edits; action='delete' (id) removes; action='search' (query) does FTS5 across title and content. structuredContent always carries the typed result (discriminate on `action`).",
 	parameters: NoteParams,
 	success: NoteResult,
-	dependencies: [DataReader, DataStore]
-}).annotate(Tool.Title, "Note").annotate(Tool.Readonly, false).annotate(Tool.Destructive, true).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, false);
+	failure: ToolRefusal
+}).addDependency(DataReader).addDependency(DataStore).annotate(Tool.Title, "Note").annotate(Tool.Readonly, false).annotate(Tool.Destructive, true).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, false);
 
 //#endregion
 export { NoteParams, NoteResult, handleNote, noteTool };

package/tools/overview.js

@@ -1,3 +1,4 @@
+import { ToolOutputSchema } from "@effected/mcp";
 import { Effect, Option, Schema } from "effect";
 import { DataReader } from "@vitest-agent/engine";
 import { Tool } from "effect/unstable/ai";
@@ -34,7 +35,7 @@ const OverviewAbsent = Schema.Struct({
 *
 * @public
 */
-const TestOverviewResult = Schema.Union([OverviewAvailable, OverviewAbsent]).annotate({
+const TestOverviewResult = ToolOutputSchema.objectRooted(Schema.Union([OverviewAvailable, OverviewAbsent])).annotate({
 	identifier: "TestOverviewResult",
 	title: "test_overview result",
 	description: "Per-project run metrics. Discriminate on `dataAvailable` for cold-start handling."

package/tools/ping.js

@@ -1,5 +1,6 @@
-import { Effect, Schema } from "effect";
+import { Effect, Option, Schema } from "effect";
 import { Tool } from "effect/unstable/ai";
+import { CurrentDistribution, DistributionField } from "@effected/engine";
 
 //#region src/tools/ping.ts
 /**
@@ -7,10 +8,13 @@ import { Tool } from "effect/unstable/ai";
 *
 * @public
 */
-const PingResult = Schema.Struct({ message: Schema.Literal("pong").annotate({ description: "Constant `pong`. Presence confirms the MCP server responded." }) }).annotate({
+const PingResult = Schema.Struct({
+	message: Schema.Literal("pong").annotate({ description: "Constant `pong`. Presence confirms the MCP server responded." }),
+	distribution: DistributionField.annotate({ description: "The package that shipped this bin (`{ name, version }`, e.g. `@vitest-agent/plugin`), or null when `@vitest-agent/mcp` was launched directly. Packaging provenance, not a version to compare." })
+}).annotate({
 	identifier: "PingResult",
 	title: "ping result",
-	description: "Liveness probe. Carries no data beyond the constant `pong` discriminant."
+	description: "Liveness probe: the constant `pong`, plus the distribution the server was launched through."
 });
 /**
 * The Effect-native `ping` tool. No parameters (the default
@@ -20,7 +24,7 @@ const PingResult = Schema.Struct({ message: Schema.Literal("pong").annotate({ de
 * @public
 */
 const pingTool = Tool.make("ping", {
-	description: "Ping the MCP server — returns 'pong'. Used to verify hot-patch reload.",
+	description: "Ping the MCP server — returns 'pong' and the distribution (carrier package) it was launched through. Used to verify hot-patch reload.",
 	success: PingResult
 }).annotate(Tool.Title, "Ping").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true);
 /**
@@ -28,7 +32,13 @@ const pingTool = Tool.make("ping", {
 *
 * @public
 */
-const handlePing = () => Effect.succeed({ message: "pong" });
+const handlePing = () => Effect.gen(function* () {
+	const distribution = yield* CurrentDistribution;
+	return {
+		message: "pong",
+		distribution: Option.getOrNull(distribution)
+	};
+});
 
 //#endregion
 export { PingResult, handlePing, pingTool };

package/tools/register-agent.js

@@ -1,3 +1,4 @@
+import { ToolOutputSchema } from "@effected/mcp";
 import { Effect, Option, Schema } from "effect";
 import { DataReader, DataStore, deriveIdempotencyKey } from "@vitest-agent/engine";
 import { Tool } from "effect/unstable/ai";
@@ -75,7 +76,7 @@ const RegisterAgentFailure = Schema.Struct({
 *
 * @public
 */
-const RegisterAgentResult = Schema.Union([RegisterAgentSuccess, RegisterAgentFailure]).annotate({
+const RegisterAgentResult = ToolOutputSchema.objectRooted(Schema.Union([RegisterAgentSuccess, RegisterAgentFailure])).annotate({
 	identifier: "RegisterAgentResult",
 	title: "register_agent result",
 	description: "Discriminate on `ok`. The four failure codes are documented per their `code` literal."

package/tools/run-tests.js

@@ -1,5 +1,6 @@
 import { McpSession } from "../session.js";
 import { createRequire } from "node:module";
+import { ToolOutputSchema } from "@effected/mcp";
 import { Data, Effect, Schema, Semaphore } from "effect";
 import { DataReader, DataStore } from "@vitest-agent/engine";
 import { Tool } from "effect/unstable/ai";
@@ -64,12 +65,12 @@ const RunTestsNoMatch = Schema.Struct({
 *
 * @public
 */
-const RunTestsResult = Schema.Union([
+const RunTestsResult = ToolOutputSchema.objectRooted(Schema.Union([
 	RunTestsOk,
 	RunTestsTimeout,
 	RunTestsError,
 	RunTestsNoMatch
-]).annotate({
+])).annotate({
 	identifier: "RunTestsResult",
 	title: "run_tests result",
 	description: "Discriminate on `kind`. ok carries the full AgentReport plus per-test classifications; timeout / error are the two failure modes; no-match indicates that the resolved filter set matched zero test cases."
@@ -420,13 +421,22 @@ const makeBestEffortFork = (services) => (effect) => Effect.runFork(Effect.provi
 * `{ kind: "error" }` envelope, so it never rejects.
 */
 const runTestsBody = async (input, ctx) => {
-	const files = input.files ? sanitizeTestArgs(input.files) : [];
-	const project = input.project ? sanitizeTestArgs([input.project])[0] : void 0;
+	let files;
+	let project;
 	const tagsInput = input.tags;
-	if (tagsInput) {
-		if (tagsInput.all) sanitizeTestArgs(tagsInput.all);
-		if (tagsInput.any) sanitizeTestArgs(tagsInput.any);
-		if (tagsInput.none) sanitizeTestArgs(tagsInput.none);
+	try {
+		files = input.files ? sanitizeTestArgs(input.files) : [];
+		project = input.project ? sanitizeTestArgs([input.project])[0] : void 0;
+		if (tagsInput) {
+			if (tagsInput.all) sanitizeTestArgs(tagsInput.all);
+			if (tagsInput.any) sanitizeTestArgs(tagsInput.any);
+			if (tagsInput.none) sanitizeTestArgs(tagsInput.none);
+		}
+	} catch (err) {
+		return {
+			kind: "error",
+			message: err instanceof Error ? err.message : String(err)
+		};
 	}
 	const resolvedExpression = composeTagExpression(tagsInput ?? null);
 	const hasFilter = files.length > 0 || project !== void 0 || resolvedExpression !== null;

package/tools/status.js

@@ -1,3 +1,4 @@
+import { ToolOutputSchema } from "@effected/mcp";
 import { Effect, Option, Schema } from "effect";
 import { DataReader } from "@vitest-agent/engine";
 import { Tool } from "effect/unstable/ai";
@@ -20,7 +21,7 @@ const StatusAbsent = Schema.Struct({
 *
 * @public
 */
-const TestStatusResult = Schema.Union([StatusAvailable, StatusAbsent]).annotate({
+const TestStatusResult = ToolOutputSchema.objectRooted(Schema.Union([StatusAvailable, StatusAbsent])).annotate({
 	identifier: "TestStatusResult",
 	title: "test_status result",
 	description: "Per-project last-run summary. Discriminate on `dataAvailable` for cold-start handling."

package/tools/tdd-behavior.js

@@ -1,9 +1,11 @@
 import { IdempotentReplayMarker } from "../utils/replay-marker.js";
 import { catchTddErrorsAsEnvelope } from "./_tdd-error-envelope.js";
+import { McpToolkit, ToolOutputSchema, ToolRefusal } from "@effected/mcp";
 import { Effect, Match, Option, Schema } from "effect";
 import { DataReader, DataStore } from "@vitest-agent/engine";
 import { Tool } from "effect/unstable/ai";
 import { BehaviorDetail, BehaviorRow } from "@vitest-agent/sdk";
+import { Remediation } from "@effected/engine";
 
 //#region src/tools/tdd-behavior.ts
 /**
@@ -25,11 +27,7 @@ const TddBehaviorErrorEnvelope = Schema.Struct({
 	ok: Schema.Literal(false).annotate({ description: "Discriminant — `false` when a tagged TDD error was caught." }),
 	error: Schema.StructWithRest(Schema.Struct({
 		_tag: Schema.String.annotate({ description: "Tagged error name (e.g. BehaviorNotFoundError, GoalNotFoundError)." }),
-		remediation: Schema.Struct({
-			suggestedTool: Schema.String,
-			suggestedArgs: Schema.Record(Schema.String, Schema.Unknown),
-			humanHint: Schema.String
-		}).annotate({ description: "Suggested next action: the tool to call, its arguments, and a plain-language hint." })
+		remediation: Remediation.annotate({ description: "Suggested next action: a plain-language hint, the tool to call, and its arguments." })
 	}), [Schema.Record(Schema.String, Schema.Unknown)])
 }).annotate({ identifier: "TddBehaviorErrorEnvelope" });
 const TddBehaviorCreateOk = Schema.Struct({
@@ -70,7 +68,7 @@ const TddBehaviorListByTddTaskOk = Schema.Struct({
 	tddTaskId: Schema.Number,
 	behaviors: Schema.Array(BehaviorRow)
 });
-const TddBehaviorResult = Schema.Union([
+const TddBehaviorResult = ToolOutputSchema.objectRooted(Schema.Union([
 	TddBehaviorCreateOk,
 	TddBehaviorUpdateOk,
 	TddBehaviorDeleteOk,
@@ -79,7 +77,7 @@ const TddBehaviorResult = Schema.Union([
 	TddBehaviorListByGoalOk,
 	TddBehaviorListByTddTaskOk,
 	TddBehaviorErrorEnvelope
-]).annotate({
+])).annotate({
 	identifier: "TddBehaviorResult",
 	title: "tdd_behavior result",
 	description: "Discriminate on `action` (or `ok=false` for the tagged-error envelope)."
@@ -210,12 +208,12 @@ const handleTddBehavior = (input) => Match.value(input).pipe(Match.discriminator
 *
 * @public
 */
-const tddBehaviorTool = Tool.make("tdd_behavior", {
+const tddBehaviorTool = McpToolkit.unionTool("tdd_behavior", {
 	description: "Use to manage TDD behaviors, with a CRUD action discriminator: action='create' (goalId, behavior, suggestedTestName?, dependsOnBehaviorIds?) is idempotent on (goalId, behavior); action='update' (id, ...patch) edits; action='delete' (id) hard-deletes; action='get' (id) reads; action='list_by_goal' (goalId) lists one goal's behaviors; action='list_by_tdd_task' (tddTaskId) lists across all goals.",
 	parameters: TddBehaviorInput,
 	success: TddBehaviorResult,
-	dependencies: [DataReader, DataStore]
-}).annotate(Tool.Title, "TDD behavior").annotate(Tool.Readonly, false).annotate(Tool.Destructive, true).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, false);
+	failure: ToolRefusal
+}).addDependency(DataReader).addDependency(DataStore).annotate(Tool.Title, "TDD behavior").annotate(Tool.Readonly, false).annotate(Tool.Destructive, true).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, false);
 
 //#endregion
 export { TddBehaviorInput, TddBehaviorResult, handleTddBehavior, tddBehaviorTool };

package/tools/tdd-goal.js

@@ -1,9 +1,11 @@
 import { IdempotentReplayMarker } from "../utils/replay-marker.js";
 import { catchTddErrorsAsEnvelope } from "./_tdd-error-envelope.js";
+import { McpToolkit, ToolOutputSchema, ToolRefusal } from "@effected/mcp";
 import { Effect, Match, Option, Schema } from "effect";
 import { DataReader, DataStore } from "@vitest-agent/engine";
 import { Tool } from "effect/unstable/ai";
 import { GoalDetail, GoalRow } from "@vitest-agent/sdk";
+import { Remediation } from "@effected/engine";
 
 //#region src/tools/tdd-goal.ts
 /**
@@ -25,11 +27,7 @@ const TddErrorEnvelope = Schema.Struct({
 	ok: Schema.Literal(false).annotate({ description: "Discriminant — `false` when a tagged TDD error was caught." }),
 	error: Schema.StructWithRest(Schema.Struct({
 		_tag: Schema.String.annotate({ description: "Tagged error name (e.g. GoalNotFoundError, TddTaskNotFoundError)." }),
-		remediation: Schema.Struct({
-			suggestedTool: Schema.String,
-			suggestedArgs: Schema.Record(Schema.String, Schema.Unknown),
-			humanHint: Schema.String
-		}).annotate({ description: "Suggested next action: the tool to call, its arguments, and a plain-language hint." })
+		remediation: Remediation.annotate({ description: "Suggested next action: a plain-language hint, the tool to call, and its arguments." })
 	}), [Schema.Record(Schema.String, Schema.Unknown)])
 }).annotate({ identifier: "TddErrorEnvelope" });
 const TddGoalCreateOk = Schema.Struct({
@@ -64,7 +62,7 @@ const TddGoalListOk = Schema.Struct({
 	tddTaskId: Schema.Number,
 	goals: Schema.Array(GoalDetail).annotate({ description: "All goals for the TDD task, with their behaviors." })
 }).annotate({ identifier: "TddGoalListOk" });
-const TddGoalResult = Schema.Union([
+const TddGoalResult = ToolOutputSchema.objectRooted(Schema.Union([
 	TddGoalCreateOk,
 	TddGoalUpdateOk,
 	TddGoalDeleteOk,
@@ -72,7 +70,7 @@ const TddGoalResult = Schema.Union([
 	TddGoalGetMissing,
 	TddGoalListOk,
 	TddErrorEnvelope
-]).annotate({
+])).annotate({
 	identifier: "TddGoalResult",
 	title: "tdd_goal result",
 	description: "Discriminate first on `action` (or on `ok=false` for the tagged-error envelope). Get returns `found:true|false`; create/update/delete/list return `ok:true` on success."
@@ -178,12 +176,12 @@ const handleTddGoal = (input) => Match.value(input).pipe(Match.discriminatorsExh
 *
 * @public
 */
-const tddGoalTool = Tool.make("tdd_goal", {
+const tddGoalTool = McpToolkit.unionTool("tdd_goal", {
 	description: "Use to manage TDD goals, with a CRUD action discriminator: action='create' (tddTaskId, goal) is idempotent on (tddTaskId, goal); action='update' (id, goal?, status?) edits text and/or lifecycle status; action='delete' (id) hard-deletes (prefer status:'abandoned'); action='get' (id) reads with nested behaviors; action='list' (tddTaskId) returns all goals for a TDD task.",
 	parameters: TddGoalInput,
 	success: TddGoalResult,
-	dependencies: [DataReader, DataStore]
-}).annotate(Tool.Title, "TDD goal").annotate(Tool.Readonly, false).annotate(Tool.Destructive, true).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, false);
+	failure: ToolRefusal
+}).addDependency(DataReader).addDependency(DataStore).annotate(Tool.Title, "TDD goal").annotate(Tool.Readonly, false).annotate(Tool.Destructive, true).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, false);
 
 //#endregion
 export { TddGoalInput, TddGoalResult, handleTddGoal, tddGoalTool };

package/tools/tdd-phase-transition-request.js

@@ -1,7 +1,9 @@
+import { ToolOutputSchema } from "@effected/mcp";
 import { Effect, Option, Schema } from "effect";
 import { DataReader, DataStore } from "@vitest-agent/engine";
 import { Tool } from "effect/unstable/ai";
 import { requiredArtifactForTransition, transitionEnforcesBehaviorMatch, validatePhaseTransition } from "@vitest-agent/sdk";
+import { Remediation } from "@effected/engine";
 
 //#region src/tools/tdd-phase-transition-request.ts
 /**
@@ -45,11 +47,7 @@ const denialReasonLiteral = Schema.Literals([
 	"evidence_not_for_behavior",
 	"evidence_test_was_already_failing"
 ]);
-const RemediationSchema = Schema.Struct({
-	suggestedTool: Schema.String.annotate({ description: "Next tool the agent should call to make progress." }),
-	suggestedArgs: Schema.Record(Schema.String, Schema.Unknown).annotate({ description: "Concrete arguments for `suggestedTool` that fix the underlying issue." }),
-	humanHint: Schema.String.annotate({ description: "Plain-language explanation of what to do next." })
-}).annotate({ identifier: "PhaseTransitionRemediation" });
+const RemediationSchema = Remediation.annotate({ description: "Suggested next action: `hint` explains what to do, `suggestedTool` is the tool to call next, and `suggestedArgs` its arguments." });
 const PhaseTransitionAccepted = Schema.Struct({
 	accepted: Schema.Literal(true).annotate({ description: "Discriminant — `true` when the transition was granted." }),
 	phase: phaseLiteral.annotate({ description: "Phase the session is now in (echo of `requestedPhase`)." }),
@@ -74,7 +72,7 @@ const PhaseTransitionDenied = Schema.Struct({
 *
 * @public
 */
-const PhaseTransitionResult = Schema.Union([PhaseTransitionAccepted, PhaseTransitionDenied]).annotate({
+const PhaseTransitionResult = ToolOutputSchema.objectRooted(Schema.Union([PhaseTransitionAccepted, PhaseTransitionDenied])).annotate({
 	identifier: "PhaseTransitionResult",
 	title: "tdd_phase_transition_request result",
 	description: "Discriminate on `accepted`. Acceptance carries the new phaseId; denial carries a typed reason and a remediation pointer."
@@ -124,7 +122,7 @@ const handlePhaseTransitionRequest = (input) => Effect.gen(function* () {
 				action: "list",
 				tddTaskId: input.tddTaskId
 			},
-			humanHint: `No tdd_session_goals row with id=${input.goalId}. Call tdd_goal({ action: "list" }) to find the correct goal id.`
+			hint: `No tdd_session_goals row with id=${input.goalId}. Call tdd_goal({ action: "list" }) to find the correct goal id.`
 		}
 	};
 	if (goalOpt.value.sessionId !== input.tddTaskId) return {
@@ -137,7 +135,7 @@ const handlePhaseTransitionRequest = (input) => Effect.gen(function* () {
 				action: "list",
 				tddTaskId: input.tddTaskId
 			},
-			humanHint: `Goal id=${input.goalId} belongs to TDD task ${goalOpt.value.sessionId}, not the requested tddTaskId=${input.tddTaskId}. Pass the tddTaskId of the goal's parent task, or pick a goal that belongs to the active task.`
+			hint: `Goal id=${input.goalId} belongs to TDD task ${goalOpt.value.sessionId}, not the requested tddTaskId=${input.tddTaskId}. Pass the tddTaskId of the goal's parent task, or pick a goal that belongs to the active task.`
 		}
 	};
 	if (goalOpt.value.status !== "in_progress") return {
@@ -150,7 +148,7 @@ const handlePhaseTransitionRequest = (input) => Effect.gen(function* () {
 				id: input.goalId,
 				status: "in_progress"
 			},
-			humanHint: `Goal id=${input.goalId} has status '${goalOpt.value.status}'. Phase transitions require the goal to be in_progress. Call tdd_goal_update({status:'in_progress'}) before requesting transitions.`
+			hint: `Goal id=${input.goalId} has status '${goalOpt.value.status}'. Phase transitions require the goal to be in_progress. Call tdd_goal_update({status:'in_progress'}) before requesting transitions.`
 		}
 	};
 	if (input.behaviorId !== void 0) {
@@ -165,7 +163,7 @@ const handlePhaseTransitionRequest = (input) => Effect.gen(function* () {
 					scope: "goal",
 					goalId: input.goalId
 				},
-				humanHint: `No tdd_session_behaviors row with id=${input.behaviorId}. Call tdd_behavior_list to find the correct behavior id.`
+				hint: `No tdd_session_behaviors row with id=${input.behaviorId}. Call tdd_behavior_list to find the correct behavior id.`
 			}
 		};
 		if (behaviorOpt.value.goalId !== input.goalId) return {
@@ -175,7 +173,7 @@ const handlePhaseTransitionRequest = (input) => Effect.gen(function* () {
 			remediation: {
 				suggestedTool: "tdd_behavior_get",
 				suggestedArgs: { id: input.behaviorId },
-				humanHint: `Behavior id=${input.behaviorId} belongs to goal ${behaviorOpt.value.goalId}, not the requested goalId=${input.goalId}. Pass the goalId of the behavior's parent goal.`
+				hint: `Behavior id=${input.behaviorId} belongs to goal ${behaviorOpt.value.goalId}, not the requested goalId=${input.goalId}. Pass the goalId of the behavior's parent goal.`
 			}
 		};
 	}
@@ -215,7 +213,7 @@ const handlePhaseTransitionRequest = (input) => Effect.gen(function* () {
 				remediation: {
 					suggestedTool: "run_tests",
 					suggestedArgs: {},
-					humanHint: crossSessionCount > 0 ? `${baseHint} ${crossSessionCount} artifact${crossSessionCount === 1 ? " was" : "s were"} recorded under a different session of this conversation in the last ${DIAGNOSTIC_WINDOW_MINUTES} minutes — the subagent's hooks may be attributing to a detached session; set VITEST_AGENT_TDD_TASK_ID=${input.tddTaskId} in the subagent's environment or dispatch it as an unnamed background subagent.` : baseHint
+					hint: crossSessionCount > 0 ? `${baseHint} ${crossSessionCount} artifact${crossSessionCount === 1 ? " was" : "s were"} recorded under a different session of this conversation in the last ${DIAGNOSTIC_WINDOW_MINUTES} minutes — the subagent's hooks may be attributing to a detached session; set VITEST_AGENT_TDD_TASK_ID=${input.tddTaskId} in the subagent's environment or dispatch it as an unnamed background subagent.` : baseHint
 				}
 			};
 		}
@@ -231,7 +229,7 @@ const handlePhaseTransitionRequest = (input) => Effect.gen(function* () {
 			remediation: {
 				suggestedTool: "run_tests",
 				suggestedArgs: {},
-				humanHint: `Cited artifact id ${resolvedArtifactId} does not exist. Artifacts are recorded by hooks observing your tool calls (Decision D7), so run the test (e.g. via the run_tests MCP tool) or make the file edit first; the post-tool-use hook will write the matching tdd_artifacts row and return its id, which can then be cited here.`
+				hint: `Cited artifact id ${resolvedArtifactId} does not exist. Artifacts are recorded by hooks observing your tool calls (Decision D7), so run the test (e.g. via the run_tests MCP tool) or make the file edit first; the post-tool-use hook will write the matching tdd_artifacts row and return its id, which can then be cited here.`
 			}
 		};
 		citedArtifact = artifactOpt.value;
@@ -257,7 +255,16 @@ const handlePhaseTransitionRequest = (input) => Effect.gen(function* () {
 		cited_artifact: citedArtifact,
 		requested_behavior_id: input.behaviorId ?? null
 	});
-	if (!result.accepted) return result;
+	if (!result.accepted) {
+		const { humanHint, ...remediation } = result.remediation;
+		return {
+			...result,
+			remediation: {
+				...remediation,
+				hint: humanHint
+			}
+		};
+	}
 	const out = yield* store.writeTddPhase({
 		tddTaskId: input.tddTaskId,
 		phase: result.phase,