@vanillagreen/pi-claude-bridge 1.9.0 → 3.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanillagreen/pi-claude-bridge",
-  "version": "1.9.0",
+  "version": "3.2.2",
   "description": "Pi provider bridge that runs Claude Code through the Claude Agent SDK, with opt-in forwarding for Pi prompt context.",
   "type": "module",
   "keywords": [
@@ -19,12 +19,12 @@
   },
   "vstack": {
     "extensionManager": {
-      "displayName": "Claude Bridge",
+      "displayName": "Pi Claude",
       "settings": [
         {
           "key": "enabled",
-          "label": "Enable Claude bridge provider",
-          "description": "Register claude-bridge models that route Pi turns through Claude Code via the Claude Agent SDK.",
+          "label": "Enable Pi Claude provider",
+          "description": "Register pi-claude models that route Pi turns through Claude Code via the Claude Agent SDK.",
           "type": "boolean",
           "default": true,
           "category": "General",
@@ -34,7 +34,7 @@
         {
           "key": "appendSystemPrompt",
           "label": "Forward AGENTS.md + skills",
-          "description": "Original bridge behavior: append AGENTS.md and Pi's skills block to Claude Code's claude_code preset prompt.",
+          "description": "Original bridge behavior: append the nearest context file (AGENTS.override.md, AGENTS.md, or AGENTS.MD) and Pi's skills block to Claude Code's claude_code preset prompt.",
           "type": "boolean",
           "default": true,
           "category": "Base Prompt",
@@ -85,19 +85,10 @@
           "category": "Claude Code",
           "apply": "live"
         },
-        {
-          "key": "allowExtraUsage",
-          "label": "Allow extra usage helper",
-          "description": "Allow claude-bridge to launch Claude Code's /extra-usage flow when rate limits require extra usage. Billing/admin approval still happens in Claude's browser page.",
-          "type": "boolean",
-          "default": false,
-          "category": "Claude Code",
-          "apply": "live"
-        },
         {
           "key": "fastMode",
           "label": "Fast mode",
-          "description": "Enable Claude Code fast mode for bridge requests when the selected model supports it. Off by default.",
+          "description": "Enable Claude Code fast mode for bridge requests when the selected model and account support it. Off by default.",
           "type": "boolean",
           "default": false,
           "category": "Claude Code",
@@ -106,7 +97,7 @@
         {
           "key": "forceEffort",
           "label": "Force Claude effort",
-          "description": "Override Pi's thinking-level mapping for all claude-bridge requests. Pi 0.80.6 and newer can select max natively; none keeps Pi's selected level.",
+          "description": "Override Pi's thinking-level mapping for all Pi Claude requests. Pi 0.80.6 and newer can select max natively; none keeps Pi's selected level.",
           "type": "enum",
           "enumValues": [
             "none",
@@ -123,7 +114,7 @@
         {
           "key": "modelEffortOverrides",
           "label": "Model effort overrides",
-          "description": "Optional JSON object mapping claude-bridge model ids to Claude Code effort levels, e.g. {\"claude-opus-4-8\":\"max\"}. Keys may also use claude-bridge/<id> or *.",
+          "description": "Optional JSON object mapping Pi Claude model ids to Claude Code effort levels, e.g. {\"claude-opus-4-8\":\"max\"}. Keys may also use pi-claude/<id> or *.",
           "type": "string",
           "default": "{}",
           "category": "Claude Code",
@@ -142,18 +133,18 @@
     }
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.215",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.220",
     "@anthropic-ai/sdk": "^0.112.4",
-    "cc-session-io": "^0.3.1",
+    "cc-session-io": "^0.3.2",
     "change-case": "^5.4.4"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-ai": ">=0.81.0",
+    "@earendil-works/pi-coding-agent": ">=0.81.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.80.10",
-    "@earendil-works/pi-coding-agent": "^0.80.10",
+    "@earendil-works/pi-ai": "^0.84.0",
+    "@earendil-works/pi-coding-agent": "^0.84.0",
     "@types/node": "^24.3.0",
     "esbuild": "^0.28.0",
     "tsx": "^4.21.0",

package/src/account-host.ts

@@ -0,0 +1,112 @@
+// Reciprocal account-host service: a local /usage probe the companion account
+// manager calls to read a profile's identity and usage figures under that
+// profile's credential scope. Extracted from index.ts (pure move).
+
+import { subscriberProfileEnv, type ClaudeAccountRoute, type ClaudeBridgeAccountHostV1 } from "./account-router.js";
+import { preflightClaudeExecutable, resolveClaudeExecutable, spawnClaudeCodeWithDiagnostics } from "./claude-executable.js";
+import { loadConfig } from "./config.js";
+import { CLAUDE_BRIDGE_TOOL_ISOLATION, denyAllToolsHook } from "./connectors.js";
+import { debug, makeCliDebugOptions } from "./debug.js";
+import { sdkQueryFactory } from "./sdk-query.js";
+
+/** Local /usage probe for the reciprocal account-host service: the companion
+ *  account manager asks the bridge (the SDK owner) to read a profile's identity
+ *  and usage figures under that profile's credential scope. */
+// This is a published entry point (BRIDGE_ACCOUNT_HOST.probeProfile) and
+// `signal` is optional, so a stalled child with no caller signal would hang the
+// returned promise forever and leak the process. The internal deadline bounds
+// every call; generous next to the in-query probe's 1.5s race because a cold
+// child spawn is part of the budget here.
+const ACCOUNT_PROBE_DEADLINE_MS = 10_000;
+
+export async function probeClaudeAccountProfile(input: {
+	profile: ClaudeAccountRoute;
+	cwd: string;
+	signal?: AbortSignal;
+	/** Deadline override for tests; production callers use the default. */
+	deadlineMs?: number;
+}): Promise<{
+	identity?: { email?: string; organization?: string; subscriptionType?: string; authMethod?: string };
+	usage?: unknown;
+}> {
+	const config = loadConfig(input.cwd);
+	const claudeExecutable = resolveClaudeExecutable(config.provider?.pathToClaudeCodeExecutable);
+	if (claudeExecutable) preflightClaudeExecutable(claudeExecutable, input.cwd);
+	const probe = sdkQueryFactory({
+		prompt: "/usage",
+		options: {
+			cwd: input.cwd,
+			env: {
+				...subscriberProfileEnv(input.profile),
+				ENABLE_CLAUDEAI_MCP_SERVERS: "0",
+				DISABLE_AUTO_COMPACT: "1",
+			},
+			maxTurns: 1,
+			// bypassPermissions makes tool containment the only gate, so the probe
+			// gets BOTH layers: the standard bridge isolation lists AND a deny-all
+			// PreToolUse hook — a /usage probe has no business executing anything.
+			permissionMode: "bypassPermissions",
+			...CLAUDE_BRIDGE_TOOL_ISOLATION,
+			hooks: { PreToolUse: [{ hooks: [denyAllToolsHook()] }] },
+			...(claudeExecutable ? { pathToClaudeCodeExecutable: claudeExecutable } : {}),
+			spawnClaudeCodeProcess: spawnClaudeCodeWithDiagnostics,
+			...makeCliDebugOptions("account-probe"),
+		},
+	});
+	const onAbort = () => {
+		void probe.interrupt().catch(() => {});
+		try { probe.close(); } catch {}
+	};
+	if (input.signal?.aborted) onAbort();
+	else input.signal?.addEventListener("abort", onAbort, { once: true });
+	let controls: Promise<{
+		identity?: { email?: string; organization?: string; subscriptionType?: string; authMethod?: string };
+		usage?: unknown;
+	}> | undefined;
+	let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
+	const deadline = new Promise<"deadline">((resolveDeadline) => {
+		deadlineTimer = setTimeout(() => {
+			debug(`account-probe: deadline expired for ${input.profile.label}; killing probe child`);
+			onAbort();
+			resolveDeadline("deadline");
+		}, input.deadlineMs ?? ACCOUNT_PROBE_DEADLINE_MS);
+		deadlineTimer.unref?.();
+	});
+	const consume = (async () => {
+		for await (const message of probe) {
+			if (message.type === "system" && (message as any).subtype === "init" && !controls) {
+				controls = Promise.allSettled([
+					probe.accountInfo(),
+					probe.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET(),
+				]).then(([identityResult, usageResult]) => ({
+					...(identityResult.status === "fulfilled" ? { identity: {
+						email: identityResult.value.email,
+						organization: identityResult.value.organization,
+						subscriptionType: identityResult.value.subscriptionType,
+					} } : {}),
+					...(usageResult.status === "fulfilled" ? { usage: usageResult.value } : {}),
+				}));
+			}
+		}
+		return controls ? await controls : {};
+	})();
+	try {
+		// The race — not close() alone — is what guarantees the promise settles: a
+		// truly wedged child can survive close(), and then the for-await above
+		// never ends.
+		const result = await Promise.race([consume, deadline]);
+		return result === "deadline" ? {} : result;
+	} finally {
+		clearTimeout(deadlineTimer);
+		input.signal?.removeEventListener("abort", onAbort);
+		probe.close();
+		// After a deadline kill the consumer may still reject; that outcome is
+		// already accounted for.
+		void consume.catch(() => {});
+	}
+}
+
+export const BRIDGE_ACCOUNT_HOST: ClaudeBridgeAccountHostV1 = {
+	version: 1,
+	probeProfile: probeClaudeAccountProfile,
+};

package/src/account-router.ts

@@ -0,0 +1,272 @@
+// Optional multi-account subscription routing contract.
+//
+// A companion extension may publish a router on `globalThis` under the
+// versioned symbol below to supply a subscription profile for each fresh
+// Claude request. The bridge passes only an opaque profile id, a display
+// label, and an optional CLAUDE_CONFIG_DIR; credentials remain owned by the
+// official Claude CLI. Incompatible future shapes must use a new
+// symbol/version instead of mutating this contract in place.
+
+import type { AssistantMessageEvent, AssistantMessageEventStream } from "@earendil-works/pi-ai";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { debug } from "./debug.js";
+import { resetTimestampMs } from "./rate-limit.js";
+
+export const CLAUDE_ACCOUNT_ROUTER_SYMBOL = Symbol.for("vstack.pi.claude-account-router.v1");
+export const CLAUDE_BRIDGE_ACCOUNT_HOST_SYMBOL = Symbol.for("vstack.pi.claude-bridge.account-host.v1");
+
+export interface ClaudeAccountRoute {
+	profileId: string;
+	label: string;
+	configDir?: string;
+	/** Effective model selected by the companion after model-scoped quota exhaustion. */
+	modelId?: string;
+	fallbackReason?: "fable-quota";
+}
+
+export type ClaudeAccountFailureKind = "auth" | "billing" | "rate-limit" | "overloaded" | "server" | "network";
+
+export interface ClaudeAccountRouterV1 {
+	version: 1;
+	acquire(input: {
+		modelId: string;
+		sessionId?: string;
+		excludedProfileIds?: string[];
+		forceRerank?: boolean;
+		reason?: string;
+	}): ClaudeAccountRoute;
+	recordIdentity(profileId: string, identity: {
+		email?: string;
+		organization?: string;
+		organizationId?: string;
+		subscriptionType?: string;
+		authMethod?: string;
+	}): void;
+	recordUsage(profileId: string, usage: unknown): void;
+	recordRateLimit(profileId: string, info: Record<string, unknown> | undefined, modelId: string): number;
+	recordFailure(profileId: string, kind: ClaudeAccountFailureKind, modelId: string): void;
+	recordSuccess(profileId: string, sessionId?: string): void;
+	current(modelId: string, sessionId?: string): ClaudeAccountRoute | undefined;
+	/** Resolve a previously issued profile id back to its route. The bridge
+	 *  persists ONLY the opaque profile id into Pi session entries (config-dir
+	 *  paths are account-identifying and travel with shared session archives),
+	 *  so restoring a session re-derives the config dir here. A missing router
+	 *  or unknown id degrades to the default-profile rule. */
+	resolveProfile?(profileId: string): Pick<ClaudeAccountRoute, "profileId" | "configDir"> | undefined;
+}
+
+export interface ClaudeBridgeAccountHostV1 {
+	version: 1;
+	probeProfile(input: {
+		profile: ClaudeAccountRoute;
+		cwd: string;
+		signal?: AbortSignal;
+	}): Promise<{
+		identity?: {
+			email?: string;
+			organization?: string;
+			subscriptionType?: string;
+			authMethod?: string;
+		};
+		usage?: unknown;
+	}>;
+}
+
+export function resolveClaudeAccountRouter(): ClaudeAccountRouterV1 | undefined {
+	const host = globalThis as unknown as Record<PropertyKey, unknown>;
+	const candidate = host[CLAUDE_ACCOUNT_ROUTER_SYMBOL] as ClaudeAccountRouterV1 | undefined;
+	return candidate?.version === 1 ? candidate : undefined;
+}
+
+/** Run a companion-router telemetry callback without letting it fail the turn.
+ *  The router is third-party code reached from delivery paths (a throwing
+ *  recordSuccess would otherwise error a turn whose answer already rendered). */
+export function safeRouterCall(label: string, call: () => void): void {
+	try {
+		call();
+	} catch (error) {
+		debug(`router callback ${label} threw:`, error);
+	}
+}
+
+export function subscriberProfileEnv(
+	profile: Pick<ClaudeAccountRoute, "configDir">,
+	base: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+	const env: NodeJS.ProcessEnv = { ...base };
+	// Managed profiles are subscription identities. Inherited API/provider
+	// credentials and endpoint overrides would silently bypass the profile and
+	// create separate billing or route its OAuth token through a gateway.
+	const directOverrides = new Set([
+		"ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_OAUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN",
+		"ANTHROPIC_BASE_URL", "ANTHROPIC_CUSTOM_HEADERS", "ANTHROPIC_AWS_API_KEY",
+		"ANTHROPIC_FOUNDRY_AUTH_TOKEN", "ANTHROPIC_BEDROCK_BASE_URL",
+		"ANTHROPIC_VERTEX_BASE_URL", "ANTHROPIC_FOUNDRY_BASE_URL", "AWS_BEARER_TOKEN_BEDROCK",
+	]);
+	for (const key of Object.keys(env)) {
+		if (directOverrides.has(key) || key.startsWith("CLAUDE_CODE_USE_")) delete env[key];
+	}
+	if (profile.configDir) env.CLAUDE_CONFIG_DIR = profile.configDir;
+	else delete env.CLAUDE_CONFIG_DIR;
+	return env;
+}
+
+/** The claude config dir the CHILD actually uses under this profile: the
+ *  profile's own configDir, else the real default (`~/.claude`). NEVER the
+ *  parent's CLAUDE_CONFIG_DIR — subscriberProfileEnv scrubs that from managed
+ *  children, so any bridge-side session IO that resolved through the process
+ *  env would write JSONLs where the child never looks and break resume. */
+export function claudeDirForProfile(profile: Pick<ClaudeAccountRoute, "configDir">): string {
+	return profile.configDir?.trim() || join(homedir(), ".claude");
+}
+
+export interface AccountSessionScope {
+	accountProfileId?: string;
+	claudeConfigDir?: string;
+}
+
+/** Session scope for a managed request: the opaque profile id plus the FULLY
+ *  RESOLVED claude dir (see claudeDirForProfile). Empty for legacy requests,
+ *  which keep reading CLAUDE_CONFIG_DIR from the process env as before. */
+export function accountSessionScope(profile: ClaudeAccountRoute | undefined): AccountSessionScope {
+	return profile
+		? { accountProfileId: profile.profileId, claudeConfigDir: claudeDirForProfile(profile) }
+		: {};
+}
+
+export function commitsVisibleOutput(event: AssistantMessageEvent): boolean {
+	if (event.type === "text_delta" || event.type === "thinking_delta" || event.type === "toolcall_delta") {
+		return event.delta.length > 0;
+	}
+	if (event.type === "text_end" || event.type === "thinking_end") return event.content.length > 0;
+	return event.type === "toolcall_end";
+}
+
+/**
+ * Holds protocol setup events until the first visible delta/tool call. A failed
+ * account can then be discarded and retried without leaking a duplicate `start`
+ * frame into Pi. Terminal success/error commits the buffered frames.
+ */
+export class RetryEventBuffer {
+	private readonly pending: AssistantMessageEvent[] = [];
+	private committed = false;
+	private ended = false;
+	private discarded = false;
+	private readonly target: AssistantMessageEventStream;
+	private readonly onCommit?: () => void;
+
+	constructor(target: AssistantMessageEventStream, onCommit?: () => void) {
+		this.target = target;
+		this.onCommit = onCommit;
+	}
+
+	push(event: AssistantMessageEvent): void {
+		if (this.discarded) return;
+		if (this.committed) {
+			this.target.push(event);
+			return;
+		}
+		this.pending.push(event);
+		if (commitsVisibleOutput(event) || event.type === "done" || event.type === "error") this.commit();
+	}
+
+	end(): void {
+		if (this.discarded) return;
+		this.ended = true;
+		if (this.committed) this.target.end();
+	}
+
+	commit(): void {
+		if (this.discarded || this.committed) return;
+		this.committed = true;
+		this.onCommit?.();
+		for (const event of this.pending) this.target.push(event);
+		this.pending.length = 0;
+		if (this.ended) this.target.end();
+	}
+
+	discard(): void {
+		if (this.committed) return;
+		this.discarded = true;
+		this.pending.length = 0;
+	}
+
+	get hasCommittedOutput(): boolean { return this.committed; }
+}
+
+export function rateLimitTypeFromInfo(info: Record<string, unknown> | undefined): unknown {
+	return info?.rateLimitType ?? info?.rate_limit_type ?? info?.type;
+}
+
+export function rateLimitResetFromInfo(info: Record<string, unknown> | undefined): unknown {
+	return info?.resetsAt ?? info?.resets_at ?? info?.resetAt ?? info?.reset_at;
+}
+
+export function rateLimitResetMs(info: Record<string, unknown> | undefined): number | undefined {
+	// The seconds-vs-ms magnitude heuristic lives in resetTimestampMs; this is
+	// just field extraction over it.
+	return resetTimestampMs(rateLimitResetFromInfo(info));
+}
+
+// An HTTP status code counts only in an http-ish context ("status 429",
+// "HTTP 500", "API Error: 529", "code: 401") — a bare 3-digit number in prose
+// ("took 500ms", "line 502") must not classify (S5).
+function httpStatusInText(normalized: string): number | undefined {
+	const match = /\b(?:http|https|status(?: code)?|error|code)\b[^a-z0-9]{0,4}([45]\d\d)\b/.exec(normalized);
+	return match ? Number(match[1]) : undefined;
+}
+
+function classifyStatusCode(status: number): ClaudeAccountFailureKind | undefined {
+	if (status === 401) return "auth";
+	// Anthropic maps 403 to permission_error (org restrictions,
+	// oauth_org_not_allowed): this credential cannot serve the request, so
+	// another profile might — same rotation posture as 401.
+	if (status === 403) return "auth";
+	if (status === 402) return "billing";
+	if (status === 429) return "rate-limit";
+	if (status === 529) return "overloaded";
+	if (status >= 500 && status <= 599) return "server";
+	return undefined;
+}
+
+export function classifyClaudeFailure(value: unknown): ClaudeAccountFailureKind | undefined {
+	const details: unknown[] = [value];
+	let numericStatus: number | undefined;
+	if (value && typeof value === "object") {
+		const record = value as Record<string, unknown>;
+		details.push(record.name, record.type, record.message, record.code, record.status, record.statusCode, record.body, record.error);
+		for (const field of [record.status, record.statusCode]) {
+			if (typeof field === "number" && Number.isInteger(field)) { numericStatus = field; break; }
+		}
+	}
+	const text = details.map((detail) => {
+		if (typeof detail === "string" || typeof detail === "number") return String(detail);
+		try { return JSON.stringify(detail ?? ""); } catch { return String(detail); }
+	}).join(" ");
+	const normalized = text.toLowerCase().replace(/[_-]+/g, " ");
+	// Structured status fields are unambiguous — classify them before prose.
+	const statusKind = numericStatus !== undefined ? classifyStatusCode(numericStatus) : undefined;
+	if (statusKind) return statusKind;
+	// `permission error` covers the API's permission_error type (403); the bare
+	// words "permission denied" alone stay unclassified — they are just as likely
+	// a filesystem EACCES, which no other account can fix.
+	if (/authentication (?:failed|error)|permission error|oauth org not allowed|oauth token.*expired|token.*expired|unauthorized|invalid token|login required|please run .*login|not logged in/.test(normalized)
+		|| httpStatusInText(normalized) === 401 || httpStatusInText(normalized) === 403) return "auth";
+	// Extra Usage is controlled by Claude account settings. A request asking for
+	// it means the current model allowance was rejected, not that Pi should make
+	// a billing-policy decision or globally disable the profile.
+	if (/extra usage|overage/.test(normalized)) return "rate-limit";
+	if (/billing error|payment|required.*billing|credit balance.*(?:low|insufficient|empty)|insufficient credits/.test(normalized)) return "billing";
+	// `quota` alone is ambiguous ("disk quota exceeded") — require rate/usage
+	// context words alongside it.
+	const quotaInUsageContext = /\bquota\b/.test(normalized) && /\b(?:rate|usage|limits?|requests?|tokens?|messages?|api)\b/.test(normalized);
+	if (/\brate limit|usage limit|session limit|weekly limit|monthly limit|limit reached|you(?:'|’)ve hit your .* limit|too many requests|resets? (?:at )?\d/.test(normalized)
+		|| quotaInUsageContext
+		|| httpStatusInText(normalized) === 429) return "rate-limit";
+	if (/overloaded|capacity/.test(normalized) || httpStatusInText(normalized) === 529) return "overloaded";
+	const statusInText = httpStatusInText(normalized);
+	if (/server error|internal server/.test(normalized) || (statusInText !== undefined && statusInText >= 500)) return "server";
+	if (/network|timeout|timed out|socket|econn|connection closed|fetch failed|unexpected end|\beof\b/.test(normalized)) return "network";
+	return undefined;
+}

package/src/agents-md.ts

@@ -1,37 +1,78 @@
 // AGENTS.md discovery and sanitization for forwarding to Claude Code.
 //
 // Pi uses AGENTS.md for long-lived instructions; Claude Code reads the same
-// content under "# CLAUDE.md". We walk up from cwd looking for AGENTS.md,
+// content under "# CLAUDE.md". We walk up from cwd looking for a context file,
 // fall back to <piUserDir>/AGENTS.md (~/.pi/agent/AGENTS.md unless
 // PI_CODING_AGENT_DIR points elsewhere), and rewrite pi-specific references
 // (~/.pi, .pi/, .pi, pi) to their Claude Code equivalents so any paths or
 // references in the file still resolve inside the CC subprocess.
 //
+// Per directory we mirror the AGENTS.* entries of Pi's own candidate order
+// (resource-loader.ts): AGENTS.override.md, AGENTS.md, AGENTS.MD -- the override
+// replaces AGENTS.md in the same directory. Pi's list continues with CLAUDE.md and
+// CLAUDE.MD, which we deliberately omit: the Claude Code subprocess already loads
+// CLAUDE.md natively, so forwarding it would apply the same context twice.
+//
+// We forward the NEAREST context file only, while Pi loads one per ancestor directory
+// and concatenates them. That single-layer model predates override support and is kept
+// deliberately: the bridge sanitizes and re-headers whatever it forwards into one
+// "# CLAUDE.md" block, and the subprocess separately loads the repo's own CLAUDE.md, so
+// concatenating every ancestor layer here risks duplicating context rather than
+// completing it. Changing it is a behavior change for every bridge user and belongs in
+// its own change, not in per-directory override parity.
+//
 // In isolated mode (CLAUDE_BRIDGE_ISOLATED=1), all AGENTS.md discovery is
 // disabled. Embedding hosts provide their instruction surface explicitly.
 
-import { existsSync, readFileSync } from "fs";
+import { lstatSync, readFileSync, statSync } from "fs";
 import { dirname, join, resolve } from "path";
 import { isolatedFromEnv, piUserDir } from "./config.js";
+import { debug } from "./debug.js";
+
+const CONTEXT_FILE_CANDIDATES = ["AGENTS.override.md", "AGENTS.md", "AGENTS.MD"];
 
-function globalAgentsPath(): string {
-	return join(piUserDir(), "AGENTS.md");
+function contextFileInDir(dir: string): string | undefined {
+	for (const filename of CONTEXT_FILE_CANDIDATES) {
+		const candidate = join(dir, filename);
+		try {
+			if (statSync(candidate).isFile()) return candidate;
+		} catch (error) {
+			// A genuinely absent candidate is the normal case and stays silent. Anything else --
+			// a dangling symlink (which reports ENOENT through stat but resolves through lstat),
+			// a permissions error, an I/O fault -- means a context file the user intended is being
+			// skipped, and skipping an override silently forwards the AGENTS.md it was meant to
+			// supersede. Only ENOENT from lstat proves genuine absence; a traversal or permission
+			// fault throws from both calls and must not be mistaken for "no such file".
+			let lstatCode: string | undefined;
+			let entryExists = false;
+			try {
+				lstatSync(candidate);
+				entryExists = true;
+			} catch (lstatError) {
+				lstatCode = (lstatError as NodeJS.ErrnoException).code;
+			}
+			if (entryExists || lstatCode !== "ENOENT") {
+				const detail = (error as NodeJS.ErrnoException).code ?? String(error);
+				const suffix = entryExists ? "" : ` (lstat: ${lstatCode ?? "unknown"})`;
+				debug(`agents-md: skipping unusable ${candidate}: ${detail}${suffix}`);
+			}
+		}
+	}
+	return undefined;
 }
 
 export function resolveAgentsMdPath(): string | undefined {
 	if (isolatedFromEnv()) return undefined;
 	const fromCwd = findAgentsMdInParents(process.cwd());
 	if (fromCwd) return fromCwd;
-	const globalPath = globalAgentsPath();
-	if (existsSync(globalPath)) return globalPath;
-	return undefined;
+	return contextFileInDir(piUserDir());
 }
 
 export function findAgentsMdInParents(startDir: string): string | undefined {
 	let current = resolve(startDir);
 	while (true) {
-		const candidate = join(current, "AGENTS.md");
-		if (existsSync(candidate)) return candidate;
+		const candidate = contextFileInDir(current);
+		if (candidate) return candidate;
 		const parent = dirname(current);
 		if (parent === current) break;
 		current = parent;
@@ -47,7 +88,10 @@ export function extractAgentsAppend(): string | undefined {
 		if (!content) return undefined;
 		const sanitized = sanitizeAgentsContent(content);
 		return sanitized.length > 0 ? `# CLAUDE.md\n\n${sanitized}` : undefined;
-	} catch {
+	} catch (error) {
+		// An unreadable AGENTS.md silently drops the user's standing instructions
+		// from every child prompt — degrade as before, but leave a trace.
+		debug(`agents-md: failed to read ${agentsPath}:`, error instanceof Error ? error.message : String(error));
 		return undefined;
 	}
 }