docs: document status tool tests

src/agents/tools/assistant-phase-text.test.ts

@@ -1,3 +1,5 @@
+// Assistant phase text tests cover extracting final-answer text from signed
+// assistant message phases.
 import { describe, expect, it } from "vitest";
 import { extractAssistantText as extractChatHistoryAssistantText } from "./chat-history-text.js";
 import { extractAssistantText as extractSessionAssistantText } from "./session-message-text.js";
@@ -52,6 +54,8 @@ describe("phase-aware assistant text helpers", () => {
   }
 
   it("does not fall back to commentary when an explicit final_answer is empty", () => {
+    // An explicit empty final answer means there is no publishable response;
+    // commentary should stay private.
     const message = assistantMessage(
       assistantTextPart("commentary", "commentary", "Need simpler use cat overwrite full file."),
       assistantTextPart("final", "final_answer", "   "),

src/agents/tools/sessions-list-tool.test.ts

@@ -1,3 +1,5 @@
+// sessions_list tool tests cover session metadata projection, visibility
+// helpers, and numeric argument validation.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { createSessionsListTool } from "./sessions-list-tool.js";
 
@@ -69,6 +71,8 @@ describe("sessions-list-tool", () => {
   });
 
   it("keeps deliveryContext.threadId in sessions_list results", async () => {
+    // Thread/topic ids are required for channel-specific follow-up routing, so
+    // list results must preserve both string and numeric variants.
     mocks.gatewayCall.mockImplementation(async (opts: unknown) => {
       const request = opts as { method?: string };
       if (request.method === "sessions.list") {
@@ -200,6 +204,8 @@ describe("sessions-list-tool", () => {
     [{ messageLimit: 1.5 }, "messageLimit must be a non-negative integer"],
     [{ messageLimit: -1 }, "messageLimit must be a non-negative integer"],
   ])("rejects invalid numeric parameter %o", async (params, message) => {
+    // Reject before gateway dispatch so malformed limits cannot reach session
+    // store queries.
     const tool = createSessionsListTool({ config: {} as never });
 
     await expect(tool.execute("call-4", params)).rejects.toThrow(message);

src/agents/tools/sessions-yield-tool.test.ts

@@ -1,3 +1,5 @@
+// sessions_yield tool tests cover cooperative turn yielding and unsupported
+// context errors.
 import { describe, expect, it, vi } from "vitest";
 import { createSessionsYieldTool } from "./sessions-yield-tool.js";
 
@@ -30,6 +32,8 @@ describe("sessions_yield tool", () => {
   });
 
   it("passes the custom message through the yield callback", async () => {
+    // The callback message becomes operator-visible scheduler context, so the
+    // tool must not replace a supplied reason with the default text.
     const onYield = vi.fn();
     const tool = createSessionsYieldTool({ sessionId: "test-session", onYield });
     const result = await tool.execute("call-1", { message: "Waiting for fact-checker" });

src/agents/tools/update-plan-tool.test.ts

@@ -1,3 +1,4 @@
+// update_plan tool tests cover compact plan payloads and plan-shape validation.
 import { describe, expect, it } from "vitest";
 import { createUpdatePlanTool } from "./update-plan-tool.js";
 
@@ -26,6 +27,8 @@ describe("update_plan tool", () => {
   });
 
   it("rejects multiple in-progress steps", async () => {
+    // The UI and agent state assume one current step; multiple active steps
+    // make progress reporting ambiguous.
     const tool = createUpdatePlanTool();
 
     await expect(

src/agents/tools/web-shared.test.ts

@@ -1,3 +1,5 @@
+// Shared web helper tests cover timeout normalization and process-local cache
+// expiry guards.
 import {
   MAX_TIMER_TIMEOUT_MS,
   MAX_TIMER_TIMEOUT_SECONDS,
@@ -32,6 +34,8 @@ describe("web shared timeout seconds", () => {
   });
 
   it("drops cached values while the process clock is invalid", () => {
+    // Bad system clocks can make cache expiry nonsensical; fail closed instead
+    // of serving stale web data indefinitely.
     const cache = new Map<string, CacheEntry<string>>();
     writeCache(cache, "key", "old", 60_000);
     expect(readCache(cache, "key")?.value).toBe("old");