@gajae-code/coding-agent 0.15.2 → 0.15.3

package/src/sdk/bus/telegram-daemon.ts

@@ -273,6 +273,8 @@ export const ASK_CONTROLS_CAPABILITY = "ask_controls_v1";
 export const TOOL_ACTIVITY_CAPABILITY = "tool_activity_v2";
 /** Receive-only compatibility capability for pre-v2 hosts. */
 export const LEGACY_TOOL_ACTIVITY_CAPABILITY = "tool_activity_v1";
+/** Opts notification adapters into positioned-only delivery for matching live effects. */
+export const POSITIONED_NOTIFICATION_EFFECTS_CAPABILITY = "positioned_notification_effects_v1";
 type ToolActivityCapability = "v1" | "v2";
 
 function negotiateToolActivityCapability(
@@ -5261,6 +5263,7 @@ export class TelegramNotificationDaemon {
 					ASK_SELECTED_ACK_CAPABILITY,
 					TOOL_ACTIVITY_CAPABILITY,
 					LEGACY_TOOL_ACTIVITY_CAPABILITY,
+					POSITIONED_NOTIFICATION_EFFECTS_CAPABILITY,
 					"ephemeral_turn_v1",
 				],
 			});

package/src/sdk/cli/session-cli.ts

@@ -11,6 +11,7 @@ import type {
 	SessionLifecycleOperation,
 	SessionLifecycleSavedSession,
 	SessionLifecycleSavedSessionIdentity,
+	SessionReconcileUncertainTarget,
 } from "../lifecycle/service";
 import { PROMPT_CLIENT_REF_MAX_LENGTH } from "../prompt-status";
 import { validateAdapterControl, validateAdapterSecretFields } from "../protocol/adapter-validation";
@@ -36,6 +37,7 @@ export type SdkSessionCliAction =
 	| "send"
 	| "status"
 	| "tail"
+	| "retire"
 	| "raw"
 	| "control"
 	| "query"
@@ -209,7 +211,8 @@ function isLifecycleOperation(operation: string): operation is LifecycleMutation
 		operation === "session.fork" ||
 		operation === "session.resume" ||
 		operation === "session.close" ||
-		operation === "session.delete"
+		operation === "session.delete" ||
+		operation === "session.reconcile_uncertain"
 	);
 }
 
@@ -1294,11 +1297,16 @@ function lifecycleMutationRequest(
 			2,
 		);
 	const target = input as JsonRecord & { sessionId: string };
-	return operation === "session.resume"
-		? { ...base, operation, capability: operation, target }
-		: operation === "session.close"
-			? { ...base, operation, capability: operation, target }
-			: { ...base, operation, capability: "session.delete", target };
+	if (operation === "session.resume") return { ...base, operation, capability: operation, target };
+	if (operation === "session.close") return { ...base, operation, capability: operation, target };
+	if (operation === "session.reconcile_uncertain")
+		return {
+			...base,
+			operation,
+			capability: operation,
+			target: input as unknown as SessionReconcileUncertainTarget,
+		};
+	return { ...base, operation, capability: "session.delete", target };
 }
 
 async function runRawGlobal(
@@ -1346,6 +1354,7 @@ export async function runSdkSessionCli(
 			action !== "send" &&
 			action !== "status" &&
 			action !== "tail" &&
+			action !== "retire" &&
 			action !== "raw" &&
 			action !== "control" &&
 			action !== "query" &&
@@ -1353,7 +1362,7 @@ export async function runSdkSessionCli(
 		)
 			throw new SdkSessionCliError(
 				"usage",
-				"Expected one of: list, inspect, send, status, tail, raw (control|query|global).",
+				"Expected one of: list, inspect, send, status, tail, retire, raw (control|query|global).",
 				2,
 			);
 		const agentDir = args.agentDir ?? getAgentDir();
@@ -1390,6 +1399,24 @@ export async function runSdkSessionCli(
 			);
 			return;
 		}
+		if (action === "retire") {
+			const sessionId = requireValue(args.sessionId, "<sessionId>");
+			const input = await inputFromArgs(args);
+			if (input.sessionId !== undefined && input.sessionId !== sessionId)
+				throw new SdkSessionCliError(
+					"invalid_input",
+					"Retirement sessionId does not match the selected session.",
+					2,
+				);
+			const secretError = validateAdapterSecretFields("session.reconcile_uncertain", input);
+			if (secretError) throw new SdkSessionCliError(secretError.code, secretError.message, 2);
+			writeOutput(
+				stripSecretFields(
+					await runRawGlobal(agentDir, "session.reconcile_uncertain", { ...input, sessionId }, args),
+				),
+			);
+			return;
+		}
 
 		const kind = rawKind(requireValue(action, "<verb>"), args);
 		if (!kind) throw new SdkSessionCliError("usage", "raw requires one of: control, query, global.", 2);

package/src/sdk/lifecycle/service.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import path from "node:path";
 import {
 	SessionListTraversalError,
 	type SessionListTraversalPage,
@@ -12,6 +13,7 @@ export type SessionLifecycleOperation =
 	| "session.resume"
 	| "session.close"
 	| "session.delete"
+	| "session.reconcile_uncertain"
 	| "session.list";
 
 export interface SessionLifecycleActor {
@@ -117,6 +119,18 @@ export interface SessionCloseTarget {
 	readonly endpointIncarnation?: string;
 }
 
+export interface SessionReconcileUncertainTarget {
+	readonly sessionId: string;
+	readonly cwd: string;
+	readonly stateRoot: string;
+	readonly endpointGeneration: number;
+	readonly endpointMtimeMs: number;
+	readonly processIncarnation: string;
+	readonly hostIncarnation: string;
+	readonly lifecycleRequestId: string;
+	readonly remoteCreateKey: string;
+}
+
 export interface SessionDeleteTarget {
 	readonly sessionId: string;
 	readonly cwd?: string;
@@ -146,6 +160,10 @@ export type SessionForkRequest = SessionLifecycleMutationRequestBase<"session.fo
 export type SessionResumeRequest = SessionLifecycleMutationRequestBase<"session.resume", SessionResumeTarget>;
 export type SessionCloseRequest = SessionLifecycleMutationRequestBase<"session.close", SessionCloseTarget>;
 export type SessionDeleteRequest = SessionLifecycleMutationRequestBase<"session.delete", SessionDeleteTarget>;
+export type SessionReconcileUncertainRequest = SessionLifecycleMutationRequestBase<
+	"session.reconcile_uncertain",
+	SessionReconcileUncertainTarget
+>;
 export interface SessionListRequest {
 	readonly operation: "session.list";
 	readonly actor: SessionLifecycleActor;
@@ -161,7 +179,8 @@ export type SessionLifecycleMutationRequest =
 	| SessionForkRequest
 	| SessionResumeRequest
 	| SessionCloseRequest
-	| SessionDeleteRequest;
+	| SessionDeleteRequest
+	| SessionReconcileUncertainRequest;
 
 export type SessionLifecycleCertainty = "terminal" | "retryable" | "cleanup_pending" | "uncertain";
 
@@ -213,6 +232,11 @@ export interface SessionDeleteResult {
 	readonly operation: "session.delete";
 	readonly result: SessionLifecycleSessionResult;
 }
+export interface SessionReconcileUncertainResult {
+	readonly ok: true;
+	readonly operation: "session.reconcile_uncertain";
+	readonly result: SessionLifecycleSessionResult;
+}
 export interface SessionListSuccessResult {
 	readonly ok: true;
 	readonly operation: "session.list";
@@ -254,6 +278,12 @@ export type SessionDeleteFailure = {
 	readonly certainty: SessionLifecycleCertainty;
 	readonly error: SessionLifecycleError;
 };
+export type SessionReconcileUncertainFailure = {
+	readonly ok: false;
+	readonly operation: "session.reconcile_uncertain";
+	readonly certainty: SessionLifecycleCertainty;
+	readonly error: SessionLifecycleError;
+};
 export type SessionListFailure = {
 	readonly ok: false;
 	readonly operation: "session.list";
@@ -266,6 +296,7 @@ export type SessionForkOutcome = SessionForkResult | SessionForkFailure;
 export type SessionResumeOutcome = SessionResumeResult | SessionResumeFailure;
 export type SessionCloseOutcome = SessionCloseResult | SessionCloseFailure;
 export type SessionDeleteOutcome = SessionDeleteResult | SessionDeleteFailure;
+export type SessionReconcileUncertainOutcome = SessionReconcileUncertainResult | SessionReconcileUncertainFailure;
 export type SessionListOutcome = SessionListSuccessResult | SessionListFailure;
 export type SessionLifecycleResult =
 	| SessionCreateOutcome
@@ -273,6 +304,7 @@ export type SessionLifecycleResult =
 	| SessionResumeOutcome
 	| SessionCloseOutcome
 	| SessionDeleteOutcome
+	| SessionReconcileUncertainOutcome
 	| SessionListOutcome;
 
 /** Shared, side-effect-free validation for lifecycle mutation requests. */
@@ -288,7 +320,8 @@ export type SessionLifecycleMutationValidation =
 	| SessionForkFailure
 	| SessionResumeFailure
 	| SessionCloseFailure
-	| SessionDeleteFailure;
+	| SessionDeleteFailure
+	| SessionReconcileUncertainFailure;
 
 const RETRYABLE_BROKER_ERRORS = new Set([
 	"unavailable",
@@ -338,6 +371,7 @@ function operationOf(value: unknown): SessionLifecycleOperation {
 		value === "session.resume" ||
 		value === "session.close" ||
 		value === "session.delete" ||
+		value === "session.reconcile_uncertain" ||
 		value === "session.list"
 	)
 		return value;
@@ -376,6 +410,33 @@ function validTarget(target: unknown): target is Readonly<Record<string, unknown
 	return isRecord(target);
 }
 
+export function validateSessionReconcileUncertainTarget(value: unknown): value is SessionReconcileUncertainTarget {
+	if (!isRecord(value)) return false;
+	const target = value;
+	const bounded = (value: unknown, max: number): value is string =>
+		typeof value === "string" && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/u.test(value);
+	return (
+		bounded(target.sessionId, 256) &&
+		/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(target.sessionId) &&
+		bounded(target.cwd, 4096) &&
+		path.isAbsolute(target.cwd) &&
+		bounded(target.stateRoot, 4096) &&
+		path.isAbsolute(target.stateRoot) &&
+		path.resolve(target.stateRoot) === path.join(path.resolve(target.cwd), ".gjc", "state") &&
+		typeof target.endpointGeneration === "number" &&
+		Number.isSafeInteger(target.endpointGeneration) &&
+		target.endpointGeneration > 0 &&
+		typeof target.endpointMtimeMs === "number" &&
+		Number.isFinite(target.endpointMtimeMs) &&
+		target.endpointMtimeMs > 0 &&
+		bounded(target.processIncarnation, 256) &&
+		bounded(target.hostIncarnation, 256) &&
+		bounded(target.lifecycleRequestId, 128) &&
+		/^[A-Za-z0-9._-]+$/u.test(target.lifecycleRequestId) &&
+		bounded(target.remoteCreateKey, 256)
+	);
+}
+
 /** Validates lifecycle authority and shape without contacting the Broker. */
 export function validateSessionLifecycleMutationRequest(request: unknown): SessionLifecycleMutationValidation {
 	const record = isRecord(request) ? request : {};
@@ -390,6 +451,13 @@ export function validateSessionLifecycleMutationRequest(request: unknown): Sessi
 		return failure(operation, "terminal", "capability_denied", `capability does not authorize ${operation}`);
 	if (!validTarget(record.target))
 		return failure(operation, "terminal", "invalid_request", "target must be an object");
+	if (operation === "session.reconcile_uncertain" && !validateSessionReconcileUncertainTarget(record.target))
+		return failure(
+			operation,
+			"terminal",
+			"invalid_request",
+			"session.reconcile_uncertain target must carry complete identity-bound retirement proof",
+		);
 	return {
 		ok: true,
 		operation,
@@ -439,6 +507,28 @@ function sessionResult(value: unknown, expectedSessionId?: string): SessionLifec
 	return result;
 }
 
+function reconcileUncertainResult(
+	value: unknown,
+	target: SessionReconcileUncertainTarget,
+): SessionLifecycleSessionResult | undefined {
+	if (!isRecord(value)) return undefined;
+	if (
+		value.sessionId !== target.sessionId ||
+		value.retired !== true ||
+		value.ledgerState !== "terminal_error" ||
+		value.indexType !== "session_closed" ||
+		value.stateRoot !== target.stateRoot ||
+		value.endpointGeneration !== target.endpointGeneration ||
+		value.endpointMtimeMs !== target.endpointMtimeMs ||
+		value.processIncarnation !== target.processIncarnation ||
+		value.hostIncarnation !== target.hostIncarnation ||
+		value.lifecycleRequestId !== target.lifecycleRequestId ||
+		value.remoteCreateKey !== target.remoteCreateKey
+	)
+		return undefined;
+	return { sessionId: target.sessionId, endpointGeneration: target.endpointGeneration };
+}
+
 function savedSessionTranscriptIdentity(value: unknown): SessionLifecycleSavedSessionIdentity | undefined {
 	if (!isRecord(value)) return undefined;
 	const { dev, ino, nlink, size, mtimeMs, mtimeNs, ctimeNs, sha256 } = value;
@@ -588,20 +678,39 @@ export class SessionLifecycleService {
 		this.#client = client;
 	}
 
-	async execute(
+	async #execute(
 		request: SessionLifecycleMutationRequest,
+		idempotencyKeyOverride?: string,
 	): Promise<
-		SessionCreateOutcome | SessionForkOutcome | SessionResumeOutcome | SessionCloseOutcome | SessionDeleteOutcome
+		| SessionCreateOutcome
+		| SessionForkOutcome
+		| SessionResumeOutcome
+		| SessionCloseOutcome
+		| SessionDeleteOutcome
+		| SessionReconcileUncertainOutcome
 	> {
 		const validation = validateSessionLifecycleMutationRequest(request);
 		if (!validation.ok) return validation;
 		const { operation, actor, requestKey, target } = validation;
-		const idempotencyKey = deriveSessionLifecycleIdempotencyKey(actor, requestKey, operation);
+		const normalizedTarget =
+			operation === "session.reconcile_uncertain"
+				? {
+						...target,
+						cwd: path.resolve((target as unknown as SessionReconcileUncertainTarget).cwd),
+						stateRoot: path.join(
+							path.resolve((target as unknown as SessionReconcileUncertainTarget).cwd),
+							".gjc",
+							"state",
+						),
+					}
+				: target;
+		const idempotencyKey =
+			idempotencyKeyOverride ?? deriveSessionLifecycleIdempotencyKey(actor, requestKey, operation);
 		let response: unknown;
 		try {
 			response = await this.#client.global(
 				operation,
-				{ ...target },
+				{ ...normalizedTarget },
 				{
 					idempotencyKey,
 					...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
@@ -619,12 +728,21 @@ export class SessionLifecycleService {
 		if (!isRecord(response) || response.ok !== true)
 			return failure(operation, "uncertain", "malformed_response", "lifecycle broker returned a malformed response");
 		const expectedSessionId =
-			operation === "session.resume" || operation === "session.close" || operation === "session.delete"
-				? typeof target.sessionId === "string"
-					? target.sessionId
+			operation === "session.resume" ||
+			operation === "session.close" ||
+			operation === "session.delete" ||
+			operation === "session.reconcile_uncertain"
+				? typeof normalizedTarget.sessionId === "string"
+					? normalizedTarget.sessionId
 					: undefined
 				: undefined;
-		const parsed = sessionResult(brokerSuccess(response), expectedSessionId);
+		const parsed =
+			operation === "session.reconcile_uncertain"
+				? reconcileUncertainResult(
+						brokerSuccess(response),
+						normalizedTarget as unknown as SessionReconcileUncertainTarget,
+					)
+				: sessionResult(brokerSuccess(response), expectedSessionId);
 		if (!parsed)
 			return failure(
 				operation,
@@ -637,7 +755,35 @@ export class SessionLifecycleService {
 			| SessionForkOutcome
 			| SessionResumeOutcome
 			| SessionCloseOutcome
-			| SessionDeleteOutcome;
+			| SessionDeleteOutcome
+			| SessionReconcileUncertainOutcome;
+	}
+
+	async execute(
+		request: SessionLifecycleMutationRequest,
+	): Promise<
+		| SessionCreateOutcome
+		| SessionForkOutcome
+		| SessionResumeOutcome
+		| SessionCloseOutcome
+		| SessionDeleteOutcome
+		| SessionReconcileUncertainOutcome
+	> {
+		return this.#execute(request);
+	}
+
+	async executeWithIdempotencyKey(
+		request: SessionLifecycleMutationRequest,
+		idempotencyKey: string,
+	): Promise<
+		| SessionCreateOutcome
+		| SessionForkOutcome
+		| SessionResumeOutcome
+		| SessionCloseOutcome
+		| SessionDeleteOutcome
+		| SessionReconcileUncertainOutcome
+	> {
+		return this.#execute(request, idempotencyKey);
 	}
 
 	async create(request: Omit<SessionCreateRequest, "operation">): Promise<SessionCreateOutcome> {
@@ -660,6 +806,15 @@ export class SessionLifecycleService {
 		return (await this.execute({ ...request, operation: "session.delete" })) as SessionDeleteOutcome;
 	}
 
+	async reconcileUncertain(
+		request: Omit<SessionReconcileUncertainRequest, "operation">,
+	): Promise<SessionReconcileUncertainOutcome> {
+		return (await this.execute({
+			...request,
+			operation: "session.reconcile_uncertain",
+		})) as SessionReconcileUncertainOutcome;
+	}
+
 	async list(request: Omit<SessionListRequest, "operation">): Promise<SessionListOutcome> {
 		if (!validActor((request as { actor?: unknown }).actor))
 			return failure("session.list", "terminal", "unauthorized", "authenticated actor is required");

package/src/sdk/mcp/server.ts

@@ -158,7 +158,8 @@ function isLifecycleOperation(operation: string): operation is LifecycleMutation
 		operation === "session.fork" ||
 		operation === "session.resume" ||
 		operation === "session.close" ||
-		operation === "session.delete"
+		operation === "session.delete" ||
+		operation === "session.reconcile_uncertain"
 	);
 }
 

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

@@ -1079,6 +1079,24 @@
 			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
 		]
 	},
+	{
+		"sourceId": "registry:G08",
+		"sourceFile": "packages/coding-agent/src/sdk/protocol/operation-registry.ts",
+		"sourceKind": "registry",
+		"decision": "include",
+		"sdkId": "session.reconcile_uncertain",
+		"adapterMappings": {
+			"telegram": "prohibited",
+			"discord": "prohibited",
+			"slack": "prohibited",
+			"mcp": "generic_safe",
+			"acp": "generic_safe",
+			"daemonCli": "generic_safe"
+		},
+		"testIds": [
+			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
+		]
+	},
 	{
 		"sourceId": "registry:Q01",
 		"sourceFile": "packages/coding-agent/src/sdk/protocol/operation-registry.ts",
@@ -1727,6 +1745,17 @@
 			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
 		]
 	},
+	{
+		"sourceId": "slash_command:aside",
+		"sourceFile": "packages/coding-agent/src/slash-commands/builtin-registry.ts",
+		"sourceKind": "slash_command",
+		"decision": "exclude",
+		"rationale": "explicit user-owned external CLI process launcher; not a credential-free SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "slash_command:import-session",
 		"sourceFile": "packages/coding-agent/src/slash-commands/builtin-registry.ts",
@@ -2874,6 +2903,17 @@
 			"packages/coding-agent/test/sdk-operation-inventory.test.ts"
 		]
 	},
+	{
+		"sourceId": "agent_session:isExplicitEmptyToolSelection",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal tool-selection predicate used to preserve the --no-tools boundary, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:getToolByName",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",

package/src/sdk/protocol/operation-registry.ts

@@ -135,6 +135,7 @@ const globals = [
 	["session.resume", "Resume a saved session."],
 	["session.close", "Close a saved session."],
 	["session.delete", "Delete a saved session."],
+	["session.reconcile_uncertain", "Retire an indexed terminalUncertain create effect after dead-host proof."],
 ] as const;
 
 const queries = [
@@ -349,7 +350,7 @@ export const OPERATIONS: readonly Operation[] = [
 							acp: "machine_only",
 							daemonCli: "machine_only",
 						})
-					: ["G03", "G04", "G05", "G06", "G07"].includes(id)
+					: ["G03", "G04", "G05", "G06", "G07", "G08"].includes(id)
 						? dispositions({ telegram: "prohibited", discord: "prohibited", slack: "prohibited" })
 						: dispositions(),
 			testIds: ["packages/coding-agent/test/sdk-operation-inventory.test.ts"],

package/src/sdk/session.ts

@@ -59,6 +59,7 @@ import { kNoAuth, ModelRegistry } from "../config/model-registry";
 import {
 	formatModelString,
 	parseModelPattern,
+	parseModelString,
 	resolveAllowedModels,
 	resolveModelChainWithAuth,
 	resolveModelRoleValue,
@@ -430,6 +431,8 @@ export interface CreateAgentSessionOptions {
 	authStorage?: AuthStorage;
 	/** Model registry. Default: discoverModels(authStorage, agentDir) */
 	modelRegistry?: ModelRegistry;
+	/** @internal Allows the first-party CLI root to mutate its own registry and observe an admission attempt. */
+	modelRegistryStartupMutation?: { owner: "cli-root"; onAttempt(): void };
 
 	/** Model to use. Default: from settings, else first available */
 	model?: Model;
@@ -1442,7 +1445,45 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		const runtimeServices = createOptionalRuntimeServices(settings, options.runtimeServices, { cwd: getLiveCwd });
 		modelRegistry.applyConfiguredModelBindings(settings);
 		logger.time("initializeWithSettings", initializeWithSettings, settings);
-		if (!options.modelRegistry) {
+		const startupModelReference =
+			options.model === undefined
+				? options.modelPattern
+					? parseModelString(options.modelPattern)
+					: undefined
+				: options.modelRegistryStartupMutation?.owner === "cli-root"
+					? { provider: options.model.provider, id: options.model.id }
+					: undefined;
+		const startupRegistryMutationAuthorized =
+			options.modelRegistry === undefined || options.modelRegistryStartupMutation?.owner === "cli-root";
+		const startupCredentialSelector =
+			startupModelReference &&
+			options.credentialSelector &&
+			(!options.credentialSelector.provider ||
+				options.credentialSelector.provider.toLowerCase() === startupModelReference.provider.toLowerCase())
+				? options.credentialSelector.selector
+				: undefined;
+		const startupCredentialProviderMismatch =
+			startupModelReference !== undefined &&
+			options.credentialSelector?.provider !== undefined &&
+			options.credentialSelector.provider.toLowerCase() !== startupModelReference.provider.toLowerCase();
+		const attemptedStartupCacheAdmission =
+			startupModelReference !== undefined &&
+			startupRegistryMutationAuthorized &&
+			options.credentialSelector !== undefined &&
+			modelRegistry.requiresStoredLiteralCredentialCacheAdmission(
+				startupModelReference.provider,
+				startupModelReference.id,
+			);
+		if (attemptedStartupCacheAdmission) options.modelRegistryStartupMutation?.onAttempt();
+		if (startupModelReference && startupCredentialSelector) {
+			if (attemptedStartupCacheAdmission) {
+				modelRegistry.admitCachedProviderForStoredLiteralCredential(
+					startupModelReference.provider,
+					startupCredentialSelector,
+				);
+			}
+		}
+		if (!options.modelRegistry && !attemptedStartupCacheAdmission) {
 			modelRegistry.refreshInBackground();
 		}
 		// Resolve the workspace tree through its runtime service. The compatibility
@@ -3254,8 +3295,41 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			extensionsResult.runtime.pendingProviderRegistrations = [];
 		}
 
+		let startupCredentialModelRejected = false;
+		if (startupModelReference && (startupCredentialSelector || startupCredentialProviderMismatch)) {
+			const validated =
+				!startupCredentialProviderMismatch &&
+				startupCredentialSelector !== undefined &&
+				modelRegistry.validateModelForStoredLiteralCredential(
+					startupModelReference.provider,
+					startupModelReference.id,
+					startupCredentialSelector,
+				);
+			const currentStartupModel = modelRegistry.find(startupModelReference.provider, startupModelReference.id);
+			const providerMismatchRejectsTarget =
+				startupCredentialProviderMismatch &&
+				modelRegistry.requiresStoredLiteralCredentialCacheAdmission(
+					startupModelReference.provider,
+					startupModelReference.id,
+				);
+			if (
+				(!validated && (startupCredentialSelector !== undefined || providerMismatchRejectsTarget)) ||
+				!currentStartupModel
+			) {
+				startupCredentialModelRejected = true;
+				if (model?.provider === startupModelReference.provider && model.id === startupModelReference.id) {
+					model = undefined;
+				}
+				modelFallbackMessage = `Model "${
+					options.modelPattern ?? `${startupModelReference.provider}/${startupModelReference.id}`
+				}" not found`;
+			} else if (model?.provider === startupModelReference.provider && model.id === startupModelReference.id) {
+				model = currentStartupModel;
+			}
+		}
+
 		// Resolve deferred --model pattern now that extension models are registered.
-		if (!model && options.modelPattern) {
+		if (!model && options.modelPattern && !startupCredentialModelRejected) {
 			const availableModels = modelRegistry.getAll();
 			const matchPreferences = {
 				usageOrder: settings.getStorage()?.getModelUsageOrder(),
@@ -3290,7 +3364,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// Fall back to first available model with a valid API key, honoring the
 		// path-scoped `enabledModels` allow-list when configured. Skip when the
 		// user explicitly requested a model via --model that wasn't found.
-		if (!model && !options.modelPattern) {
+		if (!model && !options.modelPattern && !startupCredentialModelRejected) {
 			// Re-resolve the allowed set: extension factories above may have
 			// registered providers/models that weren't visible at startup.
 			const fallbackCandidates = await resolveAllowedModels(modelRegistry, settings, modelMatchPreferences);
@@ -3660,11 +3734,18 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 
 		const toolNamesFromRegistry = Array.from(toolRegistry.keys());
 		const hasExplicitToolNames = options.toolNames !== undefined;
+		const hasExplicitEmptyToolSelection = hasExplicitToolNames && options.toolNames!.length === 0;
+		// `goal` is session state rather than a work tool, so it is folded into an
+		// explicit selection that already asks for tools. An *empty* explicit
+		// selection is the `--no-tools` contract ("Disable all built-in tools", see
+		// cli/root-flags.ts), and re-populating it with `goal` would leave exactly one
+		// built-in tool live against that promise.
+		const wantsGoalStateTool = hasExplicitToolNames && options.toolNames!.length > 0;
 		const requestedToolNames = hasExplicitToolNames
 			? [
 					...new Set([
 						...options.toolNames!.map(name => name.toLowerCase()),
-						...(settings.get("goal.enabled") ? ["goal"] : []),
+						...(wantsGoalStateTool && settings.get("goal.enabled") ? ["goal"] : []),
 					]),
 				]
 			: toolNamesFromRegistry;
@@ -3804,9 +3885,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				allowedDiscoveredBuiltinNames,
 				essentialBuiltinNames,
 			);
-			initialSelectedDiscoveredBuiltinToolNames = existingSession.hasPersistedDiscoveredBuiltinToolSelection
-				? restoredDiscoveredNames
-				: explicitlyRequestedDiscoveredBuiltinToolNames;
+			initialSelectedDiscoveredBuiltinToolNames = hasExplicitEmptyToolSelection
+				? []
+				: existingSession.hasPersistedDiscoveredBuiltinToolSelection
+					? restoredDiscoveredNames
+					: explicitlyRequestedDiscoveredBuiltinToolNames;
 			initialToolNames = [...new Set([...baselineInitialToolNames, ...initialSelectedDiscoveredBuiltinToolNames])];
 			hasExplicitDiscoveredBuiltinToolSelection =
 				hasExplicitToolNames &&
@@ -4163,6 +4246,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			},
 			reloadSshTool,
 			requestedToolNames: requestedToolNameSet,
+			explicitEmptyToolSelection: hasExplicitEmptyToolSelection,
 			discoverableToolAllowedNames: options.discoverableToolAllowedNames,
 			mcpDiscoveryEnabled,
 			discoveryMode: effectiveDiscoveryMode,