@vanillagreen/pi-claude-bridge 1.6.2 → 1.9.0

package/src/connector-inventory.ts

@@ -0,0 +1,281 @@
+// Deterministic enumeration of a Claude account's installed claude.ai connectors.
+//
+// The capability probe this replaces asked the MODEL to enumerate connectors via
+// ToolSearch. A search returns what the search surfaced, which is a LOWER BOUND —
+// 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).
+//
+// 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
+// result carries BOTH `directoryUuid` (the catalog identity) and
+// `installedServerId` (this account's installed instance). A marketplace catalog
+// entry has no installed-server id, which is what establishes this as the
+// INSTALLED set rather than the registry listing.
+//
+// INSTALLED IS NOT ATTACHED. This endpoint reports what the ACCOUNT has
+// 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
+// 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
+// availability and keep an attach-time check on the call path; do not derive
+// "can I call this tool right now" from this result.
+//
+// Because the answer comes from the account rather than a model turn, the result
+// is complete by construction — hence `complete: true` on success, and no
+// "partial" state. A failure is a failure, never an empty-but-successful list.
+
+const CONNECTOR_NS_PREFIX = "mcp__claude_ai_";
+const DEFAULT_API_BASE = "https://api.anthropic.com";
+// 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";
+
+export type ConnectorEntry = {
+	name: string;
+	/** This account's installed instance. Present on every live result observed. */
+	installedServerId?: string;
+	/** Catalog identity, shared across accounts that install the same connector. */
+	directoryUuid?: string;
+	description?: string;
+	isAuthless?: boolean;
+};
+
+// Discriminated so a caller cannot read `connectors` without having checked `ok`.
+// `complete` is carried explicitly rather than implied: the whole defect this
+// fixes was a result that looked authoritative while being a lower bound.
+// The absent side of each variant is declared as `?: undefined` rather than
+// omitted: this package compiles with `strict: false`, where narrowing a union
+// by a boolean discriminant does not reliably filter members, so a bare
+// `{ok:true}|{ok:false}` pair makes `inventory.reason` a compile error at every
+// call site. Spelling both sides keeps the union discriminated AND readable
+// without depending on strictNullChecks-era narrowing.
+export type ConnectorInventory =
+	| { ok: true; complete: true; connectors: ConnectorEntry[]; reason?: undefined }
+	| { ok: false; complete: false; connectors?: undefined; reason: string };
+
+// SCOPING IS BY TOKEN, NOT BY ORG. Verified live: the org UUID in the path is
+// ignored — an all-zero UUID and the literal string "not-a-uuid" both returned
+// the bearer token's own account, identically to the real org. A multi-account
+// host therefore CANNOT select an account by passing its organizationUuid; the
+// only thing that selects an account is which credential the token came from
+// (i.e. which CLAUDE_CONFIG_DIR was read). Getting that wrong yields a
+// confident, well-formed answer for the WRONG account.
+//
+// The real UUID is still sent rather than a placeholder, so the call keeps
+// working if the API starts enforcing it.
+export type ClaudeOAuthCredentials = {
+	accessToken: string;
+	organizationUuid: string;
+};
+
+type Json = Record<string, any>;
+
+/**
+ * Tool-namespace prefix for a connector, e.g. `Google Calendar` →
+ * `mcp__claude_ai_Google_Calendar__`. Connector servers are named after the
+ * connector with whitespace replaced by underscores; corroborated against the
+ * independently-authored CLAUDE_AI_CONNECTOR_TOOL_PATTERNS in connectors.ts,
+ * which was built from a live tool enumeration rather than from this rule.
+ */
+export function connectorServerNamespace(connectorName: string): string {
+	return `${CONNECTOR_NS_PREFIX}${connectorName.trim().replace(/\s+/g, "_")}__`;
+}
+
+// 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.
+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);
+	const seen = new Set<string>();
+	const paths: string[] = [];
+	for (const root of roots) {
+		for (const name of [".credentials.json", ".claude.json"]) {
+			const p = `${root}/${name}`;
+			if (!seen.has(p)) { seen.add(p); paths.push(p); }
+		}
+	}
+	return paths;
+}
+
+/**
+ * Pull the OAuth access token and organization UUID out of the Claude config.
+ * They are scanned independently across all candidate files because they are not
+ * guaranteed to co-locate: on the machine this was verified against, the token
+ * lives in `.credentials.json` and the org UUID in `.claude.json`.
+ *
+ * `readFile` returns undefined for a missing/unreadable path. Parse failures are
+ * skipped rather than thrown — a corrupt file must not mask a good one later in
+ * the list.
+ */
+export function resolveClaudeOAuth(
+	readFile: (path: string) => string | undefined,
+	env: NodeJS.ProcessEnv = process.env,
+): ClaudeOAuthCredentials | undefined {
+	let accessToken: string | undefined;
+	let organizationUuid: string | undefined;
+
+	for (const path of credentialCandidatePaths(env)) {
+		const raw = readFile(path);
+		if (!raw) continue;
+		let parsed: Json;
+		try {
+			parsed = JSON.parse(raw) as Json;
+		} catch {
+			continue;
+		}
+		accessToken ??= nonEmptyString(parsed?.claudeAiOauth?.accessToken);
+		organizationUuid ??= nonEmptyString(parsed?.oauthAccount?.organizationUuid);
+		if (accessToken && organizationUuid) break;
+	}
+
+	if (!accessToken || !organizationUuid) return undefined;
+	return { accessToken, organizationUuid };
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+export function connectorsListUrl(organizationUuid: string, apiBase: string = DEFAULT_API_BASE): string {
+	return `${trimTrailingSlashes(apiBase)}/api/oauth/organizations/${encodeURIComponent(organizationUuid)}/mcp/connectors/list`;
+}
+
+// Linear-time trailing-slash trim. This was `apiBase.replace(/\/+$/, "")`, which
+// CodeQL correctly flags as a polynomial regex on uncontrolled input: `apiBase`
+// is a caller-supplied parameter, and an anchored `+` backtracks on a long run
+// of slashes. It only became reachable as library input once this module gained
+// a real export surface, which is exactly the exposure the export was for.
+function trimTrailingSlashes(value: string): string {
+	let end = value.length;
+	while (end > 0 && value.charCodeAt(end - 1) === 47 /* "/" */) end--;
+	return value.slice(0, end);
+}
+
+export type ListConnectorsDeps = {
+	credentials: ClaudeOAuthCredentials;
+	fetchImpl?: typeof fetch;
+	apiBase?: string;
+	signal?: AbortSignal;
+};
+
+/**
+ * Enumerate the account's installed connectors. Never throws: transport and
+ * protocol failures come back as `{ ok: false }` with a reason, so a caller can
+ * distinguish "this account has no connectors" (ok, empty list) from "we could
+ * not find out" — the distinction the search-driven probe could not express.
+ *
+ * The reason string is built only from the HTTP status and the API's own error
+ * message; the bearer token is never interpolated into it or logged.
+ */
+export async function listAccountConnectors(deps: ListConnectorsDeps): Promise<ConnectorInventory> {
+	const { credentials, apiBase, signal } = deps;
+	const fetchImpl = deps.fetchImpl ?? fetch;
+	const url = connectorsListUrl(credentials.organizationUuid, apiBase);
+	// Every failure return goes through this. Transport errors are the risk: a
+	// fetch/proxy layer is free to put the request headers — and therefore the
+	// bearer token — into the message it throws, and that message would otherwise
+	// land in a reason string that callers log.
+	const fail = (reason: string): ConnectorInventory =>
+		({ ok: false, complete: false, reason: redactSecret(reason, credentials.accessToken) });
+
+	let response: Response;
+	try {
+		response = await fetchImpl(url, {
+			method: "POST",
+			headers: {
+				"Authorization": `Bearer ${credentials.accessToken}`,
+				"anthropic-beta": OAUTH_BETA_HEADER,
+				"Content-Type": "application/json",
+			},
+			body: "{}",
+			signal,
+		});
+	} catch (error) {
+		return fail(`connector list request failed: ${errorText(error)}`);
+	}
+
+	let bodyText: string;
+	try {
+		bodyText = await response.text();
+	} catch (error) {
+		return fail(`connector list response unreadable: ${errorText(error)}`);
+	}
+
+	if (!response.ok) {
+		return fail(`connector list returned HTTP ${response.status}${apiErrorSuffix(bodyText)}`);
+	}
+
+	let parsed: Json;
+	try {
+		parsed = JSON.parse(bodyText) as Json;
+	} catch {
+		return fail("connector list returned a non-JSON body");
+	}
+
+	// A missing/!Array `results` is a protocol change, not an empty account. Treat
+	// it as failure — reporting "no connectors" here would recreate exactly the
+	// silent-wrong-answer failure this module exists to remove.
+	if (!Array.isArray(parsed?.results)) {
+		return fail("connector list response had no results array");
+	}
+
+	const connectors: ConnectorEntry[] = [];
+	for (const raw of parsed.results as unknown[]) {
+		const entry = raw as Json;
+		const name = nonEmptyString(entry?.name);
+		// An unnamed entry cannot be matched to a tool namespace by any consumer,
+		// so silently keeping it would understate the inventory in a way the
+		// caller could not detect. Fail instead.
+		if (!name) {
+			return fail("connector list contained an entry with no name");
+		}
+		connectors.push({
+			name,
+			installedServerId: nonEmptyString(entry?.installedServerId),
+			directoryUuid: nonEmptyString(entry?.directoryUuid),
+			description: nonEmptyString(entry?.description),
+			isAuthless: typeof entry?.isAuthless === "boolean" ? entry.isAuthless : undefined,
+		});
+	}
+
+	return { ok: true, complete: true, connectors };
+}
+
+function apiErrorSuffix(bodyText: string): string {
+	try {
+		const message = (JSON.parse(bodyText) as Json)?.error?.message;
+		return typeof message === "string" && message.trim() ? ` (${message.trim()})` : "";
+	} catch {
+		return "";
+	}
+}
+
+// Replace the bearer token wherever it appears in text headed for a caller.
+// Also covers a URL-encoded rendering, since some transports encode headers into
+// an error's message. Short/empty tokens are not substituted — an over-eager
+// match would corrupt unrelated text.
+function redactSecret(text: string, secret: string): string {
+	if (!secret || secret.length < 8) return text;
+	let out = text;
+	for (const form of new Set([secret, encodeURIComponent(secret)])) {
+		out = out.split(form).join("[redacted]");
+	}
+	return out;
+}
+
+function errorText(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/connectors.ts

@@ -0,0 +1,359 @@
+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";
+
+// Disable Claude Code built-ins in the provider path. Pi owns tool execution;
+// Claude reaches Pi tools through the bridged MCP server instead.
+//
+// `allowedTools` is a permission auto-allow list in the Claude Agent SDK, not a
+// visibility allowlist. Use `tools: []` to remove the built-in tool set, and keep
+// this disallow list as a belt-and-suspenders guard for SDK/CLI built-ins that may
+// otherwise leak into the model context (e.g. TodoWrite, CronList, SendMessage).
+export const DISALLOWED_BUILTIN_TOOLS = [
+	"Read", "Write", "Edit", "MultiEdit", "Glob", "Grep", "Bash", "Agent", "Task",
+	"NotebookEdit", "EnterWorktree", "ExitWorktree",
+	"CronList", "CronCreate", "CronDelete", "TeamCreate", "TeamDelete",
+	"TaskOutput", "TaskStop", "SendMessage", "Skill",
+	"TodoRead", "TodoWrite",
+	"ListMcpResources", "ReadMcpResource",
+	"WebFetch", "WebSearch",
+	"AskUserQuestion", "EnterPlanMode", "ExitPlanMode",
+	"ToolSearch", "ScheduleWakeup",
+];
+
+export const CLAUDE_BRIDGE_TOOL_ISOLATION = {
+	tools: [] as string[],
+	disallowedTools: DISALLOWED_BUILTIN_TOOLS,
+	allowedTools: [`mcp__${MCP_SERVER_NAME}__*`],
+} satisfies Pick<NonNullable<Parameters<typeof query>[0]["options"]>, "tools" | "allowedTools" | "disallowedTools">;
+
+// --- Claude account cloud MCP connectors (Gmail / Calendar / Drive) ---
+//
+// By default the bridge suppresses claude.ai cloud MCP servers (see the
+// ENABLE_CLAUDEAI_MCP_SERVERS="0" note near the query builder) so Pi owns tool
+// 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.
+export function connectorsEnabledFromEnv(): boolean {
+	const v = (process.env.CLAUDE_BRIDGE_ENABLE_CONNECTORS ?? "").trim().toLowerCase();
+	return v === "1" || v === "true" || v === "yes" || v === "on";
+}
+
+// Connectors are enabled if EITHER the env var is truthy OR the resolved bridge
+// config sets `provider.enableConnectors`. Env is the simplest per-process knob
+// (one sidecar per Claude account sets it in its child env); config lets a host
+// app enable it declaratively via its written settings.json.
+export function connectorsEnabledFor(config?: Config): boolean {
+	return connectorsEnabledFromEnv() || config?.provider?.enableConnectors === true;
+}
+
+// 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
+// take precedence, so listing a server here never exposes its writes — the
+// write ids above and the PreToolUse hook still remove them.
+export const CLAUDE_AI_CONNECTOR_TOOL_PATTERNS = [
+	"mcp__claude_ai_Gmail__*",
+	"mcp__claude_ai_Google_Calendar__*",
+	"mcp__claude_ai_Google_Drive__*",
+	"mcp__claude_ai_Slack__*",
+	"mcp__claude_ai_Atlassian__*",
+];
+
+// 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.
+export const CONNECTOR_DISCOVERY_TOOLS = ["ToolSearch", "ListMcpResources", "ReadMcpResource"];
+
+// --- Connector WRITE tool control (read-inline / write-by-approval) ---
+//
+// Connector tools execute INSIDE claude via the bridge, so Memsira's Pi-level
+// ConsentGate never sees them. To keep every connector WRITE explicit + gated,
+// connector chat sessions run read-only (writes denied); the model performs a
+// write only through a gated Pi custom-tool whose app-side dispatcher runs a
+// ONE-SHOT write-enabled bridge query. This block is the bridge lever for that:
+// deny connector write tools by default, allow them only for that executor.
+//
+// Cloud connector server namespaces (the `mcp__<server>__` prefix). Every
+// claude.ai connector server lives under CONNECTOR_NS_PREFIX, so that prefix —
+// not the named trio — is what marks a tool as connector-owned.
+const CONNECTOR_NS_PREFIX = "mcp__claude_ai_";
+const CONNECTOR_NS_GMAIL = `${CONNECTOR_NS_PREFIX}Gmail__`;
+const CONNECTOR_NS_CALENDAR = `${CONNECTOR_NS_PREFIX}Google_Calendar__`;
+const CONNECTOR_NS_DRIVE = `${CONNECTOR_NS_PREFIX}Google_Drive__`;
+const CONNECTOR_NS_SLACK = `${CONNECTOR_NS_PREFIX}Slack__`;
+const CONNECTOR_NS_ATLASSIAN = `${CONNECTOR_NS_PREFIX}Atlassian__`;
+
+// Read verbs: a connector tool whose tool segment BEGINS with one of these
+// words is a non-mutating READ and stays available. Everything else on a
+// connector namespace is treated as a WRITE. Matching is on WORDS, not on a
+// literal `verb_` prefix, because connector servers do not share a naming
+// convention — verified live against a Claude account with Slack + Atlassian
+// attached:
+//
+//   Gmail      search_threads, get_message          (snake_case)
+//   Slack      slack_read_channel, slack_search_public
+//                                                   (snake_case, server-prefixed)
+//   Atlassian  getJiraIssue, searchJiraIssuesUsingJql, getConfluencePage
+//                                                   (camelCase)
+//
+// A literal-prefix test only matched the Gmail shape, so EVERY Slack and
+// Atlassian tool — reads included — classified as a write and was denied at
+// runtime, making those connectors unusable in a read-only session.
+const CONNECTOR_READ_VERBS = new Set([
+	"list", "search", "get", "read", "fetch", "find",
+	"download", "describe", "query", "count", "view", "lookup", "whoami",
+]);
+
+// Mutating words. Two jobs, both on the deny side:
+//
+//  1. A name that begins with a read verb but also names a mutation
+//     (`fetchAndLock`, `get_incident_and_acknowledge`) is a WRITE — deny wins
+//     over the read exemption, so a compound name cannot earn read treatment.
+//  2. A leading word that repeats the server name is NOT skipped when it is a
+//     mutation word, so a connector whose SERVER is verb-shaped
+//     (`Delete__delete_get_thing`) keeps its real verb.
+//
+// This list is deliberately broad and errs toward over-denial: a read wrongly
+// called a write only blocks a read, whereas the reverse runs an ungated
+// mutation. It is a backstop, not the primary protection — that is the leading
+// verb, which real connector tools put first (`createJiraIssue`,
+// `slack_send_message`, `delete_file`). Nouns that collide with real read names
+// are deliberately excluded (`comment`/`tag`/`flag`/`run`, since
+// `getComment`, `searchByTag`, `getFeatureFlag`, `getWorkflowRun` are reads).
+const CONNECTOR_MUTATION_WORDS = new Set([
+	"create", "update", "delete", "remove", "add", "edit", "send", "post",
+	"write", "upload", "publish", "schedule", "transition", "archive", "move",
+	"copy", "revoke", "assign", "invite", "share", "rename", "replace", "set",
+	"merge", "resolve", "lock", "unlock", "acknowledge", "ack", "book",
+	"start", "stop", "terminate", "restart", "join", "leave", "star", "unstar",
+	"forward", "sync", "approve", "reject", "close", "reopen", "cancel",
+	"enable", "disable", "grant", "trigger", "execute", "apply", "submit",
+	"pin", "unpin", "mute", "unmute", "subscribe", "unsubscribe", "follow",
+	"unfollow", "clear", "purge", "reset", "rotate", "deploy", "install",
+	"uninstall", "save", "store", "put", "patch", "insert", "append",
+	"prepend", "duplicate", "restore", "revert", "import", "export", "upsert",
+	"sign", "complete", "claim", "release", "promote", "demote", "escalate",
+	"resend", "retry", "react", "vote",
+]);
+
+// Splits a tool (or server) segment into lowercase words, handling snake_case,
+// camelCase, PascalCase, and acronym runs (`getHTTPResponse` → get, http,
+// response). Punctuation-only input yields an empty list, which callers treat
+// as unparseable → write.
+function connectorNameWords(segment: string): string[] {
+	return segment
+		.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+		.replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+		.split(/[^A-Za-z0-9]+/)
+		.filter(Boolean)
+		.map((word) => word.toLowerCase());
+}
+
+// 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).
+export const CONNECTOR_WRITE_TOOLS = [
+	`${CONNECTOR_NS_GMAIL}create_draft`,
+	`${CONNECTOR_NS_GMAIL}create_label`,
+	`${CONNECTOR_NS_GMAIL}label_message`,
+	`${CONNECTOR_NS_GMAIL}label_thread`,
+	`${CONNECTOR_NS_GMAIL}unlabel_message`,
+	`${CONNECTOR_NS_GMAIL}unlabel_thread`,
+	`${CONNECTOR_NS_GMAIL}apply_sensitive_label`,
+	`${CONNECTOR_NS_GMAIL}remove_sensitive_label`,
+	`${CONNECTOR_NS_CALENDAR}create_event`,
+	`${CONNECTOR_NS_CALENDAR}update_event`,
+	`${CONNECTOR_NS_CALENDAR}delete_event`,
+	`${CONNECTOR_NS_CALENDAR}respond_to_event`,
+	`${CONNECTOR_NS_DRIVE}create_file`,
+	`${CONNECTOR_NS_DRIVE}copy_file`,
+	// Slack + Atlassian writes, taken from a live enumeration of an account with
+	// both connectors attached. The PreToolUse hook already denies these by verb;
+	// listing them by id also removes them from the model's context in a
+	// read-only session (the CLI matcher needs exact ids). Additive only — an id
+	// missing here is still denied at call time.
+	`${CONNECTOR_NS_SLACK}slack_send_message`,
+	`${CONNECTOR_NS_SLACK}slack_send_message_draft`,
+	`${CONNECTOR_NS_SLACK}slack_schedule_message`,
+	`${CONNECTOR_NS_SLACK}slack_create_canvas`,
+	`${CONNECTOR_NS_SLACK}slack_update_canvas`,
+	`${CONNECTOR_NS_ATLASSIAN}createJiraIssue`,
+	`${CONNECTOR_NS_ATLASSIAN}editJiraIssue`,
+	`${CONNECTOR_NS_ATLASSIAN}transitionJiraIssue`,
+	`${CONNECTOR_NS_ATLASSIAN}addCommentToJiraIssue`,
+	`${CONNECTOR_NS_ATLASSIAN}addWorklogToJiraIssue`,
+	`${CONNECTOR_NS_ATLASSIAN}createIssueLink`,
+	`${CONNECTOR_NS_ATLASSIAN}createConfluencePage`,
+	`${CONNECTOR_NS_ATLASSIAN}updateConfluencePage`,
+	`${CONNECTOR_NS_ATLASSIAN}createConfluenceFooterComment`,
+	`${CONNECTOR_NS_ATLASSIAN}createConfluenceInlineComment`,
+	`${CONNECTOR_NS_ATLASSIAN}createCompassComponent`,
+	`${CONNECTOR_NS_ATLASSIAN}createCompassComponentRelationship`,
+	`${CONNECTOR_NS_ATLASSIAN}createCompassCustomFieldDefinition`,
+];
+
+// 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
+//     known Gmail/Calendar/Drive trio. Connectors attach account-wide, so ANY
+//     other connector on the account (Slack, Atlassian, Figma, org-custom) shows
+//     up in a bridge session — and the connector path deliberately omits
+//     `tools: []` (see toolIsolationForQuery), so those tools are discoverable
+//     and callable. Keying on the trio meant e.g. a Slack send_message ran
+//     ungated inside claude, invisible to Pi's ConsentGate.
+//  2. Verb: a tool on that space is a write UNLESS its tool segment BEGINS with a
+//     known read verb, so not-yet-known write tools (e.g. Gmail send_message,
+//     Drive delete_file, Calendar add_attendee) are blocked in a read-only
+//     session. A name under the connector prefix with no parseable `__<tool>`
+//     segment is also a write: it is a connector by construction, so deny wins.
+//     The verb is matched as a WORD across snake_case and camelCase, and a
+//     leading word that merely repeats the server name is skipped first
+//     (`Slack__slack_read_channel` reads as `read channel`), because connector
+//     servers name their tools differently from one another.
+//
+// Non-connector tools (Pi custom-tools, ToolSearch, MCP-resource tools, other MCP
+// 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;
+	// 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.
+	const sep = name.indexOf("__", CONNECTOR_NS_PREFIX.length);
+	// No separator (sep < 0) OR an EMPTY server segment (sep at the prefix, e.g.
+	// `mcp__claude_ai___search_messages`) means the name doesn't parse as
+	// <server>__<tool> — it never earns the read-prefix exemption.
+	if (sep <= CONNECTOR_NS_PREFIX.length) return true;
+	const server = name.slice(CONNECTOR_NS_PREFIX.length, sep);
+	const words = connectorNameWords(name.slice(sep + "__".length));
+	// Skip a leading run of words that just repeats the server name, so a
+	// server-prefixed tool (`Slack__slack_read_channel`) is judged on its real
+	// verb. Only an exact leading match is skipped — an unrelated first word
+	// (`Weird__Server__list_things`) stays and fails the read test. A mutation
+	// word is never skipped, so a verb-shaped server name
+	// (`Delete__delete_get_thing`, `Sync__sync_get_status`) cannot launder its
+	// own tool's verb away.
+	const serverWords = connectorNameWords(server);
+	let skipped = 0;
+	while (
+		skipped < serverWords.length
+		&& words[skipped] === serverWords[skipped]
+		&& !CONNECTOR_MUTATION_WORDS.has(words[skipped])
+	) skipped++;
+	const rest = words.slice(skipped);
+	// Nothing parseable left (empty/punctuation-only tool segment, or a tool
+	// named exactly after its server) → write.
+	if (rest.length === 0) return true;
+	if (!CONNECTOR_READ_VERBS.has(rest[0])) return true;
+	// Begins as a read but also names a mutation → deny wins.
+	return rest.some((word) => CONNECTOR_MUTATION_WORDS.has(word));
+}
+
+// Connector write mode from the env override. `allow` exposes connector write
+// tools; `deny` hides them. Returns undefined when unset so config can decide.
+export function connectorWriteModeFromEnv(): ConnectorWriteMode | undefined {
+	const v = (process.env.CLAUDE_BRIDGE_CONNECTOR_WRITE ?? "").trim().toLowerCase();
+	if (v === "allow") return "allow";
+	if (v === "deny") return "deny";
+	return undefined;
+}
+
+// Resolve the connector write mode: env wins over config, default `deny`
+// (mirrors connectorsEnabledFor's env-first precedence). Only meaningful when
+// connectors are enabled; connector chat sessions keep the default deny and the
+// one-shot approved-write executor sets allow (env or config).
+//
+// FAIL CLOSED: writes are enabled ONLY by an explicit, validated `allow`. The
+// config value is re-normalized here (defense in depth over normalizeProviderConfig)
+// so a raw legacy-config value like "Deny"/"read-only"/true can never be treated
+// as a truthy non-deny and silently open writes — anything but exact allow → deny.
+export function connectorWriteModeFor(config?: Config): ConnectorWriteMode {
+	const resolved = connectorWriteModeFromEnv() ?? normalizeConnectorWriteMode(config?.provider?.connectorWriteMode);
+	return resolved === "allow" ? "allow" : "deny";
+}
+
+// PreToolUse hook that hard-blocks connector WRITE tools at call time. Hooks run
+// regardless of permissionMode (we use bypassPermissions), so this — not the
+// static deny lists — is the real prefix-based runtime enforcement of
+// isConnectorWriteTool. disallowedTools removes today's KNOWN writes from model
+// context, but it lists exact ids on the known trio only, so a future write tool
+// (e.g. mcp__claude_ai_Gmail__send_message, ..._Drive__delete_file) or any tool
+// on another connector the account has attached (mcp__claude_ai_Slack__send_message)
+// would otherwise be callable in a read-only session; this hook denies it by prefix.
+export function connectorWriteDenyHook(): HookCallback {
+	return async (input) => {
+		// The CLI treats a hook error/timeout as an EMPTY hook output and lets
+		// 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.
+		try {
+			if (input.hook_event_name !== "PreToolUse") return { continue: true };
+			if (!isConnectorWriteTool(input.tool_name)) return { continue: true };
+			return connectorWriteDenyOutput(String(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);
+		}
+	};
+}
+
+function connectorWriteDenyOutput(toolName: string) {
+	return {
+		hookSpecificOutput: {
+			hookEventName: "PreToolUse" as const,
+			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 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.
+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()] }] } };
+}
+
+// Tool isolation for a query. When connectors are enabled we still remove
+// Claude Code's filesystem/shell built-ins (via disallowedTools; Pi owns those)
+// and auto-allow the cloud connector tool namespaces so the model can call
+// Gmail/Calendar/Drive.
+//
+// Critically, we must OMIT `tools: []` in the connector path: an empty --tools
+// allowlist strips the claude.ai cloud MCP connector tools from the model's
+// view (verified — Pi's SDK-injected custom-tools survive it, but connectors do
+// not). Dropping `tools` leaves the connectors visible; disallowedTools still
+// hard-denies the built-ins so Pi keeps ownership of file/shell/web tools.
+export function toolIsolationForQuery(connectorsEnabled: boolean, writeMode: ConnectorWriteMode = "deny"): Partial<Pick<NonNullable<Parameters<typeof query>[0]["options"]>, "tools" | "allowedTools" | "disallowedTools">> {
+	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));
+	// 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
+	// precedence over the CLAUDE_AI_CONNECTOR_TOOL_PATTERNS allow rules below, so
+	// reads stay available. Runtime enforcement covering future write tools and
+	// connector namespaces we don't enumerate here (Slack, Atlassian, org-custom)
+	// is done by connectorWriteDenyHook — see connectorQueryOptions.
+	if (writeMode !== "allow") disallowedTools.push(...CONNECTOR_WRITE_TOOLS);
+	return {
+		disallowedTools,
+		allowedTools: [...CLAUDE_BRIDGE_TOOL_ISOLATION.allowedTools, ...CLAUDE_AI_CONNECTOR_TOOL_PATTERNS],
+	};
+}