pi-goal-x 0.31.4 → 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,200 by downloads · Sep 14, 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>
@@ -115,7 +115,8 @@ Open `/goal-settings` to change these options. You can save defaults for all pro
 
 | Setting | What it controls |
 | --- | --- |
-| Autonomous run allowance (`maxAutonomousRuns`) | Positive whole number of extension-started runs per creation or `/goal-resume` period. **Unset disables automatic continuation.** Settings edits change the limit without resetting usage. |
+| Explicit execution contracts (`strictExecutionContract`) | Opt-in ready/wait protocol with one missing-decision repair, then pause. Defaults to `false`: successful executions continue automatically. |
+| Autonomous run allowance (`maxAutonomousRuns`) | Positive whole number of extension-started runs per creation or `/goal-resume` period. **Unset means unlimited; zero disables automatic continuation.** Settings edits change the limit without resetting usage. |
 | Task tracking (`disableTasks`) | Turn task lists on or off. Set to `true` to disable them. |
 | Subtask depth (`subtaskDepth`) | Limit how many levels of subtasks the agent can create. |
 | Completion requirements (`disableContracts`) | Turn explicit goal and task completion requirements on or off. Set to `true` to disable them. |
@@ -123,9 +124,11 @@ Open `/goal-settings` to change these options. You can save defaults for all pro
 | Auditor provider, model, and thinking level | Choose which model reviews completed work and its reasoning effort. |
 
 
-### Explicit execution and waiting
+### Automatic continuation and optional execution contracts
 
-Goals no longer restart merely because they remain unfinished or a tool was used. Before yielding, the agent declares runnable work or an external wait using `update_goal`, or reports complete, paused, or blocked. A missing decision permits one repair prompt within the remaining allowance, then pauses.
+Active goals continue automatically after successful executions, including reasoning-only responses and final-task verification. No tool call, task update, scheduling declaration, or cooldown is required. Unproductive loops remain possible; optional run limits and token budgets still apply.
+
+Enable `strictExecutionContract: true` in `/goal-settings` or your global/project settings to require explicit ready/wait decisions. In that mode, a missing decision permits one repair prompt within the remaining allowance, then pauses. This is a user preference; agents should not enable it merely to continue.
 
 Set an appropriate allowance in `/goal-settings`, or in `.pi/pi-goal-x-settings.json`:
 
@@ -133,7 +136,9 @@ Set an appropriate allowance in `/goal-settings`, or in `.pi/pi-goal-x-settings.
 { "maxAutonomousRuns": 20 }
 ```
 
-Agents may edit this setting. Changing it does not replenish consumed runs; explicit `/goal-resume` renews the period and continues now, including from a waiting goal. It requires a configured allowance. Tool calls within a run are not separate runs. Existing token budgets still apply.
+Agents may edit this setting. Changing it does not replenish consumed runs; explicit `/goal-resume` renews the period and continues now, including from a waiting goal. No configured allowance is required unless the effective limit is zero, which disables resume. Tool calls within a run are not separate runs. Existing token budgets still apply.
+
+Explicit `ready` is optional in default mode. New `wait` declarations require strict mode; otherwise they return a non-terminating error. Previously saved waits retain their deadline, checks, and repair rules when upgrading or disabling strict mode, and may be re-declared with the same identity. Mode changes never resume a paused goal or renew consumed runs.
 
 ```js
 update_goal({ continuation: { kind: "ready", next_action: "Verify the build artifacts" } })
@@ -163,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,200 by downloads · Sep 14, 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,200 by downloads · Sep 14, 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,200 by downloads · Sep 14, 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,200 by downloads · Sep 14, 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-commands.ts

@@ -370,6 +370,7 @@ export function registerGoalCommands(core: GoalCore): void {
 		{ key: "autoSelectSingleGoal", label: "autoSelectSingleGoal", section: "Goal behavior", kind: "boolean" },
 		{ key: "hideUnfocusedBanner", label: "hideUnfocusedBanner", section: "Goal behavior", kind: "boolean" },
 		{ key: "disableContracts", label: "disableContracts", section: "Goal behavior", kind: "boolean" },
+		{ key: "strictExecutionContract", label: "explicit execution contracts (opt-in)", section: "Goal behavior", kind: "boolean" },
 		{ key: "maxAutonomousRuns", label: "autonomous run allowance", section: "Goal behavior", kind: "positiveInteger" },
 		{ key: "stallTimeoutMinutes", label: "stall timeout (minutes)", section: "Goal behavior", kind: "positiveInteger" },
 		{ key: "objectiveMaxChars", label: "max objective length (0 = none)", section: "Goal behavior", kind: "positiveInteger" },
@@ -389,7 +390,7 @@ export function registerGoalCommands(core: GoalCore): void {
 	];
 
 	function settingsValue(config: GoalSettings, key: keyof GoalSettings | string): string {
-		if (key === "disabled" || key === "disableTasks" || key === "disableContracts" || key === "autoSelectSingleGoal" || key === "auditorProjectResources" || key === "hideUnfocusedBanner") {
+		if (key === "strictExecutionContract" || key === "disabled" || key === "disableTasks" || key === "disableContracts" || key === "autoSelectSingleGoal" || key === "auditorProjectResources" || key === "hideUnfocusedBanner") {
 			return config[key] === true ? "true" : "false";
 		}
 		if (key === "subtaskDepth") return config.subtaskDepth !== undefined ? String(config.subtaskDepth) : "1";

package/extensions/goal-core-tools.ts

@@ -509,8 +509,8 @@ async function runGoalAgentPauseFlow(ctx: ExtensionContext, reason: string | und
 pi.registerTool(defineTool({
 	name: "update_goal",
 	label: "Update Goal",
-	description: "End execution with status OR continuation. Wait: future ISO deadline; reuse wait_id/deadline without polling on recheck. Completion is audited.",
-	promptSnippet: "Declare the next execution disposition or complete, block, or pause.",
+	description: "Update lifecycle status or optionally save continuation. New waits require strictExecutionContract opt-in. Wait: future ISO deadline; reuse wait_id/deadline without polling on recheck. Completion is audited.",
+	promptSnippet: "Complete, block, pause, or optionally save a scheduling decision.",
 	promptGuidelines: [],
 	parameters: Type.Object({
 		status: Type.Optional(StringEnum(["complete", "blocked", "paused"] as const, { description: "Exclusive with continuation." })),

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;
@@ -23,6 +21,13 @@ export class GoalScheduler {
 
 	private owner(ctx: ExtensionContext): string { return ctx.sessionManager.getSessionId() || "unknown-session"; }
 	private limit(ctx: ExtensionContext): number | undefined { return loadGoalSettings(ctx.cwd).maxAutonomousRuns; }
+	private strict(ctx: ExtensionContext, s: GoalSchedulerState): boolean {
+		return loadGoalSettings(ctx.cwd).strictExecutionContract === true || !!s.wait;
+	}
+	private implicitReady(s: GoalSchedulerState): void {
+		s.phase = "ready"; s.dispatch = undefined; s.generation = randomUUID();
+		s.decision = { kind: "ready", nextAction: "Continue pursuing the goal, then verify and complete it when satisfied.", purpose: "ready" };
+	}
 	private available(ctx: ExtensionContext, s: GoalSchedulerState): boolean {
 		const limit = this.limit(ctx);
 		return limit === undefined || s.used < limit;
@@ -148,6 +153,7 @@ export class GoalScheduler {
 					if (typeof input.next_action !== "string" || !input.next_action.trim() || input.next_action.length > 2000) throw new Error("ready requires a nonempty next_action (at most 2000 characters).");
 					s.phase = "ready"; s.decision = { kind: "ready", nextAction: input.next_action.trim(), purpose: "ready" }; s.wait = undefined;
 				} else if (input.kind === "wait") {
+					if (!this.strict(ctx, s)) throw new Error("New waits require strictExecutionContract=true in /goal-settings. This is a user preference; continue pursuing the goal without a wait unless the user opts in.");
 					if (typeof input.reason !== "string" || !input.reason.trim() || input.reason.length > 2000) throw new Error("wait requires a nonempty reason (at most 2000 characters).");
 					const deadline = Date.parse(input.deadline);
 					if (!/T.*(?:Z|[+-]\d\d:\d\d)$/.test(input.deadline) || !Number.isSafeInteger(deadline) || deadline <= Date.now()) throw new Error("wait requires a future ISO deadline with a timezone.");
@@ -175,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();
@@ -230,11 +232,16 @@ export class GoalScheduler {
 	settled(ctx: ExtensionContext, successful = true): void {
 		this.inRun = false;
 		if (this.denied || (this.runGoalId && this.core.state.goal?.id !== this.runGoalId)) return;
+		invalidateGoalSettingsCache();
 		this.safe(ctx, () => {
 			const goal = this.core.state.goal;
 			if (!goal || goal.status !== "active" || !goal.autoContinue || !successful) return;
 			if (this.declared && goal.scheduler?.decision) { this.schedule(ctx); return; }
 			const s = this.state(ctx, goal);
+			if (!this.strict(ctx, s)) {
+				this.update(ctx, state => this.implicitReady(state));
+				this.schedule(ctx); return;
+			}
 			if (s.repairUsed || !this.available(ctx, s)) {
 				this.pause(ctx, !this.available(ctx, s) ? this.allowanceReason(ctx) : "No execution disposition after the contract-repair prompt. Use /goal-resume to continue.");
 				return;
@@ -248,7 +255,7 @@ export class GoalScheduler {
 	}
 	recover(ctx: ExtensionContext): void {
 		this.safe(ctx, () => {
-			this.update(ctx, s => { s.phase = "ready"; s.dispatch = undefined; s.decision = { kind: "ready", nextAction: "Retry after the provider error, then declare an execution disposition.", purpose: "recovery" }; });
+			this.update(ctx, s => { s.phase = "ready"; s.dispatch = undefined; s.decision = { kind: "ready", nextAction: this.strict(ctx, s) ? "Retry after the provider error, then declare an execution disposition." : "Retry after the provider error and continue pursuing the goal.", purpose: "recovery" }; });
 			this.schedule(ctx);
 		});
 	}
@@ -264,11 +271,15 @@ export class GoalScheduler {
 	}
 	schedule(ctx: ExtensionContext): void {
 		if (this.inRun) return;
+		invalidateGoalSettingsCache();
 		this.safe(ctx, () => {
 			this.core.reconcileFocusedGoalFromDisk(ctx);
 			const g = this.core.state.goal;
 			if (!g || g.status !== "active" || !g.autoContinue || !g.scheduler) return;
-			const s = this.state(ctx, g);
+			let s = this.state(ctx, g);
+			if (s.phase === "ready" && s.decision?.kind === "ready" && s.decision.purpose === "repair" && !this.strict(ctx, s)) {
+				s = this.update(ctx, state => this.implicitReady(state)).scheduler!;
+			}
 			if (!["ready", "waiting"].includes(s.phase)) return;
 			if (budgetReached(g)) { this.pause(ctx, "Goal token budget exhausted."); return; }
 			if (!this.available(ctx, s)) { this.pause(ctx, this.allowanceReason(ctx)); return; }
@@ -299,6 +310,7 @@ export class GoalScheduler {
 				if (s.generation !== generation) throw new Error("Scheduling generation changed.");
 				if (g.status !== "active" || !g.autoContinue || budgetReached(g) || !this.available(ctx, s)) throw new Error(this.allowanceReason(ctx));
 				if (s.wait && Date.now() >= s.wait.deadline) throw new Error("Wait deadline reached.");
+				if (s.phase === "ready" && s.decision?.kind === "ready" && s.decision.purpose === "repair" && !this.strict(ctx, s)) this.implicitReady(s);
 				let kind = s.phase === "ready" && s.decision?.kind === "ready" ? s.decision.purpose : undefined;
 				if (s.phase === "waiting" && s.wait) {
 					if (s.wait.signalled) kind = "wake";

package/extensions/goal-settings.ts

@@ -104,6 +104,7 @@ export interface GoalSettingsResolvedShape {
 	stallTimeoutMinutes?: number;
 	/** Optional extension-run limit per creation/resume; zero disables, absent inherits (default unlimited). */
 	maxAutonomousRuns?: number;
+	strictExecutionContract?: boolean;
 	/**
 	 * Maximum objective length in characters (0/unset = no limit, the
 	 * default; >0 caps objectives in create_goal, propose_goal_draft, and
@@ -331,6 +332,7 @@ const ALLOWED_SETTINGS_KEYS = new Set([
 	"auditorProjectResources",
 	"stallTimeoutMinutes",
 	"maxAutonomousRuns",
+	"strictExecutionContract",
 	"objectiveMaxChars",
 	"keybindings",
 	"hideUnfocusedBanner",
@@ -380,6 +382,7 @@ export function parseSettingsLayer(
 
 	for (const [key, value] of Object.entries(record)) {
 		switch (key) {
+			case "strictExecutionContract":
 			case "disableTasks":
 			case "disableContracts":
 			case "disabled":
@@ -790,6 +793,11 @@ function resolvedSettingsSnapshot(cwd: string, env: NodeJS.ProcessEnv): Settings
 		globalValue: global.layer.oracle?.maxFailedAttemptsPerBlocker,
 		defaultValue: 2,
 	}));
+	const strictExecutionContract = track("strictExecutionContract", resolveLeaf<boolean>({
+		projectValue: project.layer.strictExecutionContract,
+		globalValue: global.layer.strictExecutionContract,
+		defaultValue: false,
+	}));
 	const maxAutonomousRuns = track("maxAutonomousRuns", resolveLeaf<number | undefined>({
 		projectValue: project.layer.maxAutonomousRuns,
 		globalValue: global.layer.maxAutonomousRuns,
@@ -855,6 +863,7 @@ function resolvedSettingsSnapshot(cwd: string, env: NodeJS.ProcessEnv): Settings
 		hideUnfocusedBanner,
 		stallTimeoutMinutes,
 		maxAutonomousRuns,
+		strictExecutionContract,
 		objectiveMaxChars,
 		keybindings,
 		networkRecovery: {
@@ -1204,6 +1213,7 @@ function buildPersistedLayer(settings: GoalSettings): Record<string, unknown> {
 		if (so.maxFailedAttemptsPerBlocker !== undefined) o.maxFailedAttemptsPerBlocker = so.maxFailedAttemptsPerBlocker;
 		if (Object.keys(o).length > 0) persisted.oracle = o;
 	}
+	if (settings.strictExecutionContract !== undefined) persisted.strictExecutionContract = settings.strictExecutionContract;
 	if (settings.maxAutonomousRuns !== undefined) persisted.maxAutonomousRuns = settings.maxAutonomousRuns;
 	if (settings.stallTimeoutMinutes !== undefined) persisted.stallTimeoutMinutes = settings.stallTimeoutMinutes;
 	if (settings.objectiveMaxChars !== undefined) persisted.objectiveMaxChars = settings.objectiveMaxChars;
@@ -1248,6 +1258,7 @@ export function effectiveSettingsReport(cwd: string, env: NodeJS.ProcessEnv = pr
 		{ key: "thinkingLevel", label: "thinking_level", format: () => snapshot.value.thinkingLevel ?? "(default)" },
 		{ key: "auditorProjectResources", label: "auditor project resources", format: () => String(snapshot.value.auditorProjectResources) },
 		{ key: "hideUnfocusedBanner", label: "hide unfocused banner", format: () => String(snapshot.value.hideUnfocusedBanner) },
+		{ key: "strictExecutionContract", label: "explicit execution contracts (opt-in)", format: () => String(snapshot.value.strictExecutionContract) },
 		{ key: "maxAutonomousRuns", label: "autonomous run allowance", format: () => snapshot.value.maxAutonomousRuns === 0 ? "0 (disabled)" : String(snapshot.value.maxAutonomousRuns ?? "unlimited (default)") },
 		{ key: "stallTimeoutMinutes", label: "stall timeout (minutes)", format: () => String(snapshot.value.stallTimeoutMinutes) },
 		{ key: "objectiveMaxChars", label: "max objective length (0 = none)", format: () => String(snapshot.value.objectiveMaxChars) },

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;
 
@@ -183,11 +183,12 @@ export function sisyphusDisciplineBlock(goal: GoalRecord): string {
 }
 
 /** Shared outcome/blocker policy for active goals (bounded). */
-function lifecyclePolicyBlock(autonomous: boolean): string {
+function lifecyclePolicyBlock(autonomous: boolean, strict: boolean): string {
  return [
   "[OUTCOMES]",
   '- Automatic runs default to unlimited. maxAutonomousRuns in .pi/pi-goal-x-settings.json caps runs; 0 disables (agents may set it). Only creation or user /goal-resume renews usage.',
-  ...(autonomous ? ['- End execution with update_goal: ready for runnable work, wait for an external condition, or a status below. Saved decisions terminate; further work invalidates them. Missing decisions allow one repair. Never busy-poll.'] : []),
+  ...(autonomous && strict ? ['- End execution with update_goal: ready for runnable work, wait for an external condition, or a status below. Saved decisions terminate; further work invalidates them. Missing decisions allow one repair. Never busy-poll.'] : []),
+  ...(autonomous && !strict ? ['- Continue pursuing the goal automatically after each execution; no scheduling declaration is required. Optional ready saves a next action. New waits require user opt-in to strictExecutionContract; do not enable it merely to continue.'] : []),
   '- update_goal({status: "complete"}) only when every requirement is satisfied; the independent completion auditor checks actual evidence. Approval archives; rejection requires rework.',
   '- update_goal({status: "blocked"}) only after the SAME blocker recurs on three consecutive goal turns; keep trying concrete steps before then.',
   '- update_goal({status: "paused", reason: "…"}) pauses immediately. User controls: /goal-pause, /goal-resume, /goal-clear.',
@@ -207,7 +208,7 @@ let promptCacheChars = 0;
 function cachedPrompt(goal: GoalRecord, settings: GoalSettings | undefined, kind: "goal" | "continuation", build: () => string): string {
  const key = [kind, goal.id, goal.status, goal.autoContinue, goal.sisyphus, goal.objective,
   goal.verificationContract, settings?.disableTasks ? undefined : taskIndex(goal.taskList?.tasks),
-  goal.taskList?.blockCompletion, promptProfile(), goal.currentTaskId, settings?.disableTasks, settings?.disableContracts, settings?.maxAutonomousRuns !== 0];
+  goal.taskList?.blockCompletion, promptProfile(), goal.currentTaskId, settings?.disableTasks, settings?.disableContracts, settings?.maxAutonomousRuns !== 0, settings?.strictExecutionContract === true, !!goal.scheduler?.wait];
  for (let i = promptFragmentCache.length - 1; i >= 0; i--) {
   const entry = promptFragmentCache[i]!;
   if (key.every((part, j) => part === entry.key[j])) return entry.value;
@@ -238,7 +239,7 @@ function buildGoalPrompt(goal: GoalRecord, settings?: GoalSettings): string {
  // Bound individual data fields so essential rules can never be sliced off.
  return [
   `[PI GOAL ACTIVE goalId=${goal.id}]`,
-  lifecyclePolicyBlock(settings?.maxAutonomousRuns !== 0), sisyphusDisciplineBlock(goal),
+  lifecyclePolicyBlock(settings?.maxAutonomousRuns !== 0, settings?.strictExecutionContract === true || !!goal.scheduler?.wait), sisyphusDisciplineBlock(goal),
   `Status: ${statusLabel(goal)}\nMode: ${goal.sisyphus ? "sisyphus" : "regular"}`,
   untrustedObjectiveBlock(goal), taskListBlock(goal, settings), verificationContractBlock(goal, settings),
  ].filter(Boolean).join("\n\n");
@@ -264,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.4",
+  "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",