@gajae-code/coding-agent 0.11.3 → 0.11.5

package/src/sdk/protocol/operation-inventory.generated.json

@@ -2809,6 +2809,17 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:promoteRecoveryHydrationAfterOwnershipReadyFence",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal owner-recovery authority transition after a durable writer fence, never a user-facing SDK operation",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:continuePersistedHistory",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",

package/src/sdk/session.ts

@@ -10,6 +10,7 @@ import {
 	ThinkingLevel,
 } from "@gajae-code/agent-core";
 import {
+	type AssistantMessage,
 	type AuthCredentialSelector,
 	type CredentialDisabledEvent,
 	type Message,
@@ -17,6 +18,7 @@ import {
 	type ProviderSessionState,
 	type SimpleStreamOptions,
 	streamSimple,
+	type ToolResultMessage,
 } from "@gajae-code/ai";
 import {
 	getOpenAICodexTransportDetails,
@@ -88,7 +90,7 @@ import { loadActiveSubskillTools } from "../extensibility/gjc-plugins/tools";
 import { loadSkills, type Skill, type SkillWarning, setActiveSkills } from "../extensibility/skills";
 import type { FileSlashCommand } from "../extensibility/slash-commands";
 import type { HindsightSessionState } from "../hindsight/state";
-import { LocalProtocolHandler, type LocalProtocolOptions } from "../internal-urls";
+import { initializeLocalRoot, LocalProtocolHandler, type LocalProtocolOptions } from "../internal-urls";
 import { resolveMemoryBackend } from "../memory-backend";
 import asyncResultTemplate from "../prompts/tools/async-result.md" with { type: "text" };
 import { AgentRegistry, MAIN_AGENT_ID } from "../registry/agent-registry";
@@ -105,10 +107,11 @@ import { NotificationSessionController } from "../sdk/bus/session-control";
 import { shouldHostSdk } from "../sdk/host";
 import {
 	collectEnvSecrets,
+	createSecretObfuscator,
 	deobfuscateSessionContext,
 	loadSecrets,
 	obfuscateMessages,
-	SecretObfuscator,
+	type SecretObfuscator,
 } from "../secrets";
 import { AgentSession, type ForkContextSeed } from "../session/agent-session";
 import { resolveAuthBrokerConfig } from "../session/auth-broker-config";
@@ -126,7 +129,7 @@ import {
 } from "../system-prompt";
 import { AgentOutputManager } from "../task/output-manager";
 import { parseThinkingLevel, resolveThinkingLevelForModel, toReasoningEffort } from "../thinking";
-import { isMCPBridgeTool } from "../tool-discovery/tool-index";
+import { isMCPBridgeTool, selectRestorableDiscoveredBuiltinToolNames } from "../tool-discovery/tool-index";
 import {
 	applyConfiguredSearchTimeout,
 	BashTool,
@@ -221,6 +224,57 @@ function buildAsyncResultBatchMessage(entries: AsyncResultEntry[]): CustomMessag
 	};
 }
 
+/**
+ * Reconcile a resumed transcript that ends on an unpaired tool call.
+ *
+ * When a subagent finishes by calling `yield` (or any turn is torn down right
+ * after a tool executes), the terminating abort can land before the tool
+ * result is persisted, leaving the saved session ending on an assistant
+ * `toolCall` with no matching `toolResult`. Replaying that history verbatim on
+ * resume produces an invalid provider request (a tool_use not followed by a
+ * tool_result) and the resumed turn fails immediately. Synthesize a placeholder
+ * result for any such trailing unpaired tool call so a resumed session always
+ * starts from a valid, paired history. No-op for well-formed transcripts.
+ */
+export function reconcileTrailingToolCalls(messages: AgentMessage[]): AgentMessage[] {
+	let lastAssistantIdx = -1;
+	for (let i = messages.length - 1; i >= 0; i--) {
+		if (messages[i].role === "assistant") {
+			lastAssistantIdx = i;
+			break;
+		}
+	}
+	if (lastAssistantIdx === -1) return messages;
+	const lastAssistant = messages[lastAssistantIdx] as AssistantMessage;
+	const toolCalls = lastAssistant.content.filter(
+		(part): part is Extract<AssistantMessage["content"][number], { type: "toolCall" }> => part.type === "toolCall",
+	);
+	if (toolCalls.length === 0) return messages;
+	const satisfied = new Set<string>();
+	for (let i = lastAssistantIdx + 1; i < messages.length; i++) {
+		const message = messages[i];
+		if (message.role === "toolResult") satisfied.add(message.toolCallId);
+	}
+	const missing = toolCalls.filter(toolCall => !satisfied.has(toolCall.id));
+	if (missing.length === 0) return messages;
+	const now = Date.now();
+	const synthesized: ToolResultMessage[] = missing.map(toolCall => ({
+		role: "toolResult",
+		toolCallId: toolCall.id,
+		toolName: toolCall.name,
+		content: [
+			{
+				type: "text",
+				text: "Tool result was not persisted before the previous turn ended; synthesized on resume to keep tool_use/tool_result pairing valid.",
+			},
+		],
+		details: {},
+		isError: false,
+		timestamp: now,
+	}));
+	return [...messages, ...synthesized];
+}
+
 function buildMcpNotificationBatchMessage(entries: McpNotificationEntry[]): AgentMessage | null {
 	const resources: McpNotificationEntry[] = [];
 	const seen = new Set<string>();
@@ -392,6 +446,8 @@ export interface CreateAgentSessionOptions {
 	notificationHostModeSupported?: boolean;
 	/** Whether this host mode can own the root SDK endpoint. Default: true. */
 	sdkHostModeSupported?: boolean;
+	/** Override configured Discord/Slack daemon readiness, primarily for embedded hosts and deterministic tests. */
+	ensureNotificationProviderDaemon?: (provider: "discord" | "slack", settings: Settings) => Promise<unknown>;
 
 	/**
 	 * Opt-in OpenTelemetry instrumentation forwarded to the underlying Agent.
@@ -926,6 +982,7 @@ const MCP_TOOLS_ONLY_MANAGER_SUBSESSION_ERROR = "tools-only MCP managers cannot
 const MCP_CONFIG_PATH_SUBSESSION_ERROR = "mcpConfigPath cannot be used in sub-sessions";
 const MAX_EXACT_MCP_TOOL_COLLISION_NAMES = 10;
 const MAX_EXACT_MCP_TOOL_NAME_LENGTH = 100;
+const pluginMcpManagerServers = new WeakMap<MCPManager, ReadonlySet<string>>();
 
 class ExactMcpToolNameCollisionError extends Error {
 	constructor(toolNames: Iterable<string>) {
@@ -1114,8 +1171,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		const sessionManager =
 			options.sessionManager ??
 			(await logger.time("sessionManager", async () => {
-				const sessionDir = SessionManager.getDefaultSessionDir(cwd, agentDir);
-				return SessionManager.create(cwd, sessionDir);
+				return SessionManager.create(cwd, SessionManager.managedDestination(cwd, agentDir));
 			}));
 		const logicalSessionId = sessionManager.getSessionId();
 		const providerSessionId = options.providerSessionId ?? options.forkContextSeed?.cacheIdentity ?? logicalSessionId;
@@ -1166,7 +1222,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			const envEntries = collectEnvSecrets();
 			const allEntries = [...envEntries, ...fileEntries];
 			if (allEntries.length > 0) {
-				obfuscator = new SecretObfuscator(allEntries);
+				obfuscator = createSecretObfuscator(allEntries);
 			}
 		}
 		const secretsEnabled = obfuscator?.hasSecrets() === true;
@@ -1427,6 +1483,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				return sessionManager.getCwd();
 			},
 			hasUI: options.hasUI ?? false,
+			workflowGateEligible: true,
 			enableLsp,
 			get hasEditTool() {
 				const requestedToolNames = options.toolNames
@@ -1449,6 +1506,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			trackEvalExecution: (execution, abortController) =>
 				session ? session.trackEvalExecution(execution, abortController) : execution,
 			getSessionId: () => sessionManager.getSessionId?.() ?? null,
+			isManagedSessionDestination: () => sessionManager.isManagedDestination(),
 			getActiveSkillState: () => session?.getActiveSkillState(),
 			getActiveSkillPhase: () => session?.getActiveSkillPhase(),
 			getHindsightSessionState: () => session?.getHindsightSessionState(),
@@ -1538,6 +1596,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			if (asyncJobManager) AsyncJobManager.setInstance(asyncJobManager);
 		}
 		if (options.localProtocolOptions) {
+			await initializeLocalRoot(options.localProtocolOptions);
 			disposeLocalProtocolOverride = LocalProtocolHandler.installOverride(options.localProtocolOptions);
 		}
 		toolSession.getArtifactsDir = getArtifactsDir;
@@ -1559,6 +1618,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		const explicitMcpConfigPath = !isCanonicalSubSession && !options.mcpManager ? options.mcpConfigPath : undefined;
 		const customTools: CustomTool[] = [];
 		const exactMcpToolNames: string[] = [];
+		const pluginMcpToolNames: string[] = [];
 
 		// Add image tools when the active model or configured image providers can generate images.
 		const imageGenTools = await logger.time("getImageGenTools", () => getImageGenTools(modelRegistry, model));
@@ -1670,6 +1730,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 							mcpManager = owned;
 							ownsMcpManager = true;
 							customTools.push(...(result.tools as CustomTool[]));
+							pluginMcpManagerServers.set(owned, new Set(result.connectedServers));
+							owned.sealConnectionSet();
+							pluginMcpToolNames.push(...result.tools.map(tool => tool.name));
 						} else {
 							await owned.disconnectAll().catch(() => {});
 						}
@@ -1694,8 +1757,16 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				try {
 					const inheritedTools = inherited.getTools();
 					if (inheritedTools.length > 0) customTools.push(...(inheritedTools as CustomTool[]));
+					const pluginServers = pluginMcpManagerServers.get(inherited);
+					if (pluginServers) {
+						pluginMcpToolNames.push(
+							...inheritedTools
+								.filter(tool => tool.mcpServerName !== undefined && pluginServers.has(tool.mcpServerName))
+								.map(tool => tool.name),
+						);
+					}
 				} catch (error) {
-					logger.warn("Failed to inherit plugin MCP tools in subagent", { error });
+					logger.warn("Failed to inherit MCP tools in subagent", { error });
 				}
 			}
 		}
@@ -1777,6 +1848,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						controller: notificationSessionController,
 						spawnedByGjc,
 						sdkHostModeSupported: options.sdkHostModeSupported,
+						ensureProviderDaemon: options.ensureNotificationProviderDaemon,
 						runEphemeralTurn: async (promptText, signal) => {
 							if (!session) throw new Error("Ephemeral turns are unavailable.");
 							const { replyText } = await session.runEphemeralTurn({ promptText, signal });
@@ -2121,15 +2193,17 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		};
 
 		const toolNamesFromRegistry = Array.from(toolRegistry.keys());
-		const requestedToolNames = options.toolNames
+		const hasExplicitToolNames = options.toolNames !== undefined;
+		const requestedToolNames = hasExplicitToolNames
 			? [
 					...new Set([
-						...options.toolNames.map(name => name.toLowerCase()),
+						...options.toolNames!.map(name => name.toLowerCase()),
 						...(settings.get("goal.enabled") ? ["goal"] : []),
 					]),
 				]
 			: toolNamesFromRegistry;
 		const normalizedRequested = requestedToolNames.filter(name => toolRegistry.has(name));
+		const explicitRequestedToolNames = hasExplicitToolNames ? normalizedRequested : [];
 		const requestedToolNameSet = new Set(normalizedRequested);
 		// Normalize the user-facing mcp.discoveryMode alias once at session construction.
 		const toolsDiscoveryModeSetting = settings.get("tools.discoveryMode");
@@ -2152,12 +2226,17 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		const discoveryDefaultServerToolNames: string[] = [];
 		let initialSelectedMCPToolNames: string[] = [];
 		let defaultSelectedMCPToolNames: string[] = [];
+		let initialBaselineDiscoveredBuiltinToolNames: string[] = [];
+		let initialSelectedDiscoveredBuiltinToolNames: string[] = [];
+		let hasExplicitMCPToolSelection = false;
+		let hasExplicitDiscoveredBuiltinToolSelection = false;
+		let explicitlyRequestedDiscoveredBuiltinToolNames: string[] = [];
 		if (mcpDiscoveryEnabled) {
 			const defaultServerNames = new Set(settings.get("mcp.discoveryDefaultServers") ?? []);
 			for (const tool of toolRegistry.values()) {
 				if (!isMCPBridgeTool(tool)) continue;
 				discoverableMCPToolNames.add(tool.name);
-				if (initialRequestedActiveToolNames.includes(tool.name)) {
+				if (explicitRequestedToolNames.includes(tool.name)) {
 					explicitlyRequestedMCPToolNames.push(tool.name);
 				}
 				const serverName = (tool as AgentTool & { mcpServerName?: string }).mcpServerName;
@@ -2166,21 +2245,34 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				}
 			}
 		}
+		const mandatoryMCPToolNameSet = new Set(pluginMcpToolNames);
+		const selectableExplicitMCPToolNames = explicitlyRequestedMCPToolNames.filter(
+			name => !mandatoryMCPToolNameSet.has(name),
+		);
 		let initialToolNames = [...initialRequestedActiveToolNames];
 		if (mcpDiscoveryEnabled) {
-			const restoredSelectedMCPToolNames = existingSession.selectedMCPToolNames.filter(name =>
-				toolRegistry.has(name),
+			const restoredSelectedMCPToolNames = existingSession.selectedMCPToolNames.filter(
+				name => toolRegistry.has(name) && !mandatoryMCPToolNameSet.has(name),
 			);
+			if (
+				existingSession.hasPersistedMCPToolSelection &&
+				restoredSelectedMCPToolNames.length !== existingSession.selectedMCPToolNames.length
+			) {
+				sessionManager.appendMCPToolSelection(restoredSelectedMCPToolNames);
+			}
 			defaultSelectedMCPToolNames = [
 				...new Set([
 					...discoveryDefaultServerToolNames,
-					...explicitlyRequestedMCPToolNames,
 					...(explicitMcpConfigPath !== undefined ? exactMcpToolNames : []),
 				]),
 			];
+			hasExplicitMCPToolSelection =
+				hasExplicitToolNames && (options.toolNames!.length === 0 || selectableExplicitMCPToolNames.length > 0);
 			initialSelectedMCPToolNames = existingSession.hasPersistedMCPToolSelection
 				? restoredSelectedMCPToolNames
-				: [...new Set([...restoredSelectedMCPToolNames, ...defaultSelectedMCPToolNames])];
+				: hasExplicitMCPToolSelection
+					? selectableExplicitMCPToolNames
+					: defaultSelectedMCPToolNames;
 			initialToolNames = [
 				...new Set([
 					...initialRequestedActiveToolNames.filter(name => !discoverableMCPToolNames.has(name)),
@@ -2189,13 +2281,17 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			];
 		}
 
-		// Custom tools and extension-registered tools are always included regardless of toolNames filter
+		// Custom, extension-registered, and plugin-bundle MCP tools are always
+		// included regardless of the caller's built-in tool filter. Plugin MCPs
+		// remain always-on even when generic MCP discovery is disabled.
 		const alwaysInclude: string[] = [
 			...(options.customTools?.map(t => (isCustomTool(t) ? t.name : t.name)) ?? []),
 			...registeredTools.filter(t => !t.definition.defaultInactive).map(t => t.definition.name),
+			...pluginMcpToolNames,
 		];
+		const pluginMcpToolNameSet = new Set(pluginMcpToolNames);
 		for (const name of alwaysInclude) {
-			if (mcpDiscoveryEnabled && discoverableMCPToolNames.has(name)) {
+			if (mcpDiscoveryEnabled && discoverableMCPToolNames.has(name) && !pluginMcpToolNameSet.has(name)) {
 				continue;
 			}
 			if (toolRegistry.has(name) && !initialToolNames.includes(name)) {
@@ -2208,19 +2304,39 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// The model finds them via search_tool_bm25 and activates them on demand.
 		if (effectiveDiscoveryMode === "all") {
 			const essentialBuiltinNames = new Set(computeEssentialBuiltinNames(settings));
-			const explicitlyRequestedToolNames = new Set(options.toolNames?.map(name => name.toLowerCase()) ?? []);
-			// Back-compat: persisted activations live under selectedMCPToolNames today (built-in
-			// activation persistence is a follow-up). MCP names won't collide with built-in names.
-			const restoredDiscoveredNames = new Set(existingSession.selectedMCPToolNames);
-			initialToolNames = initialToolNames.filter(name => {
+			const allowedDiscoveredBuiltinNames = options.discoverableToolAllowedNames
+				? new Set(options.discoverableToolAllowedNames.map(name => name.toLowerCase()))
+				: undefined;
+			const baselineInitialToolNames = initialToolNames.filter(name => {
 				const tool = toolRegistry.get(name);
 				if (!tool?.loadMode) return true; // not a built-in — leave MCP/custom/extension to existing logic
 				if (tool.loadMode === "essential") return true;
-				if (essentialBuiltinNames.has(name)) return true;
-				if (explicitlyRequestedToolNames.has(name)) return true;
-				if (restoredDiscoveredNames.has(name)) return true;
-				return false;
+				return essentialBuiltinNames.has(name);
 			});
+			explicitlyRequestedDiscoveredBuiltinToolNames = selectRestorableDiscoveredBuiltinToolNames(
+				explicitRequestedToolNames,
+				toolRegistry,
+				allowedDiscoveredBuiltinNames,
+			).filter(name => !essentialBuiltinNames.has(name));
+			const requestedDiscoveredBuiltinToolNameSet = new Set(explicitlyRequestedDiscoveredBuiltinToolNames);
+			initialBaselineDiscoveredBuiltinToolNames = selectRestorableDiscoveredBuiltinToolNames(
+				baselineInitialToolNames.filter(name => !requestedDiscoveredBuiltinToolNameSet.has(name)),
+				toolRegistry,
+				allowedDiscoveredBuiltinNames,
+			);
+			const restoredDiscoveredNames = selectRestorableDiscoveredBuiltinToolNames(
+				existingSession.selectedDiscoveredBuiltinToolNames ?? [],
+				toolRegistry,
+				allowedDiscoveredBuiltinNames,
+				essentialBuiltinNames,
+			);
+			initialSelectedDiscoveredBuiltinToolNames = existingSession.hasPersistedDiscoveredBuiltinToolSelection
+				? restoredDiscoveredNames
+				: explicitlyRequestedDiscoveredBuiltinToolNames;
+			initialToolNames = [...new Set([...baselineInitialToolNames, ...initialSelectedDiscoveredBuiltinToolNames])];
+			hasExplicitDiscoveredBuiltinToolSelection =
+				hasExplicitToolNames &&
+				(options.toolNames!.length === 0 || explicitlyRequestedDiscoveredBuiltinToolNames.length > 0);
 		}
 
 		// Pre-register in the global agent registry BEFORE building the system prompt,
@@ -2456,7 +2572,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 
 		// Restore messages if session has existing data
 		if (hasExistingSession) {
-			agent.replaceMessages(existingSession.messages);
+			agent.replaceMessages(reconcileTrailingToolCalls(existingSession.messages));
 		} else {
 			// Save initial model, thinking level, and service tier for new sessions so they can be restored on resume.
 			if (model) {
@@ -2521,8 +2637,16 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			mcpDiscoveryEnabled,
 			discoveryMode: effectiveDiscoveryMode,
 			initialSelectedMCPToolNames,
+			initialMCPToolSelectionIsExplicit: hasExplicitMCPToolSelection,
+			initialDiscoveredBuiltinToolSelectionIsExplicit: hasExplicitDiscoveredBuiltinToolSelection,
+			initialSelectedDiscoveredBuiltinToolNames,
+			initialBaselineDiscoveredBuiltinToolNames,
 			defaultSelectedMCPToolNames,
-			persistInitialMCPToolSelection: !hasExistingSession,
+			mandatoryMCPToolNames: pluginMcpToolNames,
+			persistInitialMCPToolSelection: !hasExistingSession && hasExplicitMCPToolSelection,
+			persistInitialDiscoveredBuiltinToolSelection: !hasExistingSession && hasExplicitDiscoveredBuiltinToolSelection,
+			initialPersistedMCPToolNames: selectableExplicitMCPToolNames,
+			initialPersistedDiscoveredBuiltinToolNames: explicitlyRequestedDiscoveredBuiltinToolNames,
 			defaultSelectedMCPServerNames: settings.get("mcp.discoveryDefaultServers") ?? [],
 			ttsrManager,
 			obfuscator,
@@ -2664,6 +2788,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			});
 		}
 
+		// Constructor-time workflow-gate tool restoration is deferred by one
+		// microtask (the ToolSession closure needs `session` assigned). Await it
+		// so a resumed canonical workflow session returns with `ask` resident.
+		await session.workflowGateToolRestoration;
 		return {
 			session,
 			extensionsResult,

package/src/secrets/index.ts

@@ -1,31 +1,60 @@
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { isEnoent, logger } from "@gajae-code/utils";
+import { isEnoent, logger, pathIsWithin } from "@gajae-code/utils";
 import { YAML } from "bun";
-import type { SecretEntry } from "./obfuscator";
+import { type SecretEntry, SecretObfuscator } from "./obfuscator";
 import { compileSecretRegex } from "./regex";
 
+const PROCESS_SECRET_OBFUSCATION_KEY = randomBytes(32);
+
+/** Create an obfuscator using the process-local authenticated-placeholder key. */
+export function createSecretObfuscator(entries: SecretEntry[]): SecretObfuscator {
+	return new SecretObfuscator(entries, PROCESS_SECRET_OBFUSCATION_KEY);
+}
 export { deobfuscateSessionContext, obfuscateMessages, type SecretEntry, SecretObfuscator } from "./obfuscator";
 
+type SecretsFileScope = "global" | "project";
+
 /**
  * Load secrets from project-local and global secrets.yml files.
- * Project-local entries override global entries with matching content.
+ * Project-local plain entries override global entries with matching content.
  */
 export async function loadSecrets(cwd: string, agentDir: string): Promise<SecretEntry[]> {
 	const projectPath = path.join(cwd, ".gjc", "secrets.yml");
 	const globalPath = path.join(agentDir, "secrets.yml");
+	const agentScope = await classifySecretsFileScope(cwd, agentDir);
 
-	const globalEntries = await loadSecretsFile(globalPath);
-	const projectEntries = await loadSecretsFile(projectPath);
+	const globalEntries = await loadSecretsFile(globalPath, agentScope);
+	const projectEntries = await loadSecretsFile(projectPath, "project");
 
 	if (globalEntries.length === 0) return projectEntries;
 	if (projectEntries.length === 0) return globalEntries;
 
-	// Merge: project overrides global by content match
-	const projectContents = new Set(projectEntries.map(e => e.content));
-	const merged = [...globalEntries.filter(e => !projectContents.has(e.content)), ...projectEntries];
+	// Project plain entries override matching global plain entries, never global regex entries.
+	const projectPlainContents = new Set(projectEntries.filter(e => e.type === "plain").map(e => e.content));
+	const merged = [
+		...globalEntries.filter(e => e.type === "regex" || !projectPlainContents.has(e.content)),
+		...projectEntries,
+	];
 	return merged;
 }
 
+function pathIsLexicallyWithin(root: string, candidate: string): boolean {
+	const relative = path.relative(path.resolve(root), path.resolve(candidate));
+	return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+async function classifySecretsFileScope(cwd: string, agentDir: string): Promise<SecretsFileScope> {
+	if (pathIsLexicallyWithin(cwd, agentDir)) return "project";
+	try {
+		const [canonicalCwd, canonicalAgentDir] = await Promise.all([fs.realpath(cwd), fs.realpath(agentDir)]);
+		return pathIsWithin(canonicalCwd, canonicalAgentDir) ? "project" : "global";
+	} catch {
+		return "project";
+	}
+}
+
 /** Minimum env var value length to consider as a secret. */
 const MIN_ENV_VALUE_LENGTH = 8;
 
@@ -46,7 +75,7 @@ export function collectEnvSecrets(): SecretEntry[] {
 	return entries;
 }
 
-async function loadSecretsFile(filePath: string): Promise<SecretEntry[]> {
+async function loadSecretsFile(filePath: string, scope: SecretsFileScope): Promise<SecretEntry[]> {
 	try {
 		const text = await Bun.file(filePath).text();
 		const raw = YAML.parse(text);
@@ -55,8 +84,13 @@ async function loadSecretsFile(filePath: string): Promise<SecretEntry[]> {
 			return [];
 		}
 		const entries: SecretEntry[] = [];
+		let skippedProjectRegexEntries = 0;
 		for (let i = 0; i < raw.length; i++) {
 			const entry = raw[i];
+			if (scope === "project" && isRegexEntry(entry)) {
+				skippedProjectRegexEntries++;
+				continue;
+			}
 			if (!validateEntry(entry, filePath, i)) continue;
 			entries.push({
 				type: entry.type,
@@ -66,6 +100,12 @@ async function loadSecretsFile(filePath: string): Promise<SecretEntry[]> {
 				flags: entry.flags,
 			});
 		}
+		if (skippedProjectRegexEntries > 0) {
+			logger.warn("Project secrets.yml regex entries are ignored; regex entries are global-only", {
+				path: filePath,
+				skippedEntries: skippedProjectRegexEntries,
+			});
+		}
 		return entries;
 	} catch (err) {
 		if (isEnoent(err)) return [];
@@ -74,6 +114,10 @@ async function loadSecretsFile(filePath: string): Promise<SecretEntry[]> {
 	}
 }
 
+function isRegexEntry(entry: unknown): boolean {
+	return entry !== null && typeof entry === "object" && (entry as Record<string, unknown>).type === "regex";
+}
+
 function validateEntry(entry: unknown, filePath: string, index: number): entry is SecretEntry {
 	if (entry === null || typeof entry !== "object") {
 		logger.warn(`secrets.yml[${index}]: entry must be an object`, { path: filePath });
@@ -106,7 +150,6 @@ function validateEntry(entry: unknown, filePath: string, index: number): entry i
 		} catch (error) {
 			logger.warn(`secrets.yml[${index}]: invalid regex pattern`, {
 				path: filePath,
-				pattern: e.content,
 				error: String(error),
 			});
 			return false;

package/src/secrets/obfuscator.ts

@@ -1,3 +1,4 @@
+import { createHmac, randomBytes } from "node:crypto";
 import type { Message, TextContent } from "@gajae-code/ai";
 import { type SessionContext, transferSessionMessageIdentity } from "../session/session-manager";
 import { compileSecretRegex } from "./regex";
@@ -39,28 +40,28 @@ function generateDeterministicReplacement(secret: string): string {
 // Placeholder format
 // ═══════════════════════════════════════════════════════════════════════════
 
-const HASH_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
-const HASH_LEN = 4;
-
-/** Build an obfuscation placeholder for secret index N. Deterministic `#HASH#` token. */
-function buildPlaceholder(index: number): string {
-	let v = Bun.hash.xxHash32(String(index), 0x5345_4352);
-	let tag = "#";
-	for (let i = 0; i < HASH_LEN; i++) {
-		tag += HASH_CHARS[v % HASH_CHARS.length];
-		v = Math.floor(v / HASH_CHARS.length);
-	}
-	return `${tag}#`;
+const PLACEHOLDER_DOMAIN = "gjc.secret-obfuscation.placeholder.v1\0";
+const PLACEHOLDER_RE = /#GJC1_[A-Za-z0-9_-]{22}#/g;
+
+/** Build a versioned, authenticated placeholder whose identity depends only on the key and secret. */
+function buildPlaceholder(secret: string, key: Uint8Array): string {
+	const tag = createHmac("sha256", key)
+		.update(PLACEHOLDER_DOMAIN)
+		.update(secret, "utf8")
+		.digest()
+		.subarray(0, 16)
+		.toString("base64url");
+	return `#GJC1_${tag}#`;
 }
 
-/** Regex to match obfuscation placeholders: #HASH# */
-const PLACEHOLDER_RE = /#[A-Z0-9]{4}#/g;
-
 // ═══════════════════════════════════════════════════════════════════════════
 // SecretObfuscator
 // ═══════════════════════════════════════════════════════════════════════════
 
 export class SecretObfuscator {
+	/** Key used to authenticate reversible placeholders. */
+	#placeholderKey: Uint8Array;
+
 	/** Plain secrets: secret → index (known at construction) */
 	#plainMappings = new Map<string, number>();
 
@@ -97,14 +98,16 @@ export class SecretObfuscator {
 	/** Whether any secrets were configured */
 	#hasAny: boolean;
 
-	constructor(entries: SecretEntry[]) {
+	constructor(entries: SecretEntry[], key: Uint8Array = randomBytes(32)) {
+		if (key.byteLength !== 32) throw new Error("Secret obfuscation key must be 32 bytes");
+		this.#placeholderKey = Uint8Array.from(key);
 		let index = 0;
 		for (const entry of entries) {
 			const mode = entry.mode ?? "obfuscate";
 
 			if (entry.type === "plain") {
 				if (mode === "obfuscate") {
-					const placeholder = buildPlaceholder(index);
+					const placeholder = buildPlaceholder(entry.content, this.#placeholderKey);
 					this.#plainMappings.set(entry.content, index);
 					this.#obfuscateMappings.set(index, { secret: entry.content, placeholder });
 					this.#deobfuscateMap.set(placeholder, entry.content);
@@ -172,7 +175,7 @@ export class SecretObfuscator {
 					let index = this.#findObfuscateIndex(matchValue);
 					if (index === undefined) {
 						index = this.#nextIndex++;
-						const placeholder = buildPlaceholder(index);
+						const placeholder = buildPlaceholder(matchValue, this.#placeholderKey);
 						this.#obfuscateMappings.set(index, { secret: matchValue, placeholder });
 						this.#deobfuscateMap.set(placeholder, matchValue);
 						this.#obfuscateIndexBySecret.set(matchValue, index);

package/src/secrets/regex.ts

@@ -16,6 +16,8 @@ export function compileSecretRegex(pattern: string, flags?: string): RegExp {
 		const combined = new Set([...resolvedFlags, ...literalMatch[2]]);
 		resolvedFlags = [...combined].join("");
 	}
+	if (resolvedFlags.includes("y"))
+		throw new SyntaxError('The sticky "y" flag is incompatible with globally scanned secret regexes');
 
 	return new RegExp(resolvedPattern, enforceGlobalFlag(resolvedFlags));
 }