pi-smart-compact 10.1.5 → 10.2.1

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 ## [Unreleased]
 
+## [10.2.1] - 2026-10-05
+
+### Release approval
+
+- The release owner approved `10.2.1` as a stable patch with a version-specific
+  canary exception. Publication remains gated on the deterministic checks for
+  this exact candidate. No version-specific applied-canary cohort or live
+  provider/signature test exists; offline regressions do not establish cache-hit
+  savings or a `PROMOTE` result.
+
+### Fixed
+
+- **Native compaction prefix.** Reuse Pi's complete system/tool transcript
+  instead of prepending the current prompt and loadout a second time. Legacy
+  histories without an initial system message retain their fallback. Real-adapter
+  regressions cover initial and repeated native compaction; provider-side
+  thinking-signature acceptance is not claimed by these offline tests.
+- **Context attention follows execution gates.** Do not recommend trimming over
+  prepared compaction. Recompute prompt-start guidance instead of parking stale
+  pressure in `nextTurn`, and describe settled, background and native-hook
+  strategies separately. History guidance remains available with navigation off;
+  checkpoints no longer promise that a later rewind will be safe. Anchor advice
+  does not guarantee cleanup or cache hits, and manual-mode compaction advice
+  distinguishes staging from applying. A real offline Pi lifecycle regression
+  covers compaction between a completed high-pressure turn and the next prompt.
+
+## [10.2.0] - 2026-10-05
+
+### Release approval
+
+- Minor release approved by the release owner after the deterministic gates
+  on the exact candidate. No version-specific applied-canary cohort or live
+  provider run exists for `10.2.0`; the feature is evidenced by unit tests
+  only. The note is gated by `Navigation guide` (`contextGuidanceEnabled`)
+  and turns off with it.
+
+### Added
+
+- **Context attention.** Context pressure used to reach the model only through
+  the human status line and `smart_context status` results, so the anchor,
+  checkpoint/rewind, trim and compaction tools sat idle until a person asked
+  for them. The extension now sends the model one short note when usage
+  enters the cleanup band and one more at the compaction band, naming only
+  the actions available right now: `smart_navigation anchor` (with the lazy
+  `smart_tools` load step when needed), `smart_context checkpoint`/`rewind`
+  and `trim` only when history edits are possible on this model (signed
+  Anthropic thinking blocks them), plus whether automatic compaction will
+  prepare. Mid-turn the note rides along with the next tool batch; at a turn
+  end a cleanup note waits for the next prompt and a compaction note is
+  skipped under auto-trigger because settled compaction runs first. One note
+  per band per session, re-armed once pressure clears; the note is a tail
+  message, so the cached prefix is untouched. Gated by `Navigation guide`
+  (`contextGuidanceEnabled`), tool loading and agent tool access.
+
 ## [10.1.5] - 2026-10-05
 
 ### Release approval

package/dist/app/context-attention.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Context attention: one short note to the model when context pressure enters
+ * a band, naming only the actions that are available right now.
+ *
+ * Pressure used to reach the model only through the human status line and
+ * `smart_context status` results, so the navigation, history and compaction
+ * tools sat idle until a person asked for them. The note rides along with the
+ * next tool batch (steer) during a turn. Prompt-start notes are computed then,
+ * never parked in nextTurn where compaction or permissions can make them stale.
+ * One note per band per session, re-armed once pressure clears or the session
+ * changes. Notes append to history; they never rewrite the prompt prefix.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { CompactConfig } from "../types.ts";
+export declare const ATTENTION_CUSTOM_TYPE = "smart-compact-attention";
+type AttentionConfig = Pick<CompactConfig, "contextNavigationEnabled" | "contextGuidanceEnabled" | "toolLoading" | "autoTrigger" | "autoTriggerStrategy" | "minContextPercent" | "prepareContextPercent" | "maxContextTokens">;
+export interface ContextAttentionDeps {
+    config: () => AttentionConfig;
+    /** Agent-driven context changes are permitted and nothing (pivot, running compaction) takes priority. */
+    canAgentAct: (ctx: ExtensionContext) => boolean;
+    /** The same maintenance gate used by history cleanup; prepared work takes priority. */
+    canCleanup: (ctx: ExtensionContext) => boolean;
+    /** A lazy group can still be loaded through `smart_tools`. */
+    reachable: (group: "navigation" | "history" | "compaction") => boolean;
+}
+export declare function registerContextAttention(pi: Pick<ExtensionAPI, "on" | "sendMessage" | "getActiveTools">, deps: ContextAttentionDeps): void;
+export {};
+//# sourceMappingURL=context-attention.d.ts.map

package/dist/app/context-attention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-attention.d.ts","sourceRoot":"","sources":["../../src/app/context-attention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAEtF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAKjD,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAM/D,KAAK,eAAe,GAAG,IAAI,CAAC,aAAa,EACvC,0BAA0B,GAAG,wBAAwB,GAAG,aAAa,GAAG,aAAa,GAAG,qBAAqB,GAC3G,mBAAmB,GAAG,uBAAuB,GAAG,kBAAkB,CAAC,CAAC;AAExE,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,eAAe,CAAC;IAC9B,yGAAyG;IACzG,WAAW,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC;IAChD,uFAAuF;IACvF,UAAU,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC;IAC/C,8DAA8D;IAC9D,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,GAAG,YAAY,KAAK,OAAO,CAAC;CACxE;AAED,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,aAAa,GAAG,gBAAgB,CAAC,EAC/D,IAAI,EAAE,oBAAoB,GACzB,IAAI,CA2CN"}

package/dist/app/native-compaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-compaction.d.ts","sourceRoot":"","sources":["../../src/app/native-compaction.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,GAAG,EAAW,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EACV,aAAa,EAEb,iBAAiB,EACjB,mBAAmB,EAEpB,MAAM,aAAa,CAAC;AASrB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,OAAO,EAKL,KAAK,UAAU,EAEf,KAAK,WAAW,EAChB,KAAK,WAAW,EACjB,MAAM,6BAA6B,CAAC;AASrC,wFAAwF;AACxF,eAAO,MAAM,yBAAyB,kMAC2J,CAAC;AAQlM,yGAAyG;AACzG,MAAM,MAAM,gBAAgB,GAAG,MAAM,IAAI,EAAE,CAAC;AAE5C,kGAAkG;AAClG,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAElE;AAGD,+FAA+F;AAC/F,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,OAAO,KAAK,GAAG,SAAS,GAAG,IAAI,CAEpF;AAED,KAAK,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,UAAU,GAAG,IAAI,CAAC,CAAC;AAE9D,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAOpG;AASD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,mBAAmB,EAAE,EACpC,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,IAAI,CAUf;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC,GAAG,MAAM,CAEnF;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,OAAO,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GACrE;IAAE,OAAO,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,OAAO,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1C,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,UAAU,EACd,aAAa,EAAE,SAAS,aAAa,EAAE,GACtC,OAAO,CAAC,mBAAmB,CAAC,CAgQ9B;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAUjF;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE;IAAE,KAAK,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC,CAAA;CAAE,GAAG,MAAM,CAE/F;AAED,yEAAyE;AACzE,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IAC5C,YAAY,QAAQ,EAAE,SAAS,aAAa,EAAE,EAQ7C;CACF;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAiBtF;AAKD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAO9E;AAED,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD;AAED,uEAAuE;AACvE,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,cAAc,EAAE;QAAE,SAAS,IAAI,OAAO,EAAE,CAAC;QAAC,UAAU,IAAI,OAAO,EAAE,CAAC;QAAC,YAAY,CAAC,IAAI,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;IACzG,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,EAAE,CAAC,EAAE;QAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,IAAI,CAAA;KAAE,CAAC;CAC7E;AASD;;;;;;GAMG;AACH,wBAAgB,sBAAsB;IAGlC,OAAO,MAAM;QAAE,cAAc,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC,CAAA;KAAE,GAAG,IAAI;IAWvF,0EAA0E;IAC1E,MAAM,UAAU,OAAO,OAAO,mBAAmB,GAAG,UAAU,GAAG,SAAS;EA8B7E"}
+{"version":3,"file":"native-compaction.d.ts","sourceRoot":"","sources":["../../src/app/native-compaction.ts"],"names":[],"mappings":"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"}

package/dist/constants.d.ts

@@ -8,7 +8,7 @@ import type { CompressionProfile, ProfileConfig } from "./types.ts";
  * `package.json#version`. Do not hand-edit this line for releases; bump
  * package.json and run `bun run sync-version`.
  */
-export declare const VERSION = "10.1.5";
+export declare const VERSION = "10.2.1";
 /**
  * Opt-in components that are not installed with the extension: optional peer
  * dependencies in package.json, pinned to the versions the release audit

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAEN,KAAK,YAAY,EAEjB,MAAM,iCAAiC,CAAC;AAkEzC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAyDtE,MAAM,CAAC,OAAO,UAAU,qBAAqB,CAAC,EAAE,EAAE,YAAY,QA8lB7D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAEN,KAAK,YAAY,EAEjB,MAAM,iCAAiC,CAAC;AAmEzC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAyDtE,MAAM,CAAC,OAAO,UAAU,qBAAqB,CAAC,EAAE,EAAE,YAAY,QAumB7D"}

package/dist/index.js

@@ -5,7 +5,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 
 // src/constants.ts
-var VERSION = "10.1.5";
+var VERSION = "10.2.1";
 var OPTIONAL_COMPONENTS = {
   mnemopi: { name: "@oh-my-pi/pi-mnemopi", version: "18.3.1", enables: "Mnemopi memory store" },
   bun: { name: "bun", version: "1.4.2", enables: "Mnemopi worker runtime when no Bun 1.3.14+ is on PATH" },
@@ -9304,6 +9304,7 @@ async function attemptNativeCompaction(rc, priorAttempts) {
     };
   }
   const prefix = rc.msgs.slice(0, cut);
+  const messages = prefix.map((entry) => entry.message);
   const prefixTokens = prefix.reduce((sum, entry) => sum + rc.estimator.message(entry.message), 0);
   const totalEstimate = rc.msgs.reduce((sum, entry) => sum + rc.estimator.message(entry.message), 0);
   const retainedTailTokens = Math.max(0, totalEstimate - prefixTokens);
@@ -9337,9 +9338,11 @@ async function attemptNativeCompaction(rc, priorAttempts) {
   nestedRequests++;
   try {
     const stream = rc.ctx.modelRegistry.streamSimple(model, {
-      systemPrompt: rc.ctx.getSystemPrompt(),
-      messages: prefix.map((entry) => entry.message),
-      tools: toolSource()
+      messages,
+      ...messages[0]?.role === "system" ? {} : {
+        systemPrompt: rc.ctx.getSystemPrompt(),
+        tools: toolSource()
+      }
     }, {
       signal: rc.cancellation.signal,
       fetch: wrapper.fetch,
@@ -16807,6 +16810,109 @@ function createSettledAutoTrigger(options = {}) {
   return { request, noteCompaction, clear };
 }
 
+// src/app/context-attention.ts
+var ATTENTION_CUSTOM_TYPE = "smart-compact-attention";
+var CONTEXT_TOOL_NAME = "smart_context";
+var COMPACTION_TOOL_NAME = "smart_compact";
+var LOADER_TOOL_NAME = "smart_tools";
+function registerContextAttention(pi, deps) {
+  let noted = null;
+  const clear = () => {
+    noted = null;
+  };
+  pi.on("session_start", clear);
+  pi.on("session_before_switch", clear);
+  pi.on("session_before_fork", clear);
+  pi.on("session_tree", clear);
+  pi.on("session_compact", clear);
+  pi.on("model_select", clear);
+  pi.on("session_shutdown", clear);
+  const attention = (ctx) => {
+    const settings = deps.config();
+    if (!settings.contextGuidanceEnabled || settings.toolLoading === "off")
+      return;
+    const sessionId = resolveSessionId(ctx);
+    const pressure = contextPressure(ctx, settings);
+    const band = pressure.compaction ? "compaction" : pressure.cleanup ? "cleanup" : null;
+    if (!band) {
+      if (noted?.sessionId === sessionId)
+        noted = null;
+      return;
+    }
+    if (noted?.sessionId === sessionId && (noted.band === band || noted.band === "compaction"))
+      return;
+    if (!deps.canAgentAct(ctx))
+      return;
+    const active = new Set(pi.getActiveTools());
+    const content = renderAttention(band, pressure.percent, settings, ctx, active, deps.reachable, deps.canCleanup(ctx));
+    if (!content)
+      return;
+    noted = { sessionId, band };
+    return { customType: ATTENTION_CUSTOM_TYPE, content, display: true, details: { band, percent: pressure.percent } };
+  };
+  pi.on("before_agent_start", (_event, ctx) => {
+    const message = attention(ctx);
+    if (message)
+      return { message };
+  });
+  pi.on("message_end", (event, ctx) => {
+    const message = event.message;
+    if (message.role !== "assistant" || message.stopReason !== "toolUse")
+      return;
+    if (message.content.some((block) => block.type === "toolCall" && [NAVIGATION_TOOL_NAME, CONTEXT_TOOL_NAME, COMPACTION_TOOL_NAME].includes(block.name)))
+      return;
+    const note = attention(ctx);
+    if (note)
+      pi.sendMessage(note, { deliverAs: "steer" });
+  });
+}
+function renderAttention(band, percent, settings, ctx, active, reachable, canCleanup) {
+  const lines = [];
+  const load = (group, tool) => active.has(tool) ? "" : reachable(group) && active.has(LOADER_TOOL_NAME) ? ` Load it first: ${LOADER_TOOL_NAME} load ${group}.` : null;
+  const navigation = settings.contextNavigationEnabled ? load("navigation", NAVIGATION_TOOL_NAME) : null;
+  const history = load("history", CONTEXT_TOOL_NAME);
+  if (navigation !== null) {
+    lines.push(`- Finishing a unit of work? ${NAVIGATION_TOOL_NAME} anchor with a concise handoff (done / in progress / next step). An anchor alone does not reduce context; cleanup depends on safety and preparation gates.${navigation}`);
+  }
+  if (history !== null) {
+    let trimmable = 0;
+    if (canCleanup) {
+      try {
+        const branch = ctx.sessionManager.getBranch();
+        const plan = planContextTrim(branch, inspectContext(branch, resolveSessionId(ctx)).checkpoint?.originId, { readerApi: ctx.model?.api });
+        if (!plan.blockedReason)
+          trimmable = plan.entries.filter((entry) => entry.type === "context_edit").length;
+      } catch {}
+    }
+    if (trimmable > 0)
+      lines.push(`- ${CONTEXT_TOOL_NAME} trim: ${trimmable} archived tool output${trimmable === 1 ? "" : "s"} eligible now.${history}`);
+    lines.push(`- Starting a large read-only detour? ${CONTEXT_TOOL_NAME} checkpoint first; rewind(report) afterward only when status permits. Keep findings and evidence in the report.${trimmable > 0 ? "" : history}`);
+  }
+  if (band === "compaction" && !settings.autoTrigger) {
+    const compaction = load("compaction", COMPACTION_TOOL_NAME);
+    if (compaction !== null)
+      lines.push(`- ${COMPACTION_TOOL_NAME} stages a summary (or reports an existing one); the user runs /compact within its staging TTL to apply it. Staging does not shrink context.${compaction}`);
+  }
+  if (!lines.length)
+    return null;
+  const where = percent === null ? "" : ` ${Math.round(percent)}% of the policy window`;
+  let automatic;
+  if (!settings.autoTrigger)
+    automatic = "Automatic compaction is off here; the user can run /smart-compact.";
+  else if (settings.autoTriggerStrategy === "native-hook")
+    automatic = "Preparation runs when Pi requests compaction; this strategy has no settled trigger.";
+  else if (band === "compaction")
+    automatic = "Automatic compaction is requested when the turn settles if pressure remains.";
+  else {
+    automatic = `Automatic compaction is requested at ${settings.minContextPercent}% when the turn settles.`;
+    if (settings.autoTriggerStrategy === "background")
+      automatic = "Background preparation can start in the cleanup band. " + automatic;
+  }
+  return `Context attention:${where} (${band} band). ${automatic}
+${lines.join(`
+`)}`;
+}
+
 // src/app/host-cache-ledger.ts
 var FOREIGN_REBUILD_WARN_COUNT = 3;
 var num = (value) => typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
@@ -25011,11 +25117,12 @@ function smartCompactExtension(pi) {
     onContextEdit: (_ctx, kind) => hostCache.noteContextEdit(kind)
   });
   registerArtifactOffload(pi, automaticConfig, () => toolExposure.reachable("history"));
+  const canAutoTrim = (ctx) => toolExposure.reachable("history") && !background.hasWork() && !pendingRef.isPresent(resolveSessionId(ctx)) && !isRunning.isSessionActive(resolveSessionId(ctx));
   const smartContext = registerSmartContextTool(pi, {
     config: automaticConfig,
     isPaused: pivotQueued,
     canAgentMutate: () => policy.snapshot().agentToolAccess !== "disabled",
-    canAutoTrim: (ctx) => toolExposure.reachable("history") && !background.hasWork() && !pendingRef.isPresent(resolveSessionId(ctx)) && !isRunning.isSessionActive(resolveSessionId(ctx)),
+    canAutoTrim,
     onContextChange: (ctx) => invalidatePreparation(ctx, "branch"),
     onContextEdit: (_ctx, kind) => hostCache.noteContextEdit(kind),
     onCacheWarm: (ctx, at) => {
@@ -25023,6 +25130,12 @@ function smartCompactExtension(pi) {
         hostCache.noteCacheWarm(at);
     }
   });
+  registerContextAttention(pi, {
+    config: automaticConfig,
+    canAgentAct: (ctx) => policy.snapshot().agentToolAccess !== "disabled" && !pivotQueued(ctx) && !isRunning.isSessionActive(resolveSessionId(ctx)),
+    canCleanup: canAutoTrim,
+    reachable: (group) => toolExposure.reachable(group)
+  });
   registerSmartCompactCommand(pi, {
     pendingRef,
     runLock: isRunning,

package/dist/rtk.js

@@ -198,7 +198,7 @@ class SecretScrubber {
 }
 
 // src/constants.ts
-var VERSION = "10.1.5";
+var VERSION = "10.2.1";
 var OPTIONAL_COMPONENTS = {
   mnemopi: { name: "@oh-my-pi/pi-mnemopi", version: "18.3.1", enables: "Mnemopi memory store" },
   bun: { name: "bun", version: "1.4.2", enables: "Mnemopi worker runtime when no Bun 1.3.14+ is on PATH" },

package/docs/configuration.md

@@ -454,7 +454,7 @@ Settings → **Agent tools & navigation**.
 | `contextPivotEnabled` | `Return to an anchor` | `true` | Returning to an anchor on a new branch with a required carryover. |
 | `contextAnchorCacheEnabled` | `Anchor prompt cache` | `true` | Anthropic models: keeps a prompt-cache marker on the newest anchor. |
 | `contextAnchorStatusEnabled` | `Anchor status` | `true` | Shows the newest anchor on this branch in Pi's footer; display only. |
-| `contextGuidanceEnabled` | `Navigation guide` | `true` | Lets you or the agent open the navigation guide on request; it is never added to a request otherwise. |
+| `contextGuidanceEnabled` | `Navigation guide` | `true` | Lets you or the agent open the navigation guide on request; the full guide is never injected automatically. Also enables one short context-attention note per pressure band. Prompt-start advice uses current usage and permissions, not a parked `nextTurn` note. It names reachable tools, shares cleanup's preparation gate, and distinguishes automatic strategies and staging from applying. Checkpoint metadata can remain available when trim/rewind is blocked. Navigation off does not disable history guidance. Re-armed when pressure clears, compaction occurs or the session/model changes. |
 
 Group permissions apply in both `lazy` and `eager` modes: `compaction` follows
 `agentToolAccess`, `memory` needs `contextGraphEnabled` or a non-local

package/docs/guide.md

@@ -459,8 +459,9 @@ Settings → **Agent tools & navigation** has the switches: **Session
 navigation** (off hides the panel and the agent tool; recorded anchors and the
 other switches are kept), **Search other sessions**, **Return to an anchor**,
 **Anchor prompt cache** (Anthropic models: keeps a prompt-cache marker on the
-newest anchor, so the context before it is read from cache while later turns
-change), **Anchor status** (footer, display only) and **Navigation guide**.
+newest anchor so an unchanged prefix can be reused while later turns change;
+hits still depend on provider caching and expiry), **Anchor status** (footer,
+display only) and **Navigation guide**.
 
 Legacy `context` tool anchors recorded in earlier sessions stay readable in
 browse and search.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-smart-compact",
-	"version": "10.1.5",
+	"version": "10.2.1",
 	"description": "Pi Continuity — context hygiene and session continuity for Pi Coding Agent: recoverable cleanup, checkpoints, memory and verified compaction.",
 	"type": "module",
 	"packageManager": "bun@1.4.2",