headlesscode 1.0.2

package/src/engine/events.ts

@@ -0,0 +1,428 @@
+/**
+ * Per-session structured event feed — live worker monitoring (Phase 1).
+ *
+ * Mirrors `src/engine/usage.ts`'s idiom exactly: append-only JSONL, one file
+ * per session, loose validation on read, plain `node:fs` — no schema library.
+ *
+ *   <workspaceRoot>/.headlesscode/events/<sessionId>.jsonl
+ *
+ * Each line is one `EventRecord`:
+ *
+ *   { ts: ISO string, sessionId: string, type: string, ...fields }
+ *
+ * Event types emitted by HeadlessSession (see src/engine/loop.ts):
+ *   session_start / iteration_start / llm_response / tool_call / tool_result
+ *   checkpoint_saved / decision_blocked / decision_answered
+ *   condensed / todo_updated / paused / resumed / session_end
+ *   attempt_completion (issue #34): the session's FINAL report, emitted when
+ *   the loop accepts completion (attempt_completion tool call OR the
+ *   text-only success fallback) and carries the FULL report text — this is
+ *   the deliberate exception to EVENT_TRUNCATE_CHARS: the report is exactly
+ *   the content the model produced, so truncating it would reintroduce the
+ *   observability gap it exists to close (a surprising review/QA verdict was
+ *   previously unrecoverable without re-running the whole session). The
+ *   full report is ALSO persisted to `<workspaceRoot>/.headlesscode/reports/
+ *   <sessionId>.md` (see src/engine/reports.ts) so it survives even a feed
+ *   that never gets polled.
+ *   mode_switched (switch_mode: the session's own active mode changed in
+ *   place — same session, new system prompt/tool set; see
+ *   plans/switch-mode-headless.md)
+ *   message_injected (live chat-UI control: a human wrote a new user message
+ *   into the RUNNING session via the dashboard — POST /api/session/:id/message
+ *   → `.harness.inject-message` marker; see loop.ts's checkInjectedMessage.
+ *   The text has been appended to the session's live history as a plain
+ *   user-role message and the next LLM call sees it)
+ *
+ * `condensed` is the one structural event that was originally only a log line
+ * (`[condense] oldest turns condensed…` in src/engine/condense.ts) — the
+ * dashboard's timeline view needs it as a real event to mark where the
+ * session compressed its history, so it is emitted by HeadlessSession when a
+ * condensation pass actually replaces the oldest turns.
+ *
+ * `todo_updated` (update_todo_list: full normalized checklist + counts —
+ * done / inProgress / pending; the dashboard reads this to render live
+ * planning state)
+ *
+ * Unlike the live usage snapshot (deleted at session end because the final
+ * .jsonl record supersedes it), the event feed is a history/replay log and is
+ * KEPT after the session ends — it is never deleted in session teardown.
+ *
+ * This module is the ONLY place that knows the on-disk events layout, so the
+ * dashboard read side (`src/dashboard/aggregate.ts`'s `readSessionEvents`)
+ * and the write side (`EventFeed` below) stay in sync.
+ */
+
+import * as fsp from "node:fs/promises"
+import * as path from "node:path"
+
+/** Cap on any single event field's string content (this feed is polled frequently). */
+export const EVENT_TRUNCATE_CHARS = 500
+
+/** One line of the per-session event feed. */
+export interface EventRecord {
+	ts: string
+	sessionId: string
+	type: string
+	iteration?: number
+	/**
+	 * Recursive task decomposition (`new_task`): the id of the session that
+	 * spawned this one, present on every event of a child session (absent on
+	 * root sessions). Lets the dashboard render parent/child nesting without
+	 * cross-referencing anything else — the lineage is stamped onto each
+	 * record, so a child feed never needs its parent's feed to be readable.
+	 */
+	parentSessionId?: string
+	/**
+	 * Recursive task decomposition (`new_task`): this session's recursion
+	 * depth (0 = root). Stamped onto every event alongside parentSessionId.
+	 */
+	recursionDepth?: number
+	[field: string]: unknown
+}
+
+/** The events dir for a workspace: `<workspaceRoot>/.headlesscode/events`. */
+export function eventsDir(workspaceRoot: string): string {
+	return path.join(workspaceRoot, ".headlesscode", "events")
+}
+
+/** The event feed file path for one session. */
+export function eventsFilePath(workspaceRoot: string, sessionId: string): string {
+	return path.join(eventsDir(workspaceRoot), `${sessionId}.jsonl`)
+}
+
+/**
+ * Append one event record to a session's feed. Creates the events dir if
+ * needed. Callers are expected to wrap this in try/catch and treat failures
+ * as non-fatal (see `EventFeed`); this function itself does not swallow
+ * errors, so it fails loudly for direct callers/tests.
+ */
+export async function appendEvent(workspaceRoot: string, sessionId: string, record: EventRecord): Promise<void> {
+	const file = eventsFilePath(workspaceRoot, sessionId)
+	await fsp.mkdir(path.dirname(file), { recursive: true })
+	await fsp.appendFile(file, JSON.stringify(record) + "\n", "utf-8")
+}
+
+/**
+ * Read + loosely validate one event feed JSONL file. Malformed /
+ * partially-written lines are skipped; a missing file yields an empty array
+ * (never throws for ENOENT — matches the usage store's `readUsageFile` idiom).
+ */
+export async function readEventsFile(file: string): Promise<EventRecord[]> {
+	let raw: string
+	try {
+		raw = await fsp.readFile(file, "utf-8")
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return []
+		}
+		throw error
+	}
+	const records: EventRecord[] = []
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trim()
+		if (!trimmed) {
+			continue
+		}
+		try {
+			const parsed = JSON.parse(trimmed) as Partial<EventRecord>
+			if (
+				typeof parsed.ts === "string" &&
+				typeof parsed.sessionId === "string" &&
+				typeof parsed.type === "string"
+			) {
+				records.push(parsed as EventRecord)
+			}
+		} catch {
+			// Loose validation: skip malformed / partially-written lines.
+		}
+	}
+	return records
+}
+
+/** A string field that was possibly truncated to `EVENT_TRUNCATE_CHARS`. */
+export interface TruncatedField {
+	text: string
+	truncated: boolean
+}
+
+/** Truncate a long string for the event feed, flagging when it was cut. */
+export function truncateField(value: string, max = EVENT_TRUNCATE_CHARS): TruncatedField {
+	if (value.length <= max) {
+		return { text: value, truncated: false }
+	}
+	return { text: value.slice(0, max), truncated: true }
+}
+
+/**
+ * The session's structured event writer. Every emit is non-fatal: a failure
+ * to append is reported via the injected `onError` callback (the loop wires
+ * it to `logger.warn`, matching the established memory/usage/checkpoint
+ * try/catch idiom) and never affects the session.
+ *
+ * Emits are serialized through an internal promise chain so fire-and-forget
+ * calls (e.g. decision events surfaced from inside a tool handler) still
+ * append to the same file in emission order.
+ */
+export class EventFeed {
+	private queue: Promise<void> = Promise.resolve()
+
+	constructor(
+		private readonly workspaceRoot: string,
+		private readonly sessionId: string,
+		private readonly onError: (eventType: string, error: unknown) => void,
+		/**
+		 * Recursive task decomposition (`new_task`): the parent session's id
+		 * and this session's recursion depth, stamped onto EVERY record so a
+		 * child feed is self-describing. Absent on root sessions (no-op).
+		 */
+		private readonly lineage?: { parentSessionId?: string; recursionDepth?: number },
+	) {}
+
+	/** Append a raw event record (non-fatal). */
+	emit(type: string, fields: Record<string, unknown> = {}): Promise<void> {
+		const record: EventRecord = {
+			ts: new Date().toISOString(),
+			sessionId: this.sessionId,
+			type,
+			...(this.lineage?.parentSessionId ? { parentSessionId: this.lineage.parentSessionId } : {}),
+			...(this.lineage?.recursionDepth !== undefined ? { recursionDepth: this.lineage.recursionDepth } : {}),
+			...fields,
+		}
+		const task = this.queue.then(() => appendEvent(this.workspaceRoot, this.sessionId, record))
+		// Keep the chain alive even when a write fails (the error is reported
+		// to onError; later events must still be attempted).
+		this.queue = task.catch(() => undefined)
+		return task
+	}
+
+	sessionStart(fields: { mode: string; model: string; workspaceRoot: string; taskText: string }): Promise<void> {
+		const task = truncateField(fields.taskText)
+		return this.emit("session_start", {
+			mode: fields.mode,
+			model: fields.model,
+			workspaceRoot: fields.workspaceRoot,
+			task: task.text,
+			...(task.truncated ? { taskTruncated: true } : {}),
+		})
+	}
+
+	iterationStart(iteration: number, historyMessageCount: number): Promise<void> {
+		return this.emit("iteration_start", { iteration, historyMessageCount })
+	}
+
+	llmResponse(fields: {
+		iteration: number
+		hadToolCalls: boolean
+		textPreview?: string
+		/** Reasoning/"thinking" text (streaming-and-reasoning), truncated like other large fields. */
+		reasoningPreview?: string
+		inputTokens?: number
+		outputTokens?: number
+		cachedTokens?: number
+	}): Promise<void> {
+		const text = fields.textPreview ? truncateField(fields.textPreview) : undefined
+		const reasoning = fields.reasoningPreview ? truncateField(fields.reasoningPreview) : undefined
+		return this.emit("llm_response", {
+			iteration: fields.iteration,
+			hadToolCalls: fields.hadToolCalls,
+			...(text ? { textPreview: text.text, ...(text.truncated ? { textTruncated: true } : {}) } : {}),
+			...(reasoning
+				? { reasoningPreview: reasoning.text, ...(reasoning.truncated ? { reasoningTruncated: true } : {}) }
+				: {}),
+			...(fields.inputTokens !== undefined ? { inputTokens: fields.inputTokens } : {}),
+			...(fields.outputTokens !== undefined ? { outputTokens: fields.outputTokens } : {}),
+			...(fields.cachedTokens !== undefined ? { cachedTokens: fields.cachedTokens } : {}),
+		})
+	}
+
+	/**
+	 * One incremental chunk of a streamed LLM response (streaming-and-reasoning,
+	 * opt-in). Distinct from the single `llm_response` summary event which still
+	 * fires once at the end of the call with final totals — this is the
+	 * live-typing feed. `kind` is "text" | "reasoning" | "tool" so the dashboard
+	 * can render reasoning text differently from the answer text. Truncated like
+	 * every other large field.
+	 */
+	llmStreamChunk(fields: {
+		iteration: number
+		kind: "text" | "reasoning" | "tool"
+		chunk: string
+	}): Promise<void> {
+		const c = truncateField(fields.chunk)
+		return this.emit("llm_stream_chunk", {
+			iteration: fields.iteration,
+			kind: fields.kind,
+			chunk: c.text,
+			...(c.truncated ? { chunkTruncated: true } : {}),
+		})
+	}
+
+	toolCall(fields: { iteration: number; tool: string; args: string; argsTruncated: boolean }): Promise<void> {
+		return this.emit("tool_call", {
+			iteration: fields.iteration,
+			tool: fields.tool,
+			args: fields.args,
+			...(fields.argsTruncated ? { argsTruncated: true } : {}),
+		})
+	}
+
+	toolResult(fields: {
+		iteration: number
+		tool: string
+		isError: boolean
+		result: string
+		resultTruncated: boolean
+	}): Promise<void> {
+		return this.emit("tool_result", {
+			iteration: fields.iteration,
+			tool: fields.tool,
+			isError: fields.isError,
+			result: fields.result,
+			...(fields.resultTruncated ? { resultTruncated: true } : {}),
+		})
+	}
+
+	/**
+	 * The session's final report (issue #34). Emitted when the loop accepts
+	 * completion — the one tool call that matters most for understanding a
+	 * review/QA/worker verdict was previously invisible to the feed because
+	 * attempt_completion short-circuits before the tool-execution loop (no
+	 * tool_call/tool_result pair is ever recorded for it). `result` is the
+	 * FULL report text, deliberately NOT truncated (the only event field that
+	 * ignores EVENT_TRUNCATE_CHARS — see the module doc comment for why); the
+	 * full report is also persisted to `.headlesscode/reports/<sessionId>.md`
+	 * by the loop, so the feed and the file are two views of the same text.
+	 */
+	attemptCompletion(fields: { iteration: number; result: string }): Promise<void> {
+		return this.emit("attempt_completion", {
+			iteration: fields.iteration,
+			result: fields.result,
+		})
+	}
+
+	/** iteration 0 = the session's baseline checkpoint (before iteration 1). */
+	checkpointSaved(iteration: number): Promise<void> {
+		return this.emit("checkpoint_saved", { iteration })
+	}
+
+	/**
+	 * A context-condensation pass replaced the oldest turns with one synthetic
+	 * summary message (see src/engine/condense.ts). Carries the iteration whose
+	 * call triggered it, the message counts before/after, and the condensation
+	 * call's own token usage when known (the dashboard timeline marks the
+	 * point; the tokens make the spend visible — condensation was previously
+	 * only a log line, invisible to the feed).
+	 */
+	condensed(fields: {
+		iteration: number
+		messagesBefore: number
+		messagesAfter: number
+		inputTokens?: number
+		outputTokens?: number
+		cachedTokens?: number
+	}): Promise<void> {
+		return this.emit("condensed", {
+			iteration: fields.iteration,
+			messagesBefore: fields.messagesBefore,
+			messagesAfter: fields.messagesAfter,
+			...(fields.inputTokens !== undefined ? { inputTokens: fields.inputTokens } : {}),
+			...(fields.outputTokens !== undefined ? { outputTokens: fields.outputTokens } : {}),
+			...(fields.cachedTokens !== undefined ? { cachedTokens: fields.cachedTokens } : {}),
+		})
+	}
+
+	/**
+	 * Todo-list state change (update_todo_list): the full normalized checklist
+	 * (truncated like every other large field) plus done / in-progress /
+	 * pending counts, so the dashboard can show live planning state and the
+	 * history can show how the checklist evolved across the session.
+	 */
+	todoUpdated(fields: { todos: string; done: number; inProgress: number; pending: number }): Promise<void> {
+		const t = truncateField(fields.todos)
+		return this.emit("todo_updated", {
+			todos: t.text,
+			...(t.truncated ? { todosTruncated: true } : {}),
+			done: fields.done,
+			inProgress: fields.inProgress,
+			pending: fields.pending,
+		})
+	}
+
+	decisionBlocked(question: string, suggestions?: string[]): Promise<void> {
+		const q = truncateField(question)
+		return this.emit("decision_blocked", {
+			question: q.text,
+			...(q.truncated ? { questionTruncated: true } : {}),
+			...(suggestions && suggestions.length > 0 ? { suggestions } : {}),
+		})
+	}
+
+	/** Answer received, or the wait timed out (timedOut: true) and the worker moved on. */
+	decisionAnswered(answer?: string, timedOut = false): Promise<void> {
+		const a = answer !== undefined ? truncateField(answer) : undefined
+		return this.emit("decision_answered", {
+			...(timedOut ? { timedOut: true } : {}),
+			...(a ? { answer: a.text, ...(a.truncated ? { answerTruncated: true } : {}) } : {}),
+		})
+	}
+
+	/**
+	 * switch_mode changed the session's OWN active mode in place (same
+	 * session/history/budget, new system prompt + tool set from this point
+	 * forward — see plans/switch-mode-headless.md). autoApproved tells the
+	 * dashboard whether the switch went through the human/orchestrator
+	 * approval gate (false) or the off-by-default auto-approve opt-in (true).
+	 */
+	modeSwitched(fields: { from: string; to: string; reason: string; autoApproved: boolean }): Promise<void> {
+		const reason = truncateField(fields.reason)
+		return this.emit("mode_switched", {
+			from: fields.from,
+			to: fields.to,
+			reason: reason.text,
+			...(reason.truncated ? { reasonTruncated: true } : {}),
+			autoApproved: fields.autoApproved,
+		})
+	}
+
+	/**
+	 * Mid-session message injection (live chat-UI control): a human wrote a
+	 * new message into a RUNNING session (POST /api/session/:id/message →
+	 * `.harness.inject-message` marker; see loop.ts's checkInjectedMessage).
+	 * The text is a plain user-role message the session appended to its live
+	 * history; the dashboard renders it inline as if the user had just typed
+	 * it. Truncated like every other large field.
+	 */
+	messageInjected(fields: { text: string }): Promise<void> {
+		const t = truncateField(fields.text)
+		return this.emit("message_injected", {
+			text: t.text,
+			...(t.truncated ? { textTruncated: true } : {}),
+		})
+	}
+
+	paused(reason?: string): Promise<void> {
+		return this.emit("paused", { ...(reason ? { reason } : {}) })
+	}
+
+	resumed(reason?: string): Promise<void> {
+		return this.emit("resumed", { ...(reason ? { reason } : {}) })
+	}
+
+	sessionEnd(fields: {
+		status: string
+		iterations: number
+		costUsd: number
+		inputTokens: number
+		outputTokens: number
+		cachedTokens: number
+	}): Promise<void> {
+		return this.emit("session_end", {
+			status: fields.status,
+			iterations: fields.iterations,
+			costUsd: fields.costUsd,
+			inputTokens: fields.inputTokens,
+			outputTokens: fields.outputTokens,
+			cachedTokens: fields.cachedTokens,
+		})
+	}
+}

package/src/engine/handoff.ts

@@ -0,0 +1,71 @@
+/**
+ * Cross-restart handoff summary — `<workspaceRoot>/.headlesscode/handoff-summary.md`.
+ *
+ * Mirrors the on-disk-layout modules idiom (src/engine/reports.ts for final
+ * reports, src/engine/usage.ts for usage): one module owns one layout.
+ *
+ * Why this exists: when a session hits the iteration cap, the orchestrator
+ * spawns a continuation worker on the SAME worktree, but as a BRAND NEW
+ * conversation — the previous session's entire message history (every
+ * `read_file`/`execute_command` result, every bit of reasoning about where
+ * things live) is gone. Only the continuation task file and whatever is on
+ * disk (git diff, commits) survive. In practice the continuation task file
+ * only says "go inspect the worktree yourself", so the new session re-derives
+ * everything the old one already learned at real cost — this was measured on
+ * a live job: a continuation session re-read the exact same files (in full)
+ * that the session before it had already read in full.
+ *
+ * The fix: right before a session gives up on the iteration cap, it
+ * summarizes its own history (via condense.ts's condenseOldestTurns — the
+ * same LLM-compression machinery the mid-session condensation path already
+ * uses) and writes the result here. The orchestrator's continuation-task-file
+ * builder reads it and inlines it as "what the previous session already
+ * learned", so the new session starts from a compact summary instead of a
+ * blank slate.
+ *
+ * A single FIXED filename (not per-session): the orchestrator only ever needs
+ * "the latest handoff for this worktree", and each continuation attempt
+ * refreshes it. `clearHandoffSummary` removes it once consumed, so a stale
+ * summary from a finished task never leaks into an unrelated later one.
+ *
+ * Like every other auxiliary write path in this codebase, writing is
+ * deliberately non-fatal: callers wrap it in try/catch and log a warning — a
+ * failed handoff write must never abort or corrupt the session that produced
+ * it.
+ */
+
+import * as fs from "node:fs"
+import * as fsp from "node:fs/promises"
+import * as path from "node:path"
+
+/** The handoff summary file for a workspace: `<workspaceRoot>/.headlesscode/handoff-summary.md`. */
+export function handoffSummaryPath(workspaceRoot: string): string {
+	return path.join(workspaceRoot, ".headlesscode", "handoff-summary.md")
+}
+
+/** Persist a session's handoff summary, overwriting any previous one for this worktree. */
+export async function writeHandoffSummary(workspaceRoot: string, summaryText: string): Promise<string> {
+	const file = handoffSummaryPath(workspaceRoot)
+	await fsp.mkdir(path.dirname(file), { recursive: true })
+	await fsp.writeFile(file, summaryText, "utf-8")
+	return file
+}
+
+/** Synchronous read for the orchestrator's task-file builder (no existing async plumbing there). Returns undefined if absent/unreadable. */
+export function readHandoffSummary(workspaceRoot: string): string | undefined {
+	const file = handoffSummaryPath(workspaceRoot)
+	try {
+		return fs.readFileSync(file, "utf-8")
+	} catch {
+		return undefined
+	}
+}
+
+/** Remove a consumed handoff summary so it never leaks into a later, unrelated continuation. Non-fatal. */
+export function clearHandoffSummary(workspaceRoot: string): void {
+	try {
+		fs.unlinkSync(handoffSummaryPath(workspaceRoot))
+	} catch {
+		// Absent or unremovable — nothing to clean up, nothing to report.
+	}
+}

package/src/engine/lazy-tools.ts

@@ -0,0 +1,160 @@
+/**
+ * Lazy tool-catalog loading — opt-in (default OFF), gated to sessions that
+ * need it: a small local model's context window can be dominated by the
+ * FULL tool catalog before the task even starts (measured live 2026-08-19
+ * against Qwen3-Coder-30B-A3B on an RTX 5080: 21 schemas = ~19.5K prompt
+ * tokens against a ~24.5K real ceiling — under 5K tokens left for the
+ * actual task). Cloud sessions (OpenRouter/DeepSeek) keep today's static
+ * full catalog untouched: a stable prefix is what makes their prompt cache
+ * cheap, and changing it per-call would hurt cache-hit rate for no local
+ * benefit. This module only ever narrows what ONE session sends; it never
+ * changes what a tool DOES.
+ *
+ * Same discovery-then-fetch shape published for MCP/tool-heavy agentic
+ * workflows (dynamic tool gating + lazy schema loading): the model gets a
+ * cheap index up front (`list_tools`) and pulls a tool's real schema into
+ * its OWN next turn only once it decides it needs it (`request_tool`),
+ * instead of paying for every schema on every turn regardless of use.
+ */
+
+import type { ChatTool } from "./types.js"
+
+export const LAZY_TOOL_CATALOG_ENV = "HEADLESSCODE_LAZY_TOOL_CATALOG"
+
+export function isLazyToolCatalogEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+	const v = env[LAZY_TOOL_CATALOG_ENV]
+	return v !== undefined && v !== "" && v !== "0" && v.toLowerCase() !== "false"
+}
+
+/**
+ * Tools sent on every turn regardless of lazy-loading: the minimum needed
+ * to read, edit, run commands, delegate, and finish a task. Everything else
+ * in a session's full tool list is offered lazily via `list_tools` /
+ * `request_tool` instead.
+ *
+ * `apply_diff` deliberately excluded (available lazily, not core) — its
+ * SEARCH/REPLACE block format requires escaping literal `=======`/`<<<<<<<`
+ * markers found in real file content, and a `:start_line:[line_number]`
+ * header where `[line_number]` is a template placeholder to substitute a
+ * real integer into. Verified live 2026-08-19 against Qwen2.5-Coder-14B:
+ * it copied `:start_line:[line_number]` into a real call verbatim (treating
+ * the placeholder as literal syntax) and separately failed to escape a
+ * literal `=======` divider inside a file's own content across 4 consecutive
+ * retries despite an explicit corrective error message each time. `edit_file`
+ * and `search_replace` need none of this — plain old_string/new_string with
+ * NO escaping rules and (edit_file) a fuzzy-match fallback — and stay core.
+ */
+export const CORE_TOOL_NAMES = new Set([
+	"ask_followup_question",
+	"attempt_completion",
+	"execute_command",
+	"list_files",
+	"new_task",
+	"read_file",
+	// search_replace deliberately excluded — same reasoning as apply_diff
+	// above it in git history: search_replace requires an EXACT literal
+	// match (see searchReplaceHandler, src/tools/executor.ts) with no
+	// fallback, while edit_file has a 3-stage fallback chain (exact →
+	// whitespace-tolerant → token-based) specifically built to survive the
+	// whitespace/indentation drift a model's old_string commonly has.
+	// Verified live 2026-08-20: given both tools, a local model picked
+	// search_replace, hit exactly the whitespace-mismatch failure edit_file
+	// exists to prevent, then spiralled into an unrelated list_files loop
+	// instead of recovering — a harness/tool-catalog problem, not
+	// necessarily a model capability ceiling. Still reachable via
+	// request_tool for a session that genuinely needs it.
+	"edit_file",
+	// set_indentation deliberately core, not lazy (issue #141): it exists
+	// specifically to give local sessions — the same sessions lazy-loading
+	// targets — a way to fix a pure indentation mismatch without edit_file's
+	// two-near-identical-multi-line-strings shape. Live-verified 2026-08-21:
+	// gating it behind request_tool defeated the whole point — a model given
+	// an explicit task-level instruction to use it still defaulted back to
+	// (always-visible) edit_file 2/2 times, then on a 3rd trial DID try to
+	// call it correctly but only as narrated text, never having pulled its
+	// real schema in via request_tool first.
+	"set_indentation",
+	"switch_mode",
+	"update_todo_list",
+	"write_to_file",
+])
+
+export const LIST_TOOLS_NAME = "list_tools"
+export const REQUEST_TOOL_NAME = "request_tool"
+
+export interface SplitTools {
+	/** Always sent: the core set plus list_tools/request_tool themselves. */
+	core: ChatTool[]
+	/** Available on request only, keyed by tool name. */
+	lazyByName: Map<string, ChatTool>
+}
+
+/** Split a session's full (already executor-gated) tool list into core + lazy. */
+export function splitCoreAndLazyTools(allTools: ChatTool[]): SplitTools {
+	const core: ChatTool[] = []
+	const lazyByName = new Map<string, ChatTool>()
+	for (const tool of allTools) {
+		if (tool.type !== "function") {
+			core.push(tool)
+			continue
+		}
+		if (CORE_TOOL_NAMES.has(tool.function.name)) {
+			core.push(tool)
+		} else {
+			lazyByName.set(tool.function.name, tool)
+		}
+	}
+	return {
+		core: [...core, buildListToolsTool(), buildRequestToolTool()],
+		lazyByName,
+	}
+}
+
+export function buildListToolsTool(): ChatTool {
+	return {
+		type: "function",
+		function: {
+			name: LIST_TOOLS_NAME,
+			description:
+				"List additional tools available in this session beyond the core set " +
+				"(read_file, write_to_file, apply_diff, search_replace, edit_file, " +
+				"execute_command, list_files, attempt_completion, ask_followup_question, " +
+				"switch_mode, new_task, update_todo_list — always available, not listed " +
+				"here). Call request_tool with a name from this list to make that tool " +
+				"callable on your NEXT turn.",
+			parameters: { type: "object", properties: {}, required: [] },
+		},
+	}
+}
+
+export function buildRequestToolTool(): ChatTool {
+	return {
+		type: "function",
+		function: {
+			name: REQUEST_TOOL_NAME,
+			description:
+				"Make one additional tool (from list_tools' output) callable starting " +
+				"on your NEXT turn. Costs nothing to call again if already active.",
+			parameters: {
+				type: "object",
+				properties: { name: { type: "string", description: "Exact tool name from list_tools" } },
+				required: ["name"],
+			},
+		},
+	}
+}
+
+/** One line per lazy tool: name + its schema's own description, truncated. */
+export function renderToolIndex(lazyByName: Map<string, ChatTool>): string {
+	if (lazyByName.size === 0) {
+		return "No additional tools are available in this session."
+	}
+	const lines = [...lazyByName.values()].map((tool) => {
+		if (tool.type !== "function") {
+			return `- ${tool.type}`
+		}
+		const description = (tool.function.description ?? "").split(/(?<=[.!?])\s/)[0] ?? ""
+		return `- ${tool.function.name}: ${description.slice(0, 120)}`
+	})
+	return lines.join("\n")
+}