@oh-my-pi/pi-coding-agent 16.2.7 → 16.2.9

package/src/prompts/system/workflow-notice.md

@@ -13,7 +13,7 @@ Worth it when the task benefits from decomposition + parallel coverage, or from
 <helpers>
 State persists across eval calls, so scout in one call and fan out in the next. Every eval call has:
 
-- `agent(prompt, *, agent="task", model=None, label=None, schema=None, isolated=None, apply=None, merge=None, handle=False)` — run ONE subagent; returns its final text, or the validated object when `schema` (a JSON Schema dict) is given. With `schema` the subagent is forced to emit structured output that is validated for you — branch on the object, not on parsed prose. `agent` picks a discovered agent ("explore", "reviewer", "oracle", …); `label` names the artifact. Shared background goes in a `local://` file referenced from each prompt, not a parameter. Subagents are told their final text IS the return value, so they hand back raw data. `agent()` blocks until the subagent finishes; eval-spawned agents nest at most 3 deep. Pass `isolated=True` to run the spawn in a copy-on-write worktree so parallel `agent()` calls can edit overlapping files safely — strict opt-in, mirrors the `task` tool, defaults off regardless of `task.isolation.mode`; `isolated=True` while the setting is `"none"` errors out instead of silently downgrading. With isolation, `apply=False` keeps changes in the worktree, and `merge=False` forces patch mode even when the setting is `"branch"`. Captured root patch path, branch name, nested repo patches, and apply summary reach the workflow through `handle=True` — combine it with `apply=False` (or `apply=False, schema=…`) and read `node["patch_path"]`, `node["branch_name"]`, `node["nested_patches"]`, `node["changes_applied"]`, `node["isolation_summary"]` (JS: same keys camelCased) to recover artifacts.
+- `agent(prompt, *, agent="task", model=None, label=None, schema=None, isolated=None, apply=None, merge=None, handle=False)` — run ONE subagent; returns its final text, or the validated object when `schema` (a JSON Schema dict) is given. With `schema` the subagent is forced to emit structured output that is validated for you — branch on the object, not on parsed prose. `agent` picks a discovered agent ("explore", "reviewer", …); `label` names the artifact. Shared background goes in a `local://` file referenced from each prompt, not a parameter. Subagents are told their final text IS the return value, so they hand back raw data. `agent()` blocks until the subagent finishes; eval-spawned agents nest at most 3 deep. Pass `isolated=True` to run the spawn in a copy-on-write worktree so parallel `agent()` calls can edit overlapping files safely — strict opt-in, mirrors the `task` tool, defaults off regardless of `task.isolation.mode`; `isolated=True` while the setting is `"none"` errors out instead of silently downgrading. With isolation, `apply=False` keeps changes in the worktree, and `merge=False` forces patch mode even when the setting is `"branch"`. Captured root patch path, branch name, nested repo patches, and apply summary reach the workflow through `handle=True` — combine it with `apply=False` (or `apply=False, schema=…`) and read `node["patch_path"]`, `node["branch_name"]`, `node["nested_patches"]`, `node["changes_applied"]`, `node["isolation_summary"]` (JS: same keys camelCased) to recover artifacts.
 - `parallel(thunks)` — run zero-arg callables concurrently through a bounded pool, preserving input order; returns once all finish. The pool is bounded by the session's `task` concurrency — don't hand-tune it; fan out as wide as the work divides. A thunk that raises propagates — wrap risky work in `try/except` inside the thunk to keep partial results. In a loop, bind each closure's value with a default arg (`lambda d=d: …`) or every thunk captures the last one.
 - `pipeline(items, *stages)` — map items through `stages` left-to-right. There is a BARRIER between stages: ALL items clear stage N before stage N+1 begins. Each stage is a one-arg callable; stage 1 gets the original item, later stages get the previous result. Same pool width as `parallel()`.
 - `completion(prompt, *, model="default", system=None, schema=None)` — oneshot, stateless model call (no tools, no history). Tiers: "smol", "default", "slow". Cheap classification/scoring inside a fan-out.

package/src/prompts/tools/bash.md

@@ -29,13 +29,10 @@ Anything below → `eval` cell, not bash:
 
 <critical>
 - Bash invokes real binaries with simple args; it is NOT a scripting surface. Loops, conditionals, heredocs, inline interpreter scripts (`-e`/`-c`/`--eval`) when an eval runtime exists, several piped stages, or quote/JSON escaping mean you're writing a program → use `eval` cells: restartable, stateful, and free of shell-quoting traps.
-- NEVER shell out to search content or files: `grep/rg` → `grep`.
-- NEVER use `ls` or `find` to list or locate files — `ls` → `read` (a directory path lists entries), `find` → the `glob` tool (globbing). This is non-negotiable, even for a single quick listing.
-- Avoid head/tail/redirections: stderr already merged; long output auto-truncated, FULL capture kept at `artifact://<id>`.
 </critical>
 
 <output>
-- Returns output; exit code shown on non-zero exit.
+- Returns output (stderr merged into stdout); exit code shown on non-zero exit.
 - Truncated output → `artifact://<id>` (linked in metadata).
 </output>
 

package/src/prompts/tools/task.md

@@ -7,11 +7,10 @@ Execution blocks your turn: the call only returns once the work is completely fi
 - **Sequence only when necessary:** The only reason to run A before B is if B strictly requires A's output to function (e.g., a core API contract or schema migration). {{#if ircEnabled}}If the missing piece is small, run them in parallel and have B ask A via `irc`!{{/if}}
 - **Role matching:** Assign each subagent a specific `role` (e.g. "Security Reviewer", "DB Migrator"). Do not spawn generic workers.
 - **No overhead:** Each assignment MUST instruct its agent to skip formatters, linters, and project-wide test suites. You will run those once at the end.
-- **Do your own thinking:** NEVER assign reasoning, architecture, or design to `quick_task` or `explore`. They are for mechanical lookups only. Keep hard decisions in your own context or use `task`, `plan`, or `oracle`.
 - **One-pass agents:** Prefer agents that investigate **and** edit in a single pass; only spin a read-only discovery step (e.g. `explore`) when the affected files are genuinely unknown.
 
 # Inputs
-- `agent`: The base agent type to use (e.g., `task`, `explore`).
+- `agent` (optional): The base agent type to use (e.g., `explore`, `reviewer`). Defaults to `task` (the general-purpose worker) — omit it for the default worker instead of passing `agent: "task"`.
 {{#if batchEnabled}}
 - `context`: Shared project state, constraints, and contracts. Applies to the entire batch; do not duplicate this background into individual tasks.
 - `tasks[]`: Array of subagents to spawn.
@@ -37,13 +36,7 @@ Subagents start blank. They have no access to your conversation history.
 {{#if batchEnabled}}
 - Pass large payloads using `local://<path>` URIs, never inline text.
 {{else}}
-- *Note: The single-spawn shape has no `context` field.* Write shared project state ONCE to a `local://` file (e.g., `local://ctx.md`) and reference that URL in your assignments. Pass large payloads using `local://<path>` URIs, never inline text.
-{{/if}}
-{{#if ircEnabled}}
-- Once spawned, coordinate with live agents via `irc` using their IDs. If task B depends on task A, B SHOULD message A directly.
-{{/if}}
-{{#if asyncEnabled}}
-- If you run out of things to do and are genuinely blocked waiting for a subagent, use `job poll`. Use `job cancel` only for stalled work.
+- Write shared project state ONCE to a `local://` file (e.g., `local://ctx.md`) and reference that URL in your assignments.
 {{/if}}
 
 # Format Contracts

package/src/session/agent-session.ts

@@ -250,6 +250,7 @@ import planModeToolDecisionReminderPrompt from "../prompts/system/plan-mode-tool
 	type: "text",
 };
 import sideChannelNoToolsReminder from "../prompts/system/side-channel-no-tools.md" with { type: "text" };
+import thinkingLoopRedirectTemplate from "../prompts/system/thinking-loop-redirect.md" with { type: "text" };
 import ttsrInterruptTemplate from "../prompts/system/ttsr-interrupt.md" with { type: "text" };
 import ttsrToolReminderTemplate from "../prompts/system/ttsr-tool-reminder.md" with { type: "text" };
 import unexpectedStopRetryTemplate from "../prompts/system/unexpected-stop-retry.md" with { type: "text" };
@@ -346,6 +347,9 @@ const SESSION_STOP_CONTINUATION_CAP = 8;
 const GEMINI_HEADER_INTERRUPT_REASON = "Interrupted: emit a tool call instead of more planning";
 /** `customType` for the hidden tool-call reminder injected after the interrupt. */
 const GEMINI_TOOL_REMINDER_TYPE = "gemini-tool-call-reminder";
+/** `customType` for the hidden redirect notice injected into a turn retried after a
+ *  thinking/response loop. Steers the model off the repeated content; never displayed. */
+const THINKING_LOOP_REDIRECT_TYPE = "thinking-loop-redirect";
 
 // A side-channel assistant response is signed for the hidden prompt/history that
 // produced it. If we persist that response under a different user turn, native
@@ -2882,10 +2886,10 @@ export class AgentSession {
 	 * the mid-run-compaction planner can ask "is this turn message already on
 	 * the branch?" in O(1) instead of re-walking the branch per check.
 	 *
-	 * The Map's value is the list of branch messages that share a key — almost
-	 * always one. We only need the LIST when content equality matters (rare
-	 * collision tiebreaker via {@link sameMessageContent}); the empty/single-
-	 * entry common case lets the caller's lookup short-circuit at presence.
+	 * The mid-run ordering check uses key identity alone: same-key content
+	 * variants are one logical message at this boundary, because otherwise a
+	 * display-side rewrite can make the assistant look missing after its tool
+	 * results have already persisted.
 	 *
 	 * Pre-#3629 the equivalent was `sessionManager.getBranch()` called twice
 	 * per turn message, each call rebuilding the path via O(n²) `unshift` and
@@ -2893,17 +2897,14 @@ export class AgentSession {
 	 * per `onTurnEnd` on a long session and the load-bearing source of the
 	 * `ui.loop-blocked` warnings in the bug report.
 	 */
-	#indexPersistedMessagesByKey(): Map<string, AgentMessage[]> {
-		const index = new Map<string, AgentMessage[]>();
+	#indexPersistedMessageKeys(): Set<string> {
+		const keys = new Set<string>();
 		for (const entry of this.sessionManager.getBranch()) {
 			if (entry.type !== "message") continue;
 			const key = sessionMessagePersistenceKey(entry.message);
-			if (key === undefined) continue;
-			const existing = index.get(key);
-			if (existing) existing.push(entry.message);
-			else index.set(key, [entry.message]);
+			if (key !== undefined) keys.add(key);
 		}
-		return index;
+		return keys;
 	}
 
 	/**
@@ -3003,17 +3004,17 @@ export class AgentSession {
 		// JSON-compared every entry per turn message, which on long sessions
 		// turned each `onTurnEnd` into a seconds-long sync block (the
 		// `ui.loop-blocked` warnings tagged `subagent:*` in the bug report).
-		const branchIndex = this.#indexPersistedMessagesByKey();
+		const branchKeys = this.#indexPersistedMessageKeys();
 		const turnKeys = turnMessages.map(sessionMessagePersistenceKey);
 		const persistedKeys = new Set<string>();
 		for (let index = 0; index < turnMessages.length; index++) {
 			const key = turnKeys[index];
 			if (key === undefined) continue;
-			const candidates = branchIndex.get(key);
-			if (!candidates) continue;
-			// Key match only counts when content also matches — two distinct
-			// messages that collided on the cheap key must STILL be persisted.
-			if (candidates.some(persisted => sameMessageContent(persisted, turnMessages[index]))) {
+			// Mid-run ordering is keyed by logical identity. A persisted display
+			// variant (for example, redacted/deobfuscated content) must still count;
+			// otherwise the assistant can look missing while later tool results are
+			// present, producing a false out-of-order skip.
+			if (branchKeys.has(key)) {
 				persistedKeys.add(key);
 			}
 		}
@@ -8087,7 +8088,7 @@ export class AgentSession {
 	 */
 	async setModelTemporary(
 		model: Model,
-		thinkingLevel?: ThinkingLevel,
+		thinkingLevel?: ConfiguredThinkingLevel,
 		options?: { ephemeral?: boolean },
 	): Promise<void> {
 		const previousEditMode = this.#resolveActiveEditMode();
@@ -8968,6 +8969,22 @@ export class AgentSession {
 						...(snapcompactShapeSetting === "auto" ? {} : { shape }),
 						maxFrames,
 					});
+					const framePayloadBytes = this.#snapcompactFramePayloadBytes(snapcompactResult);
+					if (framePayloadBytes > snapcompact.FRAME_DATA_BYTES_BUDGET) {
+						logger.warn("Snapcompact exceeded the per-request frame payload budget", {
+							model: this.model?.id,
+							framePayloadBytes,
+							budget: snapcompact.FRAME_DATA_BYTES_BUDGET,
+						});
+						this.emitNotice(
+							"warning",
+							"snapcompact produced too much standing image payload. No LLM fallback was attempted.",
+							"compaction",
+						);
+						throw new Error(
+							"snapcompact cannot run locally: standing image payload exceeds the per-request budget.",
+						);
+					}
 					const ctxWindow = this.model?.contextWindow ?? 0;
 					const budget =
 						ctxWindow > 0
@@ -10930,7 +10947,7 @@ export class AgentSession {
 	 */
 	#computeSnapcompactMaxFrames(preparation: CompactionPreparation, settings: CompactionSettings): number {
 		const ctxWindow = this.model?.contextWindow ?? 0;
-		if (ctxWindow <= 0) return snapcompact.MAX_FRAMES_DEFAULT;
+		if (ctxWindow <= 0) return Math.min(snapcompact.MAX_FRAMES_DEFAULT, snapcompact.maxFramesForDataBudget());
 		const reserve = effectiveReserveTokens(ctxWindow, settings);
 		let baseTokens = computeNonMessageTokens(this);
 		for (const message of preparation.recentMessages) {
@@ -10969,7 +10986,16 @@ export class AgentSession {
 		const capReserve = textEdgeTokens + SUMMARY_TEMPLATE_TOKENS;
 		const frameBudget = totalBudget - baseTokens - capReserve;
 		if (frameBudget < snapcompact.FRAME_TOKEN_ESTIMATE) return 1;
-		return Math.min(Math.floor(frameBudget / snapcompact.FRAME_TOKEN_ESTIMATE), snapcompact.MAX_FRAMES_DEFAULT);
+		return Math.min(
+			Math.floor(frameBudget / snapcompact.FRAME_TOKEN_ESTIMATE),
+			snapcompact.MAX_FRAMES_DEFAULT,
+			snapcompact.maxFramesForDataBudget(),
+		);
+	}
+
+	#snapcompactFramePayloadBytes(result: snapcompact.CompactionResult): number {
+		const archive = snapcompact.getPreservedArchive(result.preserveData);
+		return archive ? snapcompact.frameDataBytes(archive.frames) : 0;
 	}
 
 	/**
@@ -10982,7 +11008,9 @@ export class AgentSession {
 	 */
 	#projectSnapcompactContextTokens(preparation: CompactionPreparation, result: snapcompact.CompactionResult): number {
 		const archive = snapcompact.getPreservedArchive(result.preserveData);
-		const blocks = archive ? snapcompact.historyBlocks(archive) : undefined;
+		const blocks = archive
+			? snapcompact.historyBlocks(archive, { maxFrameDataBytes: snapcompact.FRAME_DATA_BYTES_BUDGET })
+			: undefined;
 		const summaryMessage = createCompactionSummaryMessage(
 			result.summary,
 			result.tokensBefore,
@@ -11073,6 +11101,52 @@ export class AgentSession {
 		return residualTokens <= fitBudget;
 	}
 
+	/**
+	 * Last-resort reducer when {@link #runAutoCompaction} would otherwise dead-end.
+	 * The summarizer cut at the only available turn boundary, but the kept tail is
+	 * still over the recovery band because a single recent turn (a large
+	 * tool-result, a heavy fenced/XML block) is itself bigger than the band and
+	 * `findCutPoint` cannot cut inside one message. `shake("elide")` reaches INSIDE
+	 * that tail — it offloads heavy tool-result / block content to one
+	 * `artifact://` blob and leaves a recoverable placeholder — so residual context
+	 * genuinely drops instead of the guard pausing maintenance and looping the
+	 * warning. Without it the guard would pause/warn here; with it the caller
+	 * re-tests its progress predicate after the elide pass and only falls through
+	 * to the warning when residual stays over.
+	 *
+	 * Image-only tails are out of scope: `collectShakeRegions` skips image-only
+	 * tool results and user-message images aren't counted by the local estimate
+	 * that gates the dead-end, so those still surface the warning (remedy:
+	 * `/shake images`).
+	 *
+	 * Returns the elide {@link ShakeResult} when something was offloaded (so the
+	 * caller can re-test and report), or `undefined` when nothing was eligible or
+	 * the pass aborted/failed.
+	 */
+	async #tryShakeRescueForDeadEnd(signal: AbortSignal): Promise<ShakeResult | undefined> {
+		if (signal.aborted) return undefined;
+		try {
+			const result = await this.shake("elide", { signal });
+			return result.toolResultsDropped + result.blocksDropped > 0 ? result : undefined;
+		} catch (error) {
+			logger.warn("Dead-end shake rescue failed", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+			return undefined;
+		}
+	}
+
+	/** Notice describing a successful dead-end elide rescue. */
+	#emitShakeRescueNotice(result: ShakeResult): void {
+		const elided = result.toolResultsDropped + result.blocksDropped;
+		const sink = result.artifactId ? "an artifact" : "placeholders";
+		this.emitNotice(
+			"info",
+			`Compaction dead-end recovery: elided ${elided} heavy block${elided === 1 ? "" : "s"} (~${result.tokensFreed.toLocaleString()} tokens) to ${sink} so maintenance could make progress.`,
+			"compaction",
+		);
+	}
+
 	/**
 	 * Internal: Run auto-compaction with events.
 	 *
@@ -11106,6 +11180,7 @@ export class AgentSession {
 		const shouldAutoContinue =
 			!suppressContinuation && options.autoContinue !== false && compactionSettings.autoContinue !== false;
 		const suppressHandoff = options.suppressHandoff === true;
+		let fallbackFromShake = false;
 		// Shake runs inline (cheap, no remote LLM). On overflow recovery, if shake
 		// reclaims nothing we fall through to the summary-compaction body below so
 		// the oversized input still gets resolved.
@@ -11119,6 +11194,7 @@ export class AgentSession {
 				suppressContinuation,
 			);
 			if (outcome !== "fallback") return outcome;
+			fallbackFromShake = true;
 		}
 		// "overflow" and "incomplete" force inline execution because they are recovery
 		// paths the caller wants resolved before scheduling the next turn. "idle" is
@@ -11347,6 +11423,17 @@ export class AgentSession {
 							...(shapeSetting === "auto" ? {} : { shape }),
 							maxFrames,
 						});
+						const framePayloadBytes = this.#snapcompactFramePayloadBytes(snapcompactResult);
+						if (framePayloadBytes > snapcompact.FRAME_DATA_BYTES_BUDGET) {
+							logger.warn("Snapcompact exceeded the per-request frame payload budget", {
+								model: this.model?.id,
+								framePayloadBytes,
+								budget: snapcompact.FRAME_DATA_BYTES_BUDGET,
+							});
+							snapcompactBlocker =
+								"snapcompact produced too much standing image payload; using context-full auto-compaction instead.";
+							snapcompactResult = undefined;
+						}
 						if (snapcompactResult) {
 							const ctxWindow = this.model?.contextWindow ?? 0;
 							const budget =
@@ -11606,7 +11693,15 @@ export class AgentSession {
 				// won't include) is excluded. Reusing the auto-continue recovery band
 				// here turned recoverable overflows into manual dead-ends (#3412 review),
 				// so use the looser fit budget.
-				if (this.#compactionCreatedRetryFit()) {
+				let retryFits = this.#compactionCreatedRetryFit();
+				if (!retryFits && !fallbackFromShake) {
+					const rescue = await this.#tryShakeRescueForDeadEnd(autoCompactionSignal);
+					if (rescue && this.#compactionCreatedRetryFit()) {
+						retryFits = true;
+						this.#emitShakeRescueNotice(rescue);
+					}
+				}
+				if (retryFits) {
 					this.#scheduleAgentContinue({ delayMs: 100, generation });
 					continuationScheduled = true;
 				} else {
@@ -11620,7 +11715,15 @@ export class AgentSession {
 				// when auto-continue is disabled, a no-headroom threshold pass must still
 				// block later automatic continuations (todo reminders/session_stop hooks)
 				// from re-entering the same oversized context.
-				if (this.#compactionCreatedHeadroom()) {
+				let hasHeadroom = this.#compactionCreatedHeadroom();
+				if (!hasHeadroom && !fallbackFromShake) {
+					const rescue = await this.#tryShakeRescueForDeadEnd(autoCompactionSignal);
+					if (rescue && this.#compactionCreatedHeadroom()) {
+						hasHeadroom = true;
+						this.#emitShakeRescueNotice(rescue);
+					}
+				}
+				if (hasHeadroom) {
 					if (shouldAutoContinue) {
 						this.#scheduleAutoContinuePrompt(generation);
 						continuationScheduled = true;
@@ -11644,7 +11747,7 @@ export class AgentSession {
 			if (noProgressDeadEnd) {
 				this.emitNotice(
 					"warning",
-					"Compaction freed too little context to make progress — pausing automatic maintenance to avoid a compaction loop. The most recent turn alone is too large to reduce further; shrink it (e.g. clear large tool output) or switch to a larger-context model.",
+					"Compaction freed too little context to make progress — pausing automatic maintenance to avoid a compaction loop. The most recent turn alone is too large to reduce further; clear large tool output, run `/shake images` to drop attached images, or switch to a larger-context model.",
 					"compaction",
 				);
 			}
@@ -12480,6 +12583,11 @@ export class AgentSession {
 		// Remove the failed assistant message from active context before retrying.
 		this.#removeAssistantMessageFromActiveContext(message);
 
+		// A thinking/response loop retried into identical context loops again. Inject a
+		// hidden redirect so the retried turn sees a directive to break the repeated
+		// pattern instead of re-sampling the same stalled reasoning.
+		this.#maybeInjectThinkingLoopRedirect(id);
+
 		// Wait with exponential backoff (abortable).
 		const retryAbortController = new AbortController();
 		this.#retryAbortController?.abort();
@@ -12513,6 +12621,35 @@ export class AgentSession {
 		return true;
 	}
 
+	/**
+	 * Inject a hidden redirect notice when a thinking/response loop is being retried, so
+	 * the retried turn carries an instruction to break the repeated pattern instead of
+	 * re-sampling the same stalled context. Injected on every {@link AIError.Flag.ThinkingLoop}
+	 * retry (the failed assistant is dropped each attempt, so the notice does not accumulate
+	 * unboundedly). No-op unless `id` carries the ThinkingLoop flag and the loop guard is
+	 * enabled. The notice is generic on purpose — the detector's detail can quote raw model
+	 * text, which must not be interpolated into a higher-priority developer message.
+	 */
+	#maybeInjectThinkingLoopRedirect(id: number): void {
+		if (!AIError.is(id, AIError.Flag.ThinkingLoop)) return;
+		if (this.settings.get("model.loopGuard.enabled") !== true) return;
+		this.agent.appendMessage({
+			role: "custom",
+			customType: THINKING_LOOP_REDIRECT_TYPE,
+			content: thinkingLoopRedirectTemplate,
+			display: false,
+			attribution: "agent",
+			timestamp: Date.now(),
+		});
+		this.sessionManager.appendCustomMessageEntry(
+			THINKING_LOOP_REDIRECT_TYPE,
+			thinkingLoopRedirectTemplate,
+			false,
+			undefined,
+			"agent",
+		);
+	}
+
 	/**
 	 * Cancel in-progress retry.
 	 */

package/src/session/session-context.ts

@@ -77,6 +77,17 @@ export interface BuildSessionContextOptions {
  * If leafId is provided, walks from that entry to root.
  * Handles compaction and branch summaries along the path.
  */
+function snapcompactHistoryBlocksForContext(
+	archive: snapcompact.Archive | undefined,
+	options: BuildSessionContextOptions | undefined,
+) {
+	if (!archive) return undefined;
+	return snapcompact.historyBlocks(
+		archive,
+		options?.transcript ? undefined : { maxFrameDataBytes: snapcompact.FRAME_DATA_BYTES_BUDGET },
+	);
+}
+
 export function buildSessionContext(
 	entries: SessionEntry[],
 	leafId?: string | null,
@@ -273,7 +284,7 @@ export function buildSessionContext(
 						entry.shortSummary,
 						undefined,
 						undefined,
-						snapcompactArchive ? snapcompact.historyBlocks(snapcompactArchive) : undefined,
+						snapcompactHistoryBlocksForContext(snapcompactArchive, options),
 					),
 				);
 			} else {
@@ -307,7 +318,7 @@ export function buildSessionContext(
 				compaction.shortSummary,
 				providerPayload,
 				undefined,
-				snapcompactArchive ? snapcompact.historyBlocks(snapcompactArchive) : undefined,
+				snapcompactHistoryBlocksForContext(snapcompactArchive, options),
 			),
 		);
 

package/src/session/settings-stream-fn.ts

@@ -2,8 +2,8 @@
  * Settings-aware stream wrapper shared by the main agent (sdk.ts) and the
  * advisor agent (AgentSession.#buildAdvisorRuntime).
  *
- * Reads OpenRouter / Antigravity routing variants, Responses-family text
- * verbosity, per-provider in-flight caps, and the loop guard out of `Settings`
+ * verbosity, stream watchdog budgets, per-provider in-flight caps, and the loop
+ * guard out of `Settings`
  * per request, layering them onto whatever options the caller passed. Before
  * this helper existed, advisor turns called bare `streamSimple` while the main
  * turn went through an inline closure that read these settings — so an advisor on
@@ -14,6 +14,12 @@ import type { StreamFn } from "@oh-my-pi/pi-agent-core";
 import { type SimpleStreamOptions, streamSimple } from "@oh-my-pi/pi-ai";
 import { type Settings, validateProviderMaxInFlightRequests } from "../config/settings";
 
+function timeoutSecondsToMs(value: number): number | undefined {
+	if (!Number.isFinite(value) || value < 0) return undefined;
+	if (value === 0) return 0;
+	return Math.max(1, Math.trunc(value * 1000));
+}
+
 /**
  * Build a {@link StreamFn} that reads provider routing/guard settings from
  * `settings` per call and forwards to `base` (defaults to `streamSimple`).
@@ -30,11 +36,15 @@ export function createSettingsAwareStreamFn(settings: Settings, base: StreamFn =
 			model.api === "openai-codex-responses" || model.api === "openai-responses"
 				? settings.get("textVerbosity")
 				: undefined;
+		const streamFirstEventTimeoutMs = timeoutSecondsToMs(settings.get("providers.streamFirstEventTimeoutSeconds"));
+		const streamIdleTimeoutMs = timeoutSecondsToMs(settings.get("providers.streamIdleTimeoutSeconds"));
 		const merged: SimpleStreamOptions = {
 			...streamOptions,
 			openrouterVariant: streamOptions?.openrouterVariant ?? openrouterVariant,
 			antigravityEndpointMode: streamOptions?.antigravityEndpointMode ?? antigravityEndpointMode,
 			textVerbosity: streamOptions?.textVerbosity ?? textVerbosity,
+			streamFirstEventTimeoutMs: streamOptions?.streamFirstEventTimeoutMs ?? streamFirstEventTimeoutMs,
+			streamIdleTimeoutMs: streamOptions?.streamIdleTimeoutMs ?? streamIdleTimeoutMs,
 			maxInFlightRequests: validateProviderMaxInFlightRequests(
 				streamOptions?.maxInFlightRequests ?? settings.get("providers.maxInFlightRequests"),
 			),

package/src/stt/index.ts

@@ -3,5 +3,6 @@ export * from "./asr-protocol";
 export * from "./downloader";
 export * from "./models";
 export * from "./stt-controller";
+export * from "./submit-trigger";
 export * from "./transcriber";
 export * from "./wav";

package/src/stt/stt-controller.ts

@@ -15,6 +15,7 @@ import {
 	startStreamingRecording,
 	verifyRecordingFile,
 } from "./recorder";
+import { evaluateSubmitTrigger } from "./submit-trigger";
 import { transcribe } from "./transcriber";
 
 export type SttState = "idle" | "recording" | "transcribing";
@@ -33,6 +34,8 @@ interface Editor {
 	setVolatileText(text: string): void;
 	clearVolatileText(): void;
 	commitVolatileText(text: string): void;
+	submit(): void;
+	deleteBeforeCursor(count: number): void;
 }
 
 export class STTController {
@@ -53,6 +56,7 @@ export class STTController {
 	#streamEditor: Editor | null = null;
 	#streamCommitted = false;
 	#streamAbort: AbortController | null = null;
+	#streamUtterance = "";
 
 	get state(): SttState {
 		return this.#state;
@@ -190,6 +194,7 @@ export class STTController {
 		const language = settings.get("stt.language") as string | undefined;
 		this.#streamEditor = editor;
 		this.#streamCommitted = false;
+		this.#streamUtterance = "";
 		this.#streamAbort = new AbortController();
 		const stream = sttClient.startStream(modelKey, {
 			language: language || undefined,
@@ -205,6 +210,7 @@ export class STTController {
 				if (prefixed) {
 					this.#streamEditor?.commitVolatileText(prefixed);
 					this.#streamCommitted = true;
+					this.#streamUtterance += prefixed;
 				} else {
 					this.#streamEditor?.clearVolatileText();
 				}
@@ -266,13 +272,27 @@ export class STTController {
 			return;
 		}
 		if (!this.#streamCommitted && finalText) {
-			this.#streamEditor?.commitVolatileText(this.#prefixed(finalText));
+			const prefixed = this.#prefixed(finalText);
+			this.#streamEditor?.commitVolatileText(prefixed);
 			this.#streamCommitted = true;
+			this.#streamUtterance = prefixed;
 		} else {
 			this.#streamEditor?.clearVolatileText();
 		}
 		options.requestRender?.();
 		if (!failed) options.showStatus(this.#streamCommitted ? "" : "No speech detected.");
+
+		if (this.#streamCommitted && !failed && this.#streamEditor) {
+			const trigger = settings.get("stt.submitTrigger");
+			const { submit, trimTrailing } = evaluateSubmitTrigger(this.#streamUtterance, trigger);
+			if (trimTrailing > 0) {
+				this.#streamEditor.deleteBeforeCursor(trimTrailing);
+			}
+			if (submit) {
+				this.#streamEditor.submit();
+			}
+		}
+
 		this.#cleanupStream();
 		this.#setState("idle", options);
 	}
@@ -283,6 +303,7 @@ export class STTController {
 		this.#streamEditor = null;
 		this.#streamCommitted = false;
 		this.#streamAbort = null;
+		this.#streamUtterance = "";
 	}
 
 	// ── Batch (single-shot) ─────────────────────────────────────────
@@ -327,8 +348,16 @@ export class STTController {
 			this.#transcriptionAbort = null;
 			if (this.#disposed) return;
 			if (text.length > 0) {
-				editor.insertText(text);
+				const trigger = settings.get("stt.submitTrigger");
+				const { submit, trimTrailing } = evaluateSubmitTrigger(text, trigger);
+				const textToInsert = trimTrailing > 0 ? text.slice(0, -trimTrailing) : text;
+				if (textToInsert.length > 0) {
+					editor.insertText(textToInsert);
+				}
 				options.showStatus("");
+				if (submit) {
+					editor.submit();
+				}
 			} else {
 				options.showStatus("No speech detected.");
 			}

package/src/stt/submit-trigger.ts

@@ -0,0 +1,74 @@
+/**
+ * TTS/STT Submit Trigger options and evaluation logic.
+ */
+
+export const STT_SUBMIT_TRIGGER_VALUES = ["never", "release", "release-complete", "say-submit"] as const;
+
+export type SttSubmitTrigger = (typeof STT_SUBMIT_TRIGGER_VALUES)[number];
+
+export const STT_SUBMIT_TRIGGER_OPTIONS = [
+	{
+		value: "never",
+		label: "Never",
+		description: "Never automatically submit; insert dictation and remain in editor.",
+	},
+	{
+		value: "release",
+		label: "Release",
+		description: "Submit on release if the utterance has 2+ words to avoid accidental sends.",
+	},
+	{
+		value: "release-complete",
+		label: "Release with complete sentence",
+		description: "Submit on release if the utterance ends with sentence-terminal punctuation (. ? ! etc.).",
+	},
+	{
+		value: "say-submit",
+		label: "When I Say Submit",
+		description: "Submit if the utterance ends with a word containing 'submit' (strips that word before submitting).",
+	},
+] satisfies ReadonlyArray<{ value: SttSubmitTrigger; label: string; description: string }>;
+
+/**
+ * Evaluate the submit trigger against a transcribed utterance.
+ * Returns whether to submit, and the number of characters to trim from the end of the utterance.
+ */
+export function evaluateSubmitTrigger(
+	utterance: string,
+	trigger: SttSubmitTrigger,
+): { submit: boolean; trimTrailing: number } {
+	const trimmed = utterance.trim();
+	if (!trimmed) {
+		return { submit: false, trimTrailing: 0 };
+	}
+
+	if (trigger === "never") {
+		return { submit: false, trimTrailing: 0 };
+	}
+
+	if (trigger === "release") {
+		// Split by whitespace and count words
+		const words = trimmed.split(/\s+/).filter(Boolean);
+		const submit = words.length >= 2;
+		return { submit, trimTrailing: 0 };
+	}
+
+	if (trigger === "release-complete") {
+		// Matches typical sentence terminators: . ? ! ... or full-width equivalents, optionally followed by space
+		const hasTerminalPunctuation = /[.?!…。？！]\s*$/.test(trimmed);
+		return { submit: hasTerminalPunctuation, trimTrailing: 0 };
+	}
+
+	if (trigger === "say-submit") {
+		// Matches space followed by any word containing "submit" (case-insensitive), optionally followed by punctuation/spaces
+		// Also handles the case where "submit" is the only word in the utterance (no leading space)
+		const match = utterance.match(/(?:^|\s+)(\S*submit\S*)[.?!…。？！]*\s*$/i);
+		if (match && match.index !== undefined) {
+			const trimTrailing = utterance.length - match.index;
+			return { submit: true, trimTrailing };
+		}
+		return { submit: false, trimTrailing: 0 };
+	}
+
+	return { submit: false, trimTrailing: 0 };
+}