@vanillagreen/pi-claude-bridge 1.9.0 → 2.0.0

package/src/connector-audit.ts

@@ -0,0 +1,203 @@
+// Audit trail for connector calls the `claude` child executes itself.
+//
+// A claude.ai connector tool runs INSIDE the child, on the child's own MCP
+// servers, and is deliberately never mirrored into the Pi stream (see
+// isChildExecutedTool). That is the honest behaviour — mirroring wrote
+// `Tool <name> not found` into the transcript for calls that had SUCCEEDED
+// (drovr#311 / memsira#320) — but it leaves the Pi session with no record that
+// the call happened at all, so "did it really look that up?" could only be
+// answered from the child's own transcript.
+//
+// A pi `CustomEntry` closes that gap without reintroducing the bug: it is
+// persisted in the session file, is NOT a content block, and is documented as
+// "ignored by buildSessionContext", so Pi's agent loop can never dispatch it and
+// `convertPiMessages` (which reads messages, not entries) can never project it
+// back into the child's session. `CustomMessageEntry` is the sibling type that
+// DOES enter context — using it here would recreate the whole problem.
+//
+// The payload is never recorded. A connector result is live account data (mail,
+// messages, documents); the audit answers whether a call happened and what came
+// back, not what it said.
+
+import { extensionApi } from "./bridge-state.js";
+import { debug } from "./debug.js";
+import type { QueryContext, ToolCallDrainCause } from "./query-state.js";
+
+export const CONNECTOR_CALL_CUSTOM_TYPE = "claude-bridge-connector-call";
+
+/**
+ * What the bridge observed of a connector call.
+ *
+ * `unobserved` is the load-bearing one: the call was issued and the query ended
+ * before its result came back. Recording nothing for it would leave an answer in
+ * the transcript with no trace of the call behind it — indistinguishable from a
+ * turn where no call was ever made. Same reasoning as `interruptedToolCallResult`
+ * for Pi-side tools: a call that did not complete says so.
+ */
+export type ConnectorCallOutcome = "ok" | "error" | "unobserved";
+
+export interface ConnectorCallAuditData {
+	/** Raw connector tool name as the child invoked it (`mcp__claude_ai_<Server>__<tool>`). */
+	name: string;
+	/** The child's own `tool_use` id — the join key to its transcript. */
+	toolUseId: string;
+	outcome: ConnectorCallOutcome;
+	/** UTF-8 byte size of the observed result payload. Absent when the result was
+	 *  never observed, or could not be measured — never a confident 0 for
+	 *  something that was not sized. */
+	byteSize?: number;
+	/** Claude Code session that executed the call. Absent when the SDK never
+	 *  reported one for this query. */
+	childSessionId?: string;
+	/** Why an `unobserved` call ended. Absent for observed ones. */
+	reason?: ToolCallDrainCause;
+}
+
+/**
+ * Approximate UTF-8 byte size of a child tool result's payload.
+ *
+ * A string payload is measured directly; any other shape is measured as its JSON
+ * serialization, so a structured or image result reports the size it really
+ * carried. (The debug line this replaces reported `content.length` for an array
+ * payload — a BLOCK count wearing a byte size's name.)
+ *
+ * Returns undefined when there is nothing to measure or the payload cannot be
+ * serialized, so the caller omits the field rather than recording a 0 it did not
+ * measure. The payload itself is never returned or logged.
+ */
+export function connectorResultByteSize(content: unknown): number | undefined {
+	if (content === undefined || content === null) return undefined;
+	if (typeof content === "string") return Buffer.byteLength(content, "utf8");
+	try {
+		const json = JSON.stringify(content);
+		return typeof json === "string" ? Buffer.byteLength(json, "utf8") : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * An ADDITIONAL destination for connector-call records, for a host that embeds
+ * the bridge with no pi session to append to.
+ *
+ * Never throws is the contract on OUR side; a sink that throws anyway is caught
+ * and dropped, because an audit record must not be able to fail a turn.
+ */
+export type ConnectorCallAuditSink = (data: ConnectorCallAuditData) => void;
+
+let auditSink: ConnectorCallAuditSink | undefined;
+
+/**
+ * Install (or clear, with `undefined`) a host sink for connector-call records.
+ *
+ * **The sink ADDS a destination, it never replaces `appendEntry`.** A host that
+ * drives real `AgentSession`s gets the transcript-local entries for free, and a
+ * replacing sink would take those away and reopen the very audit gap this
+ * feature closes (memsira, 2026-07-28 — their `apps/sidecar/src/runtime.ts` is
+ * session-backed, and 122 of their app-chat session files carry the bridge's
+ * `claude-bridge-session` markers). A host with both a session and a sink has
+ * asked for both and gets both.
+ *
+ * It exists because the OTHER embedding shape gets nothing at all: drovr loads
+ * the bundle through a throwaway resource loader over
+ * `createAgentSessionServices` with no session, so `extensionApi` is undefined
+ * and every record it appended went nowhere (drovr #317, measured live). The
+ * sink is the seam such a host can reach without one.
+ *
+ * A callback rather than another `Symbol.for` global on purpose: the bundle
+ * already has one (`claude-bridge:activeStreamSimple`) and hosts document that
+ * coupling as a re-vendor hazard, so a second would be the wrong direction.
+ *
+ * Process-global, matching `setExtensionApi`: one bundle instance serves one
+ * host. A host that runs several conversations in ONE process must therefore
+ * route by `childSessionId` itself, or embed per conversation as drovr does.
+ */
+export function setConnectorCallAuditSink(sink: ConnectorCallAuditSink | undefined): void {
+	auditSink = sink;
+}
+
+/**
+ * Append one audit entry to every destination the host installed. Returns
+ * whether it reached AT LEAST ONE of them, so a caller can log the truth rather
+ * than assume — both are absent whenever the bridge runs outside a pi session
+ * and outside a sink-installing host (tests, the connector-inventory entry
+ * point).
+ *
+ * The two destinations are independent: one throwing must not cost the other
+ * its record. Never throws — an audit record must not be able to fail a turn.
+ */
+export function appendConnectorCallAudit(data: ConnectorCallAuditData): boolean {
+	let delivered = false;
+	if (extensionApi) {
+		try {
+			extensionApi.appendEntry(CONNECTOR_CALL_CUSTOM_TYPE, data);
+			delivered = true;
+		} catch (error) {
+			debug("appendConnectorCallAudit failed:", error);
+		}
+	}
+	if (auditSink) {
+		try {
+			// A COPY, because the sink is host code and `appendEntry` above holds a
+			// reference to the same object: a sink that mutated the record would be
+			// editing what the session already recorded.
+			auditSink({ ...data });
+			delivered = true;
+		} catch (error) {
+			debug("connector call audit sink failed:", error);
+		}
+	}
+	return delivered;
+}
+
+/**
+ * Record the observed result of a child-executed connector call, once.
+ *
+ * Keyed on the tool_use id rather than on the call site: the SDK can re-yield a
+ * `user` message, and an audit trail that counts one call twice is worse than
+ * one that counts it not at all. Returns whether an entry was appended.
+ */
+export function recordConnectorCallResult(
+	queryCtx: QueryContext,
+	toolUseId: string,
+	name: string,
+	isError: boolean,
+	byteSize: number | undefined,
+): boolean {
+	const pending = queryCtx.connectorCallAudit.get(toolUseId);
+	if (pending?.recorded) return false;
+	const childSessionId = pending?.childSessionId ?? queryCtx.childSessionId;
+	queryCtx.connectorCallAudit.set(toolUseId, { ...pending, name, childSessionId, recorded: true });
+	return appendConnectorCallAudit({
+		name,
+		toolUseId,
+		outcome: isError ? "error" : "ok",
+		...(byteSize !== undefined ? { byteSize } : {}),
+		...(childSessionId ? { childSessionId } : {}),
+	});
+}
+
+/**
+ * Record every connector call this query issued whose result never came back,
+ * naming the cause. Runs at query teardown, beside the Pi-side tool drain, and is
+ * idempotent — a call already recorded is skipped, and one recorded here is
+ * marked so a late arrival cannot record it again.
+ *
+ * Returns how many entries were appended.
+ */
+export function flushConnectorCallAudit(queryCtx: QueryContext, reason: ToolCallDrainCause): number {
+	let appended = 0;
+	for (const [toolUseId, state] of queryCtx.connectorCallAudit) {
+		if (state.recorded) continue;
+		queryCtx.connectorCallAudit.set(toolUseId, { ...state, recorded: true });
+		const childSessionId = state.childSessionId ?? queryCtx.childSessionId;
+		if (appendConnectorCallAudit({
+			name: state.name,
+			toolUseId,
+			outcome: "unobserved",
+			reason,
+			...(childSessionId ? { childSessionId } : {}),
+		})) appended++;
+	}
+	return appended;
+}

package/src/connector-cache.ts

@@ -0,0 +1,118 @@
+// Cross-PROCESS cache of the connector inventory (vstack#870).
+//
+// #868 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.
+//
+// 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
+// cache therefore has to survive process boundaries.
+//
+// Keyed by credential scope, because that is what selects the account: the org
+// UUID in the inventory request is ignored and only the credential decides whose
+// connectors come back. Two accounts on one host must not share a cache entry.
+//
+// Everything here is best-effort. A missing, unreadable, corrupt, stale, or
+// 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
+// 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`,
+// payload `{version, scope, savedAt, connectors}`, 7-day max age — as the
+// "is this connector installed" half of its write gate.
+//
+// That coupling fails OPEN on drift by design, so a format change degrades them
+// from two gates to one rather than breaking them. It is still worth making the
+// change knowingly: bump CACHE_VERSION so their staleness check rejects rather
+// than misreads, and say so in the changelog. `unit-connector-cache.mjs` pins
+// the path shape and payload keys.
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { piUserDir } from "./config.js";
+import type { ConnectorEntry } from "./connector-inventory.js";
+
+const CACHE_VERSION = 1;
+/** 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
+ *  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;
+
+export function connectorCacheScopeKey(env: NodeJS.ProcessEnv = process.env): string {
+	return env.CLAUDE_CONFIG_DIR?.trim() || "<default>";
+}
+
+/**
+ * Our own state directory, not the Claude config dir. The credential directory
+ * belongs to the CLI; the scope is encoded in the filename instead so we never
+ * write into someone else's tree. Hashed rather than escaped because a config
+ * dir is an arbitrary absolute path.
+ */
+export function connectorCachePath(scopeKey: string = connectorCacheScopeKey()): string {
+	const digest = createHash("sha256").update(scopeKey).digest("hex").slice(0, 16);
+	return join(piUserDir(), "connector-cache", `${digest}.json`);
+}
+
+/**
+ * Synchronous by design. The query path has no await boundary to hang a read on
+ * — `streamClaudeAgentSdk` returns its stream and claims the SDK query handle in
+ * the same tick — which is the whole reason the in-memory prime loses the race.
+ * A single small `readFileSync` is what makes turn 1 reachable at all.
+ */
+export function readCachedConnectors(
+	scopeKey: string = connectorCacheScopeKey(),
+	now: number = Date.now(),
+): ConnectorEntry[] | undefined {
+	let raw: string;
+	try {
+		raw = readFileSync(connectorCachePath(scopeKey), "utf8");
+	} catch {
+		return undefined;
+	}
+	let parsed: any;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return undefined;
+	}
+	if (parsed?.version !== CACHE_VERSION) return undefined;
+	// Scope is stored as well as hashed into the path: a hash collision or a
+	// hand-copied file would otherwise hand one account another's connectors,
+	// which is the exact failure the token-scoping note in connector-inventory.ts
+	// warns about.
+	if (parsed?.scope !== scopeKey) return undefined;
+	const savedAt = typeof parsed?.savedAt === "number" ? parsed.savedAt : 0;
+	if (!savedAt || now - savedAt > MAX_AGE_MS || savedAt > now) return undefined;
+	if (!Array.isArray(parsed?.connectors)) return undefined;
+	const connectors = parsed.connectors.filter(
+		(entry: any) => entry && typeof entry.name === "string" && entry.name.trim(),
+	);
+	return connectors.length > 0 ? (connectors as ConnectorEntry[]) : undefined;
+}
+
+/** Best-effort write; a failure here must never affect the turn. */
+export function writeCachedConnectors(
+	connectors: ConnectorEntry[],
+	scopeKey: string = connectorCacheScopeKey(),
+	now: number = Date.now(),
+): boolean {
+	if (!Array.isArray(connectors) || connectors.length === 0) return false;
+	const path = connectorCachePath(scopeKey);
+	try {
+		mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+		writeFileSync(
+			path,
+			JSON.stringify({ version: CACHE_VERSION, scope: scopeKey, savedAt: now, connectors }),
+			{ mode: 0o600 },
+		);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/connector-inventory.ts

@@ -33,6 +33,7 @@
 
 const CONNECTOR_NS_PREFIX = "mcp__claude_ai_";
 const DEFAULT_API_BASE = "https://api.anthropic.com";
+const DEFAULT_PROXY_BASE = "https://mcp-proxy.anthropic.com/v1/mcp";
 // OAuth-token requests to the Anthropic API require this beta header; without it
 // endpoints reject the bearer credential.
 const OAUTH_BETA_HEADER = "oauth-2025-04-20";
@@ -43,6 +44,13 @@ export type ConnectorEntry = {
 	installedServerId?: string;
 	/** Catalog identity, shared across accounts that install the same connector. */
 	directoryUuid?: string;
+	/**
+	 * 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.
+	 */
+	installState?: string;
 	description?: string;
 	isAuthless?: boolean;
 };
@@ -77,6 +85,49 @@ export type ClaudeOAuthCredentials = {
 
 type Json = Record<string, any>;
 
+/**
+ * The server name Claude Code itself registers a claude.ai connector under.
+ *
+ * This is the `mcpServers` KEY to use when declaring a connector explicitly, and
+ * it is load-bearing rather than cosmetic: the key IS the tool namespace. Keyed
+ * as anything else, the same connector appears twice — once from our
+ * declaration and once from the CLI's own loader — and consumers that pin
+ * fully-qualified tool names (memsira's executor hard-codes them into
+ * `--allowedTools` and its system prompt, and never globs a namespace) would
+ * be allowed to call neither copy reliably. Verified live: keyed as the CLI's
+ * name there is ONE server entry and one namespace (27 servers); keyed otherwise
+ * both appear (28 servers).
+ *
+ * What merges is the NAMESPACE, not the connection. Under the shared name the
+ * declaration and the CLI's own loader each still connect: across 40 cold runs
+ * the baseline logged 1 Slack connect (7 proxy connects total) and the declared
+ * arm logged 2 Slack connects (8 total), in 20 of 20 runs with no exceptions.
+ * Declaring N connectors therefore costs ~2N connections, not N. They run in
+ * parallel — slowest-connect per run moved from a 1192ms median to 1278ms, worst
+ * 1544ms, well inside the 5s cap — but that was measured with ONE declaration.
+ */
+export function connectorServerName(connectorName: string): string {
+	return `claude.ai ${connectorName.trim()}`;
+}
+
+/**
+ * The claude.ai MCP proxy endpoint for one installed connector.
+ *
+ * The `url` field is REQUIRED by the runtime schema, but the CLI does not
+ * connect to it: for `type: "claudeai-proxy"` it derives the endpoint from `id`.
+ * Caught live — pointing `url` at a local server that never responds still
+ * logged `Using claude.ai proxy at …/mcpsrv_01Wcus…` and connected. So this
+ * builds the honest value for a required field; it is `id` that must be right.
+ *
+ * That also explains why both id forms work: the `mcpsrv_…` id from
+ * `GET /v1/mcp_servers` and the `installedServerId` UUID this module returns
+ * each connected and served identical tools with the CLI's own connector
+ * loading disabled. Both resolve at the proxy; neither depends on `url`.
+ */
+export function connectorProxyUrl(installedServerId: string, proxyBase: string = DEFAULT_PROXY_BASE): string {
+	return `${trimTrailingSlashes(proxyBase)}/${encodeURIComponent(installedServerId)}`;
+}
+
 /**
  * Tool-namespace prefix for a connector, e.g. `Google Calendar` →
  * `mcp__claude_ai_Google_Calendar__`. Connector servers are named after the
@@ -246,6 +297,7 @@ export async function listAccountConnectors(deps: ListConnectorsDeps): Promise<C
 			name,
 			installedServerId: nonEmptyString(entry?.installedServerId),
 			directoryUuid: nonEmptyString(entry?.directoryUuid),
+			installState: nonEmptyString(entry?.installState),
 			description: nonEmptyString(entry?.description),
 			isAuthless: typeof entry?.isAuthless === "boolean" ? entry.isAuthless : undefined,
 		});

package/src/connectors.ts

@@ -1,6 +1,7 @@
 import { type HookCallback, type query } from "@anthropic-ai/claude-agent-sdk";
 import { normalizeConnectorWriteMode, type Config, type ConnectorWriteMode } from "./config.js";
 import { MCP_SERVER_NAME } from "./skills.js";
+import { connectorProxyUrl, connectorServerName, type ConnectorInventory } from "./connector-inventory.js";
 
 // Disable Claude Code built-ins in the provider path. Pi owns tool execution;
 // Claude reaches Pi tools through the bridged MCP server instead.
@@ -158,6 +159,22 @@ function connectorNameWords(segment: string): string[] {
 // Explicit known write tool names (current claude.ai connectors). Passed to the
 // SDK disallowedTools so today's writes are removed from the model's context by
 // 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):
+//
+//   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)
+//
+// Both pin the actions they expose against this classification, because "the
+// sidecar structurally cannot do this itself" is THIS module's claim, not
+// theirs. RECLASSIFYING AN ENTRY HERE AS A READ WOULD MAKE A CONSUMER'S
+// CONFIRMATION CARD BYPASSABLE. Additions are safe and expected; removals and
+// read-verb reclassifications are breaking — coordinate first, see
+// docs/cross-repo.md. `unit-connectors.mjs` pins the set so a change has to be
+// deliberate.
 export const CONNECTOR_WRITE_TOOLS = [
 	`${CONNECTOR_NS_GMAIL}create_draft`,
 	`${CONNECTOR_NS_GMAIL}create_label`,
@@ -198,6 +215,45 @@ export const CONNECTOR_WRITE_TOOLS = [
 	`${CONNECTOR_NS_ATLASSIAN}createCompassCustomFieldDefinition`,
 ];
 
+/**
+ * True for a tool that the `claude` CHILD executes itself, so Pi must never be
+ * asked to dispatch it.
+ *
+ * WHY THIS EXISTS. Every other tool the model calls in a bridge turn is a PI
+ * tool: Pi hands its tool set to the bridge, the bridge re-offers it to the
+ * child through the in-process MCP server, and a `tool_use` coming back is the
+ * child asking PI to run something. The bridge is built around that direction —
+ * it mirrors the call into the Pi stream, ends the Pi turn with `toolUse`, and
+ * the MCP handler blocks until Pi delivers the result.
+ *
+ * claude.ai connectors run the other way. They are the CHILD's own MCP servers,
+ * attached to the authenticated account and reachable only from inside that
+ * process. Pi has never heard of them. Mirroring one into the Pi stream anyway
+ * made Pi's agent loop look the name up in `context.tools`, 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 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.
+ *
+ * The test is the NAMESPACE, deliberately, not "does this name resolve to a Pi
+ * tool". Every claude.ai connector server lives under `mcp__claude_ai_`, and
+ * that is the only tool class the bridge knowingly delegates. A broader
+ * "unresolvable ⇒ delegated" rule would also swallow a genuine tool-name
+ * mismatch between Pi and the child, which SHOULD still surface as a loud
+ * dispatcher error.
+ *
+ * Takes the RAW SDK tool name, before `mapToolName` — connector names have no
+ * Pi-side counterpart, so mapping them is meaningless. Accepts a missing name
+ * rather than asserting one: this decides whether Pi is allowed to dispatch a
+ * block, and a nameless block is not a connector, so it answers `false`.
+ */
+export function isChildExecutedTool(name: string | undefined): boolean {
+	return typeof name === "string" && name.startsWith(CONNECTOR_NS_PREFIX);
+}
+
 // Classify a connector tool name as a WRITE (mutating) tool. FAIL CLOSED, twice:
 //
 //  1. Namespace: the whole `mcp__claude_ai_<Server>__` space counts, not just the
@@ -306,6 +362,12 @@ export function connectorWriteDenyHook(): HookCallback {
 	};
 }
 
+// The deny reason is handed verbatim to the `claude` child's model, so it must
+// 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
+// own prompt; this string only has to say that one exists.
 function connectorWriteDenyOutput(toolName: string) {
 	return {
 		hookSpecificOutput: {
@@ -313,7 +375,7 @@ function connectorWriteDenyOutput(toolName: string) {
 			permissionDecision: "deny" as const,
 			permissionDecisionReason:
 				`Connector write tool "${toolName}" is blocked in read-only connector mode. ` +
-				`Connector writes must go through Memsira's gated approval flow.`,
+				`Connector writes must go through the host application's gated approval flow.`,
 		},
 	};
 }
@@ -357,3 +419,82 @@ export function toolIsolationForQuery(connectorsEnabled: boolean, writeMode: Con
 		allowedTools: [...CLAUDE_BRIDGE_TOOL_ISOLATION.allowedTools, ...CLAUDE_AI_CONNECTOR_TOOL_PATTERNS],
 	};
 }
+
+/**
+ * Explicit `mcpServers` declarations for the account's CONNECTED connectors.
+ *
+ * Why this exists (vstack#832): 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
+ * 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.
+ * The barrier is real but small and sub-linear — manifest build 490ms none /
+ * 1996ms one / 2574ms seven, so seven costs +578ms over one, not 7x. Meanwhile
+ * first token drops from a 9840ms median (worst 35.7s) to 6887ms (worst 7.8s),
+ * because declaring removes the model's speculative ToolSearch and dead ends.
+ * The barrier buys back more than it spends.
+ *
+ * `alwaysLoad` is the mechanism: it blocks startup until the server is connected
+ * (5s cap) precisely "since the tools must be present when the turn-1 prompt is
+ * built". It is a field on the server config, so the connector has to be a server
+ * WE declare — the CLI's own loader never applies it.
+ *
+ * Two things here are load-bearing and were established by measurement, not
+ * inference:
+ *
+ * 1. The key MUST be the CLI's own server name (`connectorServerName`). The key
+ *    is the tool namespace, so any other key yields the connector twice under two
+ *    namespaces. Consumers that pin fully-qualified tool names rather than
+ *    globbing a namespace then break.
+ * 2. Only `installState === "connected"` connectors are declared. The rest are
+ *    never attempted by the CLI either, and declaring them would mean asking
+ *    `alwaysLoad` to block startup on servers that cannot connect.
+ *
+ * Deliberately NOT typed against the SDK's `McpServerConfig`: that exported union
+ * omits the `claudeai-proxy` variant entirely, and its `McpClaudeAIProxyServerConfig`
+ * has no `alwaysLoad` field — while the runtime zod schema in the shipped CLI does.
+ * Typings and runtime disagree; the runtime honours `alwaysLoad` (verified live),
+ * so this builds the object the runtime accepts and casts once, here, with the
+ * reason recorded rather than spread across call sites.
+ */
+export function connectorMcpServers(inventory: ConnectorInventory): Record<string, unknown> {
+	if (!inventory.ok) return {};
+	// Escape hatch. `alwaysLoad` holds startup until each declared server
+	// connects, and the bound on that wait is NOT established: the SDK doc
+	// comment says a 5s cap while the CLI logs `timeout of 30000ms`, and four
+	// attempts to force a genuine mid-handshake hang each failed fast for a
+	// different reason, so the worst case was never observed. An account with
+	// slow or numerous connectors therefore has an unquantified turn-1 delay,
+	// and this switch turns declarations off without giving up connectors.
+	if (connectorDeclarationsDisabled()) return {};
+	const servers: Record<string, unknown> = {};
+	for (const entry of inventory.connectors) {
+		if (entry.installState !== "connected") continue;
+		if (!entry.installedServerId) continue;
+		servers[connectorServerName(entry.name)] = {
+			type: "claudeai-proxy",
+			url: connectorProxyUrl(entry.installedServerId),
+			id: entry.installedServerId,
+			alwaysLoad: true,
+		};
+	}
+	return servers;
+}
+
+
+/**
+ * `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.
+ */
+export function connectorDeclarationsDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
+	const v = (env.CLAUDE_BRIDGE_CONNECTOR_DECLARE ?? "").trim().toLowerCase();
+	return v === "off" || v === "0" || v === "false" || v === "no";
+}

package/src/convert.ts

@@ -4,6 +4,7 @@
 import type { Message as PiMessage } from "@earendil-works/pi-ai";
 import type { ContentBlock, Message as SessionMessage } from "cc-session-io";
 import { pascalCase } from "change-case";
+import { isChildExecutedTool } from "./connectors.js";
 
 export const PROVIDER_ID = "claude-bridge";
 
@@ -21,6 +22,19 @@ export function sanitizeToolId(id: string, cache: Map<string, string>): string {
 
 export function mapPiToolNameToSdk(name: string, customToolNameToSdk?: Map<string, string>): string {
 	if (!name) return "";
+	// A claude.ai connector name is ALREADY the child's own tool id — the child
+	// owns that namespace natively. PascalCasing it invented an alias
+	// (`mcp__claude_ai_Slack__slack_search_channels` →
+	// `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).
+	//
+	// Connector names stopped reaching this function at all once they stopped
+	// being mirrored as Pi tool calls (isChildExecutedTool), so this is the
+	// belt to that braces: LEGACY Pi history recorded before that fix still
+	// carries them, and a rebuild would still project the alias.
+	if (isChildExecutedTool(name)) return name;
 	const normalized = name.toLowerCase();
 	if (customToolNameToSdk) {
 		const mapped = customToolNameToSdk.get(name) ?? customToolNameToSdk.get(normalized);