@vanillagreen/pi-claude-bridge 3.2.2 → 4.0.1

package/src/connector-cache.ts

@@ -1,13 +1,12 @@
-// Cross-PROCESS cache of the connector inventory (vstack#870).
+// Cross-PROCESS cache of the connector inventory.
 //
-// #868 primes the inventory at provider registration, but the fetch takes ~1.5s
+//  primes the inventory at provider registration, but the fetch takes ~1.5s
 // while the first query is built at ~0.5-0.8s, so turn 1 of a cold sidecar goes
-// out with no declarations and gets exactly the #832 bug it was meant to fix.
+// out with no declarations and preserves the failure this cache prevents.
 //
 // An in-process cache cannot help the consumer that needs it most. drovr builds
 // a sidecar lazily on the first bridge round and, since their sidecars are
-// per-SESSION, that is a fresh process for every new chat — so their exposure is
-// once per chat, indefinitely, and every one of those is a cold process. The
+// per-SESSION, each chat starts a separate cold process. The
 // cache therefore has to survive process boundaries.
 //
 // Keyed by credential scope, because that is what selects the account: the org
@@ -18,7 +17,7 @@
 // wrong-version cache returns undefined and the caller falls back to today's
 // behaviour — the same fail-open contract as the inventory call itself.
 //
-// The ON-DISK FORMAT HAS AN EXTERNAL READER (vstack#892). drovr quarantines this
+// The ON-DISK FORMAT HAS AN EXTERNAL READER. drovr quarantines this
 // bundle to its sidecar process, so rather than calling `listAccountConnectors`
 // in-process it re-implements the reader half — path
 // `<piUserDir()>/connector-cache/<sha256(CLAUDE_CONFIG_DIR).hex[0..16]>.json`,
@@ -43,7 +42,7 @@ import type { ConnectorEntry } from "./connector-inventory.js";
 const CACHE_VERSION = 2;
 /** Long enough to be useful across a machine's lifetime, short enough that a
  *  removed connector stops being declared without needing a manual purge. A
- *  stale entry is not dangerous — a connector that no longer resolves simply
+ *  stale entry is not dangerous — a connector that does not resolve simply
  *  fails to connect, which is the fail-open path — so this is hygiene, not a
  *  correctness boundary. */
 const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;

package/src/connector-inventory.ts

@@ -5,7 +5,7 @@
 // nothing in the result distinguishes "these are the connectors" from "these are
 // the connectors the search happened to return this time". Downstream then stored
 // that lower bound as authoritative, so an account with Slack attached could
-// report an inventory without Slack and no failure signal (vstack#838).
+// report an inventory without Slack and no failure signal.
 //
 // This module asks the account instead of the model. Verified live against a
 // personal claude_max org: the endpoint is POST (a GET returns 405) and each
@@ -18,12 +18,11 @@
 // installed. It says nothing about whether a given connector's MCP server has
 // finished attaching inside the `claude` child that is about to run a turn —
 // this is a plain HTTPS call and does not consult that process at all. The two
-// were previously conflated by accident: the ToolSearch probe could only report
-// what was already attached, so an inventory implied availability (wrongly, but
-// conservatively — it under-reported, which fails safe). They are now separately
+// are separate: the ToolSearch probe can report only what is attached, so an
+// inventory must not imply availability. They are
 // observable and can legitimately disagree: a correct `complete: true` inventory
 // can name Slack while `mcp__claude_ai_Slack__*` is not yet callable in this
-// process (vstack#832). Treat an inventory as NECESSARY BUT NOT SUFFICIENT for
+// process. Treat an inventory as NECESSARY BUT NOT SUFFICIENT for
 // availability and keep an attach-time check on the call path; do not derive
 // "can I call this tool right now" from this result.
 //
@@ -47,8 +46,7 @@ export type ConnectorEntry = {
 	/**
 	 * Account-side install state. `"connected"` marks the connectors the CLI
 	 * actually attempts; everything else it never gives a `Starting connection`
-	 * line at all. Verified live 2026-07-26: 7 `connected` / 20 `unknown` on the
-	 * app account, and the CLI connected exactly those 7.
+	 * line at all. The CLI attempts exactly the entries marked `connected`.
 	 */
 	installState?: string;
 	description?: string;

package/src/connector-runtime.ts

@@ -1,5 +1,5 @@
 // Connector prime/snapshot host: the per-credential-scope inventory cache the
-// query path reads synchronously (vstack#832/#870). Extracted from index.ts —
+// query path reads synchronously. Extracted from index.ts —
 // this is process-lifetime runtime state, not provider streaming logic.
 //
 // Connector declarations for the query path, cached per credential scope. The
@@ -32,15 +32,15 @@ export function readCredentialFile(path: string): string | undefined {
 const connectorServerCache = new Map<string, Record<string, unknown>>();
 const connectorServerPending = new Set<string>();
 // Epoch ms of the last FAILED inventory attempt per scope, so a persistently
-// failing account cools down instead of issuing one new HTTPS request per turn
-// (VST-14). Missing credentials are exempt: that check is a local file read
+// failing account cools down instead of issuing one HTTPS request per turn
+//  Missing credentials are exempt: that check is a local file read
 // with no request to bound, and a just-completed `claude login` must take
 // effect on the next turn.
 const connectorServerFailureAt = new Map<string, number>();
 
 // Deadline on the inventory round trip. Without one, a hung claude.ai request
 // held the pending flag forever — same budget as the account-host probe's
-// ACCOUNT_PROBE_DEADLINE_MS (VST-14).
+// ACCOUNT_PROBE_DEADLINE_MS.
 const CONNECTOR_PRIME_TIMEOUT_MS = 10_000;
 const CONNECTOR_PRIME_FAILURE_COOLDOWN_MS = 60_000;
 
@@ -81,12 +81,12 @@ export function connectorCredentialEnv(claudeConfigDir: string | undefined = pro
 //
 // FAILS OPEN throughout: no credentials, a failed inventory, or a thrown call
 // all resolve to "declare nothing" rather than breaking the turn. Failures are
-// NOT cached — a transient blip at registration used to pin `{}` for the
+// NOT cached. Caching a transient registration failure would pin `{}` for the
 // process lifetime, keeping every later turn undeclared and the disk-cache
 // fallback unreachable. Leaving the key unset makes the next snapshot retry;
 // the pending set dedupes concurrent fetches, and a failed inventory attempt
 // stamps a per-scope cooldown so a persistently failing account backs off
-// instead of re-priming on every turn (VST-14).
+// instead of re-priming on every turn.
 export function primeConnectorServers(claudeConfigDir?: string, overrides: PrimeConnectorOverrides = {}): void {
 	const key = connectorScopeKey(claudeConfigDir);
 	if (connectorServerCache.has(key) || connectorServerPending.has(key)) return;
@@ -124,7 +124,7 @@ export function primeConnectorServers(claudeConfigDir?: string, overrides: Prime
 			connectorServerFailureAt.delete(key);
 			// Persist so the NEXT cold process has this synchronously. Priming always
 			// loses the race against turn 1 in its own process; a cache written by an
-			// earlier run is the only thing turn 1 can read in time (vstack#870).
+			// earlier run is the only thing turn 1 can read in time.
 			if (writeCachedConnectors(inventory.connectors, key)) {
 				debug(`connectors: cached ${inventory.connectors.length} entries`);
 			}
@@ -148,7 +148,7 @@ export function connectorServersSnapshot(claudeConfigDir?: string): Record<strin
 	primeConnectorServers(claudeConfigDir);
 	// Fall back to the previous run's inventory, read synchronously. This is the
 	// only thing that can populate turn 1 of a cold process, because priming
-	// cannot finish before the first query is built (vstack#870).
+	// cannot finish before the first query is built.
 	const cached = readCachedConnectors(key);
 	if (!cached) return {};
 	const servers = connectorMcpServers({ ok: true, complete: true, connectors: cached });

package/src/connectors.ts

@@ -57,7 +57,7 @@ export function connectorsEnabledFor(config?: Config): boolean {
 // isolation (no sources), which drops the connectors even with
 // ENABLE_CLAUDEAI_MCP_SERVERS=1. So connectors mode must pass SOME source list.
 //
-// It must be `["user"]` and nothing more (vstack#990). Connector state lives in
+// It must be `["user"]` and nothing more. Connector state lives in
 // USER scope — the account's config dir (CLAUDE_CONFIG_DIR for managed router
 // profiles) — so user scope is sufficient for connectors to surface. Claude
 // Code settings files can also carry an `env` map and `apiKeyHelper`; including
@@ -98,7 +98,7 @@ export const CLAUDE_AI_CONNECTOR_TOOL_PATTERNS = [
 	"mcp__claude_ai_Atlassian__*",
 ];
 
-// --- The SDK's two-name trap for built-in tools (vstack#1007, vstack#1011) ---
+// --- The SDK's two-name trap for built-in tools ---
 //
 // The CLI gives some built-ins TWO spellings, and which one you see depends on
 // which SURFACE the name crosses:
@@ -118,9 +118,9 @@ export const CLAUDE_AI_CONNECTOR_TOOL_PATTERNS = [
 // This map declares each alias pair ONCE; every delivered-side membership set
 // derives its spellings from it instead of hand-copying names. Both prior
 // instances of the trap were exactly that hand-copy: CHILD_INTERNAL_TOOLS held
-// request-side spellings that no stream name ever matched (vstack#1007), and
+// request-side spellings that no stream name ever matched, and
 // the connectors allowlist hook DENIED the two discovery tools it exists to
-// permit (vstack#1011). Delivered-side sets accept BOTH spellings, so a CLI
+// permit. Delivered-side sets accept BOTH spellings, so a CLI
 // version that drops the aliasing cannot reintroduce the bug in either
 // direction.
 const SDK_TOOL_ALIASES: Record<string, string> = {
@@ -144,14 +144,18 @@ function deliveredSpellings(name: string): string[] {
 // REQUEST-side spellings: this list feeds the SDK option surface (the
 // disallowedTools filter in toolIsolationForQuery) and is the exported public
 // name. Delivered-side checks use CONNECTOR_DISCOVERY_TOOL_NAMES below.
-export const CONNECTOR_DISCOVERY_TOOLS = ["ToolSearch", "ListMcpResources", "ReadMcpResource"];
+const MCP_RESOURCE_TOOLS = ["ListMcpResources", "ReadMcpResource"];
+export const CONNECTOR_DISCOVERY_TOOLS = ["ToolSearch", ...MCP_RESOURCE_TOOLS];
 
-// Delivered-side membership set for the discovery tools: both spellings of
-// each entry, derived from SDK_TOOL_ALIASES. A PreToolUse hook's `tool_name`
-// carries the canonical spelling (`ListMcpResourcesTool`), so testing the
-// request-side list directly made the fail-closed allowlist hook DENY the two
-// resource tools it exists to permit (vstack#1011).
+// Delivered-side membership sets carry both spellings, derived from the one
+// alias declaration above. The resource-only set keeps those audit calls
+// dispatchable without making ToolSearch a Pi call.
 const CONNECTOR_DISCOVERY_TOOL_NAMES = new Set(CONNECTOR_DISCOVERY_TOOLS.flatMap(deliveredSpellings));
+const MCP_RESOURCE_TOOL_NAMES = new Set(MCP_RESOURCE_TOOLS.flatMap(deliveredSpellings));
+
+export function isMcpResourceTool(name: string): boolean {
+	return MCP_RESOURCE_TOOL_NAMES.has(name);
+}
 
 // --- Connector WRITE tool control (read-inline / write-by-approval) ---
 //
@@ -243,12 +247,12 @@ function connectorNameWords(segment: string): string[] {
 // exact tool id (the CLI matcher only supports exact ids or a whole-server glob).
 //
 // PUBLIC CONTRACT — this list and `isConnectorWriteTool` have downstream
-// dependents that gate real user-facing approvals on them (vstack#892):
+// dependents that gate real user-facing approvals on them:
 //
 //   memsira  routes connector writes through its own gated approval flow
 //   drovr    keeps its chat sidecar permanently write-`deny` and runs an
 //            approved write as a separate one-shot `claude -p` scoped by
-//            `--allowedTools` to exactly one connector tool (drovr#288)
+//            `--allowedTools` to exactly one connector tool
 //
 // Both pin the actions they expose against this classification, because "the
 // sidecar structurally cannot do this itself" is THIS module's claim, not
@@ -329,23 +333,21 @@ export function isConnectorTool(name: string | undefined): boolean {
 // `content_block_start` / assistant-message blocks, the exact fields
 // processStreamEvent/processAssistantMessage read. Stream names are a
 // DELIVERED surface (see SDK_TOOL_ALIASES): the two MCP-resource built-ins'
-// request-side spellings used to sit in this set and never matched anything
-// (vstack#1007). If an aliased name is ever added here, derive its spellings
-// via deliveredSpellings rather than hand-copying them.
+// request-side spellings do not belong in this set because they match nothing.
+// Derive every aliased name via deliveredSpellings rather than hand-copying it.
 //
-// The MCP-resource tools are now EXCLUDED deliberately, under BOTH spellings:
+// The MCP-resource tools are EXCLUDED under BOTH spellings:
 // a resource read is a real account-surface access, and both consumer hosts
 // audit it through the Pi mirror (an out-of-process sidecar has no view of the
 // bridge's own connector-call entries or the child transcript), so it stays
-// mirrored into Pi. Do not re-add either spelling without revisiting that
-// decision in vstack#1007. The allowlist hook is what lets those calls run at
-// all — see isAllowlistedConnectorSessionTool (vstack#1011).
+// mirrored into Pi. Do not add either spelling to this set. The allowlist hook
+// is what lets those calls run; see isAllowlistedConnectorSessionTool.
 const CHILD_INTERNAL_TOOLS = new Set(["ToolSearch", "ScheduleWakeup"]);
 
 /**
  * True for a Claude Code built-in meta-tool the child resolves in-process.
  *
- * Mirroring one into the Pi stream (vstack#980) made Pi's agent loop dispatch a
+ * Mirroring one into the Pi stream would make Pi's agent loop dispatch a
  * tool it does not have and deliver an error result for an id no MCP handler
  * ever claimed. The result queued in `pendingResults` until the reaper dropped
  * it — one "dropped 1 tool result(s) whose handler never matched (ToolSearch)"
@@ -375,13 +377,13 @@ export function isChildInternalTool(name: string | undefined): boolean {
  *    miss, and write a synthetic `Tool <name> not found` error result into the
  *    transcript — while the child went on and executed the real call. The Pi
  *    transcript then RECORDED A FAILURE FOR A CALL THAT SUCCEEDED, next to an
- *    answer built from the real payload, so the model's correct answer read as
- *    a fabrication (drovr#311, memsira#320). The false result is also projected
+ *    answer built from the real payload, so the model's correct answer appears
+ *    fabricated. The false result is also projected
  *    back into the child's session on a rebuild (`syncSharedSession`), which is
  *    how a lie in a mirror becomes a lie in the conversation of record.
  *
  * 2. Claude Code's own in-process meta-tools (`isChildInternalTool`), which the
- *    child resolves without any dispatcher at all (vstack#980).
+ *    child resolves without any dispatcher at all.
  *
  * Takes the RAW SDK tool name, before `mapToolName` — child-executed names have
  * no Pi-side counterpart, so mapping them is meaningless. Accepts a missing
@@ -487,7 +489,7 @@ export function connectorWriteDenyHook(): HookCallback {
 		// the tool call proceed (fail OPEN) — so any exception in this body
 		// must convert to a deny, never an allow. Today's body is pure string
 		// checks on schema-validated input; the catch pins that invariant for
-		// whatever gets added here later.
+		// subsequent changes to this body.
 		try {
 			if (input.hook_event_name !== "PreToolUse") return { continue: true };
 			// A non-string tool name cannot be classified, and this hook fails
@@ -507,7 +509,7 @@ export function connectorWriteDenyHook(): HookCallback {
 // stay PRODUCT-NEUTRAL: this is shared source and every consuming app shows it.
 // Naming one host told a different app's model to use a product it has never
 // heard of, which is confusing at exactly the moment someone is debugging a
-// refused write (vstack#892). Each host describes its own approval flow in its
+// refused write. Each host describes its own approval flow in its
 // own prompt; this string only has to say that one exists.
 function connectorWriteDenyOutput(toolName: string) {
 	return {
@@ -533,8 +535,8 @@ function connectorWriteDenyOutput(toolName: string) {
 //
 // This is a DELIVERED-side check — `name` is a hook's `input.tool_name`, which
 // carries the canonical spelling — so membership is tested against
-// CONNECTOR_DISCOVERY_TOOL_NAMES (both spellings), not the request-side list
-// (vstack#1011). That also carries vstack#1007's mirroring decision: the
+// CONNECTOR_DISCOVERY_TOOL_NAMES (both spellings), not the request-side list.
+// The allowlist hook also carries the mirroring rule: the
 // MCP-resource tools are deliberately NOT child-internal so every resource
 // read mirrors into Pi as the consumers' audit surface — a mirror that can
 // only exist if this allowlist lets the call execute. Denying the canonical
@@ -669,14 +671,12 @@ export function toolIsolationForQuery(connectorsEnabled: boolean, writeMode: Con
 /**
  * Explicit `mcpServers` declarations for the account's CONNECTED connectors.
  *
- * Why this exists (vstack#832): claude.ai connectors load async and non-blocking,
+ * Why this exists: claude.ai connectors load async and non-blocking,
  * and the turn-1 tool manifest is built at +410-665ms — roughly 300ms BEFORE the
  * CLI has even fetched the connector list. The model therefore composes its first
  * answer against a manifest containing no connectors and says it has no access,
- * while the connector attaches ~1s later and is never asked. Measured end to end
- * on 40 cold sidecars (memsira, 2026-07-26): a connector tool call happened in
- * 7/20 baseline runs versus 20/20 with the declaration, and "I don't have access"
- * went 13/20 → 0/20, one-sided Fisher exact p = 6.4e-6. Confirmed at seven
+ * while the connector attaches later and is never asked. The declaration must
+ * be available before the first query. Confirmed at seven
  * declarations over a further 30 runs: 5/10 → 10/10 calls, 5/10 → 0/10 denials.
  *
  * It is also FASTER, which is the opposite of what the startup barrier suggests.
@@ -736,9 +736,8 @@ export function connectorMcpServers(inventory: ConnectorInventory): Record<strin
 
 /**
  * `CLAUDE_BRIDGE_CONNECTOR_DECLARE=off` (or `0`/`false`/`no`) disables explicit
- * connector declarations while leaving connectors themselves enabled. Falls back
- * to the pre-#832 behaviour: connectors still load, they just race the turn-1
- * manifest again.
+ * connector declarations while leaving connectors themselves enabled. Without
+ * declarations, connector loading races the turn-1 manifest.
  */
 export function connectorDeclarationsDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
 	const v = (env.CLAUDE_BRIDGE_CONNECTOR_DECLARE ?? "").trim().toLowerCase();

package/src/consume-query.ts

@@ -111,7 +111,7 @@ export async function consumeQuery(
 		if (account) {
 			// Thunk, not a value: this runs once per SDK message — including one
 			// stream_event per streamed token — and debug() only evaluates function
-			// args after its DEBUG early return (VST-15).
+			// args after its DEBUG early return.
 			debug("consumeQuery: managed message", () => JSON.stringify({
 				type: message.type,
 				subtype: (message as any).subtype,
@@ -203,8 +203,8 @@ export async function consumeQuery(
 					}
 					// Other non-success subtypes (error_max_turns,
 					// error_during_execution) surface at completion via the held
-					// failure — an explicit error event where these turns previously
-					// ended silently. Session persistence and deferred replay still run.
+					// failure. These turns require an explicit error event instead of
+					// silent completion. Session persistence and deferred replay still run.
 				}
 				break;
 			case "system":

package/src/convert.ts

@@ -28,7 +28,7 @@ export function mapPiToolNameToSdk(name: string, customToolNameToSdk?: Map<strin
 	// `McpClaudeAiSlackSlackSearchChannels`) that appeared in the child's
 	// projected history, so the model imitated it on the next turn and got a
 	// real `Tool ... not found` from the MCP dispatcher before retrying the
-	// canonical name — one wasted round-trip per affected call (memsira#320).
+	// canonical name — one wasted round-trip per affected call.
 	//
 	// Connector names stopped reaching this function at all once they stopped
 	// being mirrored as Pi tool calls (isChildExecutedTool), so this is the

package/src/debug.ts

@@ -50,7 +50,7 @@ export function debug(...args: unknown[]) {
 		if (a instanceof Error) return `${a.name}: ${a.message}${a.stack ? "\n" + a.stack : ""}`;
 		// A function argument is a lazy payload: hot-path call sites (per-token
 		// stream events) pass a thunk so the expensive formatting only runs when
-		// DEBUG is on — fmt is only reached past the early return (VST-15).
+		// DEBUG is on — fmt is only reached past the early return.
 		if (typeof a === "function") return fmt((a as () => unknown)());
 		return JSON.stringify(a);
 	};
@@ -121,7 +121,7 @@ export function makeCliDebugOptions(tag: string): { debug?: boolean; debugFile?:
 /** Diagnostic dump — for "should never happen" paths. Gated on the same
  *  CLAUDE_BRIDGE_DEBUG flag as debug(): the entries carry session metadata
  *  and land in a log outside any host app's retention/cleanup boundary, so
- *  a host that has not opted into debugging must get no disk write (VST-15). */
+ *  a host that has not opted into debugging must get no disk write. */
 export function diagDump(label: string, data: Record<string, unknown>) {
 	if (!DEBUG) return;
 	try {

package/src/index.ts

@@ -79,7 +79,7 @@ export { cancelScheduledSessionPersistence, conversationFingerprint, conversatio
 export { NATIVE_PROVIDER_UNSUPPORTED_MESSAGE, buildNativeProvider, claudeAuthSourceLabel, supportsNativeProvider } from "./native-provider.js";
 export { DEFAULT_STREAM_IDLE_TIMEOUT_MS, STREAM_IDLE_BACKOFF_HINT_MS, STREAM_IDLE_TIMEOUT_ENV, buildStreamIdleTimeoutErrorMessage, createStreamIdleWatchdog, streamIdleTimeoutMsFromEnv, type StreamIdleTimeoutInfo, type StreamIdleWatchdog, type StreamIdleWatchdogState } from "./stream-idle-watchdog.js";
 export { ALLOWED_RATE_LIMIT_WARNING_UTILIZATION_THRESHOLD, formatAllowedRateLimitWarning, formatResetTimestamp, isUsageLimitMessage, normalizeRateLimitUtilization, resetTimestampMs, uniqueNonEmptyLines } from "./rate-limit.js";
-export { mapToolName } from "./tool-mapping.js";
+export { isPiDispatchable, mapToolName } from "./tool-mapping.js";
 export { cancelScheduledToolUseEnd, endToolUseTurn, finalizeToolUseTurnFromMcpInvocation, noteChildExecutedToolResults, processAssistantMessage, processStreamEvent, reapStaleQueuedResults, scheduleToolUseTurnEnd } from "./assistant-stream.js";
 export {
 	accountSessionScope,
@@ -239,18 +239,17 @@ export interface DeferredUserReplayPlan {
 	// with no image blocks).
 	prompt: string | null;
 	// Present when the run carries image blocks — the replay must send these
-	// (via wrapPromptStream) or the images are silently lost (vstack#993).
+	// (via wrapPromptStream) or the images are silently lost.
 	blocks: ContentBlockParam[] | null;
 }
 
 /** Plan replay of user messages pi injected mid-query (steer drain, followUp).
  *  Captures the ENTIRE trailing consecutive user run, not just the last
- *  message — dropping the earlier ones was silent input loss (vstack#967) —
- *  but never walks below `capturedThrough`, the position an earlier callback
+ *  message, but never walks below `capturedThrough`, the position a prior callback
  *  of the SAME query already captured (or deliberately held at, for an
  *  all-empty run). Without that lower bound a second mid-query steer re-planned
  *  the whole run from scratch and the first steer was queued — and delivered to
- *  Claude — twice (vstack#1009). */
+ *  Claude — twice. */
 export function planDeferredUserReplay(messages: Context["messages"], capturedThrough = 0): DeferredUserReplayPlan {
 	let runStart = messages.length;
 	while (runStart > capturedThrough && messages[runStart - 1]?.role === "user") runStart--;
@@ -299,7 +298,7 @@ export function resolveMcpTools(context: Context, excludeToolName?: string): {
 		// namespace belongs to the child's own MCP servers, so a Pi tool sitting
 		// on it would be advertised a SECOND time under our prefix — two names
 		// for one capability, and the model picking the wrong one gets a real
-		// `Tool ... not found` from the dispatcher (memsira#320). It would also
+		// `Tool... not found` from the dispatcher. It would also
 		// be uncallable in any case: a `tool_use` under that namespace is treated
 		// as child-executed and never handed to Pi (isChildExecutedTool), so
 		// filtering here is what makes the two halves agree end to end.
@@ -418,8 +417,8 @@ function buildMcpServers(tools: Tool[], queryCtx: QueryContext): Record<string,
 // 2. consumeQuery() iterates the SDK generator, pushing events to currentPiStream
 // 3. On tool_use: ends the current pi stream, nulls it out. The MCP handler
 //    blocks the generator naturally — no events arrive until resolved.
-// 4. Pi executes the tool, calls streamSimple again. We swap in the new stream,
-//    resolve the MCP handler, and the generator unblocks — events flow to new stream.
+// 4. Pi executes the tool and calls streamSimple again. We swap in the replacement
+//    stream, resolve the MCP handler, and the generator unblocks into that stream.
 //
 // Note: resetTurnState clears turnSawStreamEvent while the generator may still
 // have queued messages from the previous turn. This is safe because step 3 nulls
@@ -502,7 +501,7 @@ function applyProviderRegistration(trigger: string): void {
 	debug(`${trigger}: native registration upsert, credentialed=${credentialed} (module=${moduleInstanceId})`);
 	// Start the connector inventory now, not on the first turn: the query path
 	// can only read a synchronous snapshot, so priming here is what gets the
-	// declarations in place before turn 1 (vstack#832). Fire and forget —
+	// declarations in place before turn 1. Fire and forget —
 	// registration must not wait on the network. Primes the DEFAULT credential
 	// scope only; managed profiles are primed per request in their own scope.
 	if (hasClaudeCredentials() && connectorsEnabledFor(loadConfig(process.cwd()))) primeConnectorServers();
@@ -529,7 +528,7 @@ function applyProviderRegistration(trigger: string): void {
 	}
 }
 
-/** Provider entry point. Pi calls this for each new prompt and each tool result.
+/** Provider entry point. Pi calls this for each prompt and each tool result.
  *  Two cases: tool result delivery (active query) or fresh query. Exported for
  *  the rotation-stream unit tests, which drive it with a fake SDK factory. */
 export function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream {
@@ -619,7 +618,7 @@ function streamClaudeAgentSdkInLane(model: Model<any>, context: Context, options
 		if (queryCtx.pendingToolCalls.size > 0) {
 			// A waiting handler whose call never reached Pi can never be answered —
 			// fail it now with a retryable error instead of letting the SDK await it
-			// forever (the 2026-08-17 five-and-a-half-hour deadlock, vstack#1469).
+			// indefinitely.
 			// Forwarded-but-unanswered handlers stay: steer-split batches legitimately
 			// deliver their results in a later callback.
 			const stranded = drainStrandedToolCalls(queryCtx);
@@ -646,7 +645,7 @@ function streamClaudeAgentSdkInLane(model: Model<any>, context: Context, options
 		// so we save them for replay as continuation queries after consumeQuery ends.
 		// The cursor may only advance over messages actually captured for replay:
 		// claiming Claude owns a user message that was never deferred is permanent
-		// silent input loss (vstack#967 — only the LAST of several trailing user
+		// silent input loss ( — only the LAST of several trailing user
 		// messages was captured while the cursor skipped them all).
 		let capturedThrough = context.messages.length;
 		if (lastMsgRole === "user") {
@@ -654,13 +653,13 @@ function streamClaudeAgentSdkInLane(model: Model<any>, context: Context, options
 			// Math.max-advances with every callback's capturedThrough below), so a
 			// second steer callback only queues messages BEYOND what the first one
 			// already owns — re-planning the whole trailing run queued the earlier
-			// steer twice (vstack#1009). latestCursor, not the shared record's
+			// steer twice. latestCursor, not the shared record's
 			// cursor, deliberately: it lives on this QueryContext, so it is correct
 			// for reentrant and detached foreign queries too, whose contexts the
-			// shared cursor does not index (vstack#1001).
+			// shared cursor does not index.
 			const replay = planDeferredUserReplay(context.messages, queryCtx.latestCursor);
 			// Image-only runs have no usable text but must still replay — capture
-			// whenever EITHER form has content (vstack#993).
+			// whenever EITHER form has content.
 			if (replay.prompt || replay.blocks) {
 				ctx().deferredUserMessages.push({ text: replay.prompt ?? "", blocks: replay.blocks ?? undefined });
 				debug(`provider: deferred ${replay.userMessageCount} user message(s) for replay after query${replay.blocks ? ` (${replay.blocks.length} blocks incl. images)` : ""}: ${(replay.prompt ?? "[image-only]").slice(0, 60)}`);
@@ -678,12 +677,12 @@ function streamClaudeAgentSdkInLane(model: Model<any>, context: Context, options
 		// Cursor may only ADVANCE, and only for a query that holds the record's
 		// claim. A reentrant subagent call routed through this instance arrives
 		// here with a SHORT foreign context (its own [user…] conversation, not
-		// the one the cursor indexes) — writing its length used to shrink the
+		// the one the cursor indexes). Writing its length would shrink the
 		// parent cursor and make the next REUSE replay already-owned history.
 		// The stackDepth guard covers a pushed subagent context; the detached
 		// flag covers a foreign one-shot on the top-level ctx, whose GROWN
 		// mid-query context could otherwise out-length the parent's cursor and
-		// advance it past history Claude never saw (vstack#1001); Math.max
+		// advance it past history Claude never saw; Math.max
 		// remains the backstop for a legacy-record foreign context the
 		// fingerprint guard could not classify.
 		const activeSession = getSharedSession();
@@ -702,7 +701,7 @@ function streamClaudeAgentSdkInLane(model: Model<any>, context: Context, options
 		debug(`provider: orphaned tool result after abort, emitting end_turn`);
 		// The detached flag deliberately survives query end: an orphaned result
 		// from a foreign one-shot indexes ITS conversation, and writing that
-		// length here would move (even shrink) the parent's cursor (vstack#1001).
+		// length here would move (even shrink) the parent's cursor.
 		const activeSession = getSharedSession();
 		if (activeSession && stackDepth() === 0 && !ctx().detachedFromSharedSession) setSharedSession({ ...activeSession, cursor: context.messages.length });
 		const c = ctx();  // capture current context for the microtask
@@ -883,7 +882,7 @@ function streamClaudeAgentSdkInLane(model: Model<any>, context: Context, options
 	const { sessionId: resumeSessionId, promptStart } = syncResult;
 	// A FOREIGN-conversation query (conversation-fingerprint mismatch against
 	// the shared record — a subagent-shaped request arriving while the parent
-	// is IDLE, vstack#1001) also runs as a clean one-shot and gets the same
+	// is IDLE,) also runs as a clean one-shot and gets the same
 	// hands-off treatment as a reentrant one below: never persist over the
 	// module-level record, never mark it for rebuild. The flag also rides the
 	// QueryContext so the mismatch/abort/teardown paths that mutate the record
@@ -961,13 +960,13 @@ function streamClaudeAgentSdkInLane(model: Model<any>, context: Context, options
 
 	// 4. Capture context for abort handling (must be AFTER pushContext)
 	const abortCtx = ctx();
-	// Failure metadata consumeQuery observed, surviving an iterator THROW (the
-	// .catch below reuses it instead of re-classifying — see C5 note there).
+	// Failure metadata from consumeQuery survives an iterator throw. The catch
+	// below reuses it instead of re-classifying it; see the C5 note.
 	const attemptFailure: { failure?: ClaudeAttemptFailure } = {};
 	// A reentrant (subagent) query must never write the module-level shared
 	// session: its completion/failure handlers would overwrite the PARENT's
 	// record with the child's session id and cursor. A foreign-conversation
-	// one-shot (vstack#1001) has exactly the same non-claim on the record.
+	// one-shot has exactly the same non-claim on the record.
 	const persistSession = (next: SessionState | null): void => {
 		if (isReentrant || foreignContext) return;
 		setSharedSession(next && conversationFp ? { conversationFingerprint: conversationFp, ...next } : next);
@@ -976,7 +975,7 @@ function streamClaudeAgentSdkInLane(model: Model<any>, context: Context, options
 		if (isReentrant || foreignContext) return;
 		markSessionForRebuild(opts);
 	};
-	// #967 invariant: a deferred (mid-query) user message may be dropped only
+	//  invariant: a deferred (mid-query) user message may be dropped only
 	// LOUDLY — the cursor already advanced over it on the promise of replay.
 	// Callers that keep a session record after a non-empty drop must persist it
 	// with needsRebuild so the next turn re-imports the steers from Pi history.
@@ -1185,7 +1184,7 @@ function streamClaudeAgentSdkInLane(model: Model<any>, context: Context, options
 				// execute. Deferred user input is dropped LOUDLY, and when steers
 				// were dropped the record is marked needsRebuild: the cursor already
 				// advanced over them on the promise of replay, so a plain REUSE next
-				// turn would silently lose them forever (#967).
+					// turn would silently lose them forever.
 				if (!abortCtx.handledTerminalError) surfaceFailure(failure);
 				const droppedSteers = dropDeferredUserMessages("terminal-failure");
 				const activeSession = getSharedSession();
@@ -1235,7 +1234,7 @@ function streamClaudeAgentSdkInLane(model: Model<any>, context: Context, options
 
 					const contOptions = { ...queryOptions, resume: resumeId, ...makeCliDebugOptions("continuation") };
 					// Runs carrying image blocks replay as blocks (wrapPromptStream) so
-					// the images survive; text-only runs stay plain strings (vstack#993).
+					// the images survive; text-only runs stay plain strings.
 					const contQuery = sdkQueryFactory({ prompt: steer.blocks ? wrapPromptStream(steer.blocks) : steer.text, options: contOptions });
 					abortCtx.activeQuery = contQuery;
 
@@ -1250,7 +1249,7 @@ function streamClaudeAgentSdkInLane(model: Model<any>, context: Context, options
 							if (!abortCtx.handledTerminalError) surfaceFailure(continuation.failure);
 							// The shifted steer may never have reached the child, and any
 							// remaining ones certainly did not — the record must rebuild so
-							// they re-import from Pi history (#967).
+							// they re-import from Pi history.
 							if (dropDeferredUserMessages("continuation-failure", steer).length > 0) {
 								markRebuildForThisQuery();
 							}
@@ -1269,7 +1268,7 @@ function streamClaudeAgentSdkInLane(model: Model<any>, context: Context, options
 						};
 						recordAttemptFailure(continuationFailure);
 						if (!abortCtx.handledTerminalError) surfaceFailure(continuationFailure);
-						// Same #967 posture as the failure branch above.
+						// Apply the same rebuild rule as the failure branch above.
 						if (dropDeferredUserMessages("continuation-error", steer).length > 0) {
 							markRebuildForThisQuery();
 						}
@@ -1291,7 +1290,7 @@ function streamClaudeAgentSdkInLane(model: Model<any>, context: Context, options
 			if (wasAborted || options?.signal?.aborted) {
 				markRebuildForThisQuery({ forceRotate: true });
 			}
-			// #967: a record kept past this error with steers behind its cursor
+			// a record kept past this error with steers behind its cursor
 			// must rebuild so they re-import from Pi history. (The non-abort
 			// surface path below replaces the record with null, which rebuilds too.)
 			if (dropDeferredUserMessages("query-error").length > 0) {
@@ -1351,7 +1350,7 @@ function streamClaudeAgentSdkInLane(model: Model<any>, context: Context, options
 				...(options ?? {}),
 				[ROTATION_STATE_KEY]: rotationState,
 			} as BridgeStreamOptions);
-			// End exactly once per outcome (VST-53). Ending in a `finally` ran on
+			// End exactly once per outcome. Ending in a `finally` ran on
 			// the throw path too, BEFORE the .catch below could push its error
 			// event — and EventStream.push is a silent no-op after end, so a failed
 			// rotation ended the turn with no error event at all. Success ends
@@ -1445,8 +1444,8 @@ export default function (pi: ExtensionAPI) {
 	// branch switch) both mutate pi's messages array out from under the
 	// bridge. syncSharedSession's REUSE check would otherwise see
 	// slice(cursor) === [] (or skip entries) and keep --resume'ing a CC
-	// session that no longer matches pi's history. /compact in particular
-	// triggers CC's autocompact-thrashing guard (issue #8). Force the next
+	// session that does not match pi's history. /compact in particular
+		// triggers CC's autocompact-thrashing guard. Force the next
 	// call down the REBUILD path so CC sees the current history.
 	const markRebuild = (event: string) => {
 		const activeSession = getSharedSession();

package/src/models.ts

@@ -1,9 +1,9 @@
 // Canonical selection + display order for the model picker.
 // Extracted from index.ts so tests can import without activating the extension.
 
-export const FABLE_MODEL_ID = "claude-fable-5";
+export const FABLE_MODEL_ID = "claude-fable-5-1";
 // Opus 4.8 is both a selectable model and the safety-fallback target for the two
-// primaries whose classifiers can decline a turn (Fable 5, Opus 5).
+// primaries whose classifiers can decline a turn (Fable 5.1, Opus 5).
 export const FABLE_FALLBACK_MODEL_ID = "claude-opus-4-8";
 export const OPUS_5_MODEL_ID = "claude-opus-5";
 export const SONNET_5_MODEL_ID = "claude-sonnet-5";
@@ -36,7 +36,7 @@ type BridgeModelMetadata = {
 const FALLBACK_MODELS: Record<string, BridgeModelMetadata> = {
 	[FABLE_MODEL_ID]: {
 		id: FABLE_MODEL_ID,
-		name: "Claude Fable 5",
+		name: "Claude Fable 5.1",
 		reasoning: true,
 		thinkingLevelMap: { xhigh: "xhigh", max: "max" },
 		input: ["text", "image"],
@@ -80,8 +80,8 @@ export function modelDisplayName(modelId: string): string {
 }
 
 // Project pi-ai's model entries down to the fields pi's registerProvider expects,
-// keep MODEL_IDS_IN_ORDER ordering, and fill bridge-owned future IDs when pi-ai
-// has not shipped metadata for them yet. Unknown missing IDs are still dropped.
+// keep MODEL_IDS_IN_ORDER ordering, and fill bridge-owned metadata for supported
+// IDs absent from pi-ai. Unknown missing IDs are still dropped.
 export function buildModels<T extends { id: string; [key: string]: any }>(piAiModels: T[]) {
 	return MODEL_IDS_IN_ORDER
 		.map((id) => piAiModels.find((m) => m.id === id) ?? FALLBACK_MODELS[id])