docs: document dispatch report helpers

src/agents/subagent-announce-dispatch.ts

@@ -1,4 +1,11 @@
+/**
+ * Subagent announcement dispatch strategy.
+ *
+ * Completion handoff and requester-visible replies use this to choose between
+ * steering a subagent and directly delivering a message, with phase evidence.
+ */
 type SubagentDeliveryPath = "steered" | "direct" | "none";
+/** Stable reasons an announcement delivery can fail without throwing. */
 export type SubagentAnnounceDeliveryFailureReason =
   | "completion_handoff_pending"
   | "generated_media_missing"
@@ -10,6 +17,7 @@ type SubagentAnnounceSteerOutcome =
   | { status: "steered"; deliveredAt?: number; enqueuedAt?: number }
   | { status: "none" | "dropped" };
 
+/** Result of trying to deliver a subagent announcement. */
 export type SubagentAnnounceDeliveryResult = {
   delivered: boolean;
   path: SubagentDeliveryPath;
@@ -33,6 +41,7 @@ type SubagentAnnounceDispatchPhaseResult = {
   error?: string;
 };
 
+/** Converts a steer outcome into the shared delivery result shape. */
 export function mapSteerOutcomeToDeliveryResult(
   outcome: SubagentAnnounceSteerOutcome,
 ): SubagentAnnounceDeliveryResult {
@@ -50,6 +59,7 @@ export function mapSteerOutcomeToDeliveryResult(
   };
 }
 
+/** Runs the ordered steer/direct announcement delivery strategy. */
 export async function runSubagentAnnounceDispatch(params: {
   expectsCompletionMessage: boolean;
   signal?: AbortSignal;
@@ -99,6 +109,8 @@ export async function runSubagentAnnounceDispatch(params: {
     return withPhases(primaryDirect);
   }
 
+  // Completion handoff prefers direct delivery first so the completion agent's
+  // final visible message wins before falling back to steering.
   const primaryDirect = await params.direct();
   appendPhase("direct-primary", primaryDirect);
   if (primaryDirect.delivered || primaryDirect.terminal) {

src/agents/system-prompt-report.ts

@@ -1,3 +1,9 @@
+/**
+ * System prompt report builder.
+ *
+ * Session metadata uses this report to account for prompt size, bootstrap file
+ * injection, skills, and tool schema footprint without storing raw prompt text.
+ */
 import { createHash } from "node:crypto";
 import type { SessionSystemPromptReport } from "../config/sessions/types.js";
 import { buildBootstrapInjectionStats } from "./bootstrap-budget.js";
@@ -70,6 +76,8 @@ function buildToolSchemaStats(
       return Object.keys(props as Record<string, unknown>).length;
     })(),
   };
+  // Tool parameter objects are reused across runs; cache their stable size/hash
+  // so report generation stays cheap during frequent prompt rebuilds.
   toolSchemaStatsCache.set(parameters, stats);
   return stats;
 }
@@ -94,6 +102,7 @@ function measureRenderedProjectContextChars(systemPrompt: string): number {
   return extractBetween(systemPrompt, "\n# Project Context\n", "\n## Silent Replies\n").length;
 }
 
+/** Builds the stored report for a rendered system prompt and its inputs. */
 export function buildSystemPromptReport(params: {
   source: SessionSystemPromptReport["source"];
   generatedAt: number;

src/agents/tools-effective-inventory-groups.ts

@@ -1,3 +1,9 @@
+/**
+ * Effective tool inventory grouping.
+ *
+ * Tool inventory reports use this to present effective tools in stable source
+ * groups while preserving each source's original tool order.
+ */
 import type {
   EffectiveToolInventoryEntry,
   EffectiveToolInventoryGroup,
@@ -17,6 +23,7 @@ function groupLabel(source: EffectiveToolSource): string {
   }
 }
 
+/** Groups effective tool inventory entries by source in UI/report order. */
 export function buildEffectiveToolInventoryGroups(
   entries: readonly EffectiveToolInventoryEntry[],
 ): EffectiveToolInventoryGroup[] {