@schuettc/pi-claude-bridge 0.7.0-schuettc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eli Dickinson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# pi-claude-bridge
+
+[![npm version](https://img.shields.io/npm/v/pi-claude-bridge)](https://www.npmjs.com/package/pi-claude-bridge)
+
+Pi extension that integrates Claude Code via the [Agent SDK](https://github.com/anthropics/claude-agent-sdk-typescript). Based initially on [claude-agent-sdk-pi](https://github.com/prateekmedia/claude-agent-sdk-pi) by Prateek Sunal. This fork adds streaming, MCP tool bridging, custom pi tool bridging, session resume/persistence, context sync, thinking support, skills forwarding, and many correctness fixes.
+
+1. **Provider** — Use Opus/Sonnet/Haiku as models in pi, with all tool calls flowing through pi's TUI
+2. **AskClaude tool** — Delegate tasks or questions to Claude Code when using another provider
+
+
+**FYI:** Anthropic [announced and then unannounced](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) a change to how you would be billed for tools that use the Agent SDK like this one. It currently uses your regular subscription quota just like Claude Code.
+
+<p>
+<a href="assets/claude-bridge1.png"><img src="assets/claude-bridge1.png" width="49%"></a>&nbsp;
+<a href="assets/claude-bridge2.png"><img src="assets/claude-bridge2.png" width="49%"></a>
+</p>
+
+## Install
+
+```
+pi install npm:pi-claude-bridge
+```
+
+## Provider
+
+Use `/model` to select `claude-bridge/claude-fable-5`, `claude-bridge/claude-opus-5`, `claude-bridge/claude-opus-4-8`, `claude-bridge/claude-opus-4-7`, `claude-bridge/claude-opus-4-6`, `claude-bridge/claude-sonnet-5`, `claude-bridge/claude-sonnet-4-6`, or `claude-bridge/claude-haiku-4-5`.
+
+Behind the scenes, pi's tools are bridged to Claude Code but it should all work like normal in pi. Bash commands get a 120-second default timeout (matching Claude Code's default) since pi's bash has no timeout by default. Skills in pi are copied over to Claude Code's system prompt so should work as they would with any other pi provider. Steering works mid-turn: a message sent while Claude is running a tool reaches it at that tool boundary, not after the whole turn finishes.
+
+**Other extensions' own model calls:** some extensions run a small agent of their own — to summarize, label or take notes — rather than going through the conversation. On a bridge model those calls used to crash pi outright; they now run as their own Claude Code session, using the calling extension's system prompt and tools and leaving your conversation's session alone. Each one is a Claude Code subprocess on the model you selected, so if an extension makes them often, consider pointing it at a cheaper model where it lets you.
+
+**1M Context:** Opus 5, Opus 4.8, and Opus 4.7 get 1M context by default. Opus 4.6 only gets 1M if you're on a Max plan or pay for Extra Usage. Sonnet 4.6 only gets 1M if you pay for Extra Usage. You will need to set `provider.plan` and/or `provider.longContextExtraUsage` for 1M context in Opus 4.6/Sonnet 4.6 as described in [Configuration](#configuration).
+
+## AskClaude Tool
+
+Opt-in: set `askClaude.enabled` to `true` (see [Configuration](#configuration)). Available when using any non-claude-bridge provider. Pi's LLM can delegate tasks to Claude Code and wait for it to answer a question or perform a task. Examples of how to use:
+
+- "Ask Claude to plan a fix"
+- "If you get stuck, ask claude for help"
+- "Ask claude to review the plan in @foo.md, implement it, then ask an isolated=true claude to review the implementation"
+- "Ask claude to poke holes in this theory"
+- "Find all the places in the codebase that handle auth"
+
+You could also create skills or add something to AGENTS.md to e.g. "Always call Ask Claude to review complicated feature implementations before considering the task complete."
+
+### Parameters
+
+- **`prompt`** — the question or task for Claude Code
+- **`mode`** — `read` (default, read files and search/fetch on web), `none`, or `full` (read+write+bash, disable this mode with `allowFullMode: false` in config)
+- **`model`** — `opus` (default), `sonnet`, `haiku`, or a full model ID
+- **`thinking`** — effort level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`
+- **`isolated`** — when `true`, Claude gets a clean session with no conversation history (default: `false`)
+
+## Configuration
+
+Config: `~/.pi/agent/claude-bridge.json` (global) or the project Pi config directory, usually `.pi/claude-bridge.json` (project; merged over global).
+
+```json
+{
+  "askClaude": {
+    "enabled": true,
+    "allowFullMode": true,
+    "defaultIsolated": false,
+    "description": "Custom tool description override"
+  },
+  "provider": {
+    "plan": "max",
+    "longContextExtraUsage": false,
+    "strictMcpConfig": true,
+    "pathToClaudeCodeExecutable": "/home/you/.nix-profile/bin/claude"
+  }
+}
+```
+
+`askClaude`:
+- `enabled` — register the AskClaude tool (default `false`). If it's unset, the startup notice below points this out once.
+- `name` — override the tool's pi-side name (default `"AskClaude"`)
+- `label` — override the TUI label (default `"Ask Claude Code"`)
+- `description` — override the tool description. Default when `allowFullMode: true`: *"Delegate to Claude Code for a second opinion or analysis (code review, architecture questions, debugging theories), or to autonomously handle a task. Defaults to read-only mode — use full mode when the user wants to delegate a task that requires changes. Prefer to handle straightforward tasks yourself."*
+- `defaultMode` — `"read"` (default), `"none"`, or `"full"`
+- `defaultIsolated` — start each call in a fresh session (default `false`)
+- `allowFullMode` — allow `mode: "full"`; set `false` to lock it out
+- `appendSkills` — forward pi's skills block into the system prompt (default `true`)
+
+`provider`:
+- `plan` (default `"pro"`) — set to `"max"` if you have a Max (or Team Premium/Enterprise) Anthropic plan. This enables Opus with 1M context.
+- `longContextExtraUsage` — set to `true` to enable 1M context models even if they cost money through Extra Usage on your plan. It enables Sonnet 4.6 with 1M on every plan and Opus 4.6 with 1M on Pro. Not needed for Opus 4.7 or 4.8.
+- `strictMcpConfig` — block MCP servers from `~/.claude.json` / `.mcp.json` (default `true`). Cloud MCP (Gmail/Drive via claude.ai OAuth) is always blocked.
+- `autoMemoryEnabled` — enable Claude Code's auto-memory system (default `false`)
+- `pathToClaudeCodeExecutable` — path to the `claude` binary. Useful if your OS/filesystem has the SDK's bundled musl/glibc binaries in a place where they can't run. For example, with Nix you can set the binary to e.g. `"/home/you/.nix-profile/bin/claude"`.
+
+
+**Startup notice:** the first interactive session to reach Claude Code lists whichever of `provider.plan` and `askClaude.enabled` you have left unset, then records `startupNoticeShown` (the date, `YYYY-MM-DD`) in the global config so it doesn't nag again.
+
+**Extension providers and models.json:** pi's `modelOverrides` in `~/.pi/agent/models.json` do not currently apply to extension-registered providers (like claude-bridge). Overriding `contextWindow` or other fields requires editing `src/models.ts` directly.
+
+## Tests
+
+`npm run test:unit` for offline tests (`tests/unit-*.mjs`: queue, import, skills). 
+
+`npm test` for the full suite, which adds integration tests that hit APIs (`tests/int-*.{sh,mjs}`: smoke, multi-turn, cache, session-resume, session-rebuild, tool-message). Set `CLAUDE_BRIDGE_TESTING_ALT_MODEL` in `.env.test` for the alt-provider smoke test (e.g. `openrouter/z-ai/glm-4.7-flash`).
+
+Integration tests spawn real `pi` and Claude Code subprocesses, so they need write access to `~/.claude` for CC's session state — a sandbox that blocks it makes the next turn's `--resume` fail with `No conversation found with session ID`. The RPC harness probes for this at startup and fails fast.
+
+## Debugging
+
+Set `CLAUDE_BRIDGE_DEBUG=1` to enable debug output:
+
+- **Bridge log** at `~/.pi/agent/claude-bridge.log` — every provider call, session sync decision, tool result delivery, and CC's stderr. Override location with `CLAUDE_BRIDGE_DEBUG_PATH`.
+- **Per-query Claude Code CLI logs** at `~/.pi/agent/cc-cli-logs/<timestamp>-<tag>-<seq>.log` — the CC subprocess's own debug stream, one file per `query()` call. Tags are `provider` (main turn) or `askclaude` (sub-delegation). Useful when a resume fails or CC misbehaves internally — shows the CLI's own view of session loading, API requests, and tool calls.
+
+When filing a bug about a session-resume failure (e.g. "No conversation found"), the most useful attachments are the `syncResult:` lines from the bridge log plus the matching `cc-cli-logs/` file for the failing query.
+
+## Known issues
+
+**Sessions get rebuilt more often than they need to be, and a rebuild is expensive.** The bridge rewrites Claude Code's session from pi's history whenever pi's messages move underneath it — after an abort, `/compact`, tree navigation, or an API error. Measured over this repo's own bridge log, a rebuild boundary loses the prompt cache roughly 58% of the time against 26% for a plain resume, so an abort-heavy session costs noticeably more than a clean one. Aborts alone are 46% of rebuilds.
+
+**Files Claude Code edits are not carried across a rebuild.** CC records the post-edit contents as an `edited_text_file` attachment; those aren't carried, because they hang off a tool-result record rather than a prompt and so have no stable position to restore them to. The edit itself survives — it's in the history as a tool call and its result — so this costs Claude the file snapshot, not the knowledge that it made the change. `@file` expansions *are* carried.

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@schuettc/pi-claude-bridge",
+  "version": "0.7.0-schuettc.1",
+  "private": false,
+  "description": "Pi extension that uses Claude Code (via Agent SDK) as a model provider and adds an AskClaude tool.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "extension",
+    "claude-code",
+    "claude-agent-sdk"
+  ],
+  "author": "Eli Dickinson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/schuettc/pi-claude-bridge.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "assets"
+  ],
+  "scripts": {
+    "test:unit": "node --import tsx --import ./tests/lib/setup.mjs --test tests/unit-*.mjs",
+    "test": "set -a && [ -f .env.test ] && . .env.test; set +a && npm run test:unit && tests/int-smoke.sh && tests/int-multi-turn.sh && tests/int-cache.sh && node --import tsx --test tests/int-*.mjs",
+    "test:usage": "tests/usage-test.sh",
+    "typecheck": "tsc --noEmit"
+  },
+  "type": "module",
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.141",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "cc-session-io": "^0.4.0",
+    "change-case": "^5.4.4"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.82.1",
+    "@earendil-works/pi-coding-agent": ">=0.82.1",
+    "@earendil-works/pi-tui": ">=0.82.1",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.73.0",
+    "@earendil-works/pi-agent-core": "^0.83.0",
+    "@earendil-works/pi-ai": "^0.83.0",
+    "@earendil-works/pi-coding-agent": "^0.83.0",
+    "@earendil-works/pi-tui": "^0.83.0",
+    "@types/node": "^24.13.2",
+    "tsx": "^4.22.4",
+    "typebox": "^1.3.7",
+    "typescript": "^6.0.3"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

package/src/agents-md.ts

@@ -0,0 +1,14 @@
+// Pi owns context-file discovery; the bridge only formats the list Pi loaded so
+// Claude receives the same instructions, in the same order, that Pi applies.
+
+type ContextFile = { path: string; content: string };
+
+export function formatProjectContext(contextFiles: ContextFile[]): string | undefined {
+	if (contextFiles.length === 0) return undefined;
+
+	let prompt = "<project_context>\n\nProject-specific instructions and guidelines:\n\n";
+	for (const { path, content } of contextFiles) {
+		prompt += `<project_instructions path="${path}">\n${content}\n</project_instructions>\n\n`;
+	}
+	return `${prompt}</project_context>`;
+}

package/src/askclaude-ui.ts

@@ -0,0 +1,90 @@
+// Status-line rendering helpers for the AskClaude tool.
+//
+// While Claude Code runs inside an AskClaude call, the pi TUI can't surface
+// each tool_use individually — there's only one status row for the whole
+// delegation. These helpers shape a tool_use record into a short, path-aware
+// label (e.g. "Read(src/foo.ts)", "Bash(git log --oneline…)") and collapse
+// runs of the same tool so the line doesn't flicker. Used only by
+// promptAndWait; the provider path exposes tools directly through pi's TUI
+// and doesn't need this.
+
+export interface ToolCallState {
+	name: string;
+	status: string;
+	rawInput?: unknown;
+}
+
+export function extractPath(rawInput: unknown): string | undefined {
+	if (!rawInput || typeof rawInput !== "object") return undefined;
+	const input = rawInput as Record<string, unknown>;
+	if (typeof input.file_path === "string") return input.file_path;
+	if (typeof input.path === "string") return input.path;
+	if (typeof input.command === "string") return input.command.substring(0, 80);
+	return undefined;
+}
+
+export function shortPath(p: string): string {
+	const cwd = process.cwd();
+	if (p.startsWith(cwd + "/")) return p.slice(cwd.length + 1);
+	if (p.startsWith("/")) {
+		const parts = p.split("/");
+		if (parts.length > 3) return parts.slice(-2).join("/");
+	}
+	return p;
+}
+
+export function formatToolAction(tc: ToolCallState): string | undefined {
+	const path = extractPath(tc.rawInput);
+	const verb = tc.name.toLowerCase().split(/\s/)[0];
+	if (verb === "read" || verb === "readfile") {
+		return path ? `Read(${shortPath(path)})` : "Read";
+	} else if (verb === "glob") {
+		const input = tc.rawInput as Record<string, unknown> | undefined;
+		const pat = typeof input?.pattern === "string" ? input.pattern.slice(0, 40) : "";
+		return pat ? `Glob(${pat})` : "Glob";
+	} else if (verb === "edit" || verb === "write" || verb === "writefile" || verb === "multiedit") {
+		return path ? `Edit(${shortPath(path)})` : "Edit";
+	} else if (verb === "bashoutput") {
+		return undefined; // redundant with preceding Bash call
+	} else if (verb === "bash" || verb === "terminal") {
+		return path ? `Bash(${path})` : "Bash";
+	} else if (verb === "agent") {
+		const input = tc.rawInput as Record<string, unknown> | undefined;
+		return `Agent(${String(input?.description ?? "").slice(0, 40)})`;
+	} else if (verb === "grep") {
+		const input = tc.rawInput as Record<string, unknown> | undefined;
+		const pat = typeof input?.pattern === "string" ? input.pattern.slice(0, 40) : "";
+		return pat ? `Grep(${pat})` : "Grep";
+	} else if (verb === "skill") {
+		const input = tc.rawInput as Record<string, unknown> | undefined;
+		const name = typeof input?.skill === "string" ? input.skill.slice(0, 40) : "";
+		return name ? `Skill(${name})` : "Skill";
+	} else if (verb === "todowrite" || verb === "taskcreate" || verb === "taskupdate") {
+		const todos = Array.isArray((tc.rawInput as any)?.todos) ? (tc.rawInput as any).todos : [];
+		const current = todos.find((t: any) => t.status === "in_progress") ?? todos.find((t: any) => t.status === "pending");
+		const label = current ? String(current.content ?? "").slice(0, 40) : "";
+		return label || undefined;
+	} else if (verb === "askclaude") {
+		// Recursive — don't show AskClaude in its own action summary
+		return undefined;
+	}
+	return tc.name;
+}
+
+export function buildActionSummary(calls: Map<string, ToolCallState>): string {
+	const parts: string[] = [];
+	let prevVerb = "";
+	for (const [, tc] of calls) {
+		const action = formatToolAction(tc);
+		if (!action) continue;
+		const verb = tc.name.toLowerCase().split(/\s/)[0];
+		// Collapse consecutive calls to the same tool — keep only the latest
+		if (verb === prevVerb) {
+			parts[parts.length - 1] = action;
+		} else {
+			parts.push(action);
+		}
+		prevVerb = verb;
+	}
+	return parts.join("; ");
+}

package/src/attachments.ts

@@ -0,0 +1,135 @@
+// Carrying Claude Code's own attachments across a session rebuild.
+//
+// CC expands an `@file` mention itself — pi passes `@` through untouched — and
+// writes the expansion as a `type: "attachment"` record in its session file. pi
+// never sees it, so rebuilding a session from pi's history drops the file while
+// keeping the prompt text that referred to it: the model silently loses
+// something it was reasoning about, with nothing logged.
+//
+// Extracted from index.ts so tests can import it without activating the extension.
+
+import type { JsonlRecord, ImportAttachment } from "cc-session-io";
+import { messageContentToText } from "./convert.js";
+
+// Only `@file` expansions are carried. They are the one thing pi genuinely never
+// sees, so a rebuild is the only chance to keep them.
+//
+// `edited_text_file` is deliberately excluded even though it also carries file
+// content. CC writes one after editing a file, and the edit itself is already in
+// pi's history as a tool call and its result, so the attachment duplicates context
+// the rebuild reproduces anyway. It also usually hangs off a *tool result* record
+// rather than a prompt, which has no position in the ordinal scheme below — on
+// real sessions that left 81 of them unresolvable (see
+// diag/attachment-coverage.mjs). Half-carrying a kind is worse than not claiming
+// it: the ones that slipped through would be an arbitrary subset.
+//
+// Everything else CC rewrites every turn (`skill_listing`, `task_reminder`,
+// `agent_listing_delta`, `mcp_instructions_delta`, …) and loses nothing.
+const CONTENT_BEARING = new Set(["file"]);
+
+export type CarriedAttachment = {
+	attachment: { type: string; [key: string]: unknown };
+	/** Position of the parent among the session's text-bearing user records. */
+	userOrdinal: number;
+	/** That record's text, to verify the ordinal still points at the same turn. */
+	parentText: string;
+};
+
+type Rec = Record<string, unknown>;
+
+/** A user record holding a prompt, as opposed to one holding tool results. */
+function userPromptText(record: Rec): string | undefined {
+	if (record.type !== "user") return undefined;
+	const content = (record.message as Rec | undefined)?.content;
+	if (Array.isArray(content) && content.some((b) => (b as Rec)?.type === "tool_result")) return undefined;
+	const text = messageContentToText(content as never);
+	return text ? text : undefined;
+}
+
+/**
+ * Content-bearing attachments in a session, each tagged with where its parent
+ * sits among the text-bearing user records.
+ *
+ * The ordinal is the mapping key rather than the record index: a rebuild does not
+ * reproduce the old record list one-for-one — `importMessages` splits a message
+ * carrying tool results into two records, and CC appends records of its own — but
+ * the sequence of user prompts is the same conversation either way.
+ *
+ * Attachments also chain to one another, so an ordinal is resolved transitively up
+ * the parent links until it reaches a prompt. Most real attachments are
+ * `edited_text_file` records CC writes after editing a file, which have nothing to
+ * do with at-mentions; only their position in the conversation matters here.
+ */
+export function collectCarriedAttachments(records: readonly JsonlRecord[]): CarriedAttachment[] {
+	const ordinalOf = new Map<string, number>();
+	const textOf = new Map<string, string>();
+	let ordinal = 0;
+	const carried: CarriedAttachment[] = [];
+
+	for (const raw of records) {
+		const record = raw as Rec;
+		const prompt = userPromptText(record);
+		if (prompt !== undefined) {
+			ordinalOf.set(record.uuid as string, ordinal++);
+			textOf.set(record.uuid as string, prompt);
+			continue;
+		}
+		if (record.type !== "attachment") continue;
+		const parent = record.parentUuid as string | null;
+		// Attachments chain to each other — a run of them hangs off one prompt, and
+		// 63 of 179 in real sessions parent to another attachment rather than to a
+		// message. Inherit the ordinal so the whole run keys to the prompt that
+		// caused it. Recorded for every attachment, not just the ones carried, since
+		// a content-bearing one can chain off a `skill_listing` we ignore.
+		if (parent === null || !ordinalOf.has(parent)) continue;
+		const inherited = ordinalOf.get(parent)!;
+		ordinalOf.set(record.uuid as string, inherited);
+		textOf.set(record.uuid as string, textOf.get(parent)!);
+
+		const attachment = record.attachment as { type: string; [key: string]: unknown } | undefined;
+		if (!attachment || !CONTENT_BEARING.has(attachment.type)) continue;
+		carried.push({ attachment, userOrdinal: inherited, parentText: textOf.get(parent)! });
+	}
+	return carried;
+}
+
+/**
+ * Resolve each carried attachment to a position in the array about to be
+ * imported — the messages *after* conversion and repair, since that is the index
+ * space `importMessages` reads. Repair is idempotent, so an already-repaired array
+ * passes through its second run unchanged and the indices stay valid.
+ *
+ * Deliberately conservative: attaching a file to the wrong turn tells the model it
+ * saw something at a point it did not, which is worse than the loss this exists to
+ * prevent. So the ordinal has to land on a prompt whose text still matches; any
+ * disagreement is reported and dropped rather than approximated.
+ */
+export function placeCarriedAttachments(
+	carried: readonly CarriedAttachment[],
+	messages: readonly { role: string; content: unknown }[],
+): { attachments: ImportAttachment[]; skipped: string[] } {
+	const prompts: { index: number; text: string }[] = [];
+	messages.forEach((msg, index) => {
+		if (msg.role !== "user") return;
+		if (Array.isArray(msg.content) && msg.content.some((b) => (b as Rec)?.type === "tool_result")) return;
+		const text = messageContentToText(msg.content as never);
+		if (text) prompts.push({ index, text });
+	});
+
+	const attachments: ImportAttachment[] = [];
+	const skipped: string[] = [];
+	for (const item of carried) {
+		const name = String(item.attachment.filename ?? item.attachment.type);
+		const candidate = prompts[item.userOrdinal];
+		if (!candidate) {
+			skipped.push(`${name}: prompt #${item.userOrdinal} is no longer in history`);
+			continue;
+		}
+		if (candidate.text !== item.parentText) {
+			skipped.push(`${name}: prompt #${item.userOrdinal} changed`);
+			continue;
+		}
+		attachments.push({ afterIndex: candidate.index, attachment: item.attachment });
+	}
+	return { attachments, skipped };
+}

package/src/config.ts

@@ -0,0 +1,89 @@
+// User-facing extension config. Loaded once at extension registration from
+// the global agent dir (getAgentDir(), e.g. ~/.pi/agent/claude-bridge.json)
+// and the project Pi config directory, project overriding global. Missing or
+// unparseable files are ignored (error to console.error, empty object
+// returned) so the extension always starts.
+
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+
+export interface Config {
+	/** Date (YYYY-MM-DD) the one-time startup notice was shown. Written by the extension, not the user. */
+	startupNoticeShown?: string;
+	askClaude?: {
+		enabled?: boolean;
+		name?: string;
+		label?: string;
+		description?: string;
+		defaultMode?: "full" | "read" | "none";
+		defaultIsolated?: boolean;
+		allowFullMode?: boolean;
+		appendSkills?: boolean;
+	};
+	/** Low-level Claude Agent SDK plumbing. Most users won't need these. */
+	provider?: {
+		strictMcpConfig?: boolean;
+		autoMemoryEnabled?: boolean;
+		pathToClaudeCodeExecutable?: string;
+		// Subscription plan tier. Setting to "max" enables Opus 4.6 at 1M context
+		plan?: "pro" | "max";
+		// Set to true to opt into metered 1M context usage ("extra usage" in
+		// Anthropic billing). Enables Sonnet 4.6 [1m] on every plan and Opus 4.6
+		// [1m] on Pro.
+		longContextExtraUsage?: boolean;
+	};
+}
+
+export function tryParseJson(path: string): Partial<Config> {
+	if (!existsSync(path)) return {};
+	try {
+		return JSON.parse(readFileSync(path, "utf-8"));
+	} catch (e) {
+		console.error(`claude-bridge: failed to parse ${path}: ${e}`);
+		return {};
+	}
+}
+
+export function claudeCodeSettings(provider: Config["provider"] = {}): { autoMemoryEnabled: boolean } {
+	return { autoMemoryEnabled: provider.autoMemoryEnabled ?? false };
+}
+
+export function globalConfigPath(): string {
+	return join(getAgentDir(), "claude-bridge.json");
+}
+
+/** Record today's date in the global config so the startup notice shows once, preserving every
+ *  other field. Returns the config path for display either way.
+ *
+ *  Parses directly rather than through tryParseJson, which reports an unparseable file as `{}`:
+ *  spreading that would replace a user's whole config with just this marker the first time they
+ *  leave a trailing comma in it. Losing the notice is the cheaper failure, so the write is
+ *  skipped and the notice simply shows again next session. */
+export function markStartupNoticeShown(): string {
+	const path = globalConfigPath();
+	let existing: Partial<Config> = {};
+	if (existsSync(path)) {
+		try {
+			existing = JSON.parse(readFileSync(path, "utf-8"));
+		} catch (e) {
+			console.error(`claude-bridge: leaving ${path} alone, it does not parse: ${e}`);
+			return path;
+		}
+	}
+	// en-CA renders YYYY-MM-DD in local time; toISOString() would report UTC.
+	const next = { ...existing, startupNoticeShown: new Date().toLocaleDateString("en-CA") };
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`);
+	return path;
+}
+
+export function loadConfig(cwd: string): Config {
+	const global = tryParseJson(globalConfigPath());
+	const project = tryParseJson(join(cwd, CONFIG_DIR_NAME, "claude-bridge.json"));
+	return {
+		startupNoticeShown: project.startupNoticeShown ?? global.startupNoticeShown,
+		askClaude: { ...global.askClaude, ...project.askClaude },
+		provider: { ...global.provider, ...project.provider },
+	};
+}