@oh-my-pi/pi-agent-core 18.2.10 → 18.3.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [18.3.0] - 2026-09-24
+
+### Added
+
+- Added support for documenting agent tools on demand through the new `AgentTool.docTopics` method.
+- Added `TOOL_INTERRUPT_ABORT_REASON` so interruptible tools can distinguish queued steering, peer messages, or background completions from a full run abort.
+
+### Changed
+
+- Improved interrupt handling so tools respect wait mode and can be interrupted when appropriate.
+- Updated Anthropic compaction compatibility with signature verification.
+
+## [18.2.11] - 2026-09-23
+
+### Fixed
+
+- Fixed background job completions interrupting foreground Bash and eval calls, which could cause those calls to be repeatedly moved into the background.
+
 ## [18.2.9] - 2026-09-22
 
 ### Fixed

package/THIRD-PARTY-NOTICES.txt

@@ -293,7 +293,7 @@ MIT License
 Copyright (c) 2026 Sander Land
   (measured tokenizer vocabulary data, reconstruction model, and reference
   implementation: https://github.com/sanderland/ctok)
-Copyright (c) 2026 Can Bölük and the Oh My Pi contributors
+Copyright (c) 2026 Can Bölük and the omp contributors
 Copyright (c) 2026 Stencil Labs, Inc.
   (Rust implementation and the compact binary vocabulary encoding in
   crates/pi-natives/src/utok/claude)

package/dist/types/agent-loop.d.ts

@@ -32,6 +32,12 @@ export declare function createToolScopedAbortReason(message: string, toolCallMes
  * boundary; this reason stops after persisting the completed tool batch.
  */
 export declare const TERMINAL_TOOL_RESULT_ABORT_REASON: unique symbol;
+/**
+ * Abort reason carried by an interruptible tool's signal when queued steering,
+ * a peer IRC, or a background completion cut it short. Lets a wait tell the
+ * designed wake path apart from an external/user abort of the run.
+ */
+export declare const TOOL_INTERRUPT_ABORT_REASON: unique symbol;
 export declare function resolveOwnedDialectFromEnv(value: string | undefined): Dialect | undefined;
 /**
  * Start an agent loop with a new prompt message.

package/dist/types/compaction/anthropic.d.ts

@@ -1,33 +1,21 @@
 /**
- * Anthropic server-side compaction (`compact-2026-01-12` beta).
+ * Anthropic on-demand compaction (`compact-2026-09-04` beta).
  *
- * The compaction request is the live turn's own request shape — same system
- * prompt, tools, and message history — plus the `compact_20260112` edit with
- * `pause_after_compaction`. The API summarizes the prompt from the already
- * cached prefix and stops; the summary arrives as a `compaction` block that
- * the provider surfaces as an `anthropicCompaction` payload. The summary is
- * plain text, so it doubles as the compaction entry's readable summary for
- * every other provider, while the Anthropic provider replays it as a native
- * block (the API drops everything that precedes it). The retained tail after
- * the cut point is replayed from session entries exactly like a local summary.
+ * The request sends only the prefix to summarize, with the live conversation's
+ * system prompt, tools and thinking settings. The returned signed block
+ * replaces that prefix; the retained tail is replayed from session entries.
  */
 import type { AnthropicCompactionPayload, ApiKey, Effort, Message, Model, SimpleStreamOptions, Tool, Usage } from "@oh-my-pi/pi-ai";
 import { type InstrumentedChatSpanOptions } from "../telemetry.js";
+import type { AgentMessage } from "../types.js";
 export declare const ANTHROPIC_COMPACTION_PRESERVE_KEY = "anthropicCompaction";
-/** The API rejects a `compact_20260112` trigger below this many input tokens. */
-export declare const ANTHROPIC_COMPACTION_MIN_TRIGGER_TOKENS = 50000;
-/**
- * Smallest context the native lane accepts. The trigger sits at the API
- * floor, so a prompt that lands below it is answered instead of compacted;
- * the margin over the floor absorbs the difference between the last reported
- * context size and the compaction request's own input.
- */
-export declare const ANTHROPIC_COMPACTION_MIN_CONTEXT_TOKENS = 55000;
 /** Summary persisted under {@link ANTHROPIC_COMPACTION_PRESERVE_KEY}. */
 export interface AnthropicCompactionPreserveData {
     provider: string;
     content: string;
-    /** Opaque provider state the API attached to the block; replayed verbatim. */
+    /** Signature attached to an on-demand block; replayed verbatim. */
+    signature?: string;
+    /** Legacy threshold block state; replay-only. */
     encryptedContent?: string;
     /** Harness file metadata (`<files>` section) replayed after the native block. */
     filesText?: string;
@@ -51,33 +39,17 @@ export declare function withAnthropicCompactionPreserveData(preserveData: Record
 /** Replay payload for a compaction summary the active model produced natively. */
 export declare function getAnthropicCompactionPayload(preserveData: Record<string, unknown> | undefined): AnthropicCompactionPayload | undefined;
 /**
- * The retained tail as the model will see it, for the summarization
- * instructions: how many of the conversation's final wire messages stay in
- * context verbatim, and the role of the first. The compaction request carries
- * the whole conversation so the prompt cache the live turn wrote is read, but
- * the summary must cover only the history before that tail — the local
- * summarizer never sees the tail, and the rebuilt context replays it after the
- * summary. Counting mirrors the provider's message conversion (consecutive
- * tool results collapse into one user message; developer messages are user
- * messages). Structured for the prompt template, which renders the
- * singular/plural wording; the description quotes no content: quoting the
- * tail would hand the summarizer the very facts it must leave to the tail.
+ * Move the existing keep-tail boundary forward until the summary/tail boundary
+ * alternates wire roles and no tool call is separated from its result. If no
+ * boundary is safe, the request summarizes the entire snapshot (empty tail).
  */
-export interface RetainedTailScope {
-    count: number;
-    role: "assistant" | "user";
-}
-export declare function describeRetainedTail(messages: readonly Message[]): RetainedTailScope | undefined;
-/**
- * Summarization prompt sent as the edit's `instructions`, which replace the
- * API default entirely. The template lays out the retained-tail boundary
- * first, so the summary covers only the history the rebuilt context drops,
- * then the caller's extra context, the same structure prompt as the local
- * summarizer, the caller's focus, and the tool-abstention clause the API
- * recommends when tools are defined (a summarization pass that calls a tool
- * yields no summary).
- */
-export declare function buildAnthropicCompactionInstructions(basePrompt: string, customInstructions: string | undefined, extraContext: string | undefined, retainedTail: RetainedTailScope | undefined): string;
+export declare function findAnthropicCompactionCut(messages: readonly (AgentMessage | {
+    role: "system";
+    content: string;
+    timestamp: number;
+})[], initialCut: number): number;
+/** Instructions replace the API default; the request contains only summarized messages. */
+export declare function buildAnthropicCompactionInstructions(basePrompt: string, customInstructions: string | undefined, extraContext: string | undefined): string;
 export interface AnthropicNativeCompactionRequest {
     systemPrompt: string[];
     messages: Message[];
@@ -88,21 +60,19 @@ export interface AnthropicNativeCompactionRequest {
 }
 export interface AnthropicNativeCompactionResponse {
     content: string;
-    encryptedContent?: string;
+    signature: string;
     usage: Usage;
     model: string;
 }
 export interface AnthropicNativeCompactionOptions extends Pick<SimpleStreamOptions, "initiatorOverride" | "metadata" | "fetch" | "sessionId" | "promptCacheKey" | "providerSessionState" | "maxInFlightRequests">, Pick<InstrumentedChatSpanOptions, "completeImpl" | "telemetry" | "retry"> {
 }
 /**
- * Run one compaction request and return the summary the API wrote, with the
- * opaque `encrypted_content` the API attached for the replay. `completeSimple`
+ * Run one compaction request and return the summary and signature the API wrote. `completeSimple`
  * resolves terminal failures as messages, so their classification is restored
  * here: an aborted response is an `AbortError` (a cancellation, never a native
  * failure) and an error response keeps its HTTP status, so auth and timeout
  * handling downstream classify it the same way as the OpenAI lanes. A response
- * without a summary is a native failure — the API answers the prompt instead
- * when its input never reached the trigger, and returns an empty block when
- * the model called a tool during summarization.
+ * without a summary is a native failure, including tool use, refusals and
+ * output limits; the configured method order can then choose a fallback.
  */
 export declare function requestAnthropicNativeCompaction(model: Model<"anthropic-messages">, apiKey: ApiKey, request: AnthropicNativeCompactionRequest, signal: AbortSignal | undefined, options: AnthropicNativeCompactionOptions): Promise<AnthropicNativeCompactionResponse>;

package/dist/types/compaction/compaction.d.ts

@@ -297,6 +297,8 @@ export interface CompactionPreparation {
     turnPrefixMessages: AgentMessage[];
     /** Messages kept in full after compaction (recent history) */
     recentMessages: AgentMessage[];
+    /** Entry IDs parallel to recentMessages, for an Anthropic-safe keep-tail boundary. */
+    recentEntryIds?: string[];
     /** Whether this is a split turn (cut point in middle of turn) */
     isSplitTurn: boolean;
     tokensBefore: number;

package/dist/types/index.d.ts

@@ -6,6 +6,7 @@ export * from "./pause.js";
 export * from "./proxy.js";
 export * from "./replay-policy.js";
 export * from "./run-collector.js";
+export * from "./sent-tool-definitions.js";
 export * from "./speculative-execution.js";
 export * from "./telemetry.js";
 export * from "./thinking.js";

package/dist/types/sent-tool-definitions.d.ts

@@ -0,0 +1,17 @@
+import type { Message, Tool } from "@oh-my-pi/pi-ai";
+/**
+ * Last wire definition this Agent sent for each tool name, so a provider that keeps
+ * withdrawn tools declared (Anthropic `tool_removal`) can re-declare them byte-identically.
+ * Used by prepareProviderCall and Agent.buildSideRequestContext.
+ */
+export declare class SentToolDefinitions {
+    #private;
+    /** Remember the definitions a request is about to send. */
+    record(tools: readonly Tool[]): void;
+    /**
+     * Definitions for names the latest `requestControls.tools.declared` in `messages` holds
+     * that are not in `active`; undefined when none. Names never sent by this Agent are
+     * skipped: the provider drops them from the declaration.
+     */
+    inactiveFor(messages: readonly Message[], active: readonly Tool[]): Tool[] | undefined;
+}

package/dist/types/types.d.ts

@@ -3,6 +3,7 @@ import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 import type { HarmonyAuditEvent } from "@oh-my-pi/pi-ai/utils/harmony-leak";
 import type { AppendOnlyContextManager } from "./append-only-context.js";
 import type { AgentRunCoverage, AgentRunSummary } from "./run-collector.js";
+import type { SentToolDefinitions } from "./sent-tool-definitions.js";
 import type { AgentTelemetryConfig } from "./telemetry.js";
 /** Stream function - can return sync or Promise for async config lookup */
 export type StreamFn = (...args: Parameters<typeof streamSimple>) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
@@ -117,8 +118,10 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
     model: Model;
     /**
      * When to interrupt tool execution for steering messages.
-     * - "immediate" = check after each tool call (default)
-     * - "wait" = defer steering until the current turn completes
+     * - "immediate" = cut interruptible waits short and raise the cooperative
+     *   `steeringSignal` for other running tools (default)
+     * - "wait" = let non-interruptible tools finish undisturbed; interruptible
+     *   waits are still cut short, since they have no work to complete
      */
     interruptMode?: "immediate" | "wait";
     /**
@@ -185,6 +188,8 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * and provider send.
      */
     transformProviderContext?: (context: Context, model: Model) => Context | Promise<Context>;
+    /** Remembers sent tool definitions to fill {@link Context.inactiveTools}. */
+    sentToolDefinitions?: SentToolDefinitions;
     /**
      * Resolves the API key or resolver for the current model before each LLM call.
      *
@@ -204,8 +209,9 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
     /**
      * Peeks whether steering messages are queued, without consuming them.
      *
-     * Polled while a tool batch runs (unless interruptMode is "wait") to decide
-     * whether to abort in-flight and skip not-yet-started *interruptible* waits;
+     * Polled while a tool batch runs (in "wait" mode, only when the batch holds an
+     * interruptible tool) to decide whether to abort in-flight and skip
+     * not-yet-started *interruptible* waits;
      * every other already-emitted call still executes and the message injects
      * at the batch boundary. The queue keeps
      * owning its messages until the loop reaches the next injection boundary and
@@ -232,7 +238,8 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * Peeks whether IRC messages should interrupt an interruptible waiting tool.
      *
      * Uses the same delivery rules as steering: the poll is non-consuming, only
-     * runs for interruptible tools, and is ignored when interruptMode is "wait".
+     * runs for interruptible tools, and cuts them short even when interruptMode
+     * is "wait".
      * The host owns message injection at the next boundary.
      */
     hasIrcInterrupts?: () => boolean | Promise<boolean>;
@@ -241,9 +248,12 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * process) is queued for aside injection at the next boundary.
      *
      * Same rules as {@link hasIrcInterrupts}: non-consuming, only cuts
-     * *interruptible* waits short, ignored when interruptMode is "wait". Without
-     * it a completion notice sits behind an hour-long `hub wait` that the agent
-     * would have abandoned had it seen the notice.
+     * *interruptible* waits short, in either interruptMode. Without
+     * it a completion notice sits behind an hour-long `wait` that the agent
+     * would have abandoned had it seen the notice. Unlike a peer IRC it never
+     * raises {@link ToolCallContext.steeringSignal}: a queued completion must
+     * not push ordinary foreground work (auto-background bash/eval) into the
+     * background.
      */
     hasBackgroundCompletions?: () => boolean | Promise<boolean>;
     /**
@@ -900,6 +910,12 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
     loadMode?: ToolLoadMode;
     /** Short one-line summary used for tool discovery indexes. */
     summary?: string;
+    /**
+     * On-demand documentation topics (`topic → markdown`), readable as
+     * `xd://<tool>/<topic>`. Lets a tool keep large sub-surfaces out of its
+     * description and advertise only a one-line pointer per topic.
+     */
+    docTopics?(): Readonly<Record<string, string>>;
     /**
      * Concurrency mode for tool scheduling when multiple calls are in one turn.
      * - "shared": can run alongside other shared tools (default)
@@ -923,7 +939,7 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
      * cleanly (e.g. `job` poll), so the abort surfaces the tool's current
      * snapshot rather than corrupting a side effect. Every other call runs to
      * completion even when steering is queued; the message lands at the next
-     * batch boundary. Honored only when `interruptMode` is "immediate".
+     * batch boundary. Honored in both `interruptMode`s.
      */
     interruptible?: boolean | ((args: Partial<Static<TParameters>>) => boolean);
     /**

package/package.json

@@ -1,10 +1,13 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "18.2.10",
+	"version": "18.3.0",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
-	"author": "Stencil Labs, Inc.",
+	"author": {
+		"name": "Stencil Labs, Inc.",
+		"url": "https://stencil.so"
+	},
 	"contributors": [
 		"Mario Zechner"
 	],
@@ -35,16 +38,16 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "18.2.10",
-		"@oh-my-pi/pi-catalog": "18.2.10",
-		"@oh-my-pi/pi-natives": "18.2.10",
-		"@oh-my-pi/pi-utils": "18.2.10",
-		"@oh-my-pi/pi-wire": "18.2.10",
-		"@oh-my-pi/snapcompact": "18.2.10",
+		"@oh-my-pi/pi-ai": "18.3.0",
+		"@oh-my-pi/pi-catalog": "18.3.0",
+		"@oh-my-pi/pi-natives": "18.3.0",
+		"@oh-my-pi/pi-utils": "18.3.0",
+		"@oh-my-pi/pi-wire": "18.3.0",
+		"@oh-my-pi/snapcompact": "18.3.0",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {
-		"@oh-my-pi/omptype": "18.2.10",
+		"@oh-my-pi/omptype": "18.3.0",
 		"@opentelemetry/context-async-hooks": "^2.9.0",
 		"@opentelemetry/sdk-trace-base": "^2.9.0",
 		"@types/bun": "^1.3.14"

package/src/agent-loop.ts

@@ -5,6 +5,7 @@
 import {
 	type AssistantMessage,
 	type AssistantMessageEvent,
+	type ApiKeyResolution,
 	type ComputerAction,
 	type ComputerSafetyCheck,
 	type Context,
@@ -164,6 +165,13 @@ export function createToolScopedAbortReason(
  */
 export const TERMINAL_TOOL_RESULT_ABORT_REASON = Symbol.for("pi-agent-core.terminal-tool-result");
 
+/**
+ * Abort reason carried by an interruptible tool's signal when queued steering,
+ * a peer IRC, or a background completion cut it short. Lets a wait tell the
+ * designed wake path apart from an external/user abort of the run.
+ */
+export const TOOL_INTERRUPT_ABORT_REASON = Symbol.for("pi-agent-core.tool-interrupt");
+
 const STEERING_INTERRUPT_POLL_MS = 250;
 
 class HarmonyLeakInterruption extends Error {
@@ -1758,6 +1766,12 @@ async function prepareProviderCall(
 			tools: undefined,
 		};
 	}
+	// After `transformProviderContext`, so the recorded definitions are exactly what the provider receives.
+	if (config.sentToolDefinitions && llmContext.tools) {
+		config.sentToolDefinitions.record(llmContext.tools);
+		const inactiveTools = config.sentToolDefinitions.inactiveFor(llmContext.messages, llmContext.tools);
+		if (inactiveTools) llmContext = { ...llmContext, inactiveTools };
+	}
 	return { model, context: llmContext, promptToolWireTools, ownedDialect };
 }
 
@@ -1814,8 +1828,13 @@ async function streamAssistantResponse(
 				? providerAbortSignals[0]!
 				: AbortSignal.any(providerAbortSignals);
 	const requestApiKey = (config.getApiKey ? await config.getApiKey(model) : undefined) ?? config.apiKey;
-	const resolvedApiKey = await resolveApiKeyOnce(requestApiKey, finalRequestSignal);
-	const apiKey = isApiKeyResolver(requestApiKey) ? seedApiKeyResolver(resolvedApiKey, requestApiKey) : requestApiKey;
+	let resolvedCredential: ApiKeyResolution;
+	const resolvedApiKey = await resolveApiKeyOnce(requestApiKey, finalRequestSignal, resolved => {
+		resolvedCredential = resolved;
+	});
+	const apiKey = isApiKeyResolver(requestApiKey)
+		? seedApiKeyResolver(resolvedCredential ?? resolvedApiKey, requestApiKey)
+		: requestApiKey;
 
 	// Re-resolve metadata after credential selection so the per-request value
 	// reflects the credential actually used, not the snapshot from AgentLoopConfig construction.
@@ -2866,7 +2885,10 @@ async function executeToolCalls(
 	const emittedToolResults: ToolResultMessage[] = [];
 	const toolCallInfos = toolCalls.map(call => ({ id: call.id, name: call.name }));
 	const batchId = `${assistantMessage.timestamp ?? Date.now()}_${toolCalls[0]?.id ?? "batch"}`;
-	const shouldInterruptImmediately = interruptMode !== "wait";
+	// `interruptMode: "wait"` only spares side-effecting work: interruptible
+	// waits are always cut short, since a pure wait has nothing to finish and
+	// would otherwise sit out its full window with a message already queued.
+	const softInterrupts = interruptMode !== "wait";
 	const steeringAbortController = new AbortController();
 	const ircAbortController = new AbortController();
 	// Cooperative channel: aborted when queued steering (or an interrupting
@@ -2875,7 +2897,7 @@ async function executeToolCalls(
 	// backgrounds itself so the message injects promptly — but it never kills
 	// anything; ignoring it is always safe.
 	const steeringSoftController = new AbortController();
-	// Interruptible tools (pure waits: hub wait, vibe) observe steering +
+	// Interruptible tools (pure waits: wait, vibe) observe steering +
 	// external + IRC aborts. Every other tool sees ONLY the external signal:
 	// neither queued steering nor a peer IRC ever hard-kills a partially
 	// side-effecting foreground tool (e.g. `bash`) — those get the cooperative
@@ -2938,28 +2960,40 @@ async function executeToolCalls(
 	const checkAsideInterrupts = async (): Promise<void> => {
 		// Asides only fire once: an interrupt already recorded on interruptState
 		// must not re-abort, and (unlike steering) never re-consumes a queue.
-		if (!shouldInterruptImmediately || signal?.aborted || interruptState.triggered) return;
+		// A completion-triggered record is the exception — it leaves the
+		// cooperative signal down, so keep polling until a peer IRC escalates
+		// (only when soft interrupts are enabled; otherwise nothing is left).
+		if (signal?.aborted) return;
+		if (interruptState.triggered && (!softInterrupts || steeringSoftController.signal.aborted)) return;
 		// Peer IRC and background completions (finished jobs, exited supervised
 		// processes) hard-abort interruptible waits only; foreground tools keep
-		// running (no partial side effects) but get the cooperative soft signal
-		// so backgroundable work can step aside for the queued notice.
+		// running (no partial side effects).
 		let source: AsideInterruptSource | undefined;
 		if (hasIrcInterrupts && (await hasIrcInterrupts())) source = "irc";
-		else if (hasBackgroundCompletions && (await hasBackgroundCompletions())) source = "background";
-		if (!source || interruptState.triggered) return;
-		interruptState.triggered = true;
-		interruptState.source = source;
-		ircAbortController.abort();
-		steeringSoftController.abort();
+		else if (!interruptState.triggered && hasBackgroundCompletions && (await hasBackgroundCompletions()))
+			source = "background";
+		if (!source) return;
+		if (!interruptState.triggered) {
+			interruptState.triggered = true;
+			interruptState.source = source;
+			ircAbortController.abort(TOOL_INTERRUPT_ABORT_REASON);
+		}
+		// Only an urgent aside raises the cooperative signal that makes
+		// backgroundable foreground work (auto-background bash/eval) detach
+		// itself. A peer waiting on an IRC is blocked on this batch; a finished
+		// background job is not — its notice is an aside that injects at the
+		// batch boundary either way. Detaching ordinary foreground work for it
+		// also cascades: the freshly detached job's own completion re-triggers
+		// this check for the next command, so millisecond-long commands chain
+		// into separate background deliveries (#12869).
+		if (source !== "background" && softInterrupts) steeringSoftController.abort();
 	};
 
 	const checkSteering = async (): Promise<void> => {
 		// `signal` (external/user abort) is checked separately from the internal
 		// abort controllers: once the run is externally aborted it is unwinding
 		// and the interrupt would be redundant.
-		if (!shouldInterruptImmediately || signal?.aborted) {
-			return;
-		}
+		if (signal?.aborted) return;
 		// Mid-batch steering detection must be non-consuming. If a direct
 		// integration only provides getSteeringMessages(), the queue drains at the
 		// injection boundary below; polling it here would strand or drop messages.
@@ -2977,8 +3011,9 @@ async function executeToolCalls(
 			}
 		}
 		if (steeringQueued) {
-			// Queued steering hard-aborts only interruptible waits and raises the
-			// cooperative soft signal for everything else: the boundary dequeue
+			// Queued steering hard-aborts only interruptible waits and (unless
+			// interruptMode is "wait") raises the cooperative soft signal for
+			// everything else: the boundary dequeue
 			// below injects the message as soon as running tools finish (or
 			// background themselves), and not-yet-started interruptible waits
 			// are skipped. Idempotent — a second steer poll after the abort is
@@ -2986,8 +3021,8 @@ async function executeToolCalls(
 			if (!steeringAbortController.signal.aborted) {
 				interruptState.triggered = true;
 				interruptState.source = steeringSource ?? "unknown";
-				steeringAbortController.abort();
-				steeringSoftController.abort();
+				steeringAbortController.abort(TOOL_INTERRUPT_ABORT_REASON);
+				if (softInterrupts) steeringSoftController.abort();
 			}
 			return;
 		}
@@ -3037,7 +3072,7 @@ async function executeToolCalls(
 
 	const runTool = async (record: (typeof records)[number], index: number): Promise<void> => {
 		// A pending interrupt preempts not-yet-started *interruptible* waits so
-		// the message injects promptly instead of sitting out a `hub wait`.
+		// the message injects promptly instead of sitting out a `wait`.
 		// Non-interruptible work is never skipped, whatever the source: the
 		// expensive part — generating the call — is already paid, the tool
 		// itself is cheap, and a skip only makes the model re-emit the same
@@ -3296,12 +3331,15 @@ async function executeToolCalls(
 
 	// While tool calls are in flight, queued steering or interrupting IRC would
 	// otherwise wait out the tools' own window. Poll only non-consuming queues:
-	// detection hard-aborts interruptible waits (running or not yet started)
-	// and soft-signals cooperative tools (auto-background bash), so the boundary
-	// dequeue below injects the message promptly. Gated on immediate-interrupt
-	// mode; checkSteering is idempotent (no-op once triggered).
+	// detection hard-aborts interruptible waits (running or not yet started),
+	// and steering/IRC additionally soft-signal cooperative tools
+	// (auto-background bash), so the boundary dequeue below injects the message
+	// promptly. In "wait" mode only a batch holding an interruptible wait needs
+	// the watch; checkSteering is idempotent (no-op once triggered).
 	const hasAsidePeek = hasIrcInterrupts !== undefined || hasBackgroundCompletions !== undefined;
-	const watchSteeringWhileRunning = shouldInterruptImmediately && (hasSteeringMessages !== undefined || hasAsidePeek);
+	const watchSteeringWhileRunning =
+		(softInterrupts || records.some(record => record.interruptible)) &&
+		(hasSteeringMessages !== undefined || hasAsidePeek);
 	const eventDrivenSteeringWatch =
 		watchSteeringWhileRunning && config.waitForSteeringMessages !== undefined && hasSteeringMessages !== undefined;
 	const steeringWatchAbortController = new AbortController();
@@ -3335,7 +3373,17 @@ async function executeToolCalls(
 						() => false,
 					);
 					if (!(await Promise.race([steeringChecked, watchAbortedFalse]))) return;
-					if (steeringWatchSignal.aborted || interruptState.triggered) return;
+					// Stop once nothing is left to escalate: the cooperative signal
+					// is up, or (without soft interrupts) the waits are cut. A
+					// completion-only trigger leaves the soft signal down, so keep
+					// watching: a genuine steer arriving afterwards must still
+					// reach foreground tools.
+					if (
+						steeringWatchSignal.aborted ||
+						steeringSoftController.signal.aborted ||
+						(!softInterrupts && interruptState.triggered)
+					)
+						return;
 					if (!(await Promise.race([steeringQueued, watchAbortedFalse]))) return;
 				}
 			})()

package/src/agent.ts

@@ -38,6 +38,7 @@ import {
 } from "./agent-loop";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import { isProviderRefusalMessage } from "./replay-policy";
+import { SentToolDefinitions } from "./sent-tool-definitions";
 import { Tokenizer, tokenizerEncodingForModel } from "./tokenizer";
 import type {
 	AgentBeforeModelCall,
@@ -389,6 +390,7 @@ export class Agent {
 	#convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
 	#transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
 	#transformProviderContext?: (context: Context, model: Model) => Context | Promise<Context>;
+	#sentToolDefinitions = new SentToolDefinitions();
 	#steeringQueue: AgentMessage[] = [];
 	#followUpQueue: AgentMessage[] = [];
 	#queuedMessageClaims: Partial<Record<QueuedMessageQueue, QueuedMessageClaim>> = {};
@@ -837,6 +839,11 @@ export class Agent {
 				}) ?? []);
 		let context: Context = { systemPrompt, messages, tools };
 		if (this.#transformProviderContext) context = await this.#transformProviderContext(context, model);
+		// Side requests reuse the main loop's sent definitions without recording their own.
+		if (context.tools?.length) {
+			const inactiveTools = this.#sentToolDefinitions.inactiveFor(context.messages, context.tools);
+			if (inactiveTools) context = { ...context, inactiveTools };
+		}
 		return context;
 	}
 
@@ -1579,6 +1586,7 @@ export class Agent {
 			preferWebsockets: this.#preferWebsockets,
 			convertToLlm: this.#convertToLlm,
 			transformProviderContext: this.#transformProviderContext,
+			sentToolDefinitions: this.#sentToolDefinitions,
 			transformContext: this.#transformContext,
 			onPayload: this.#onPayload,
 			onResponse: this.#onResponse,

package/src/compaction/anthropic.ts

@@ -1,21 +1,14 @@
 /**
- * Anthropic server-side compaction (`compact-2026-01-12` beta).
+ * Anthropic on-demand compaction (`compact-2026-09-04` beta).
  *
- * The compaction request is the live turn's own request shape — same system
- * prompt, tools, and message history — plus the `compact_20260112` edit with
- * `pause_after_compaction`. The API summarizes the prompt from the already
- * cached prefix and stops; the summary arrives as a `compaction` block that
- * the provider surfaces as an `anthropicCompaction` payload. The summary is
- * plain text, so it doubles as the compaction entry's readable summary for
- * every other provider, while the Anthropic provider replays it as a native
- * block (the API drops everything that precedes it). The retained tail after
- * the cut point is replayed from session entries exactly like a local summary.
+ * The request sends only the prefix to summarize, with the live conversation's
+ * system prompt, tools and thinking settings. The returned signed block
+ * replaces that prefix; the retained tail is replayed from session entries.
  */
 
 import type {
 	AnthropicCompactionPayload,
 	ApiKey,
-	AssistantMessage,
 	Effort,
 	Message,
 	Model,
@@ -27,26 +20,18 @@ import * as AIError from "@oh-my-pi/pi-ai/error";
 import { supportsAnthropicCompaction } from "@oh-my-pi/pi-ai/providers/anthropic-compaction";
 import { isRecord, prompt } from "@oh-my-pi/pi-utils";
 import { type InstrumentedChatSpanOptions, instrumentedCompleteSimple } from "../telemetry";
+import type { AgentMessage } from "../types";
 import anthropicCompactionInstructionsPrompt from "./prompts/anthropic-compaction-instructions.md" with { type: "text" };
 
 export const ANTHROPIC_COMPACTION_PRESERVE_KEY = "anthropicCompaction";
 
-/** The API rejects a `compact_20260112` trigger below this many input tokens. */
-export const ANTHROPIC_COMPACTION_MIN_TRIGGER_TOKENS = 50_000;
-
-/**
- * Smallest context the native lane accepts. The trigger sits at the API
- * floor, so a prompt that lands below it is answered instead of compacted;
- * the margin over the floor absorbs the difference between the last reported
- * context size and the compaction request's own input.
- */
-export const ANTHROPIC_COMPACTION_MIN_CONTEXT_TOKENS = 55_000;
-
 /** Summary persisted under {@link ANTHROPIC_COMPACTION_PRESERVE_KEY}. */
 export interface AnthropicCompactionPreserveData {
 	provider: string;
 	content: string;
-	/** Opaque provider state the API attached to the block; replayed verbatim. */
+	/** Signature attached to an on-demand block; replayed verbatim. */
+	signature?: string;
+	/** Legacy threshold block state; replay-only. */
 	encryptedContent?: string;
 	/** Harness file metadata (`<files>` section) replayed after the native block. */
 	filesText?: string;
@@ -82,6 +67,9 @@ export function getPreservedAnthropicCompactionData(
 	return {
 		provider: candidate.provider,
 		content: candidate.content,
+		...(typeof candidate.signature === "string" && candidate.signature.length > 0
+			? { signature: candidate.signature }
+			: {}),
 		...(typeof candidate.encryptedContent === "string" && candidate.encryptedContent.length > 0
 			? { encryptedContent: candidate.encryptedContent }
 			: {}),
@@ -118,93 +106,63 @@ export function getAnthropicCompactionPayload(
 		type: "anthropicCompaction",
 		provider: preserved.provider,
 		content: preserved.content,
+		...(preserved.signature ? { signature: preserved.signature } : {}),
 		...(preserved.encryptedContent ? { encryptedContent: preserved.encryptedContent } : {}),
 		...(preserved.filesText ? { filesText: preserved.filesText } : {}),
 	};
 }
 
 /**
- * The retained tail as the model will see it, for the summarization
- * instructions: how many of the conversation's final wire messages stay in
- * context verbatim, and the role of the first. The compaction request carries
- * the whole conversation so the prompt cache the live turn wrote is read, but
- * the summary must cover only the history before that tail — the local
- * summarizer never sees the tail, and the rebuilt context replays it after the
- * summary. Counting mirrors the provider's message conversion (consecutive
- * tool results collapse into one user message; developer messages are user
- * messages). Structured for the prompt template, which renders the
- * singular/plural wording; the description quotes no content: quoting the
- * tail would hand the summarizer the very facts it must leave to the tail.
+ * Move the existing keep-tail boundary forward until the summary/tail boundary
+ * alternates wire roles and no tool call is separated from its result. If no
+ * boundary is safe, the request summarizes the entire snapshot (empty tail).
  */
-export interface RetainedTailScope {
-	count: number;
-	role: "assistant" | "user";
-}
-
-export function describeRetainedTail(messages: readonly Message[]): RetainedTailScope | undefined {
-	const first = messages[0];
-	if (!first) return undefined;
-	let count = 0;
-	let previousWasToolResult = false;
-	for (const message of messages) {
-		const isToolResult = message.role === "toolResult";
-		if (!(isToolResult && previousWasToolResult)) count += 1;
-		previousWasToolResult = isToolResult;
+export function findAnthropicCompactionCut(
+	messages: readonly (AgentMessage | { role: "system"; content: string; timestamp: number })[],
+	initialCut: number,
+): number {
+	let calls: Map<string, number> | undefined;
+	for (let i = 0; i < messages.length; i++) {
+		const message = messages[i];
+		if (message.role !== "assistant") continue;
+		for (const block of message.content) {
+			if (block.type === "toolCall") (calls ??= new Map()).set(block.id, i);
+		}
 	}
-	// Mirror the provider's trailing-assistant prefill: a tail ending in a
-	// live assistant turn gains a synthetic trailing user message on the
-	// wire, which stays verbatim too. Only blocks the converter emits count —
-	// blank text never serializes, and images, redacted thinking, and fallback
-	// markers need target context this scope lacks, so a turn of only those
-	// emits nothing and draws no pad. Without the pad in
-	// the scope, the summary could duplicate the tail head.
-	const last = messages[messages.length - 1];
-	if (last?.role === "assistant" && last.content.some(emitsWireBlock)) {
-		count += 1;
+	let lastResult: Int32Array | undefined;
+	if (calls) {
+		lastResult = new Int32Array(messages.length);
+		for (let i = 0; i < messages.length; i++) {
+			const message = messages[i];
+			if (message.role !== "toolResult") continue;
+			const callIndex = calls.get(message.toolCallId);
+			if (callIndex !== undefined) lastResult[callIndex] = i;
+		}
 	}
-	return { count, role: first.role === "assistant" ? "assistant" : "user" };
-}
-
-/**
- * Whether an assistant content block reaches the wire. Server-tool blocks
- * serialize unconditionally; blank text never does. Redacted thinking and
- * fallback markers replay only for specific deployments, which the scope
- * cannot see, so a turn of only those conservatively draws no pad.
- */
-function emitsWireBlock(block: AssistantMessage["content"][number]): boolean {
-	switch (block.type) {
-		case "text":
-			return block.text.trim().length > 0;
-		case "toolCall":
-		case "anthropicServerTool":
-			return true;
-		case "thinking":
-			return block.thinking.trim().length > 0 || (block.thinkingSignature ?? "").trim().length > 0;
-		default:
-			return false;
+	let protectedThrough = -1;
+	for (let i = 0; i < initialCut; i++) protectedThrough = Math.max(protectedThrough, lastResult?.[i] ?? -1);
+	for (let cut = initialCut; cut < messages.length; cut++) {
+		protectedThrough = Math.max(protectedThrough, lastResult?.[cut - 1] ?? -1);
+		if (cut <= protectedThrough) continue;
+		const first = messages[cut];
+		if (first.role === "system" || first.role === "developer") continue;
+		const previous = messages[cut - 1];
+		if (!previous) continue;
+		if ((previous.role === "assistant") !== (first.role === "assistant")) return cut;
 	}
+	return messages.length;
 }
 
-/**
- * Summarization prompt sent as the edit's `instructions`, which replace the
- * API default entirely. The template lays out the retained-tail boundary
- * first, so the summary covers only the history the rebuilt context drops,
- * then the caller's extra context, the same structure prompt as the local
- * summarizer, the caller's focus, and the tool-abstention clause the API
- * recommends when tools are defined (a summarization pass that calls a tool
- * yields no summary).
- */
+/** Instructions replace the API default; the request contains only summarized messages. */
 export function buildAnthropicCompactionInstructions(
 	basePrompt: string,
 	customInstructions: string | undefined,
 	extraContext: string | undefined,
-	retainedTail: RetainedTailScope | undefined,
 ): string {
 	return prompt.render(anthropicCompactionInstructionsPrompt, {
 		basePrompt,
 		customInstructions,
 		extraContext,
-		retainedTail,
 	});
 }
 
@@ -219,7 +177,7 @@ export interface AnthropicNativeCompactionRequest {
 
 export interface AnthropicNativeCompactionResponse {
 	content: string;
-	encryptedContent?: string;
+	signature: string;
 	usage: Usage;
 	model: string;
 }
@@ -239,15 +197,13 @@ export interface AnthropicNativeCompactionOptions
 		Pick<InstrumentedChatSpanOptions, "completeImpl" | "telemetry" | "retry"> {}
 
 /**
- * Run one compaction request and return the summary the API wrote, with the
- * opaque `encrypted_content` the API attached for the replay. `completeSimple`
+ * Run one compaction request and return the summary and signature the API wrote. `completeSimple`
  * resolves terminal failures as messages, so their classification is restored
  * here: an aborted response is an `AbortError` (a cancellation, never a native
  * failure) and an error response keeps its HTTP status, so auth and timeout
  * handling downstream classify it the same way as the OpenAI lanes. A response
- * without a summary is a native failure — the API answers the prompt instead
- * when its input never reached the trigger, and returns an empty block when
- * the model called a tool during summarization.
+ * without a summary is a native failure, including tool use, refusals and
+ * output limits; the configured method order can then choose a fallback.
  */
 export async function requestAnthropicNativeCompaction(
 	model: Model<"anthropic-messages">,
@@ -271,11 +227,7 @@ export async function requestAnthropicNativeCompaction(
 			promptCacheKey: options.promptCacheKey,
 			providerSessionState: options.providerSessionState,
 			maxInFlightRequests: options.maxInFlightRequests,
-			anthropicCompaction: {
-				triggerInputTokens: ANTHROPIC_COMPACTION_MIN_TRIGGER_TOKENS,
-				pauseAfterCompaction: true,
-				instructions: request.instructions,
-			},
+			anthropicCompaction: { instructions: request.instructions },
 		},
 		{
 			telemetry: options.telemetry,
@@ -294,16 +246,21 @@ export async function requestAnthropicNativeCompaction(
 			: new AIError.ProviderHttpError(message, response.errorStatus);
 	}
 	const payload = response.providerPayload;
-	if (payload?.type !== "anthropicCompaction" || payload.content.length === 0) {
+	if (
+		response.stopDetails?.type !== "compaction" ||
+		payload?.type !== "anthropicCompaction" ||
+		!payload.content ||
+		!payload.signature
+	) {
 		throw new Error(
 			response.stopDetails?.type === "compaction"
-				? "Anthropic compaction returned no summary"
+				? "Anthropic compaction returned no signed summary"
 				: "Anthropic compaction response carried no compaction block",
 		);
 	}
 	return {
 		content: payload.content,
-		encryptedContent: payload.encryptedContent,
+		signature: payload.signature,
 		usage: response.usage,
 		model: response.model,
 	};

package/src/compaction/compaction.ts

@@ -43,9 +43,8 @@ import { ThinkingLevel } from "../thinking";
 import { Tokenizer } from "../tokenizer";
 import type { AgentMessage } from "../types";
 import {
-	ANTHROPIC_COMPACTION_MIN_CONTEXT_TOKENS,
 	buildAnthropicCompactionInstructions,
-	describeRetainedTail,
+	findAnthropicCompactionCut,
 	getPreservedAnthropicCompactionData,
 	requestAnthropicNativeCompaction,
 	shouldUseAnthropicNativeCompaction,
@@ -1252,6 +1251,8 @@ export interface CompactionPreparation {
 	turnPrefixMessages: AgentMessage[];
 	/** Messages kept in full after compaction (recent history) */
 	recentMessages: AgentMessage[];
+	/** Entry IDs parallel to recentMessages, for an Anthropic-safe keep-tail boundary. */
+	recentEntryIds?: string[];
 	/** Whether this is a split turn (cut point in middle of turn) */
 	isSplitTurn: boolean;
 	tokensBefore: number;
@@ -1380,16 +1381,22 @@ export function prepareCompaction(
 			}
 		}
 	} else if (previousCompaction) {
-		// Local summaries exclude the retained tail, whose original entries precede
-		// the compaction record. Native replay already carries that tail. Only look
-		// backwards: advisor snapshots put all retained messages after the summary
-		// and may carry a keep ID from their previous, differently indexed snapshot.
+		// Local and Anthropic summaries exclude the retained tail, whose
+		// original entries precede the compaction record.
 		for (let i = resetBoundaryIndex + 1; i < prevCompactionIndex; i++) {
 			if (pathEntries[i].id === previousCompaction.firstKeptEntryId) {
 				boundaryStart = i;
 				break;
 			}
 		}
+		if (previousCompaction.firstKeptEntryId === "" && previousCompaction.providerReplayThroughEntryId) {
+			// An empty snapshot tail can still have turns appended during
+			// background compaction; those start after the summarized snapshot.
+			const snapshotIdx = pathEntries.findIndex(
+				entry => entry.id === previousCompaction.providerReplayThroughEntryId,
+			);
+			if (snapshotIdx >= 0 && snapshotIdx < prevCompactionIndex) boundaryStart = snapshotIdx + 1;
+		}
 	}
 
 	// Keep original IDs beside the converted messages so estimation, cutting,
@@ -1437,6 +1444,11 @@ export function prepareCompaction(
 		return undefined;
 	}
 
+	const recentEntryIds: string[] = [];
+	for (let i = cutPoint.firstKeptEntryIndex; i < compactionEntries.length; i++) {
+		recentEntryIds.push(compactionEntries[i].id);
+	}
+
 	// Extract file operations from messages and previous compaction
 	const fileOps = extractFileOperations(messagesToSummarize, pathEntries, prevCompactionIndex);
 
@@ -1452,6 +1464,7 @@ export function prepareCompaction(
 		messagesToSummarize,
 		turnPrefixMessages,
 		recentMessages,
+		recentEntryIds,
 		isSplitTurn: cutPoint.isSplitTurn,
 		tokensBefore,
 		previousSummary: previousCompaction?.summary,
@@ -1579,6 +1592,7 @@ export async function compact(
 		messagesToSummarize,
 		turnPrefixMessages,
 		recentMessages,
+		recentEntryIds,
 		isSplitTurn,
 		tokensBefore,
 		previousSummary,
@@ -1826,35 +1840,19 @@ export async function compact(
 		}
 	}
 
-	// Anthropic server-side compaction: the live turn's request shape plus the
-	// compact edit, so the API summarizes from its cached prefix. The summary is
-	// real text, persisted both as the entry summary and as the native replay
-	// payload. A context below the API's trigger floor cannot compact remotely
-	// and takes the local summarizer instead — an eligibility boundary, not a
-	// failure.
+	// On-demand compaction summarizes only the prefix; the tail is never sent
+	// to this request and is replayed after the returned signed block.
 	let nativeSummary: string | undefined;
-	let nativeEncryptedContent: string | undefined;
+	let nativeSignature: string | undefined;
+	let nativeFirstKeptEntryId = firstKeptEntryId;
 	let nativeUsedTokens: number | undefined;
-	if (
-		!usedRemoteCompaction &&
-		settings.remoteEnabled !== false &&
-		shouldUseAnthropicNativeCompaction(model) &&
-		tokensBefore >= ANTHROPIC_COMPACTION_MIN_CONTEXT_TOKENS
-	) {
+	if (!usedRemoteCompaction && settings.remoteEnabled !== false && shouldUseAnthropicNativeCompaction(model)) {
 		const previousNative = getPreservedAnthropicCompactionData(previousPreserveData);
-		// Lead with the previous summary exactly as the live context renders it:
-		// natively when this provider wrote it, as text otherwise. The request
-		// then shares the live turn's prefix byte-for-byte. A prior snapcompact
-		// archive is already merged into that summary text, so the archive
-		// migration message the OpenAI lanes carry is omitted here.
-		// The rewrite marker must precede every message this request replays —
-		// summarized history and retained tail alike — exactly like the live
-		// context rebuild predates its tail. A previous compaction's commit
-		// timestamp is newer than re-retained or re-summarized turns, so
-		// reusing it would strip their bound thinking only in this request,
-		// diverging from the cached live prefix (and possibly dropping below
-		// the trigger). Manually built preparations with no input at all fall
-		// back to the current time.
+		// Lead with the previous summary as the live context renders it:
+		// natively when this provider wrote it, as text otherwise.
+		// A prior snapcompact archive is already merged into that summary
+		// text. Predate the rewrite marker before all replayed messages so
+		// retained thinking stays bound to the original prefix.
 		const firstReplayed = messagesToSummarize[0] ?? turnPrefixMessages[0] ?? recentMessages[0];
 		const previousSummaryAt =
 			firstReplayed !== undefined ? new Date(firstReplayed.timestamp - 1).toISOString() : new Date().toISOString();
@@ -1866,6 +1864,7 @@ export async function compact(
 									type: "anthropicCompaction",
 									provider: previousNative.provider,
 									content: previousNative.content,
+									...(previousNative.signature ? { signature: previousNative.signature } : {}),
 									...(previousNative.encryptedContent
 										? { encryptedContent: previousNative.encryptedContent }
 										: {}),
@@ -1874,29 +1873,40 @@ export async function compact(
 							: undefined,
 				})
 			: undefined;
-		const convertToLlm = summaryOptions.convertToLlm ?? defaultConvertToLlm;
-		const retainedTail = convertToLlm(recentMessages);
-		const messages = [
-			...convertToLlm([
-				...(previousSummaryMessage ? [previousSummaryMessage] : []),
-				...messagesToSummarize,
-				...turnPrefixMessages,
-			]),
-			...retainedTail,
-		];
+		const allMessages = [...messagesToSummarize, ...turnPrefixMessages, ...recentMessages];
+		const originalCut = messagesToSummarize.length + turnPrefixMessages.length;
+		const nativeCut = findAnthropicCompactionCut(allMessages, originalCut);
+		// Hand-built preparations lacking entry IDs cannot move their persisted
+		// boundary into the tail. Summarizing all is still safe.
+		const safeCut =
+			nativeCut > originalCut && nativeCut < allMessages.length && !recentEntryIds?.[nativeCut - originalCut]
+				? allMessages.length
+				: nativeCut;
+		nativeFirstKeptEntryId =
+			safeCut === allMessages.length
+				? ""
+				: safeCut === originalCut
+					? firstKeptEntryId
+					: (recentEntryIds?.[safeCut - originalCut] ?? "");
+		for (let i = originalCut; i < safeCut; i++) extractFileOpsFromMessage(allMessages[i], fileOps);
+		const messages = (summaryOptions.convertToLlm ?? defaultConvertToLlm)([
+			...(previousSummaryMessage ? [previousSummaryMessage] : []),
+			...allMessages.slice(0, safeCut),
+		]);
 		try {
 			const remote = await requestAnthropicNativeCompaction(
 				model,
 				apiKey,
 				{
-					systemPrompt: summaryOptions.remoteSystemPrompt ?? [SUMMARIZATION_SYSTEM_PROMPT],
+					// The live prompt, not the local summarizer's synthetic system
+					// prompt: kept thinking remains valid only under identical controls.
+					systemPrompt: summaryOptions.remoteSystemPrompt ?? [],
 					messages,
 					tools: summaryOptions.tools,
 					instructions: buildAnthropicCompactionInstructions(
 						summaryOptions.promptOverride ?? SUMMARIZATION_PROMPT,
 						customInstructions,
 						formatAdditionalContext(summaryOptions.extraContext).trim() || undefined,
-						describeRetainedTail(retainedTail),
 					),
 					maxTokens: Math.min(Math.floor(0.8 * reserveTokens), MAX_SUMMARY_TOKENS),
 					reasoning: resolveCompactionEffort(model, summaryOptions.thinkingLevel),
@@ -1915,7 +1925,7 @@ export async function compact(
 				},
 			);
 			nativeSummary = remote.content;
-			nativeEncryptedContent = remote.encryptedContent;
+			nativeSignature = remote.signature;
 			nativeUsedTokens = calculatePromptTokens(remote.usage);
 			usedRemoteCompaction = true;
 		} catch (err) {
@@ -2004,7 +2014,7 @@ export async function compact(
 	summary = upsertFileOperations(summary, readFiles, modifiedFiles, fileOps.read);
 	if (nativeSummary !== undefined) {
 		// The replayed block stays byte-identical to the API's summary so it
-		// matches `encryptedContent`. The harness file lists above travel
+		// matches its signature. The harness file lists above travel
 		// separately: the converter replaces the summary message with the
 		// block and skips its text, so they would otherwise be invisible to
 		// this provider. Every other provider keeps reading the entry text.
@@ -2012,7 +2022,7 @@ export async function compact(
 		preserveData = withAnthropicCompactionPreserveData(preserveData, {
 			provider: model.provider,
 			content: nativeSummary,
-			...(nativeEncryptedContent ? { encryptedContent: nativeEncryptedContent } : {}),
+			...(nativeSignature ? { signature: nativeSignature } : {}),
 			...(filesText ? { filesText } : {}),
 			model: model.id,
 			usedTokens: nativeUsedTokens,
@@ -2034,7 +2044,7 @@ export async function compact(
 	return {
 		summary,
 		shortSummary,
-		firstKeptEntryId,
+		firstKeptEntryId: nativeSummary !== undefined ? nativeFirstKeptEntryId : firstKeptEntryId,
 		tokensBefore,
 		details: { readFiles, modifiedFiles } as CompactionDetails,
 		preserveData: finalPreserveData,

package/src/compaction/prompts/anthropic-compaction-instructions.md

@@ -1,8 +1,4 @@
-{{#if retainedTail}}
-SCOPE: The conversation's final {{#when retainedTail.count "==" 1}}{{retainedTail.role}} message stays{{else}}{{retainedTail.count}} messages, starting with a {{retainedTail.role}} message, stay{{/when}} in context verbatim after your summary. Summarize ONLY the history before those messages. You MUST NOT restate anything from those final messages — the reader sees them right after the summary — and you MUST treat them as the most recent state when describing progress and next steps.
-{{else}}
-SCOPE: The conversation above is the transcript to summarize. The API replaces everything before your summary with it, so nothing you leave out survives into the next context window.
-{{/if}}
+The conversation above is the complete history to summarize. The API replaces every message in this request with your summary; no message you leave out survives.
 
 {{#if extraContext}}
 {{extraContext}}
@@ -14,4 +10,4 @@ SCOPE: The conversation above is the transcript to summarize. The API replaces e
 Additional focus: {{customInstructions}}
 {{/if}}
 
-You MUST NOT call any tools while writing the summary; respond with the summary text only.
+You MUST NOT call any tools while writing the summary; respond with the summary text only.

package/src/index.ts

@@ -14,6 +14,8 @@ export * from "./proxy";
 export * from "./replay-policy";
 // Run-level telemetry collector + aggregators
 export * from "./run-collector";
+// Tool definitions remembered for Anthropic inactive-tool re-declaration
+export * from "./sent-tool-definitions";
 // Speculative execution coordinator
 export * from "./speculative-execution";
 // Telemetry

package/src/sent-tool-definitions.ts

@@ -0,0 +1,40 @@
+import type { Message, Tool } from "@oh-my-pi/pi-ai";
+
+/**
+ * Last wire definition this Agent sent for each tool name, so a provider that keeps
+ * withdrawn tools declared (Anthropic `tool_removal`) can re-declare them byte-identically.
+ * Used by prepareProviderCall and Agent.buildSideRequestContext.
+ */
+export class SentToolDefinitions {
+	#byName = new Map<string, Tool>();
+
+	/** Remember the definitions a request is about to send. */
+	record(tools: readonly Tool[]): void {
+		for (const tool of tools) this.#byName.set(tool.name, tool);
+	}
+
+	/**
+	 * Definitions for names the latest `requestControls.tools.declared` in `messages` holds
+	 * that are not in `active`; undefined when none. Names never sent by this Agent are
+	 * skipped: the provider drops them from the declaration.
+	 */
+	inactiveFor(messages: readonly Message[], active: readonly Tool[]): Tool[] | undefined {
+		let declared: readonly string[] | undefined;
+		for (let index = messages.length - 1; index >= 0; index--) {
+			const message = messages[index];
+			if (message?.role === "assistant" && message.requestControls?.tools) {
+				declared = message.requestControls.tools.declared;
+				break;
+			}
+		}
+		if (!declared) return undefined;
+		const activeNames = new Set(active.map(tool => tool.name));
+		const inactive: Tool[] = [];
+		for (const name of declared) {
+			if (activeNames.has(name)) continue;
+			const tool = this.#byName.get(name);
+			if (tool) inactive.push(tool);
+		}
+		return inactive.length > 0 ? inactive : undefined;
+	}
+}

package/src/types.ts

@@ -24,6 +24,7 @@ import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 import type { HarmonyAuditEvent } from "@oh-my-pi/pi-ai/utils/harmony-leak";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import type { AgentRunCoverage, AgentRunSummary } from "./run-collector";
+import type { SentToolDefinitions } from "./sent-tool-definitions";
 import type { AgentTelemetryConfig } from "./telemetry";
 
 /** Stream function - can return sync or Promise for async config lookup */
@@ -163,8 +164,10 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 
 	/**
 	 * When to interrupt tool execution for steering messages.
-	 * - "immediate" = check after each tool call (default)
-	 * - "wait" = defer steering until the current turn completes
+	 * - "immediate" = cut interruptible waits short and raise the cooperative
+	 *   `steeringSignal` for other running tools (default)
+	 * - "wait" = let non-interruptible tools finish undisturbed; interruptible
+	 *   waits are still cut short, since they have no work to complete
 	 */
 	interruptMode?: "immediate" | "wait";
 
@@ -238,6 +241,9 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 */
 	transformProviderContext?: (context: Context, model: Model) => Context | Promise<Context>;
 
+	/** Remembers sent tool definitions to fill {@link Context.inactiveTools}. */
+	sentToolDefinitions?: SentToolDefinitions;
+
 	/**
 	 * Resolves the API key or resolver for the current model before each LLM call.
 	 *
@@ -259,8 +265,9 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	/**
 	 * Peeks whether steering messages are queued, without consuming them.
 	 *
-	 * Polled while a tool batch runs (unless interruptMode is "wait") to decide
-	 * whether to abort in-flight and skip not-yet-started *interruptible* waits;
+	 * Polled while a tool batch runs (in "wait" mode, only when the batch holds an
+	 * interruptible tool) to decide whether to abort in-flight and skip
+	 * not-yet-started *interruptible* waits;
 	 * every other already-emitted call still executes and the message injects
 	 * at the batch boundary. The queue keeps
 	 * owning its messages until the loop reaches the next injection boundary and
@@ -289,7 +296,8 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * Peeks whether IRC messages should interrupt an interruptible waiting tool.
 	 *
 	 * Uses the same delivery rules as steering: the poll is non-consuming, only
-	 * runs for interruptible tools, and is ignored when interruptMode is "wait".
+	 * runs for interruptible tools, and cuts them short even when interruptMode
+	 * is "wait".
 	 * The host owns message injection at the next boundary.
 	 */
 	hasIrcInterrupts?: () => boolean | Promise<boolean>;
@@ -298,9 +306,12 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * process) is queued for aside injection at the next boundary.
 	 *
 	 * Same rules as {@link hasIrcInterrupts}: non-consuming, only cuts
-	 * *interruptible* waits short, ignored when interruptMode is "wait". Without
-	 * it a completion notice sits behind an hour-long `hub wait` that the agent
-	 * would have abandoned had it seen the notice.
+	 * *interruptible* waits short, in either interruptMode. Without
+	 * it a completion notice sits behind an hour-long `wait` that the agent
+	 * would have abandoned had it seen the notice. Unlike a peer IRC it never
+	 * raises {@link ToolCallContext.steeringSignal}: a queued completion must
+	 * not push ordinary foreground work (auto-background bash/eval) into the
+	 * background.
 	 */
 	hasBackgroundCompletions?: () => boolean | Promise<boolean>;
 
@@ -1031,6 +1042,12 @@ export interface AgentTool<
 	loadMode?: ToolLoadMode;
 	/** Short one-line summary used for tool discovery indexes. */
 	summary?: string;
+	/**
+	 * On-demand documentation topics (`topic → markdown`), readable as
+	 * `xd://<tool>/<topic>`. Lets a tool keep large sub-surfaces out of its
+	 * description and advertise only a one-line pointer per topic.
+	 */
+	docTopics?(): Readonly<Record<string, string>>;
 	/**
 	 * Concurrency mode for tool scheduling when multiple calls are in one turn.
 	 * - "shared": can run alongside other shared tools (default)
@@ -1055,7 +1072,7 @@ export interface AgentTool<
 	 * cleanly (e.g. `job` poll), so the abort surfaces the tool's current
 	 * snapshot rather than corrupting a side effect. Every other call runs to
 	 * completion even when steering is queued; the message lands at the next
-	 * batch boundary. Honored only when `interruptMode` is "immediate".
+	 * batch boundary. Honored in both `interruptMode`s.
 	 */
 	interruptible?: boolean | ((args: Partial<Static<TParameters>>) => boolean);
 	/**