pi-goal-x 0.31.5 → 0.31.6

package/README.md

@@ -6,7 +6,7 @@
   <a href="https://pi.dev/packages?type=extension" target="_blank" rel="noopener noreferrer">
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset="assets/badge-dark.svg">
-      <img src="assets/badge-light.svg" alt="TOP 0.3% of Pi coding agent extensions: #7 of 3,352 by downloads · Sep 16, 2026 (best recorded rank)" width="480">
+      <img src="assets/badge-light.svg" alt="TOP 0.3% of Pi coding agent extensions: #7 of 3,318 by downloads · Sep 17, 2026 (best recorded rank)" width="480">
     </picture>
   </a>
 </div>
@@ -168,3 +168,7 @@ Existing producers that directly send `triggerTurn`/`followUp` messages still ru
 ## License
 
 MIT
+
+### Prompt caching
+
+Goal state is refreshed at the request tail while the system prompt and conversation prefix stay stable. Pi retains control of provider cache settings. See [prompt caching](docs/prompt-caching.md) for explicit-cache handling, validation, and cache invalidation boundaries.

package/assets/badge-dark.svg

@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="480" height="54" viewBox="0 0 480 54" role="img" aria-label="TOP 0.3% of Pi coding agent extensions: #7 of 3,352 by downloads · Sep 16, 2026 (best recorded rank)">
+<svg xmlns="http://www.w3.org/2000/svg" width="480" height="54" viewBox="0 0 480 54" role="img" aria-label="TOP 0.3% of Pi coding agent extensions: #7 of 3,318 by downloads · Sep 17, 2026 (best recorded rank)">
   <!-- Dark mode -->
   <style>
     .frame { fill: #14181f; stroke: #2a3040; stroke-width: 1; }
@@ -13,6 +13,6 @@
     <text class="rank" x="18" y="34">TOP 0.3%</text>
     <line class="divider" x1="128" y1="13" x2="128" y2="41"/>
     <text class="label" x="143" y="25">of Pi coding agent extensions</text>
-    <text class="meta" x="143" y="41">#7 of 3,352 by downloads · Sep 16, 2026</text>
+    <text class="meta" x="143" y="41">#7 of 3,318 by downloads · Sep 17, 2026</text>
   </a>
 </svg>

package/assets/badge-light.svg

@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="480" height="54" viewBox="0 0 480 54" role="img" aria-label="TOP 0.3% of Pi coding agent extensions: #7 of 3,352 by downloads · Sep 16, 2026 (best recorded rank)">
+<svg xmlns="http://www.w3.org/2000/svg" width="480" height="54" viewBox="0 0 480 54" role="img" aria-label="TOP 0.3% of Pi coding agent extensions: #7 of 3,318 by downloads · Sep 17, 2026 (best recorded rank)">
   <!-- Light mode -->
   <style>
     .frame { fill: #f6f8fa; stroke: #d0d7de; stroke-width: 1; }
@@ -13,6 +13,6 @@
     <text class="rank" x="18" y="34">TOP 0.3%</text>
     <line class="divider" x1="128" y1="13" x2="128" y2="41"/>
     <text class="label" x="143" y="25">of Pi coding agent extensions</text>
-    <text class="meta" x="143" y="41">#7 of 3,352 by downloads · Sep 16, 2026</text>
+    <text class="meta" x="143" y="41">#7 of 3,318 by downloads · Sep 17, 2026</text>
   </a>
 </svg>

package/docs/architecture.md

@@ -19,7 +19,7 @@ handlers from their dedicated modules:
 | `goal-task-tools.ts` | `set_goal_tasks` / `update_goal_task` executors plus flat parent-linked conversion, id-stable merge, `countTasks` |
 | `goal-task-confirmation.ts` | Task-only result boundary (`{decision}`, no auditor toggle) with neutral Confirm task list / Keep current tasks labels |
 | `goal-commands.ts` | The curated fourteen-command palette and its handlers |
-| `goal-events.ts` | The 14 lifecycle event handlers (`context`, `turn_start`, `tool_call`, `tool_execution_end`, `turn_end`, `message_end`, `session_start`, `session_before_compact`, `session_compact`, `session_tree`, `before_agent_start`, `agent_end`, `agent_settled`, `session_shutdown`) |
+| `goal-events.ts` | Lifecycle and provider event handlers (`context`, `before_provider_request`, `turn_start`, `tool_call`, `tool_execution_end`, `turn_end`, `message_end`, `session_start`, `session_before_compact`, `session_compact`, `session_tree`, `before_agent_start`, `agent_end`, `agent_settled`, `session_shutdown`) |
 | `goal-widget.ts` | Terminal input keybindings (Esc pause / abort-audit, Ctrl+Shift+T overlay) and the hidden debug helpers |
 | `goal-format.ts` | Pure formatting/message-introspection helpers and renderers |
 | `goal-service.ts` | `GoalService` — the sole mutation boundary: ordered reconcile → id/focus-revision validation → clone-mutate → write/archive → ledger → memory commit → returned effects |
@@ -341,3 +341,5 @@ operable; `/goal-clear` confirms; task confirmation uses neutral labels;
 completion commits are failure-checked; and cross-process mutations are
 serialized with persisted revisions plus per-goal filesystem locks that
 return typed conflicts to stale writers instead of overwriting blindly.
+
+Prompt layout and explicit provider cache handling are documented in [prompt caching](prompt-caching.md). Live goal state is constructed in the context hook; before_agent_start performs lifecycle preflight without modifying the system prompt.

package/docs/prompt-caching.md

@@ -0,0 +1,21 @@
+# Prompt caching
+
+pi-goal-x preserves the provider's reusable prompt prefix during normal user turns, autonomous checkpoints, and tool loops. No extra extension setting is required. Pi's provider configuration still determines whether caching is enabled, its retention period, and model support.
+
+The request layout is:
+
+1. Host system prompt and tool schemas.
+2. Conversation history, with each goal checkpoint normalized to a tiny, stable trigger in its original position.
+3. One request-only goal-state message containing the current objective, tasks, lifecycle rules, usage, budget, scheduling state, and applicable recovery/auditor reminders.
+
+Changing goal state never rewrites the system prompt or historical messages. The full goal-state message is not persisted into the session. Old checkpoints remain until Pi compacts history; retaining small markers avoids shifting the prefix on every continuation. Display-only auditor messages are consistently excluded, and tool calls stay adjacent to their results.
+
+For Anthropic-style explicit caching, the extension moves Pi's existing cache_control breakpoint from the transient state message onto the preceding cacheable history block. The Bedrock equivalent moves the cachePoint. Both preserve the configured TTL and do not add breakpoints. Payloads without an existing explicit marker—including caching disabled and implicit-cache providers—are unchanged. The extension does not set cache keys, enable paid extended retention, or replace provider defaults.
+
+Execution tools already use an idempotent profile: goal progress, focus, and lifecycle changes do not change schemas. Explicit switches into/out of drafting and changes to disableTasks can change tools and legitimately rebuild the cache. Drafting messages are appended to conversation history. Isolated auditor and Oracle sessions already use fixed instructions/tool profiles and place goal-specific evidence in their user messages; their tool loops retain history. They have separate sessions and use Pi's cache defaults. Opting these sessions into project resources also opts into any behavior from those resources.
+
+Cache reuse can still be interrupted by Pi compaction, branch/session changes, model/provider switches, other extensions changing earlier content, changed tool schemas, provider expiry, minimum-length or breakpoint-lookback limits, or routing. The extension cannot guarantee a hit rate or a particular cost reduction. The reported issue used Pi 0.85.1; this change is validated against the repository's supported installed SDK, without expanding its peer dependency range.
+
+Validation includes consecutive request-prefix regressions; actual Anthropic, Anthropic-compatible Chat Completions, OpenAI Chat Completions and Responses serialization with short/long/disabled retention; Bedrock payload-shape checks; lifecycle/tool-pair safety tests; and full SDK parent/auditor/Oracle payload captures. These tests stop before HTTP dispatch. They verify request construction, not live provider hit rates.
+
+Provider references: [Anthropic prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) describes exact-prefix matching and explicit breakpoints; [DeepSeek context caching](https://api-docs.deepseek.com/guides/kv_cache/) describes its automatic prefix cache and usage counters.

package/extensions/goal-events.ts

@@ -1,4 +1,4 @@
-import { schedulerSummary } from "./goal-scheduler-state.ts";
+import { cacheGoalHistory } from "./goal-prompt-cache.ts";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
 	GOAL_EVENT_ENTRY,
@@ -34,45 +34,21 @@ import type { GoalCore } from "./goal-state.ts";
 import { filterGoalSessionContext } from "./goal-session-safety.ts";
 import type { GoalMutationOutcome } from "./goal-service.ts";
 
-/**
- * Issue #30: provider-context checkpoint compaction (pure helper).
- *
- * Every historical checkpoint message is redundant: its authoritative state is
- * reconstructed from goal storage and injected once per turn by
- * before_agent_start. Normal provider requests therefore retain at most ONE
- * checkpoint marker — the latest — rewritten to the tiny bounded v2 trigger
- * content. Keeping one user-role turn-start marker avoids provider edge cases
- * where removing it would leave the request ending on an assistant or tool
- * result. Audit events, user messages, assistant messages, and tool results
- * pass through untouched.
- */
+/** Normalize checkpoints independently: deleting old markers shifts the cached prefix. */
 export function compactGoalCheckpointContext(
-	messages: readonly unknown[],
-	currentGoal: GoalRecord | null,
+ messages: readonly unknown[],
+ _currentGoal: GoalRecord | null,
 ): unknown[] | null {
- let lastCheckpointIndex = -1;
- let checkpointGoalId: string | null = null;
- const checkpoints: number[] = [];
- // Parse each message once; retain ordinary messages and rewrite only the last marker.
+ let output: unknown[] | null = null;
  for (let i = 0; i < messages.length; i++) {
-  const id = goalEventMessageId(messages[i] as {customType?: string; details?: unknown; content?: unknown});
-  if (id !== null) { checkpoints.push(i); lastCheckpointIndex = i; checkpointGoalId = id; }
+  const message = messages[i] as { customType?: string; details?: unknown; content?: unknown };
+  const id = goalEventMessageId(message);
+  if (id === null) { output?.push(message); continue; }
+  output ??= messages.slice(0, i);
+  output.push({ ...message, content: checkpointTriggerPrompt(id), display: false,
+   details: { version: 2, kind: "checkpoint", goalId: id } });
  }
- if (checkpointGoalId === null) return null;
- const output: unknown[] = [];
- let start = 0;
- for (const index of checkpoints) {
-  for (let i = start; i < index; i++) output.push(messages[i]);
-  start = index + 1;
- }
- const message = messages[lastCheckpointIndex] as Record<string, unknown>;
- output.push({...message, content: checkpointTriggerPrompt(checkpointGoalId), display: false, details: {
-  version: 2,
-  kind: currentGoal?.id === checkpointGoalId && currentGoal?.status === "active" ? "checkpoint" : "stale",
-  goalId: checkpointGoalId, currentGoalId: currentGoal?.id ?? null, currentStatus: currentGoal?.status ?? null,
- }});
- for (let i = start; i < messages.length; i++) output.push(messages[i]);
-	return output;
+ return output;
 }
 
 /**
@@ -84,22 +60,18 @@ export function compactGoalCheckpointContext(
  */
 export function registerGoalEvents(core: GoalCore): void {
 	const { pi } = core;
+	let liveContent: string | undefined;
+	pi.on("before_provider_request", event => cacheGoalHistory(event.payload, liveContent));
 	let continuationAfterSettleFor: string | null = null;
 	let networkErrorRecoveryAfterSettleFor: string | null = null;
 
 	pi.on("context", async (event, ctx) => {
 		const filtered = filterGoalSessionContext(event.messages);
 		const messages = compactGoalCheckpointContext(filtered ?? event.messages, core.state.goal) ?? filtered;
-		if (core.scheduler.needsLiveContext() && core.state.goal) {
-			const goal = core.state.goal;
-			const settings = loadGoalSettings(ctx.cwd);
-			// Custom-message runs bypass before_agent_start. Refresh mutable scheduling
-			// state, but do not repeat policy/objective already in the inherited prompt.
-			const content = ctx.getSystemPrompt?.().includes(`[PI GOAL ACTIVE goalId=${goal.id}]`)
-				? `[CURRENT EXECUTION STATE goalId=${goal.id}]\nStatus: ${goal.status}; autoContinue: ${goal.autoContinue}.\n${schedulerSummary(goal.scheduler, settings.maxAutonomousRuns)}`
-				: goalPrompt(goal, settings);
-			const live = { role: "custom" as const, customType: "pi-goal-live-context", content, display: false, timestamp: Date.now() };
-			return { messages: [live, ...(messages ?? event.messages)] as typeof event.messages };
+		const content = liveContent = currentGoalContext(ctx);
+		if (content) {
+			const live = { role: "custom" as const, customType: "pi-goal-live-context", content, display: false, timestamp: 0 };
+			return { messages: [...(messages ?? event.messages), live] as typeof event.messages };
 		}
 		return messages === null ? undefined : { messages: messages as typeof event.messages };
 	});
@@ -343,16 +315,9 @@ export function registerGoalEvents(core: GoalCore): void {
 	});
 
 	pi.on("before_agent_start", async (event, ctx) => {
-		core.scheduler.prepare();
 		core.advanceTurnSeq();
   if (!hasActiveDraft(core)) core.installGoalToolProfile(!loadGoalSettings(ctx.cwd).disableTasks);
-		const currentSystemPrompt = () => ctx.getSystemPrompt?.() || event.systemPrompt;
 		const incomingGoalId = extractGoalIdFromInjectedMessage(event.prompt ?? "");
-		// Several prompt enrichments may need the same ledger snapshot. Keep one
-		// local read for this hook instead of repeatedly traversing the cached
-		// ledger when rejection and post-compaction steering overlap.
-		let promptLedger: ReturnType<typeof readGoalLedger> | undefined;
-		const getPromptLedger = () => promptLedger ??= { events: core.state.goal ? goalRuntimeEvents(ctx, core.state.goal.id) : [], malformed: 0 };
 
 		// If this turn was triggered by a hidden goal checkpoint that no longer
 		// matches the active goal, abort the whole turn instead of letting the
@@ -371,9 +336,7 @@ export function registerGoalEvents(core: GoalCore): void {
 					ctx.abort?.();
 				} catch {}
 				core.updateUI(ctx);
-				return {
-					systemPrompt: `${currentSystemPrompt()}\n\n${staleContinuationPrompt(incomingGoalId, core.state.goal)}`,
-				};
+				return;
 			}
 			core.runtime.setCheckpoint(null);
 		} else {
@@ -385,22 +348,29 @@ export function registerGoalEvents(core: GoalCore): void {
 			networkErrorRecoveryAfterSettleFor = null;
 		}
 
+		core.reconcileFocusedGoalFromDisk(ctx);
+		core.runningGoalId = core.state.goal?.status === "active" ? core.state.goal.id : null;
+	});
+
+	/** Request-only state: no live counters, focus, or reminders enter the system prefix. */
+	function currentGoalContext(ctx: ExtensionContext): string | undefined {
+		const checkpoint = core.runtime.getCheckpointGoalId();
+		if (checkpoint !== null && !core.isActionableContinuationGoal(checkpoint)) {
+			return staleContinuationPrompt(checkpoint, core.state.goal);
+		}
+		// Several prompt enrichments may need the same ledger snapshot. Keep one
+		// local read for this hook instead of repeatedly traversing the cached
+		// ledger when rejection and post-compaction steering overlap.
+		let promptLedger: ReturnType<typeof readGoalLedger> | undefined;
+		const getPromptLedger = () => promptLedger ??= { events: core.state.goal ? goalRuntimeEvents(ctx, core.state.goal.id) : [], malformed: 0 };
+
 		if (!core.state.goal) {
-			core.runningGoalId = null;
 			const openCount = otherOpenGoalCount(core.goalsById, null);
 			if (openCount > 0) {
-				return { systemPrompt: `${currentSystemPrompt()}\n\n${unfocusedOpenGoalsPrompt(openCount)}` };
+				return unfocusedOpenGoalsPrompt(openCount);
 			}
 			return;
 		}
-		core.reconcileFocusedGoalFromDisk(ctx);
-		if (!core.state.goal) {
-			core.runningGoalId = null;
-			const openCount = otherOpenGoalCount(core.goalsById, null);
-			if (openCount > 0) return { systemPrompt: `${currentSystemPrompt()}\n\n${unfocusedOpenGoalsPrompt(openCount)}` };
-			return;
-		}
-		core.runningGoalId = core.state.goal.status === "active" ? core.state.goal.id : null;
 		if (core.state.goal.status === "complete") return;
 		if (core.state.goal.status === "paused") {
 			const current = core.state.goal;
@@ -421,9 +391,7 @@ export function registerGoalEvents(core: GoalCore): void {
 			} catch {
 				// Ledger read failure should not break the prompt
 			}
-			return {
-				systemPrompt: `${currentSystemPrompt()}\n\n[PI GOAL PAUSED goalId=${current.id}]\n${untrustedObjectiveBlock(current)}${pauseExtras.join("\n")}${auditorExtra}\n\nThe goal is paused. Do not autonomously continue substantive work unless the user resumes it with /goal-resume. If the user explicitly asks to finish the paused goal and the objective is already satisfied based on available evidence, you may call update_goal({status: "complete"}). To abandon a goal, the user runs /goal-clear. Do not report the goal blocked in response to a pause.`,
-			};
+			return `[PI GOAL PAUSED goalId=${current.id}]\n${untrustedObjectiveBlock(current)}${pauseExtras.join("\n")}${auditorExtra}\n\nThe goal is paused. Do not autonomously continue substantive work unless the user resumes it with /goal-resume. If the user explicitly asks to finish the paused goal and the objective is already satisfied based on available evidence, you may call update_goal({status: "complete"}). To abandon a goal, the user runs /goal-clear. Do not report the goal blocked in response to a pause.`;
 		}
 		// Token-budget-limited goals get one-time wrap-up steering: summarize,
 		// do not start new substantive work, never claim completion unless real.
@@ -440,13 +408,11 @@ export function registerGoalEvents(core: GoalCore): void {
 			const reminder = core.runtime.consumePostBudgetReminder()
 				? `\n\n[TOKEN BUDGET REACHED goalId=${limitedGoal.id}]\nThe goal's token budget has been reached${budgetText ? ` (${budgetText}${balanceText})` : ""}. Wrap up the current work in one final response: summarize what was accomplished and what remains, do not start new substantive work, and do not claim the goal is complete unless it actually is. To continue, the user must raise or remove the budget and resume the goal.`
 				: "";
-			return {
-				systemPrompt: `${currentSystemPrompt()}\n\n[PI GOAL BUDGET LIMITED goalId=${limitedGoal.id}]\n${untrustedObjectiveBlock(limitedGoal)}${budgetText ? `\n${budgetText}` : ""}${reminder}`,
-			};
+			return `[PI GOAL BUDGET LIMITED goalId=${limitedGoal.id}]\n${untrustedObjectiveBlock(limitedGoal)}${budgetText ? `\n${budgetText}` : ""}${reminder}`;
 		}
   if (core.state.goal.status === "blocked") {
    const blocked = core.state.goal;
-   return {systemPrompt: `${currentSystemPrompt()}\n\n[PI GOAL BLOCKED goalId=${blocked.id}]\n${untrustedObjectiveBlock(blocked)}\nBlocker: ${blocked.pauseReason ?? "unspecified"}\nThe goal is blocked; the user must run /goal-resume before goal work continues.`};
+   return `[PI GOAL BLOCKED goalId=${blocked.id}]\n${untrustedObjectiveBlock(blocked)}\nBlocker: ${blocked.pauseReason ?? "unspecified"}\nThe goal is blocked; the user must run /goal-resume before goal work continues.`;
   }
 		const activeGoal = core.state.goal;
 		const settings = loadGoalSettings(ctx.cwd);
@@ -466,7 +432,7 @@ export function registerGoalEvents(core: GoalCore): void {
 		}
 		if (core.runtime.isPostCompactReminderPending() && shouldInjectPostCompactReminder({ pending: true, goal: activeGoal })) {
 			core.runtime.clearPostCompactReminder();
-			// PR E §62: post-compaction DELTA — the active system goal block already
+			// PR E §62: post-compaction DELTA — the current goal block already
 			// carries objective/policy/task gate/contract; inject only what
 			// compaction may have lost. Falls back to a generic note on ledger
 			// read failure.
@@ -479,8 +445,8 @@ export function registerGoalEvents(core: GoalCore): void {
 				prompt = `${prompt}\n\n[POST-COMPACTION RESYNC goalId=${core.state.goal.id}]\nThe conversation was just compacted. Re-read the objective and continue from the actual artifacts/state; do not rely on memory of the prior chat.`;
 			}
 		}
-		return { systemPrompt: `${currentSystemPrompt()}\n\n${prompt}` };
-	});
+		return prompt;
+	}
 
 	pi.on("agent_end", async (event, ctx) => {
 		const endedGoalId = core.runningGoalId;

package/extensions/goal-prompt-cache.ts

@@ -0,0 +1,49 @@
+import { asRecord } from "./goal-record.ts";
+
+/**
+ * Pi marks the final user block for explicit caching. Our request-only state
+ * never enters history, so that block cannot be reused on the next request.
+ * Move that existing breakpoint to the preceding cacheable history block.
+ * Implicit caches and cacheRetention=none have no marker and are untouched.
+ * Reuse the provider's TTL and marker count rather than enabling caching here.
+ */
+export function cacheGoalHistory(payload: unknown, liveContent: string | undefined): unknown {
+ const root = asRecord(payload);
+ if (!liveContent || !Array.isArray(root?.messages)) return undefined;
+ const messages = root.messages;
+ const last = asRecord(messages.at(-1));
+ if (last?.role !== "user" || !Array.isArray(last.content)) return undefined;
+ // Bedrock represents its breakpoint as a separate content block.
+ const bedrockPoint = asRecord(last.content.at(-1));
+ if (asRecord(bedrockPoint?.cachePoint) && asRecord(last.content.at(-2))?.text === liveContent) {
+  for (let i = messages.length - 2; i >= 0; i--) {
+   const previous = asRecord(messages[i]);
+   if (!Array.isArray(previous?.content) || previous.content.length === 0) continue;
+   if (!previous.content.some(block => asRecord(block)?.cachePoint)) previous.content.push(bedrockPoint);
+   last.content.pop();
+   return payload;
+  }
+  return undefined;
+ }
+ const tail = asRecord(last.content.at(-1));
+ if (tail?.type !== "text" || tail.text !== liveContent || !asRecord(tail.cache_control)) return undefined;
+ for (let i = messages.length - 1; i >= 0; i--) {
+  const message = asRecord(messages[i]);
+  if (!message || !["user", "assistant", "tool"].includes(String(message.role))) continue;
+  if (typeof message.content === "string" && message.content.length > 0) {
+   message.content = [{ type: "text", text: message.content, cache_control: tail.cache_control }];
+   delete tail.cache_control;
+   return payload;
+  }
+  if (!Array.isArray(message.content)) continue;
+  for (let j = message.content.length - 1; j >= 0; j--) {
+   const block = asRecord(message.content[j]);
+   // Thinking blocks cannot carry cache_control. Never split/reorder tool pairs.
+   if (!block || block === tail || !["text", "image", "tool_use", "tool_result"].includes(String(block.type))) continue;
+   block.cache_control ??= tail.cache_control;
+   delete tail.cache_control;
+   return payload;
+  }
+ }
+ return undefined;
+}

package/extensions/goal-scheduler.ts

@@ -11,8 +11,6 @@ export class GoalScheduler {
 	private timer: ReturnType<typeof setTimeout> | undefined;
 	private ctx: ExtensionContext | undefined;
 	private inRun = false;
-	private prepared = false;
-	private liveContext = false;
 	private armedGeneration: string | undefined;
 	private declared = false;
 	private runGoalId: string | undefined;
@@ -183,14 +181,10 @@ export class GoalScheduler {
 		} catch (error) { return { content: [{ type: "text", text: `Scheduling decision NOT saved: ${error instanceof Error ? error.message : String(error)}` }], details: { error: true }, terminate: false }; }
 	}
 
-	prepare(): void { this.prepared = true; }
-	needsLiveContext(): boolean { return this.liveContext; }
-
 	/** One logical run can contain multiple agent_start events during native retry/compaction. */
 	begin(ctx: ExtensionContext): void {
 		this.ctx = ctx;
 		if (this.inRun) { this.core.runningGoalId = this.core.state.goal?.id ?? null; return; }
-		this.liveContext = !this.prepared; this.prepared = false;
 		this.inRun = true; this.declared = false; this.denied = false;
 		this.runGoalId = this.core.state.goal?.id;
 		this.cancelTimer(); this.core.runtime.clearContinuationTimer();

package/extensions/prompts/goal-prompts.ts

@@ -11,8 +11,8 @@ export const MAX_PROMPT_FRAGMENT_CHARS = 10_000;
 
 /**
  * Issue #30: a persisted continuation checkpoint is a tiny trigger record, not
- * a full prompt. The authoritative goal state is injected once per turn by
- * before_agent_start; the persisted marker only needs to carry the goal id.
+ * a full prompt. The authoritative goal state is injected at the request tail by
+ * the context hook; the persisted marker only needs to carry the goal id.
  */
 export const CHECKPOINT_TRIGGER_MAX_CHARS = 160;
 
@@ -265,8 +265,8 @@ export function objectiveEditedPrompt(goal: GoalRecord): string {
  * Deprecated compatibility wrapper (issue #30). The full continuation prompt
  * was the defect: every auto-continue turn persisted the whole objective/task/
  * contract/policy block as a custom session message, growing sessions by
- * ~6.4K chars per turn. The authoritative state is now injected once per turn
- * by before_agent_start; the persisted follow-up is only a tiny trigger.
+ * ~6.4K chars per turn. The authoritative state is now injected at the request tail
+ * by the context hook; the persisted follow-up is only a tiny trigger.
  *
  * Kept for one minor release so external call sites migrate explicitly.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-goal-x",
-  "version": "0.31.5",
+  "version": "0.31.6",
   "description": "Adds /goal to pi: conversational goal planning, flexible or ordered goals, persistent progress, and an independent completion auditor.",
   "license": "MIT",
   "author": "pi-goal-x contributors",
@@ -34,6 +34,7 @@
     "docs/agent-flow-design.md",
     "docs/agentic-runtime-prd.md",
     "docs/architecture.md",
+    "docs/prompt-caching.md",
     "docs/pi-autoresearch-survey.md",
     "docs/pi-goal-x-unified-dashboard-plan.md",
     "docs/unified-dashboard.md",