@vanillagreen/pi-claude-bridge 2.0.0 → 4.0.0

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 (kendex#838).
 //
 // 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
@@ -23,7 +23,7 @@
 // conservatively — it under-reported, which fails safe). They are now separately
 // 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 (kendex#832). 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.
 //
@@ -140,16 +140,23 @@ export function connectorServerNamespace(connectorName: string): string {
 }
 
 // Candidate credential files, in precedence order. CLAUDE_CONFIG_DIR is set
-// per-account by hosts that run one sidecar per Claude account, so it must win
-// over the home-directory default or a multi-account host reads the wrong
-// account's connectors. Both file names are probed under each root because the
-// token and the org UUID do not reliably live in the same file across versions.
+// per-account by hosts that run one sidecar per Claude account, so when it is
+// set that root is probed EXCLUSIVELY: falling through to `~/.claude`/$HOME
+// would silently borrow the DEFAULT account's token for a managed profile
+// whose own `.credentials.json` is missing — a confident, well-formed answer
+// for the wrong account (see the token-scoping note above). Only the
+// no-config-dir default probes the home locations. Both file names are probed
+// under each root because the token and the org UUID do not reliably live in
+// the same file across versions.
 export function credentialCandidatePaths(env: NodeJS.ProcessEnv = process.env): string[] {
 	const roots: string[] = [];
 	const configDir = env.CLAUDE_CONFIG_DIR?.trim();
-	if (configDir) roots.push(configDir);
-	const home = env.HOME?.trim();
-	if (home) roots.push(`${home}/.claude`, home);
+	if (configDir) {
+		roots.push(configDir);
+	} else {
+		const home = env.HOME?.trim();
+		if (home) roots.push(`${home}/.claude`, home);
+	}
 	const seen = new Set<string>();
 	const paths: string[] = [];
 	for (const root of roots) {

package/src/connector-runtime.ts

@@ -0,0 +1,158 @@
+// Connector prime/snapshot host: the per-credential-scope inventory cache the
+// query path reads synchronously (kendex#832/#870). 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
+// inventory is one HTTPS round trip; doing it per TURN would add that latency
+// to every message, and an account's connector set does not change
+// mid-session. Keyed by CLAUDE_CONFIG_DIR because that is what selects the
+// account — the org UUID in the request path is ignored, so two accounts on
+// one host differ only by which credential directory was read.
+//
+// FAILS OPEN. If credentials or the inventory call fail we return no
+// declarations and the turn proceeds exactly as it does today: connectors may
+// race, which is the bug, but a network blip must not break the turn outright.
+
+import { readFileSync as nodeReadFileSync } from "node:fs";
+import { readCachedConnectors, scopeKeyFor, writeCachedConnectors } from "./connector-cache.js";
+import { listAccountConnectors, resolveClaudeOAuth } from "./connector-inventory.js";
+import { connectorMcpServers } from "./connectors.js";
+import { debug } from "./debug.js";
+
+// Read a credential file, treating any read error as "absent" — a missing or
+// unreadable candidate must fall through to the next one, not abort resolution.
+export function readCredentialFile(path: string): string | undefined {
+	try {
+		return nodeReadFileSync(path, "utf8");
+	} catch {
+		return 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
+// 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).
+const CONNECTOR_PRIME_TIMEOUT_MS = 10_000;
+const CONNECTOR_PRIME_FAILURE_COOLDOWN_MS = 60_000;
+
+/** Overrides for tests; production callers use the defaults. */
+export type PrimeConnectorOverrides = {
+	timeoutMs?: number;
+	failureCooldownMs?: number;
+	now?: () => number;
+};
+
+function connectorScopeKey(claudeConfigDir: string | undefined = process.env.CLAUDE_CONFIG_DIR): string {
+	// One rule for every scope key — the on-disk cache and this in-memory cache
+	// must name the same scopes (see scopeKeyFor).
+	return scopeKeyFor(claudeConfigDir);
+}
+
+// Credential resolution env for a selected scope: managed requests always pass
+// their RESOLVED dir (accountSessionScope), so the parent's CLAUDE_CONFIG_DIR
+// never leaks into another profile's lookup; legacy passes undefined and keeps
+// the process-env rule.
+export function connectorCredentialEnv(claudeConfigDir: string | undefined = process.env.CLAUDE_CONFIG_DIR): NodeJS.ProcessEnv {
+	const env = { ...process.env };
+	if (claudeConfigDir?.trim()) env.CLAUDE_CONFIG_DIR = claudeConfigDir.trim();
+	else delete env.CLAUDE_CONFIG_DIR;
+	return env;
+}
+
+// Kick off the inventory fetch for the current credential scope. Fire and
+// forget: the query path can only read a SYNCHRONOUS snapshot, because
+// streamClaudeAgentSdk returns a stream and claims the SDK query handle in the
+// same tick — there is no await boundary to hang a fetch on without
+// restructuring abort handling.
+//
+// Primed at provider registration so the result is in hand well before the
+// first turn (the call measured ~400ms against app startup). If a turn arrives
+// first it declares nothing and behaves exactly as it does today — the race is
+// back for that one turn, which is the bug, but never worse than the status quo.
+//
+// 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
+// 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).
+export function primeConnectorServers(claudeConfigDir?: string, overrides: PrimeConnectorOverrides = {}): void {
+	const key = connectorScopeKey(claudeConfigDir);
+	if (connectorServerCache.has(key) || connectorServerPending.has(key)) return;
+	const now = overrides.now ?? Date.now;
+	const cooldownMs = overrides.failureCooldownMs ?? CONNECTOR_PRIME_FAILURE_COOLDOWN_MS;
+	const failedAt = connectorServerFailureAt.get(key);
+	if (failedAt !== undefined && now() - failedAt < cooldownMs) {
+		debug("connectors: prime cooling down after failure; declaring none until retry window opens");
+		return;
+	}
+	connectorServerPending.add(key);
+	void (async () => {
+		let failed = false;
+		try {
+			const credentials = resolveClaudeOAuth(readCredentialFile, connectorCredentialEnv(claudeConfigDir));
+			if (!credentials) {
+				debug("connectors: no OAuth credentials; declaring none (will retry)");
+				return;
+			}
+			const inventory = await listAccountConnectors({
+				credentials,
+				// A hung inventory request must not outlive the deadline: the abort
+				// surfaces as `ok: false` and takes the cooldown path below.
+				signal: AbortSignal.timeout(overrides.timeoutMs ?? CONNECTOR_PRIME_TIMEOUT_MS),
+			});
+			if (!inventory.ok) {
+				failed = true;
+				debug(`connectors: inventory failed (${inventory.reason}); declaring none (will retry after cooldown)`);
+				return;
+			}
+			const servers = connectorMcpServers(inventory);
+			debug(`connectors: declaring ${Object.keys(servers).length} of ${inventory.connectors.length} installed`,
+				Object.keys(servers).join(", ") || "none");
+			connectorServerCache.set(key, servers);
+			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 (kendex#870).
+			if (writeCachedConnectors(inventory.connectors, key)) {
+				debug(`connectors: cached ${inventory.connectors.length} entries`);
+			}
+		} catch (error) {
+			failed = true;
+			debug("connectors: declaration lookup threw; declaring none (will retry after cooldown)", error);
+		} finally {
+			if (failed) connectorServerFailureAt.set(key, now());
+			connectorServerPending.delete(key);
+		}
+	})();
+}
+
+/** Synchronous snapshot for the query path; `{}` until priming resolves. */
+export function connectorServersSnapshot(claudeConfigDir?: string): Record<string, unknown> {
+	const key = connectorScopeKey(claudeConfigDir);
+	const ready = connectorServerCache.get(key);
+	if (ready) return ready;
+	// Always start (or continue) the live fetch — the cache is a head start, not
+	// a replacement, and the refresh keeps the next process current.
+	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 (kendex#870).
+	const cached = readCachedConnectors(key);
+	if (!cached) return {};
+	const servers = connectorMcpServers({ ok: true, complete: true, connectors: cached });
+	if (Object.keys(servers).length === 0) return {};
+	debug(`connectors: turn-1 declarations from cache — ${Object.keys(servers).join(", ")}`);
+	return servers;
+}

package/src/connectors.ts

@@ -1,6 +1,6 @@
-import { type HookCallback, type query } from "@anthropic-ai/claude-agent-sdk";
+import { type HookCallback, type query, type SettingSource } from "@anthropic-ai/claude-agent-sdk";
 import { normalizeConnectorWriteMode, type Config, type ConnectorWriteMode } from "./config.js";
-import { MCP_SERVER_NAME } from "./skills.js";
+import { MCP_SERVER_NAME, MCP_TOOL_PREFIX } 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;
@@ -35,8 +35,8 @@ export const CLAUDE_BRIDGE_TOOL_ISOLATION = {
 // execution and tokens stay lean. This opt-in flag lets the authenticated
 // Claude account's authorized Google connectors flow through to the model,
 // exposing Gmail/Calendar/Drive tools the account has connected. Gated so the
-// default behavior is unchanged. See
-// docs/plans/claude-bridge-google-connectors.md.
+// default behavior is unchanged. See the Connectors section of this package's
+// README.
 export function connectorsEnabledFromEnv(): boolean {
 	const v = (process.env.CLAUDE_BRIDGE_ENABLE_CONNECTORS ?? "").trim().toLowerCase();
 	return v === "1" || v === "true" || v === "yes" || v === "on";
@@ -50,6 +50,41 @@ export function connectorsEnabledFor(config?: Config): boolean {
 	return connectorsEnabledFromEnv() || config?.provider?.enableConnectors === true;
 }
 
+// Which filesystem setting sources the `claude` child may load.
+//
+// claude.ai cloud MCP connectors only load when Claude Code resolves its
+// filesystem setting sources at all: the SDK treats settingSources=undefined as
+// 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 (kendex#990). 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
+// "project"/"local" would let a repo's checked-in `.claude/settings.json`
+// reintroduce exactly the provider-override env the bridge scrubs from the
+// child (e.g. ANTHROPIC_BASE_URL → traffic redirection) on any bridge query
+// whose cwd is a hostile checkout. User scope is the account owner's own
+// machine config: whoever writes it already owns the child's env.
+//
+// An explicit `provider.settingSources` in bridge config still wins verbatim —
+// that config channel is user-scope/trust-gated (see loadConfig) — but adding
+// "project"/"local" there reopens the repo-controlled settings surface; the
+// README says so.
+export function settingSourcesForQuery(
+	connectorsEnabled: boolean,
+	appendSystemPrompt: boolean,
+	configured?: SettingSource[],
+): SettingSource[] | undefined {
+	if (connectorsEnabled) return configured ?? ["user"];
+	// Non-connectors: appendSystemPrompt=true (default) keeps SDK isolation
+	// (undefined = no filesystem settings; configured sources deliberately do
+	// not apply in isolation mode). If users turn it off they opted into Claude
+	// Code's own settings behavior; project scope there is the historical
+	// contract and runs alongside --strict-mcp-config (see the query builder).
+	return appendSystemPrompt ? undefined : configured ?? ["user", "project"];
+}
+
 // Cloud MCP connector tool namespaces auto-allowed when connectors are enabled.
 // Names match Claude Code's claude.ai connector servers.
 // Whole-server globs (the only glob shape the CLI matcher honors). Deny rules
@@ -63,14 +98,61 @@ export const CLAUDE_AI_CONNECTOR_TOOL_PATTERNS = [
 	"mcp__claude_ai_Atlassian__*",
 ];
 
+// --- The SDK's two-name trap for built-in tools (kendex#1007, kendex#1011) ---
+//
+// The CLI gives some built-ins TWO spellings, and which one you see depends on
+// which SURFACE the name crosses:
+//
+//   REQUEST side — anything passed INTO the SDK query options (`tools`,
+//   `allowedTools`, `disallowedTools`, permission rules). These strings go
+//   through the SDK's rule parser, which normalizes a request-side spelling
+//   (`ListMcpResources`) through its alias map before matching. Constants that
+//   feed only this surface keep the request-side spelling.
+//
+//   DELIVERED side — any name the CLI hands BACK to us at runtime: a PreToolUse
+//   hook's `input.tool_name`, the stream's `content_block_start.name`,
+//   assistant-message tool_use blocks. These carry the CANONICAL (aliased)
+//   name (`ListMcpResourcesTool`), and nothing normalizes them for us — a raw
+//   membership test against a request-side spelling silently never matches.
+//
+// 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 (kendex#1007), and
+// the connectors allowlist hook DENIED the two discovery tools it exists to
+// permit (kendex#1011). 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> = {
+	ListMcpResources: "ListMcpResourcesTool",
+	ReadMcpResource: "ReadMcpResourceTool",
+};
+
+// Every spelling a DELIVERED tool name may carry for a request-side name.
+function deliveredSpellings(name: string): string[] {
+	const canonical = SDK_TOOL_ALIASES[name];
+	return canonical ? [name, canonical] : [name];
+}
+
 // Claude Code registers a Claude account's cloud connectors as DEFERRED tools
 // that the model must load via ToolSearch (and enumerate via the MCP-resource
 // tools). The default bridge isolation disallows all three so Pi owns tool
 // discovery — but that hides the connectors from the model entirely. When
 // connectors are enabled we must let these through so Gmail/Calendar/Drive are
 // discoverable. Verified: disallowing ToolSearch reliably yields NO_CONNECTORS.
+//
+// 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"];
 
+// 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 (kendex#1011).
+const CONNECTOR_DISCOVERY_TOOL_NAMES = new Set(CONNECTOR_DISCOVERY_TOOLS.flatMap(deliveredSpellings));
+
 // --- Connector WRITE tool control (read-inline / write-by-approval) ---
 //
 // Connector tools execute INSIDE claude via the bridge, so Memsira's Pi-level
@@ -161,7 +243,7 @@ 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 (kendex#892):
 //
 //   memsira  routes connector writes through its own gated approval flow
 //   drovr    keeps its chat sidecar permanently write-`deny` and runs an
@@ -215,6 +297,66 @@ export const CONNECTOR_WRITE_TOOLS = [
 	`${CONNECTOR_NS_ATLASSIAN}createCompassCustomFieldDefinition`,
 ];
 
+/**
+ * True for a claude.ai connector tool — the CHILD's own cloud MCP servers,
+ * attached to the authenticated account and reachable only from inside that
+ * process (`mcp__claude_ai_<Server>__<tool>`).
+ *
+ * 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.
+ *
+ * This is the CONNECTOR test: it gates connector-only concerns (the
+ * connector-call audit, write classification). For the broader "the child runs
+ * this itself, never mirror it" question, use `isChildExecutedTool`.
+ */
+export function isConnectorTool(name: string | undefined): boolean {
+	return typeof name === "string" && name.startsWith(CONNECTOR_NS_PREFIX);
+}
+
+// Claude Code built-in meta-tools the child resolves ENTIRELY in-process:
+// deferred-tool discovery and scheduled wakeups. They surface in a bridge
+// stream when connectors are enabled (CONNECTOR_DISCOVERY_TOOLS un-blocks
+// discovery so deferred connector tools are reachable), but they are not
+// connector calls and Pi cannot run them. Matched EXACTLY, never by prefix or
+// substring: a Pi tool that merely resembles one of these names is a Pi tool,
+// and a mismatch on it must still surface as a dispatcher error.
+//
+// Membership is tested against the STREAM-side spelling — the `name` on
+// `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
+// (kendex#1007). If an aliased name is ever added here, derive its spellings
+// via deliveredSpellings rather than hand-copying them.
+//
+// The MCP-resource tools are now EXCLUDED deliberately, 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 kendex#1007. The allowlist hook is what lets those calls run at
+// all — see isAllowlistedConnectorSessionTool (kendex#1011).
+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 (kendex#980) made 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)"
+ * warning and one phantom failed tool call per discovery, plus a spurious
+ * pi-turn boundary. These calls also never enter the connector-call audit:
+ * that trail records account-data access, and tool discovery is not that.
+ */
+export function isChildInternalTool(name: string | undefined): boolean {
+	return typeof name === "string" && CHILD_INTERNAL_TOOLS.has(name);
+}
+
 /**
  * True for a tool that the `claude` CHILD executes itself, so Pi must never be
  * asked to dispatch it.
@@ -226,32 +368,29 @@ export const CONNECTOR_WRITE_TOOLS = [
  * 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.
+ * Two tool classes run the other way, and both must stay un-mirrored:
  *
- * 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.
+ * 1. claude.ai connectors (`isConnectorTool`). Pi has never heard of them.
+ *    Mirroring one 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.
+ *
+ * 2. Claude Code's own in-process meta-tools (`isChildInternalTool`), which the
+ *    child resolves without any dispatcher at all (kendex#980).
  *
- * 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`.
+ * Takes the RAW SDK tool name, before `mapToolName` — child-executed 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 neither a connector nor a child
+ * built-in, so it answers `false`.
  */
 export function isChildExecutedTool(name: string | undefined): boolean {
-	return typeof name === "string" && name.startsWith(CONNECTOR_NS_PREFIX);
+	return isConnectorTool(name) || isChildInternalTool(name);
 }
 
 // Classify a connector tool name as a WRITE (mutating) tool. FAIL CLOSED, twice:
@@ -277,7 +416,7 @@ export function isChildExecutedTool(name: string | undefined): boolean {
 // servers) are never connector writes → false. Used by connectorWriteDenyHook and
 // by callers (e.g. the one-shot write executor) that enumerate live connector tools.
 export function isConnectorWriteTool(name: string): boolean {
-	if (!name.startsWith(CONNECTOR_NS_PREFIX)) return false;
+	if (!isConnectorTool(name)) return false;
 	// First `__` after the prefix ends the server segment. First (not last) so a
 	// server name containing `__` leaves the extra segment in `tool`, which then
 	// fails the read-prefix test — ambiguity resolves to write.
@@ -351,13 +490,15 @@ export function connectorWriteDenyHook(): HookCallback {
 		// whatever gets added here later.
 		try {
 			if (input.hook_event_name !== "PreToolUse") return { continue: true };
+			// A non-string tool name cannot be classified, and this hook fails
+			// CLOSED: deny it rather than let an unclassifiable call proceed.
+			// (Before isConnectorTool tolerated non-strings, `startsWith` threw
+			// here and the catch denied — this keeps that contract explicit.)
+			if (typeof input.tool_name !== "string") return connectorWriteDenyOutput("<unknown>");
 			if (!isConnectorWriteTool(input.tool_name)) return { continue: true };
-			return connectorWriteDenyOutput(String(input.tool_name));
+			return connectorWriteDenyOutput(input.tool_name);
 		} catch {
-			const toolName = typeof (input as { tool_name?: unknown })?.tool_name === "string"
-				? (input as { tool_name: string }).tool_name
-				: "<unknown>";
-			return connectorWriteDenyOutput(toolName);
+			return connectorWriteDenyOutput(safeToolNameFrom(input));
 		}
 	};
 }
@@ -366,7 +507,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 (kendex#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 {
@@ -380,15 +521,114 @@ function connectorWriteDenyOutput(toolName: string) {
 	};
 }
 
-// Connector query-option fragment: tool isolation (allow/deny lists) plus, when
-// connectors are enabled and writes are denied, the runtime PreToolUse write
-// hook. Spread into the SDK query options; continuation queries inherit it via
-// `{ ...queryOptions }`. Exported so the wiring is unit-testable end to end.
+// The names a connectors-mode child session may call at all — the fail-closed
+// complement of DISALLOWED_BUILTIN_TOOLS. That denylist blocks the built-ins we
+// know about TODAY, but a connectors session ingests untrusted third-party
+// content (mail bodies, tickets, documents), and a future CLI built-in absent
+// from the list would be callable by whatever that content talks the model
+// into. Exactly three name classes have any business executing in a connector
+// session: Pi's bridged custom tools, the claude.ai connector namespace (whose
+// writes the write-deny hook still catches), and the discovery built-ins that
+// make deferred connector tools reachable.
+//
+// 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
+// (kendex#1011). That also carries kendex#1007's mirroring decision: 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
+// spellings didn't just remove discovery; it silently emptied that audit
+// trail too.
+export function isAllowlistedConnectorSessionTool(name: string): boolean {
+	return name.startsWith(MCP_TOOL_PREFIX)
+		|| name.startsWith(CONNECTOR_NS_PREFIX)
+		|| CONNECTOR_DISCOVERY_TOOL_NAMES.has(name);
+}
+
+// PreToolUse ALLOWLIST hook for connectors mode. Same fail-closed shape as
+// connectorWriteDenyHook: the CLI treats a hook error/timeout as an empty hook
+// output and lets the call proceed, so every exception in this body must
+// convert to a deny, never an allow.
+export function connectorBuiltinAllowlistHook(): HookCallback {
+	return async (input) => {
+		try {
+			if (input.hook_event_name !== "PreToolUse") return { continue: true };
+			if (typeof input.tool_name !== "string") return allowlistDenyOutput("<unknown>");
+			if (isAllowlistedConnectorSessionTool(input.tool_name)) return { continue: true };
+			return allowlistDenyOutput(input.tool_name);
+		} catch {
+			return allowlistDenyOutput(safeToolNameFrom(input));
+		}
+	};
+}
+
+// Exception-proof tool-name read for hook catch handlers: the input may be
+// hostile enough that even reading `tool_name` throws, and a catch handler
+// that throws makes the CLI treat the hook as empty output — fail OPEN.
+function safeToolNameFrom(input: unknown): string {
+	try {
+		const candidate = (input as { tool_name?: unknown })?.tool_name;
+		return typeof candidate === "string" ? candidate : "<unknown>";
+	} catch {
+		return "<unknown>";
+	}
+}
+
+// Product-neutral for the same reason as connectorWriteDenyOutput: this string
+// is shown verbatim to the child's model in every consuming app.
+function allowlistDenyOutput(toolName: string) {
+	return {
+		hookSpecificOutput: {
+			hookEventName: "PreToolUse" as const,
+			permissionDecision: "deny" as const,
+			permissionDecisionReason:
+				`Tool "${toolName}" is not available in this connector session. ` +
+				`Only bridged custom tools, claude.ai connector tools, and tool discovery are permitted here.`,
+		},
+	};
+}
+
+// PreToolUse hook that denies EVERY tool call. For children that must never
+// execute anything — the account probe runs `/usage` with bypassPermissions,
+// and a slash command needs no tools at all. Same fail-closed try/catch-deny
+// shape as the hooks above.
+export function denyAllToolsHook(): HookCallback {
+	return async (input) => {
+		try {
+			if (input.hook_event_name !== "PreToolUse") return { continue: true };
+			return denyAllOutput(typeof input.tool_name === "string" ? input.tool_name : "<unknown>");
+		} catch {
+			return denyAllOutput("<unknown>");
+		}
+	};
+}
+
+function denyAllOutput(toolName: string) {
+	return {
+		hookSpecificOutput: {
+			hookEventName: "PreToolUse" as const,
+			permissionDecision: "deny" as const,
+			permissionDecisionReason: `Tool "${toolName}" is not available: this session executes no tools.`,
+		},
+	};
+}
+
+// Connector query-option fragment: tool isolation (allow/deny lists) plus the
+// runtime PreToolUse hooks — the fail-closed builtin allowlist always, and the
+// write-deny hook additionally while writes are denied. Spread into the SDK
+// query options; continuation queries inherit it via `{ ...queryOptions }`.
+// Exported so the wiring is unit-testable end to end.
 export function connectorQueryOptions(connectorsEnabled: boolean, writeMode: ConnectorWriteMode = "deny"): Partial<Pick<NonNullable<Parameters<typeof query>[0]["options"]>, "tools" | "allowedTools" | "disallowedTools" | "hooks">> {
 	const isolation = toolIsolationForQuery(connectorsEnabled, writeMode);
-	// Only enforce (and only meaningful) when connectors are on and writes denied.
-	if (!connectorsEnabled || writeMode === "allow") return isolation;
-	return { ...isolation, hooks: { PreToolUse: [{ hooks: [connectorWriteDenyHook()] }] } };
+	if (!connectorsEnabled) return isolation;
+	// The allowlist applies in BOTH write modes — the one-shot write executor is
+	// still a connectors session ingesting third-party content. Deny rules from
+	// either hook win over any allow.
+	const hooks = writeMode === "allow"
+		? [connectorBuiltinAllowlistHook()]
+		: [connectorBuiltinAllowlistHook(), connectorWriteDenyHook()];
+	return { ...isolation, hooks: { PreToolUse: [{ hooks }] } };
 }
 
 // Tool isolation for a query. When connectors are enabled we still remove
@@ -405,7 +645,13 @@ export function toolIsolationForQuery(connectorsEnabled: boolean, writeMode: Con
 	if (!connectorsEnabled) return CLAUDE_BRIDGE_TOOL_ISOLATION;
 	// Keep ToolSearch + MCP-resource tools available so the model can discover the
 	// deferred cloud connector tools; still block file/shell/web built-ins.
-	const disallowedTools = DISALLOWED_BUILTIN_TOOLS.filter((t) => !CONNECTOR_DISCOVERY_TOOLS.includes(t));
+	//
+	// REQUEST-side surface: the surviving list goes into the SDK options, where
+	// the rule parser alias-normalizes it, so DISALLOWED_BUILTIN_TOOLS correctly
+	// holds request-side spellings and this filter's OUTPUT stays request-side.
+	// Filtering through the both-spellings set only makes the un-block
+	// spelling-proof should a canonical name ever land in the denylist.
+	const disallowedTools = DISALLOWED_BUILTIN_TOOLS.filter((t) => !CONNECTOR_DISCOVERY_TOOL_NAMES.has(t));
 	// Deny connector WRITE tools unless writes are explicitly allowed (fail
 	// closed: any mode but exact "allow" is treated as read-only). This removes
 	// today's KNOWN writes from the model's context by exact id; deny rules take
@@ -423,7 +669,7 @@ 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 (kendex#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,