claude-code/src/main.tsx

// These side-effects must run before all other imports:
// 1. profileCheckpoint marks entry before heavy module evaluation begins
// 2. startMdmRawRead fires MDM subprocesses (plutil/reg query) so they run in
//    parallel with the remaining ~135ms of imports below
// 3. startKeychainPrefetch fires both macOS keychain reads (OAuth + legacy API
//    key) in parallel — isRemoteManagedSettingsEligible() otherwise reads them
//    sequentially via sync spawn inside applySafeConfigEnvironmentVariables()
//    (~65ms on every macOS startup)
import { profileCheckpoint, profileReport } from "./utils/startupProfiler.js";

// eslint-disable-next-line custom-rules/no-top-level-side-effects
profileCheckpoint("main_tsx_entry");

import { startMdmRawRead } from "./utils/settings/mdm/rawRead.js";

// eslint-disable-next-line custom-rules/no-top-level-side-effects
startMdmRawRead();

import {
	ensureKeychainPrefetchCompleted,
	startKeychainPrefetch,
} from "./utils/secureStorage/keychainPrefetch.js";

// eslint-disable-next-line custom-rules/no-top-level-side-effects
startKeychainPrefetch();

import { feature } from "bun:bundle";
import {
  Command as CommanderCommand,
  InvalidArgumentError,
  Option,
} from '@commander-js/extra-typings'
import chalk from 'chalk'
import { readFileSync } from 'fs'
import mapValues from 'lodash-es/mapValues.js'
import pickBy from 'lodash-es/pickBy.js'
import uniqBy from 'lodash-es/uniqBy.js'
import React from 'react'
import { getOauthConfig } from './constants/oauth.js'
import { getRemoteSessionUrl } from './constants/product.js'
import { getSystemContext, getUserContext } from './context.js'
import { init, initializeTelemetryAfterTrust } from './entrypoints/init.js'
import { addToHistory } from './history.js'
import type { Root } from '@anthropic/ink'
import { launchRepl } from './replLauncher.js'
import {
	hasGrowthBookEnvOverride,
	initializeGrowthBook,
	refreshGrowthBookAfterAuthChange,
} from "./services/analytics/growthbook.js";
import { fetchBootstrapData } from "./services/api/bootstrap.js";
import {
	type DownloadResult,
	downloadSessionFiles,
	type FilesApiConfig,
	parseFileSpecs,
} from "./services/api/filesApi.js";
import { prefetchPassesEligibility } from "./services/api/referral.js";
import type {
	McpSdkServerConfig,
	McpServerConfig,
	ScopedMcpServerConfig,
} from "./services/mcp/types.js";
import {
	isPolicyAllowed,
	loadPolicyLimits,
	refreshPolicyLimits,
	waitForPolicyLimitsToLoad,
} from "./services/policyLimits/index.js";
import {
	loadRemoteManagedSettings,
	refreshRemoteManagedSettings,
} from "./services/remoteManagedSettings/index.js";
import type { ToolInputJSONSchema } from "./Tool.js";
import {
	createSyntheticOutputTool,
	isSyntheticOutputToolEnabled,
} from "@claude-code-best/builtin-tools/tools/SyntheticOutputTool/SyntheticOutputTool.js";
import { getTools } from "./tools.js";
import {
	canUserConfigureAdvisor,
	getInitialAdvisorSetting,
	isAdvisorEnabled,
	isValidAdvisorModel,
	modelSupportsAdvisor,
} from "./utils/advisor.js";
import { isAgentSwarmsEnabled } from "./utils/agentSwarmsEnabled.js";
import { count, uniq } from "./utils/array.js";
import { installAsciicastRecorder } from "./utils/asciicast.js";
import {
	getSubscriptionType,
	isClaudeAISubscriber,
	prefetchAwsCredentialsAndBedRockInfoIfSafe,
	prefetchGcpCredentialsIfSafe,
	validateForceLoginOrg,
} from "./utils/auth.js";
import {
	checkHasTrustDialogAccepted,
	getGlobalConfig,
	getRemoteControlAtStartup,
	isAutoUpdaterDisabled,
	saveGlobalConfig,
} from "./utils/config.js";
import { seedEarlyInput, stopCapturingEarlyInput } from "./utils/earlyInput.js";
import { getInitialEffortSetting, parseEffortValue } from "./utils/effort.js";
import {
	getInitialFastModeSetting,
	isFastModeEnabled,
	prefetchFastModeStatus,
	resolveFastModeStatusFromCache,
} from "./utils/fastMode.js";
import { applyConfigEnvironmentVariables } from "./utils/managedEnv.js";
import { createSystemMessage, createUserMessage } from "./utils/messages.js";
import { getPlatform } from "./utils/platform.js";
import { getBaseRenderOptions } from "./utils/renderOptions.js";
import { getSessionIngressAuthToken } from "./utils/sessionIngressAuth.js";
import { settingsChangeDetector } from "./utils/settings/changeDetector.js";
import { skillChangeDetector } from "./utils/skills/skillChangeDetector.js";
import { jsonParse, writeFileSync_DEPRECATED } from "./utils/slowOperations.js";
import { computeInitialTeamContext } from "./utils/swarm/reconnection.js";
import { initializeWarningHandler } from "./utils/warningHandler.js";
import { isWorktreeModeEnabled } from "./utils/worktreeModeEnabled.js";

// Lazy require to avoid circular dependency: teammate.ts -> AppState.tsx -> ... -> main.tsx
/* eslint-disable @typescript-eslint/no-require-imports */
const getTeammateUtils = () =>
	require("./utils/teammate.js") as typeof import("./utils/teammate.js");
const getTeammatePromptAddendum = () =>
	require("./utils/swarm/teammatePromptAddendum.js") as typeof import("./utils/swarm/teammatePromptAddendum.js");
const getTeammateModeSnapshot = () =>
	require("./utils/swarm/backends/teammateModeSnapshot.js") as typeof import("./utils/swarm/backends/teammateModeSnapshot.js");
/* eslint-enable @typescript-eslint/no-require-imports */
// Dead code elimination: conditional import for COORDINATOR_MODE
/* eslint-disable @typescript-eslint/no-require-imports */
const coordinatorModeModule = feature("COORDINATOR_MODE")
	? (require("./coordinator/coordinatorMode.js") as typeof import("./coordinator/coordinatorMode.js"))
	: null;
/* eslint-enable @typescript-eslint/no-require-imports */
// Dead code elimination: conditional import for KAIROS (assistant mode)
/* eslint-disable @typescript-eslint/no-require-imports */
const assistantModule = feature("KAIROS")
	? (require("./assistant/index.js") as typeof import("./assistant/index.js"))
	: null;
const kairosGate = feature("KAIROS")
	? (require("./assistant/gate.js") as typeof import("./assistant/gate.js"))
	: null;

import { relative, resolve } from "path";
import { isAnalyticsDisabled } from "src/services/analytics/config.js";
import { getFeatureValue_CACHED_MAY_BE_STALE } from "src/services/analytics/growthbook.js";
import {
  type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
  logEvent,
} from 'src/services/analytics/index.js'
import { initializeAnalyticsGates } from 'src/services/analytics/sink.js'
import {
	getOriginalCwd,
	setAdditionalDirectoriesForClaudeMd,
	setIsRemoteMode,
	setMainLoopModelOverride,
	setMainThreadAgentType,
	setTeleportedSessionInfo,
} from "./bootstrap/state.js";
import { filterCommandsForRemoteMode, getCommands } from "./commands.js";
import type { StatsStore } from "./context/stats.js";
import {
  launchAssistantInstallWizard,
  launchAssistantSessionChooser,
  launchInvalidSettingsDialog,
  launchResumeChooser,
  launchSnapshotUpdateDialog,
  launchTeleportRepoMismatchDialog,
  launchTeleportResumeWrapper,
} from './dialogLaunchers.js'
import { SHOW_CURSOR } from '@anthropic/ink'
import {
	exitWithError,
	exitWithMessage,
	getRenderContext,
	renderAndRun,
	showSetupScreens,
} from "./interactiveHelpers.js";
import { initBuiltinPlugins } from "./plugins/bundled/index.js";
/* eslint-enable @typescript-eslint/no-require-imports */
import { checkQuotaStatus } from "./services/claudeAiLimits.js";
import {
	getMcpToolsCommandsAndResources,
	prefetchAllMcpResources,
} from "./services/mcp/client.js";
import {
	VALID_INSTALLABLE_SCOPES,
	VALID_UPDATE_SCOPES,
} from "./services/plugins/pluginCliCommands.js";
import { initBundledSkills } from "./skills/bundled/index.js";
import type { AgentColorName } from "@claude-code-best/builtin-tools/tools/AgentTool/agentColorManager.js";
import {
	getActiveAgentsFromList,
	getAgentDefinitionsWithOverrides,
	isBuiltInAgent,
	isCustomAgent,
	parseAgentsFromJson,
} from "@claude-code-best/builtin-tools/tools/AgentTool/loadAgentsDir.js";
import type { LogOption } from "./types/logs.js";
import type { Message as MessageType } from "./types/message.js";
import {
	CLAUDE_IN_CHROME_SKILL_HINT,
	CLAUDE_IN_CHROME_SKILL_HINT_WITH_WEBBROWSER,
} from "./utils/claudeInChrome/prompt.js";
import {
	setupClaudeInChrome,
	shouldAutoEnableClaudeInChrome,
	shouldEnableClaudeInChrome,
} from "./utils/claudeInChrome/setup.js";
import { getContextWindowForModel } from "./utils/context.js";
import { loadConversationForResume } from "./utils/conversationRecovery.js";
import { buildDeepLinkBanner } from "./utils/deepLink/banner.js";
import {
	hasNodeOption,
	isBareMode,
	isEnvTruthy,
	isInProtectedNamespace,
} from "./utils/envUtils.js";
import { refreshExampleCommands } from "./utils/exampleCommands.js";
import type { FpsMetrics } from "./utils/fpsTracker.js";
import { getWorktreePaths } from "./utils/getWorktreePaths.js";
import {
	findGitRoot,
	getBranch,
	getIsGit,
	getWorktreeCount,
} from "./utils/git.js";
import { getGhAuthStatus } from "./utils/github/ghAuthStatus.js";
import { safeParseJSON } from "./utils/json.js";
import { logError } from "./utils/log.js";
import { getModelDeprecationWarning } from "./utils/model/deprecation.js";
import {
	getDefaultMainLoopModel,
	getUserSpecifiedModelSetting,
	normalizeModelStringForAPI,
	parseUserSpecifiedModel,
} from "./utils/model/model.js";
import { ensureModelStringsInitialized } from "./utils/model/modelStrings.js";
import { PERMISSION_MODES } from "./utils/permissions/PermissionMode.js";
import {
	getAutoModeEnabledStateIfCached,
	initializeToolPermissionContext,
	initialPermissionModeFromCLI,
	isDefaultPermissionModeAuto,
	parseToolListFromCLI,
	removeDangerousPermissions,
	stripDangerousPermissionsForAutoMode,
	verifyAutoModeGateAccess,
} from "./utils/permissions/permissionSetup.js";
import { cleanupOrphanedPluginVersionsInBackground } from "./utils/plugins/cacheUtils.js";
import { initializeVersionedPlugins } from "./utils/plugins/installedPluginsManager.js";
import { getManagedPluginNames } from "./utils/plugins/managedPlugins.js";
import { getGlobExclusionsForPluginCache } from "./utils/plugins/orphanedPluginFilter.js";
import { getPluginSeedDirs } from "./utils/plugins/pluginDirectories.js";
import { countFilesRoundedRg } from "./utils/ripgrep.js";
import {
	processSessionStartHooks,
	processSetupHooks,
} from "./utils/sessionStart.js";
import {
	cacheSessionTitle,
	getSessionIdFromLog,
	loadTranscriptFromFile,
	saveAgentSetting,
	saveMode,
	searchSessionsByCustomTitle,
	sessionIdExists,
} from "./utils/sessionStorage.js";
import { ensureMdmSettingsLoaded } from "./utils/settings/mdm/settings.js";
import {
	getInitialSettings,
	getManagedSettingsKeysForLogging,
	getSettingsForSource,
	getSettingsWithErrors,
} from "./utils/settings/settings.js";
import { resetSettingsCache } from "./utils/settings/settingsCache.js";
import type { ValidationError } from "./utils/settings/validation.js";
import {
	DEFAULT_TASKS_MODE_TASK_LIST_ID,
	TASK_STATUSES,
} from "./utils/tasks.js";
import {
	logPluginLoadErrors,
	logPluginsEnabledForSession,
} from "./utils/telemetry/pluginTelemetry.js";
import { logSkillsLoaded } from "./utils/telemetry/skillLoadedEvent.js";
import { generateTempFilePath } from "./utils/tempfile.js";
import { validateUuid } from "./utils/uuid.js";
// Plugin startup checks are now handled non-blockingly in REPL.tsx

import { registerMcpAddCommand } from "src/commands/mcp/addCommand.js";
import { registerMcpXaaIdpCommand } from "src/commands/mcp/xaaIdpCommand.js";
import { logPermissionContextForAnts } from "src/services/internalLogging.js";
import { fetchClaudeAIMcpConfigsIfEligible } from "src/services/mcp/claudeai.js";
import { clearServerCache } from "src/services/mcp/client.js";
import {
	areMcpConfigsAllowedWithEnterpriseMcpConfig,
	dedupClaudeAiMcpServers,
	doesEnterpriseMcpConfigExist,
	filterMcpServersByPolicy,
	getClaudeCodeMcpConfigs,
	getMcpServerSignature,
	parseMcpConfig,
	parseMcpConfigFromFilePath,
} from "src/services/mcp/config.js";
import {
	excludeCommandsByServer,
	excludeResourcesByServer,
} from "src/services/mcp/utils.js";
import { isXaaEnabled } from "src/services/mcp/xaaIdpLogin.js";
import { getRelevantTips } from "src/services/tips/tipRegistry.js";
import { logContextMetrics } from "src/utils/api.js";
import {
	CLAUDE_IN_CHROME_MCP_SERVER_NAME,
	isClaudeInChromeMCPServer,
} from "src/utils/claudeInChrome/common.js";
import { registerCleanup } from "src/utils/cleanupRegistry.js";
import { eagerParseCliFlag } from "src/utils/cliArgs.js";
import { createEmptyAttributionState } from "src/utils/commitAttribution.js";
import {
	countConcurrentSessions,
	registerSession,
	updateSessionName,
} from "src/utils/concurrentSessions.js";
import { getCwd } from "src/utils/cwd.js";
import { logForDebugging, setHasFormattedOutput } from "src/utils/debug.js";
import {
	errorMessage,
	getErrnoCode,
	isENOENT,
	TeleportOperationError,
	toError,
} from "src/utils/errors.js";
import {
	getFsImplementation,
	safeResolvePath,
} from "src/utils/fsOperations.js";
import {
	gracefulShutdown,
	gracefulShutdownSync,
} from "src/utils/gracefulShutdown.js";
import { setAllHookEventsEnabled } from "src/utils/hooks/hookEvents.js";
import { refreshModelCapabilities } from "src/utils/model/modelCapabilities.js";
import { peekForStdinData, writeToStderr } from "src/utils/process.js";
import { setCwd } from "src/utils/Shell.js";
import {
	type ProcessedResume,
	processResumedConversation,
} from "src/utils/sessionRestore.js";
import { parseSettingSourcesFlag } from "src/utils/settings/constants.js";
import { plural } from "src/utils/stringUtils.js";
import {
	type ChannelEntry,
	getInitialMainLoopModel,
	getIsNonInteractiveSession,
	getSdkBetas,
	getSessionId,
	getUserMsgOptIn,
	setAllowedChannels,
	setAllowedSettingSources,
	setChromeFlagOverride,
	setClientType,
	setCwdState,
	setDirectConnectServerUrl,
	setFlagSettingsPath,
	setInitialMainLoopModel,
	setInlinePlugins,
	setIsInteractive,
	setKairosActive,
	setOriginalCwd,
	setQuestionPreviewFormat,
	setSdkBetas,
	setSessionBypassPermissionsMode,
	setSessionPersistenceDisabled,
	setSessionSource,
	setUserMsgOptIn,
	switchSession,
} from "./bootstrap/state.js";

/* eslint-disable @typescript-eslint/no-require-imports */
const autoModeStateModule = feature("TRANSCRIPT_CLASSIFIER")
	? (require("./utils/permissions/autoModeState.js") as typeof import("./utils/permissions/autoModeState.js"))
	: null;

// TeleportRepoMismatchDialog, TeleportResumeWrapper dynamically imported at call sites
import { migrateBypassPermissionsAcceptedToSettings } from "./migrations/migrateBypassPermissionsAcceptedToSettings.js";
import { migrateEnableAllProjectMcpServersToSettings } from "./migrations/migrateEnableAllProjectMcpServersToSettings.js";
import { migrateFennecToOpus } from "./migrations/migrateFennecToOpus.js";
import { migrateLegacyOpusToCurrent } from "./migrations/migrateLegacyOpusToCurrent.js";
import { migrateOpusToOpus1m } from "./migrations/migrateOpusToOpus1m.js";
import { migrateReplBridgeEnabledToRemoteControlAtStartup } from "./migrations/migrateReplBridgeEnabledToRemoteControlAtStartup.js";
import { migrateSonnet1mToSonnet45 } from "./migrations/migrateSonnet1mToSonnet45.js";
import { migrateSonnet45ToSonnet46 } from "./migrations/migrateSonnet45ToSonnet46.js";
import { resetAutoModeOptInForDefaultOffer } from "./migrations/resetAutoModeOptInForDefaultOffer.js";
import { resetProToOpusDefault } from "./migrations/resetProToOpusDefault.js";
import { createRemoteSessionConfig } from "./remote/RemoteSessionManager.js";
/* eslint-enable @typescript-eslint/no-require-imports */
// teleportWithProgress dynamically imported at call site
import {
	createDirectConnectSession,
	DirectConnectError,
} from "./server/createDirectConnectSession.js";
import { initializeLspServerManager } from "./services/lsp/manager.js";
import { shouldEnablePromptSuggestion } from "./services/PromptSuggestion/promptSuggestion.js";
import {
	type AppState,
	getDefaultAppState,
	IDLE_SPECULATION_STATE,
} from "./state/AppStateStore.js";
import { onChangeAppState } from "./state/onChangeAppState.js";
import { createStore } from "./state/store.js";
import { asSessionId } from "./types/ids.js";
import { filterAllowedSdkBetas } from "./utils/betas.js";
import { isInBundledMode, isRunningWithBun } from "./utils/bundledMode.js";
import { logForDiagnosticsNoPII } from "./utils/diagLogs.js";
import {
	filterExistingPaths,
	getKnownPathsForRepo,
} from "./utils/githubRepoPathMapping.js";
import {
	clearPluginCache,
	loadAllPluginsCacheOnly,
} from "./utils/plugins/pluginLoader.js";
import { migrateChangelogFromConfig } from "./utils/releaseNotes.js";
import { SandboxManager } from "./utils/sandbox/sandbox-adapter.js";
import { fetchSession, prepareApiRequest } from "./utils/teleport/api.js";
import {
	checkOutTeleportedSessionBranch,
	processMessagesForTeleportResume,
	teleportToRemoteWithErrorHandling,
	validateGitState,
	validateSessionRepository,
} from "./utils/teleport.js";
import {
  shouldEnableThinkingByDefault,
  type ThinkingConfig,
} from './utils/thinking.js'
import { initUser, resetUserCache } from './utils/user.js'
import {
	getTmuxInstallInstructions,
	isTmuxAvailable,
	parsePRReference,
} from "./utils/worktree.js";

// eslint-disable-next-line custom-rules/no-top-level-side-effects
profileCheckpoint("main_tsx_imports_loaded");

/**
 * Log managed settings keys to Statsig for analytics.
 * This is called after init() completes to ensure settings are loaded
 * and environment variables are applied before model resolution.
 */
function logManagedSettings(): void {
	try {
		const policySettings = getSettingsForSource("policySettings");
		if (policySettings) {
			const allKeys = getManagedSettingsKeysForLogging(policySettings);
			logEvent("tengu_managed_settings_loaded", {
				keyCount: allKeys.length,
				keys: allKeys.join(
					",",
				) as unknown as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
			});
		}
	} catch {
		// Silently ignore errors - this is just for analytics
	}
}

// Check if running in debug/inspection mode
function isBeingDebugged() {
	const isBun = isRunningWithBun();

	// Check for inspect flags in process arguments (including all variants)
	const hasInspectArg = process.execArgv.some((arg) => {
		if (isBun) {
			// Note: Bun has an issue with single-file executables where application arguments
			// from process.argv leak into process.execArgv (similar to https://github.com/oven-sh/bun/issues/11673)
			// This breaks use of --debug mode if we omit this branch
			// We're fine to skip that check, because Bun doesn't support Node.js legacy --debug or --debug-brk flags
			return /--inspect(-brk)?/.test(arg);
		} else {
			// In Node.js, check for both --inspect and legacy --debug flags
			return /--inspect(-brk)?|--debug(-brk)?/.test(arg);
		}
	});

	// Check if NODE_OPTIONS contains inspect flags
	const hasInspectEnv =
		process.env.NODE_OPTIONS &&
		/--inspect(-brk)?|--debug(-brk)?/.test(process.env.NODE_OPTIONS);

	// Check if inspector is available and active (indicates debugging)
	try {
		// Dynamic import would be better but is async - use global object instead
		// eslint-disable-next-line @typescript-eslint/no-explicit-any
		const inspector = (global as any).require("inspector");
		const hasInspectorUrl = !!inspector.url();
		return hasInspectorUrl || hasInspectArg || hasInspectEnv;
	} catch {
		// Ignore error and fall back to argument detection
		return hasInspectArg || hasInspectEnv;
	}
}



/**
 * Per-session skill/plugin telemetry. Called from both the interactive path
 * and the headless -p path (before runHeadless) — both go through
 * main.tsx but branch before the interactive startup path, so it needs two
 * call sites here rather than one here + one in QueryEngine.
 */
function logSessionTelemetry(): void {
	const model = parseUserSpecifiedModel(
		getInitialMainLoopModel() ?? getDefaultMainLoopModel(),
	);
	void logSkillsLoaded(
		getCwd(),
		getContextWindowForModel(model, getSdkBetas()),
	);
	void loadAllPluginsCacheOnly()
		.then(({ enabled, errors }) => {
			const managedNames = getManagedPluginNames();
			logPluginsEnabledForSession(
				enabled,
				managedNames,
				getPluginSeedDirs(),
			);
			logPluginLoadErrors(errors, managedNames);
		})
		.catch((err) => logError(err));
}

function getCertEnvVarTelemetry(): Record<string, boolean> {
	const result: Record<string, boolean> = {};
	if (process.env.NODE_EXTRA_CA_CERTS) {
		result.has_node_extra_ca_certs = true;
	}
	if (process.env.CLAUDE_CODE_CLIENT_CERT) {
		result.has_client_cert = true;
	}
	if (hasNodeOption("--use-system-ca")) {
		result.has_use_system_ca = true;
	}
	if (hasNodeOption("--use-openssl-ca")) {
		result.has_use_openssl_ca = true;
	}
	return result;
}

async function logStartupTelemetry(): Promise<void> {
	if (isAnalyticsDisabled()) return;
	const [isGit, worktreeCount, ghAuthStatus] = await Promise.all([
		getIsGit(),
		getWorktreeCount(),
		getGhAuthStatus(),
	]);

	logEvent("tengu_startup_telemetry", {
		is_git: isGit,
		worktree_count: worktreeCount,
		gh_auth_status:
			ghAuthStatus as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
		sandbox_enabled: SandboxManager.isSandboxingEnabled(),
		are_unsandboxed_commands_allowed:
			SandboxManager.areUnsandboxedCommandsAllowed(),
		is_auto_bash_allowed_if_sandbox_enabled:
			SandboxManager.isAutoAllowBashIfSandboxedEnabled(),
		auto_updater_disabled: isAutoUpdaterDisabled(),
		prefers_reduced_motion:
			getInitialSettings().prefersReducedMotion ?? false,
		...getCertEnvVarTelemetry(),
	});
}

// @[MODEL LAUNCH]: Consider any migrations you may need for model strings. See migrateSonnet1mToSonnet45.ts for an example.
// Bump this when adding a new sync migration so existing users re-run the set.
const CURRENT_MIGRATION_VERSION = 11;
function runMigrations(): void {
	if (getGlobalConfig().migrationVersion !== CURRENT_MIGRATION_VERSION) {
		migrateBypassPermissionsAcceptedToSettings();
		migrateEnableAllProjectMcpServersToSettings();
		resetProToOpusDefault();
		migrateSonnet1mToSonnet45();
		migrateLegacyOpusToCurrent();
		migrateSonnet45ToSonnet46();
		migrateOpusToOpus1m();
		migrateReplBridgeEnabledToRemoteControlAtStartup();
		if (feature("TRANSCRIPT_CLASSIFIER")) {
			resetAutoModeOptInForDefaultOffer();
		}
		if (process.env.USER_TYPE === "ant") {
			migrateFennecToOpus();
		}
		saveGlobalConfig((prev) =>
			prev.migrationVersion === CURRENT_MIGRATION_VERSION
				? prev
				: { ...prev, migrationVersion: CURRENT_MIGRATION_VERSION },
		);
	}
	// Async migration - fire and forget since it's non-blocking
	migrateChangelogFromConfig().catch(() => {
		// Silently ignore migration errors - will retry on next startup
	});
}

/**
 * Prefetch system context (including git status) only when it's safe to do so.
 * Git commands can execute arbitrary code via hooks and config (e.g., core.fsmonitor,
 * diff.external), so we must only run them after trust is established or in
 * non-interactive mode where trust is implicit.
 */
function prefetchSystemContextIfSafe(): void {
	const isNonInteractiveSession = getIsNonInteractiveSession();

	// In non-interactive mode (--print), trust dialog is skipped and
	// execution is considered trusted (as documented in help text)
	if (isNonInteractiveSession) {
		logForDiagnosticsNoPII(
			"info",
			"prefetch_system_context_non_interactive",
		);
		void getSystemContext();
		return;
	}

	// In interactive mode, only prefetch if trust has already been established
	const hasTrust = checkHasTrustDialogAccepted();
	if (hasTrust) {
		logForDiagnosticsNoPII("info", "prefetch_system_context_has_trust");
		void getSystemContext();
	} else {
		logForDiagnosticsNoPII(
			"info",
			"prefetch_system_context_skipped_no_trust",
		);
	}
	// Otherwise, don't prefetch - wait for trust to be established first
}

/**
 * Start background prefetches and housekeeping that are NOT needed before first render.
 * These are deferred from setup() to reduce event loop contention and child process
 * spawning during the critical startup path.
 * Call this after the REPL has been rendered.
 */
export function startDeferredPrefetches(): void {
	// This function runs after first render, so it doesn't block the initial paint.
	// However, the spawned processes and async work still contend for CPU and event
	// loop time, which skews startup benchmarks (CPU profiles, time-to-first-render
	// measurements). Skip all of it when we're only measuring startup performance.
	if (
		isEnvTruthy(process.env.CLAUDE_CODE_EXIT_AFTER_FIRST_RENDER) ||
		// --bare: skip ALL prefetches. These are cache-warms for the REPL's
		// first-turn responsiveness (initUser, getUserContext, tips, countFiles,
		// modelCapabilities, change detectors). Scripted -p calls don't have a
		// "user is typing" window to hide this work in — it's pure overhead on
		// the critical path.
		isBareMode()
	) {
		return;
	}

	// Process-spawning prefetches (consumed at first API call, user is still typing)
	void initUser();
	void getUserContext();
	prefetchSystemContextIfSafe();
	void getRelevantTips();
	if (
		isEnvTruthy(process.env.CLAUDE_CODE_USE_BEDROCK) &&
		!isEnvTruthy(process.env.CLAUDE_CODE_SKIP_BEDROCK_AUTH)
	) {
		void prefetchAwsCredentialsAndBedRockInfoIfSafe();
	}
	if (
		isEnvTruthy(process.env.CLAUDE_CODE_USE_VERTEX) &&
		!isEnvTruthy(process.env.CLAUDE_CODE_SKIP_VERTEX_AUTH)
	) {
		void prefetchGcpCredentialsIfSafe();
	}
	void countFilesRoundedRg(getCwd(), AbortSignal.timeout(3000), []);

	// Analytics and feature flag initialization
	void initializeAnalyticsGates();

	void refreshModelCapabilities();

	// File change detectors deferred from init() to unblock first render
	void settingsChangeDetector.initialize();
	if (!isBareMode()) {
		void skillChangeDetector.initialize();
	}

	// Event loop stall detector — logs when the main thread is blocked >500ms
	if (process.env.USER_TYPE === "ant") {
		void import("./utils/eventLoopStallDetector.js").then((m) =>
			m.startEventLoopStallDetector(),
		);
	}
}

function loadSettingsFromFlag(settingsFile: string): void {
	try {
		const trimmedSettings = settingsFile.trim();
		const looksLikeJson =
			trimmedSettings.startsWith("{") && trimmedSettings.endsWith("}");

		let settingsPath: string;

		if (looksLikeJson) {
			// It's a JSON string - validate and create temp file
			const parsedJson = safeParseJSON(trimmedSettings);
			if (!parsedJson) {
				process.stderr.write(
					chalk.red("Error: Invalid JSON provided to --settings\n"),
				);
				process.exit(1);
			}

			// Create a temporary file and write the JSON to it.
			// Use a content-hash-based path instead of random UUID to avoid
			// busting the Anthropic API prompt cache. The settings path ends up
			// in the Bash tool's sandbox denyWithinAllow list, which is part of
			// the tool description sent to the API. A random UUID per subprocess
			// changes the tool description on every query() call, invalidating
			// the cache prefix and causing a 12x input token cost penalty.
			// The content hash ensures identical settings produce the same path
			// across process boundaries (each SDK query() spawns a new process).
			settingsPath = generateTempFilePath("claude-settings", ".json", {
				contentHash: trimmedSettings,
			});
			writeFileSync_DEPRECATED(settingsPath, trimmedSettings, "utf8");
		} else {
			// It's a file path - resolve and validate by attempting to read
			const { resolvedPath: resolvedSettingsPath } = safeResolvePath(
				getFsImplementation(),
				settingsFile,
			);
			try {
				readFileSync(resolvedSettingsPath, "utf8");
			} catch (e) {
				if (isENOENT(e)) {
					process.stderr.write(
						chalk.red(
							`Error: Settings file not found: ${resolvedSettingsPath}\n`,
						),
					);
					process.exit(1);
				}
				throw e;
			}
			settingsPath = resolvedSettingsPath;
		}

		setFlagSettingsPath(settingsPath);
		resetSettingsCache();
	} catch (error) {
		if (error instanceof Error) {
			logError(error);
		}
		process.stderr.write(
			chalk.red(`Error processing settings: ${errorMessage(error)}\n`),
		);
		process.exit(1);
	}
}

function loadSettingSourcesFromFlag(settingSourcesArg: string): void {
	try {
		const sources = parseSettingSourcesFlag(settingSourcesArg);
		setAllowedSettingSources(sources);
		resetSettingsCache();
	} catch (error) {
		if (error instanceof Error) {
			logError(error);
		}
		process.stderr.write(
			chalk.red(
				`Error processing --setting-sources: ${errorMessage(error)}\n`,
			),
		);
		process.exit(1);
	}
}

/**
 * Parse and load settings flags early, before init()
 * This ensures settings are filtered from the start of initialization
 */
function eagerLoadSettings(): void {
	profileCheckpoint("eagerLoadSettings_start");
	// Parse --settings flag early to ensure settings are loaded before init()
	const settingsFile = eagerParseCliFlag("--settings");
	if (settingsFile) {
		loadSettingsFromFlag(settingsFile);
	}

	// Parse --setting-sources flag early to control which sources are loaded
	const settingSourcesArg = eagerParseCliFlag("--setting-sources");
	if (settingSourcesArg !== undefined) {
		loadSettingSourcesFromFlag(settingSourcesArg);
	}
	profileCheckpoint("eagerLoadSettings_end");
}

function initializeEntrypoint(isNonInteractive: boolean): void {
	// Skip if already set (e.g., by SDK or other entrypoints)
	if (process.env.CLAUDE_CODE_ENTRYPOINT) {
		return;
	}

	const cliArgs = process.argv.slice(2);

	// Check for MCP serve command (handle flags before mcp serve, e.g., --debug mcp serve)
	const mcpIndex = cliArgs.indexOf("mcp");
	if (mcpIndex !== -1 && cliArgs[mcpIndex + 1] === "serve") {
		process.env.CLAUDE_CODE_ENTRYPOINT = "mcp";
		return;
	}

	if (isEnvTruthy(process.env.CLAUDE_CODE_ACTION)) {
		process.env.CLAUDE_CODE_ENTRYPOINT = "claude-code-github-action";
		return;
	}

	// Note: 'local-agent' entrypoint is set by the local agent mode launcher
	// via CLAUDE_CODE_ENTRYPOINT env var (handled by early return above)

	// Set based on interactive status
	process.env.CLAUDE_CODE_ENTRYPOINT = isNonInteractive ? "sdk-cli" : "cli";
}

// Set by early argv processing when `claude open <url>` is detected (interactive mode only)
type PendingConnect = {
	url: string | undefined;
	authToken: string | undefined;
	dangerouslySkipPermissions: boolean;
};
const _pendingConnect: PendingConnect | undefined = feature("DIRECT_CONNECT")
	? {
			url: undefined,
			authToken: undefined,
			dangerouslySkipPermissions: false,
		}
	: undefined;

// Set by early argv processing when `claude assistant [sessionId]` is detected
type PendingAssistantChat = { sessionId?: string; discover: boolean };
const _pendingAssistantChat: PendingAssistantChat | undefined = feature(
	"KAIROS",
)
	? { sessionId: undefined, discover: false }
	: undefined;

// `claude ssh <host> [dir]` — parsed from argv early (same pattern as
// DIRECT_CONNECT above) so the main command path can pick it up and hand
// the REPL an SSH-backed session instead of a local one.
type PendingSSH = {
	host: string | undefined;
	cwd: string | undefined;
	permissionMode: string | undefined;
	dangerouslySkipPermissions: boolean;
	/** --local: spawn the child CLI directly, skip ssh/probe/deploy. e2e test mode. */
	local: boolean;
	/** Extra CLI args to forward to the remote CLI on initial spawn (--resume, -c). */
	extraCliArgs: string[];
	remoteBin: string | undefined;
};
const _pendingSSH: PendingSSH | undefined = feature("SSH_REMOTE")
	? {
			host: undefined,
			cwd: undefined,
			permissionMode: undefined,
			dangerouslySkipPermissions: false,
			local: false,
			extraCliArgs: [],
			remoteBin: undefined,
		}
	: undefined;

export async function main() {
	profileCheckpoint("main_function_start");

	// SECURITY: Prevent Windows from executing commands from current directory
	// This must be set before ANY command execution to prevent PATH hijacking attacks
	// See: https://docs.microsoft.com/en-us/windows/win32/api/processenv/nf-processenv-searchpathw
	process.env.NoDefaultCurrentDirectoryInExePath = "1";

	// Initialize warning handler early to catch warnings
	initializeWarningHandler();

	process.on("exit", () => {
		resetCursor();
	});
	process.on("SIGINT", () => {
		// In print mode, print.ts registers its own SIGINT handler that aborts
		// the in-flight query and calls gracefulShutdown; skip here to avoid
		// preempting it with a synchronous process.exit().
		if (process.argv.includes("-p") || process.argv.includes("--print")) {
			return;
		}
		process.exit(0);
	});
	profileCheckpoint("main_warning_handler_initialized");

	// Check for cc:// or cc+unix:// URL in argv — rewrite so the main command
	// handles it, giving the full interactive TUI instead of a stripped-down subcommand.
	// For headless (-p), we rewrite to the internal `open` subcommand.
	if (feature("DIRECT_CONNECT")) {
		const rawCliArgs = process.argv.slice(2);
		const ccIdx = rawCliArgs.findIndex(
			(a) => a.startsWith("cc://") || a.startsWith("cc+unix://"),
		);
		if (ccIdx !== -1 && _pendingConnect) {
			const ccUrl = rawCliArgs[ccIdx]!;
			const { parseConnectUrl } =
				await import("./server/parseConnectUrl.js");
			const parsed = parseConnectUrl(ccUrl);
			_pendingConnect.dangerouslySkipPermissions = rawCliArgs.includes(
				"--dangerously-skip-permissions",
			);

			if (rawCliArgs.includes("-p") || rawCliArgs.includes("--print")) {
				// Headless: rewrite to internal `open` subcommand
				const stripped = rawCliArgs.filter((_, i) => i !== ccIdx);
				const dspIdx = stripped.indexOf(
					"--dangerously-skip-permissions",
				);
				if (dspIdx !== -1) {
					stripped.splice(dspIdx, 1);
				}
				process.argv = [
					process.argv[0]!,
					process.argv[1]!,
					"open",
					ccUrl,
					...stripped,
				];
			} else {
				// Interactive: strip cc:// URL and flags, run main command
				_pendingConnect.url = parsed.serverUrl;
				_pendingConnect.authToken = parsed.authToken;
				const stripped = rawCliArgs.filter((_, i) => i !== ccIdx);
				const dspIdx = stripped.indexOf(
					"--dangerously-skip-permissions",
				);
				if (dspIdx !== -1) {
					stripped.splice(dspIdx, 1);
				}
				process.argv = [
					process.argv[0]!,
					process.argv[1]!,
					...stripped,
				];
			}
		}
	}

	// Handle deep link URIs early — this is invoked by the OS protocol handler
	// and should bail out before full init since it only needs to parse the URI
	// and open a terminal.
	if (feature("LODESTONE")) {
		const handleUriIdx = process.argv.indexOf("--handle-uri");
		if (handleUriIdx !== -1 && process.argv[handleUriIdx + 1]) {
			const { enableConfigs } = await import("./utils/config.js");
			enableConfigs();
			const uri = process.argv[handleUriIdx + 1]!;
			const { handleDeepLinkUri } =
				await import("./utils/deepLink/protocolHandler.js");
			const exitCode = await handleDeepLinkUri(uri);
			process.exit(exitCode);
		}

		// macOS URL handler: when LaunchServices launches our .app bundle, the
		// URL arrives via Apple Event (not argv). LaunchServices overwrites
		// __CFBundleIdentifier to the launching bundle's ID, which is a precise
		// positive signal — cheaper than importing and guessing with heuristics.
		if (
			process.platform === "darwin" &&
			process.env.__CFBundleIdentifier ===
				"com.anthropic.claude-code-url-handler"
		) {
			const { enableConfigs } = await import("./utils/config.js");
			enableConfigs();
			const { handleUrlSchemeLaunch } =
				await import("./utils/deepLink/protocolHandler.js");
			const urlSchemeResult = await handleUrlSchemeLaunch();
			process.exit(urlSchemeResult ?? 1);
		}
	}

	// `claude assistant [sessionId]` — stash and strip so the main
	// command handles it, giving the full interactive TUI. Position-0 only
	// (matching the ssh pattern below) — indexOf would false-positive on
	// `claude -p "explain assistant"`. Root-flag-before-subcommand
	// (e.g. `--debug assistant`) falls through to the stub, which
	// prints usage.
	if (feature("KAIROS") && _pendingAssistantChat) {
		const rawArgs = process.argv.slice(2);
		if (rawArgs[0] === "assistant") {
			const nextArg = rawArgs[1];
			if (nextArg && !nextArg.startsWith("-")) {
				_pendingAssistantChat.sessionId = nextArg;
				rawArgs.splice(0, 2); // drop 'assistant' and sessionId
				process.argv = [process.argv[0]!, process.argv[1]!, ...rawArgs];
			} else if (!nextArg) {
				_pendingAssistantChat.discover = true;
				rawArgs.splice(0, 1); // drop 'assistant'
				process.argv = [process.argv[0]!, process.argv[1]!, ...rawArgs];
			}
			// else: `claude assistant --help` → fall through to stub
		}
	}

	// `claude ssh <host> [dir]` — strip from argv so the main command handler
	// runs (full interactive TUI), stash the host/dir for the REPL branch at
	// ~line 3720 to pick up. Headless (-p) mode not supported in v1: SSH
	// sessions need the local REPL to drive them (interrupt, permissions).
	if (feature("SSH_REMOTE") && _pendingSSH) {
		const rawCliArgs = process.argv.slice(2);
		// SSH-specific flags can appear before the host positional (e.g.
		// `ssh --permission-mode auto host /tmp` — standard POSIX flags-before-
		// positionals). Pull them all out BEFORE checking whether a host was
		// given, so `claude ssh --permission-mode auto host` and `claude ssh host
		// --permission-mode auto` are equivalent. The host check below only needs
		// to guard against `-h`/`--help` (which commander should handle).
		if (rawCliArgs[0] === "ssh") {
			const localIdx = rawCliArgs.indexOf("--local");
			if (localIdx !== -1) {
				_pendingSSH.local = true;
				rawCliArgs.splice(localIdx, 1);
			}
			const dspIdx = rawCliArgs.indexOf("--dangerously-skip-permissions");
			if (dspIdx !== -1) {
				_pendingSSH.dangerouslySkipPermissions = true;
				rawCliArgs.splice(dspIdx, 1);
			}
			const pmIdx = rawCliArgs.indexOf("--permission-mode");
			if (
				pmIdx !== -1 &&
				rawCliArgs[pmIdx + 1] &&
				!rawCliArgs[pmIdx + 1]!.startsWith("-")
			) {
				_pendingSSH.permissionMode = rawCliArgs[pmIdx + 1];
				rawCliArgs.splice(pmIdx, 2);
			}
			const pmEqIdx = rawCliArgs.findIndex((a) =>
				a.startsWith("--permission-mode="),
			);
			if (pmEqIdx !== -1) {
				_pendingSSH.permissionMode = rawCliArgs[pmEqIdx]!.split("=")[1];
				rawCliArgs.splice(pmEqIdx, 1);
			}
			// Forward session-resume + model flags to the remote CLI's initial spawn.
			// --continue/-c and --resume <uuid> operate on the REMOTE session history
			// (which persists under the remote's ~/.claude/projects/<cwd>/).
			// --model controls which model the remote uses.
			const extractFlag = (
				flag: string,
				opts: { hasValue?: boolean; as?: string } = {},
			) => {
				const i = rawCliArgs.indexOf(flag);
				if (i !== -1) {
					_pendingSSH.extraCliArgs.push(opts.as ?? flag);
					const val = rawCliArgs[i + 1];
					if (opts.hasValue && val && !val.startsWith("-")) {
						_pendingSSH.extraCliArgs.push(val);
						rawCliArgs.splice(i, 2);
					} else {
						rawCliArgs.splice(i, 1);
					}
				}
				const eqI = rawCliArgs.findIndex((a) =>
					a.startsWith(`${flag}=`),
				);
				if (eqI !== -1) {
					_pendingSSH.extraCliArgs.push(
						opts.as ?? flag,
						rawCliArgs[eqI]!.slice(flag.length + 1),
					);
					rawCliArgs.splice(eqI, 1);
				}
			};
			const rbIdx = rawCliArgs.indexOf('--remote-bin');
			if (rbIdx !== -1 && rawCliArgs[rbIdx + 1] && !rawCliArgs[rbIdx + 1]!.startsWith('-')) {
				_pendingSSH.remoteBin = rawCliArgs[rbIdx + 1];
				rawCliArgs.splice(rbIdx, 2);
			}
			const rbEqIdx = rawCliArgs.findIndex(a => a.startsWith('--remote-bin='));
			if (rbEqIdx !== -1) {
				_pendingSSH.remoteBin = rawCliArgs[rbEqIdx]!.split('=').slice(1).join('=');
				rawCliArgs.splice(rbEqIdx, 1);
			}

			extractFlag("-c", { as: "--continue" });
			extractFlag("--continue");
			extractFlag("--resume", { hasValue: true });
			extractFlag("--model", { hasValue: true });
		}
		// After pre-extraction, any remaining dash-arg at [1] is either -h/--help
		// (commander handles) or an unknown-to-ssh flag (fall through to commander
		// so it surfaces a proper error). Only a non-dash arg is the host.
		if (
			rawCliArgs[0] === "ssh" &&
			rawCliArgs[1] &&
			!rawCliArgs[1].startsWith("-")
		) {
			_pendingSSH.host = rawCliArgs[1];
			// Optional positional cwd.
			let consumed = 2;
			if (rawCliArgs[2] && !rawCliArgs[2].startsWith("-")) {
				_pendingSSH.cwd = rawCliArgs[2];
				consumed = 3;
			}
			const rest = rawCliArgs.slice(consumed);

			// Headless (-p) mode is not supported with SSH in v1 — reject early
			// so the flag doesn't silently cause local execution.
			if (rest.includes("-p") || rest.includes("--print")) {
				process.stderr.write(
					"Error: headless (-p/--print) mode is not supported with claude ssh\n",
				);
				gracefulShutdownSync(1);
				return;
			}

			// Rewrite argv so the main command sees remaining flags but not `ssh`.
			process.argv = [process.argv[0]!, process.argv[1]!, ...rest];
		}
	}

		// Check for -p/--print and --init-only flags early to set isInteractiveSession before init()
		// This is needed because telemetry initialization calls auth functions that need this flag
		const cliArgs = process.argv.slice(2);
		const hasPrintFlag = cliArgs.includes("-p") || cliArgs.includes("--print");
		const hasInitOnlyFlag = cliArgs.includes("--init-only");
		const hasSdkUrl = cliArgs.some((arg) => arg.startsWith("--sdk-url"));
		const forceInteractive = isEnvTruthy(process.env.CLAUDE_CODE_FORCE_INTERACTIVE);
		const isNonInteractive =
			hasPrintFlag || hasInitOnlyFlag || hasSdkUrl || (!forceInteractive && !process.stdout.isTTY);

	// Stop capturing early input for non-interactive modes
	if (isNonInteractive) {
		stopCapturingEarlyInput();
	}

	// Set simplified tracking fields
	const isInteractive = !isNonInteractive;
	setIsInteractive(isInteractive);

	// Initialize entrypoint based on mode - needs to be set before any event is logged
	initializeEntrypoint(isNonInteractive);

	// Determine client type
	const clientType = (() => {
		if (isEnvTruthy(process.env.GITHUB_ACTIONS)) return "github-action";
		if (process.env.CLAUDE_CODE_ENTRYPOINT === "sdk-ts")
			return "sdk-typescript";
		if (process.env.CLAUDE_CODE_ENTRYPOINT === "sdk-py")
			return "sdk-python";
		if (process.env.CLAUDE_CODE_ENTRYPOINT === "sdk-cli") return "sdk-cli";
		if (process.env.CLAUDE_CODE_ENTRYPOINT === "claude-vscode")
			return "claude-vscode";
		if (process.env.CLAUDE_CODE_ENTRYPOINT === "local-agent")
			return "local-agent";
		if (process.env.CLAUDE_CODE_ENTRYPOINT === "claude-desktop")
			return "claude-desktop";

		// Check if session-ingress token is provided (indicates remote session)
		const hasSessionIngressToken =
			process.env.CLAUDE_CODE_SESSION_ACCESS_TOKEN ||
			process.env.CLAUDE_CODE_WEBSOCKET_AUTH_FILE_DESCRIPTOR;
		if (
			process.env.CLAUDE_CODE_ENTRYPOINT === "remote" ||
			hasSessionIngressToken
		) {
			return "remote";
		}

		return "cli";
	})();
	setClientType(clientType);

	const previewFormat = process.env.CLAUDE_CODE_QUESTION_PREVIEW_FORMAT;
	if (previewFormat === "markdown" || previewFormat === "html") {
		setQuestionPreviewFormat(previewFormat);
	} else if (
		!clientType.startsWith("sdk-") &&
		// Desktop and CCR pass previewFormat via toolConfig; when the feature is
		// gated off they pass undefined — don't override that with markdown.
		clientType !== "claude-desktop" &&
		clientType !== "local-agent" &&
		clientType !== "remote"
	) {
		setQuestionPreviewFormat("markdown");
	}

	// Tag sessions created via `claude remote-control` so the backend can identify them
	if (process.env.CLAUDE_CODE_ENVIRONMENT_KIND === "bridge") {
		setSessionSource("remote-control");
	}

	profileCheckpoint("main_client_type_determined");

	// Parse and load settings flags early, before init()
	eagerLoadSettings();

	profileCheckpoint("main_before_run");

	await run();
	profileCheckpoint("main_after_run");
}

async function getInputPrompt(
	prompt: string,
	inputFormat: "text" | "stream-json",
): Promise<string | AsyncIterable<string>> {
	if (
		!process.stdin.isTTY &&
		// Input hijacking breaks MCP.
		!process.argv.includes("mcp")
	) {
		if (inputFormat === "stream-json") {
			return process.stdin;
		}
		process.stdin.setEncoding("utf8");
		let data = "";
		const onData = (chunk: string) => {
			data += chunk;
		};
		process.stdin.on("data", onData);
		// If no data arrives in 3s, stop waiting and warn. Stdin is likely an
		// inherited pipe from a parent that isn't writing (subprocess spawned
		// without explicit stdin handling). 3s covers slow producers like curl,
		// jq on large files, python with import overhead. The warning makes
		// silent data loss visible for the rare producer that's slower still.
		const timedOut = await peekForStdinData(process.stdin, 3000);
		process.stdin.off("data", onData);
		if (timedOut) {
			process.stderr.write(
				"Warning: no stdin data received in 3s, proceeding without it. " +
					"If piping from a slow command, redirect stdin explicitly: < /dev/null to skip, or wait longer.\n",
			);
		}
		return [prompt, data].filter(Boolean).join("\n");
	}
	return prompt;
}

async function run(): Promise<CommanderCommand> {
	profileCheckpoint("run_function_start");

	// Create help config that sorts options by long option name.
	// Commander supports compareOptions at runtime but @commander-js/extra-typings
	// doesn't include it in the type definitions, so we use Object.assign to add it.
	function createSortedHelpConfig(): {
		sortSubcommands: true;
		sortOptions: true;
	} {
		const getOptionSortKey = (opt: Option): string =>
			opt.long?.replace(/^--/, "") ?? opt.short?.replace(/^-/, "") ?? "";
		return Object.assign(
			{ sortSubcommands: true, sortOptions: true } as const,
			{
				compareOptions: (a: Option, b: Option) =>
					getOptionSortKey(a).localeCompare(getOptionSortKey(b)),
			},
		);
	}
	const program = new CommanderCommand()
		.configureHelp(createSortedHelpConfig())
		.enablePositionalOptions();
	profileCheckpoint("run_commander_initialized");

	// Use preAction hook to run initialization only when executing a command,
	// not when displaying help. This avoids the need for env variable signaling.
	program.hook("preAction", async (thisCommand) => {
		profileCheckpoint("preAction_start");
		// Await async subprocess loads started at module evaluation (lines 12-20).
		// Nearly free — subprocesses complete during the ~135ms of imports above.
		// Must resolve before init() which triggers the first settings read
		// (applySafeConfigEnvironmentVariables → getSettingsForSource('policySettings')
		// → isRemoteManagedSettingsEligible → sync keychain reads otherwise ~65ms).
		await Promise.all([
			ensureMdmSettingsLoaded(),
			ensureKeychainPrefetchCompleted(),
		]);
		profileCheckpoint("preAction_after_mdm");
		await init();
		profileCheckpoint("preAction_after_init");

		// process.title on Windows sets the console title directly; on POSIX,
		// terminal shell integration may mirror the process name to the tab.
		// After init() so settings.json env can also gate this (gh-4765).
		if (!isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_TERMINAL_TITLE)) {
			process.title = "claude";
		}

		// Attach logging sinks so subcommand handlers can use logEvent/logError.
		// Before PR #11106 logEvent dispatched directly; after, events queue until
		// a sink attaches. setup() attaches sinks for the default command, but
		// subcommands (doctor, mcp, plugin, auth) never call setup() and would
		// silently drop events on process.exit(). Both inits are idempotent.
		const { initSinks } = await import("./utils/sinks.js");
		initSinks();
		profileCheckpoint("preAction_after_sinks");

		// gh-33508: --plugin-dir is a top-level program option. The default
		// action reads it from its own options destructure, but subcommands
		// (plugin list, plugin install, mcp *) have their own actions and
		// never see it. Wire it up here so getInlinePlugins() works everywhere.
		// thisCommand.opts() is typed {} here because this hook is attached
		// before .option('--plugin-dir', ...) in the chain — extra-typings
		// builds the type as options are added. Narrow with a runtime guard;
		// the collect accumulator + [] default guarantee string[] in practice.
		const pluginDir = thisCommand.getOptionValue("pluginDir");
		if (
			Array.isArray(pluginDir) &&
			pluginDir.length > 0 &&
			pluginDir.every((p) => typeof p === "string")
		) {
			setInlinePlugins(pluginDir);
			clearPluginCache("preAction: --plugin-dir inline plugins");
		}

		runMigrations();
		profileCheckpoint("preAction_after_migrations");

		// Load remote managed settings for enterprise customers (non-blocking)
		// Fails open - if fetch fails, continues without remote settings
		// Settings are applied via hot-reload when they arrive
		// Must happen after init() to ensure config reading is allowed
		void loadRemoteManagedSettings();
		void loadPolicyLimits();

		profileCheckpoint("preAction_after_remote_settings");

		// Load settings sync (non-blocking, fail-open)
		// CLI: uploads local settings to remote (CCR download is handled by print.ts)
		if (feature("UPLOAD_USER_SETTINGS")) {
			void import("./services/settingsSync/index.js").then((m) =>
				m.uploadUserSettingsInBackground(),
			);
		}

		profileCheckpoint("preAction_after_settings_sync");
	});

	program
		.name("claude")
		.description(
			`Claude Code - starts an interactive session by default, use -p/--print for non-interactive output`,
		)
		.argument("[prompt]", "Your prompt", String)
		// Subcommands inherit helpOption via commander's copyInheritedSettings —
		// setting it once here covers mcp, plugin, auth, and all other subcommands.
		.helpOption("-h, --help", "Display help for command")
		.option(
			"-d, --debug [filter]",
			'Enable debug mode with optional category filtering (e.g., "api,hooks" or "!1p,!file")',
			(_value: string | true) => {
				// If value is provided, it will be the filter string
				// If not provided but flag is present, value will be true
				// The actual filtering is handled in debug.ts by parsing process.argv
				return true;
			},
		)
		.addOption(
			new Option("--debug-to-stderr", "Enable debug mode (to stderr)")
				.argParser(Boolean)
				.hideHelp(),
		)
		.option(
			"--debug-file <path>",
			"Write debug logs to a specific file path (implicitly enables debug mode)",
			() => true,
		)
		.option(
			"--verbose",
			"Override verbose mode setting from config",
			() => true,
		)
		.option(
			"-p, --print",
			"Print response and exit (useful for pipes). Note: The workspace trust dialog is skipped when Claude is run with the -p mode. Only use this flag in directories you trust.",
			() => true,
		)
		.option(
			"--bare",
			"Minimal mode: skip hooks, LSP, plugin sync, attribution, auto-memory, background prefetches, keychain reads, and CLAUDE.md auto-discovery. Sets CLAUDE_CODE_SIMPLE=1. Anthropic auth is strictly ANTHROPIC_API_KEY or apiKeyHelper via --settings (OAuth and keychain are never read). 3P providers (Bedrock/Vertex/Foundry) use their own credentials. Skills still resolve via /skill-name. Explicitly provide context via: --system-prompt[-file], --append-system-prompt[-file], --add-dir (CLAUDE.md dirs), --mcp-config, --settings, --agents, --plugin-dir.",
			() => true,
		)
		.addOption(
			new Option(
				"--init",
				"Run Setup hooks with init trigger, then continue",
			).hideHelp(),
		)
		.addOption(
			new Option(
				"--init-only",
				"Run Setup and SessionStart:startup hooks, then exit",
			).hideHelp(),
		)
		.addOption(
			new Option(
				"--maintenance",
				"Run Setup hooks with maintenance trigger, then continue",
			).hideHelp(),
		)
		.addOption(
			new Option(
				"--output-format <format>",
				'Output format (only works with --print): "text" (default), "json" (single result), or "stream-json" (realtime streaming)',
			).choices(["text", "json", "stream-json"]),
		)
		.addOption(
			new Option(
				"--json-schema <schema>",
				"JSON Schema for structured output validation. " +
					'Example: {"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}',
			).argParser(String),
		)
		.option(
			"--include-hook-events",
			"Include all hook lifecycle events in the output stream (only works with --output-format=stream-json)",
			() => true,
		)
		.option(
			"--include-partial-messages",
			"Include partial message chunks as they arrive (only works with --print and --output-format=stream-json)",
			() => true,
		)
		.addOption(
			new Option(
				"--input-format <format>",
				'Input format (only works with --print): "text" (default), or "stream-json" (realtime streaming input)',
			).choices(["text", "stream-json"]),
		)
		.option(
			"--mcp-debug",
			"[DEPRECATED. Use --debug instead] Enable MCP debug mode (shows MCP server errors)",
			() => true,
		)
		.option(
			"--dangerously-skip-permissions",
			"Bypass all permission checks. Recommended only for sandboxes with no internet access.",
			() => true,
		)
		.option(
			"--allow-dangerously-skip-permissions",
			"Enable bypassing all permission checks as an option, without it being enabled by default. Recommended only for sandboxes with no internet access.",
			() => true,
		)
		.addOption(
			new Option(
				"--thinking <mode>",
				"Thinking mode: enabled (equivalent to adaptive), disabled",
			)
				.choices(["enabled", "adaptive", "disabled"])
				.hideHelp(),
		)
		.addOption(
			new Option(
				"--max-thinking-tokens <tokens>",
				"[DEPRECATED. Use --thinking instead for newer models] Maximum number of thinking tokens (only works with --print)",
			)
				.argParser(Number)
				.hideHelp(),
		)
		.addOption(
			new Option(
				"--max-turns <turns>",
				"Maximum number of agentic turns in non-interactive mode. This will early exit the conversation after the specified number of turns. (only works with --print)",
			)
				.argParser(Number)
				.hideHelp(),
		)
		.addOption(
			new Option(
				"--max-budget-usd <amount>",
				"Maximum dollar amount to spend on API calls (only works with --print)",
			).argParser((value) => {
				const amount = Number(value);
				if (isNaN(amount) || amount <= 0) {
					throw new Error(
						"--max-budget-usd must be a positive number greater than 0",
					);
				}
				return amount;
			}),
		)
		.addOption(
			new Option(
				"--task-budget <tokens>",
				"API-side task budget in tokens (output_config.task_budget)",
			)
				.argParser((value) => {
					const tokens = Number(value);
					if (
						isNaN(tokens) ||
						tokens <= 0 ||
						!Number.isInteger(tokens)
					) {
						throw new Error(
							"--task-budget must be a positive integer",
						);
					}
					return tokens;
				})
				.hideHelp(),
		)
		.option(
			"--replay-user-messages",
			"Re-emit user messages from stdin back on stdout for acknowledgment (only works with --input-format=stream-json and --output-format=stream-json)",
			() => true,
		)
		.addOption(
			new Option(
				"--enable-auth-status",
				"Enable auth status messages in SDK mode",
			)
				.default(false)
				.hideHelp(),
		)
		.option(
			"--allowedTools, --allowed-tools <tools...>",
			'Comma or space-separated list of tool names to allow (e.g. "Bash(git:*) Edit")',
		)
		.option(
			"--tools <tools...>",
			'Specify the list of available tools from the built-in set. Use "" to disable all tools, "default" to use all tools, or specify tool names (e.g. "Bash,Edit,Read").',
		)
		.option(
			"--disallowedTools, --disallowed-tools <tools...>",
			'Comma or space-separated list of tool names to deny (e.g. "Bash(git:*) Edit")',
		)
		.option(
			"--mcp-config <configs...>",
			"Load MCP servers from JSON files or strings (space-separated)",
		)
		.addOption(
			new Option(
				"--permission-prompt-tool <tool>",
				"MCP tool to use for permission prompts (only works with --print)",
			)
				.argParser(String)
				.hideHelp(),
		)
		.addOption(
			new Option(
				"--system-prompt <prompt>",
				"System prompt to use for the session",
			).argParser(String),
		)
		.addOption(
			new Option(
				"--system-prompt-file <file>",
				"Read system prompt from a file",
			)
				.argParser(String)
				.hideHelp(),
		)
		.addOption(
			new Option(
				"--append-system-prompt <prompt>",
				"Append a system prompt to the default system prompt",
			).argParser(String),
		)
		.addOption(
			new Option(
				"--append-system-prompt-file <file>",
				"Read system prompt from a file and append to the default system prompt",
			)
				.argParser(String)
				.hideHelp(),
		)
		.addOption(
			new Option(
				"--permission-mode <mode>",
				"Permission mode to use for the session",
			)
				.argParser(String)
				.choices(PERMISSION_MODES),
		)
		.option(
			"-c, --continue",
			"Continue the most recent conversation in the current directory",
			() => true,
		)
		.option(
			"-r, --resume [value]",
			"Resume a conversation by session ID, or open interactive picker with optional search term",
			(value) => value || true,
		)
		.option(
			"--fork-session",
			"When resuming, create a new session ID instead of reusing the original (use with --resume or --continue)",
			() => true,
		)
		.addOption(
			new Option(
				"--prefill <text>",
				"Pre-fill the prompt input with text without submitting it",
			).hideHelp(),
		)
		.addOption(
			new Option(
				"--deep-link-origin",
				"Signal that this session was launched from a deep link",
			).hideHelp(),
		)
		.addOption(
			new Option(
				"--deep-link-repo <slug>",
				"Repo slug the deep link ?repo= parameter resolved to the current cwd",
			).hideHelp(),
		)
		.addOption(
			new Option(
				"--deep-link-last-fetch <ms>",
				"FETCH_HEAD mtime in epoch ms, precomputed by the deep link trampoline",
			)
				.argParser((v) => {
					const n = Number(v);
					return Number.isFinite(n) ? n : undefined;
				})
				.hideHelp(),
		)
		.option(
			"--from-pr [value]",
			"Resume a session linked to a PR by PR number/URL, or open interactive picker with optional search term",
			(value) => value || true,
		)
		.option(
			"--no-session-persistence",
			"Disable session persistence - sessions will not be saved to disk and cannot be resumed (only works with --print)",
		)
		.addOption(
			new Option(
				"--resume-session-at <message id>",
				"When resuming, only messages up to and including the assistant message with <message.id> (use with --resume in print mode)",
			)
				.argParser(String)
				.hideHelp(),
		)
		.addOption(
			new Option(
				"--rewind-files <user-message-id>",
				"Restore files to state at the specified user message and exit (requires --resume)",
			).hideHelp(),
		)
		// @[MODEL LAUNCH]: Update the example model ID in the --model help text.
		.option(
			"--model <model>",
			`Model for the current session. Provide an alias for the latest model (e.g. 'sonnet' or 'opus') or a model's full name (e.g. 'claude-sonnet-4-6').`,
		)
		.addOption(
			new Option(
				"--effort <level>",
				`Effort level for the current session (low, medium, high, max)`,
			).argParser((rawValue: string) => {
				const value = rawValue.toLowerCase();
				const allowed = ["low", "medium", "high", "max"];
				if (!allowed.includes(value)) {
					throw new InvalidArgumentError(
						`It must be one of: ${allowed.join(", ")}`,
					);
				}
				return value;
			}),
		)
		.option(
			"--agent <agent>",
			`Agent for the current session. Overrides the 'agent' setting.`,
		)
		.option(
			"--betas <betas...>",
			"Beta headers to include in API requests (API key users only)",
		)
		.option(
			"--fallback-model <model>",
			"Enable automatic fallback to specified model when default model is overloaded (only works with --print)",
		)
		.addOption(
			new Option(
				"--workload <tag>",
				"Workload tag for billing-header attribution (cc_workload). Process-scoped; set by SDK daemon callers that spawn subprocesses for cron work. (only works with --print)",
			).hideHelp(),
		)
		.option(
			"--settings <file-or-json>",
			"Path to a settings JSON file or a JSON string to load additional settings from",
		)
		.option(
			"--add-dir <directories...>",
			"Additional directories to allow tool access to",
		)
		.option(
			"--ide",
			"Automatically connect to IDE on startup if exactly one valid IDE is available",
			() => true,
		)
		.option(
			"--strict-mcp-config",
			"Only use MCP servers from --mcp-config, ignoring all other MCP configurations",
			() => true,
		)
		.option(
			"--session-id <uuid>",
			"Use a specific session ID for the conversation (must be a valid UUID)",
		)
		.option(
			"-n, --name <name>",
			"Set a display name for this session (shown in /resume and terminal title)",
		)
		.option(
			"--agents <json>",
			'JSON object defining custom agents (e.g. \'{"reviewer": {"description": "Reviews code", "prompt": "You are a code reviewer"}}\')',
		)
		.option(
			"--setting-sources <sources>",
			"Comma-separated list of setting sources to load (user, project, local).",
		)
		// gh-33508: <paths...> (variadic) consumed everything until the next
		// --flag. `claude --plugin-dir /path mcp add --transport http` swallowed
		// `mcp` and `add` as paths, then choked on --transport as an unknown
		// top-level option. Single-value + collect accumulator means each
		// --plugin-dir takes exactly one arg; repeat the flag for multiple dirs.
		.option(
			"--plugin-dir <path>",
			"Load plugins from a directory for this session only (repeatable: --plugin-dir A --plugin-dir B)",
			(val: string, prev: string[]) => [...prev, val],
			[] as string[],
		)
		.option("--disable-slash-commands", "Disable all skills", () => true)
		.option("--chrome", "Enable Claude in Chrome integration")
		.option("--no-chrome", "Disable Claude in Chrome integration")
		.option(
			"--file <specs...>",
			"File resources to download at startup. Format: file_id:relative_path (e.g., --file file_abc:doc.txt file_def:img.png)",
		)
		.action(async (prompt, options) => {
			profileCheckpoint("action_handler_start");

			// --bare = one-switch minimal mode. Sets SIMPLE so all the existing
			// gates fire (CLAUDE.md, skills, hooks inside executeHooks, agent
			// dir-walk). Must be set before setup() / any of the gated work runs.
			if ((options as { bare?: boolean }).bare) {
				process.env.CLAUDE_CODE_SIMPLE = "1";
			}

			// Ignore "code" as a prompt - treat it the same as no prompt
			if (prompt === "code") {
				logEvent("tengu_code_prompt_ignored", {});
				// biome-ignore lint/suspicious/noConsole:: intentional console output
				console.warn(
					chalk.yellow(
						"Tip: You can launch Claude Code with just `claude`",
					),
				);
				prompt = undefined;
			}

			// Log event for any single-word prompt
			if (
				prompt &&
				typeof prompt === "string" &&
				!/\s/.test(prompt) &&
				prompt.length > 0
			) {
				logEvent("tengu_single_word_prompt", { length: prompt.length });
			}

			// Assistant mode: when .claude/settings.json has assistant: true AND
			// the tengu_kairos GrowthBook gate is on, force brief on. Permission
			// mode is left to the user — settings defaultMode or --permission-mode
			// apply as normal. REPL-typed messages already default to 'next'
			// priority (messageQueueManager.enqueue) so they drain mid-turn between
			// tool calls. SendUserMessage (BriefTool) is enabled via the brief env
			// var. SleepTool stays disabled (its isEnabled() gates on proactive).
			// kairosEnabled is computed once here and reused at the
			// getAssistantSystemPromptAddendum() call site further down.
			//
			// Trust gate: .claude/settings.json is attacker-controllable in an
			// untrusted clone. We run ~1000 lines before showSetupScreens() shows
			// the trust dialog, and by then we've already appended
			// .claude/agents/assistant.md to the system prompt. Refuse to activate
			// until the directory has been explicitly trusted.
			let kairosEnabled = false;
			let assistantTeamContext:
				| Awaited<
						ReturnType<
							NonNullable<
								typeof assistantModule
							>["initializeAssistantTeam"]
						>
				  >
				| undefined;
			if (
				feature("KAIROS") &&
				(options as { assistant?: boolean }).assistant &&
				assistantModule
			) {
				// --assistant (Agent SDK daemon mode): force the latch before
				// isAssistantMode() runs below. The daemon has already checked
				// entitlement — don't make the child re-check tengu_kairos.
				assistantModule.markAssistantForced();
			}
			if (
				feature("KAIROS") &&
				assistantModule &&
				(assistantModule.isAssistantForced() ||
					(options as Record<string, unknown>).assistant === true) &&
				// Spawned teammates share the leader's cwd + settings.json, so
				// the flag is true for them too. --agent-id being set
				// means we ARE a spawned teammate (extractTeammateOptions runs
				// ~170 lines later so check the raw commander option) — don't
				// re-init the team or override teammateMode/proactive/brief.
				!(options as { agentId?: unknown }).agentId &&
				kairosGate
			) {
				if (!checkHasTrustDialogAccepted()) {
					// biome-ignore lint/suspicious/noConsole:: intentional console output
					console.warn(
						chalk.yellow(
							"Assistant mode disabled: directory is not trusted. Accept the trust dialog and restart.",
						),
					);
				} else {
					// Blocking gate check — returns cached `true` instantly; if disk
					// cache is false/missing, lazily inits GrowthBook and fetches fresh
					// (max ~5s). --assistant skips the gate entirely (daemon is
					// pre-entitled).
					kairosEnabled =
						assistantModule.isAssistantForced() ||
						(await kairosGate.isKairosEnabled());
					if (kairosEnabled) {
						const opts = options as { brief?: boolean };
						opts.brief = true;
						setKairosActive(true);
						// Pre-seed an in-process team so Agent(name: "foo") spawns
						// teammates without TeamCreate. Must run BEFORE setup() captures
						// the teammateMode snapshot (initializeAssistantTeam calls
						// setCliTeammateModeOverride internally).
						assistantTeamContext =
							await assistantModule.initializeAssistantTeam();
					}
				}
			}

			const {
				debug = false,
				debugToStderr = false,
				dangerouslySkipPermissions,
				allowDangerouslySkipPermissions = false,
				tools: baseTools = [],
				allowedTools = [],
				disallowedTools = [],
				mcpConfig = [],
				permissionMode: permissionModeCli,
				addDir = [],
				fallbackModel,
				betas = [],
				ide = false,
				sessionId,
				includeHookEvents,
				includePartialMessages,
			} = options;

			if (options.prefill) {
				seedEarlyInput(options.prefill);
			}

			// Promise for file downloads - started early, awaited before REPL renders
			let fileDownloadPromise: Promise<DownloadResult[]> | undefined;

			const agentsJson = options.agents;
			const agentCli = options.agent;
			if (feature("BG_SESSIONS") && agentCli) {
				process.env.CLAUDE_CODE_AGENT = agentCli;
			}

			// NOTE: LSP manager initialization is intentionally deferred until after
			// the trust dialog is accepted. This prevents plugin LSP servers from
			// executing code in untrusted directories before user consent.

			// Extract these separately so they can be modified if needed
			let outputFormat = options.outputFormat;
			let inputFormat = options.inputFormat;
			let verbose = options.verbose ?? getGlobalConfig().verbose;
			let print = options.print;
			const init = options.init ?? false;
			const initOnly = options.initOnly ?? false;
			const maintenance = options.maintenance ?? false;

			// Extract disable slash commands flag
			const disableSlashCommands = options.disableSlashCommands || false;

			// Extract tasks mode options (ant-only)
			const tasksOption =
				process.env.USER_TYPE === "ant" &&
				(options as { tasks?: boolean | string }).tasks;
			const taskListId = tasksOption
				? typeof tasksOption === "string"
					? tasksOption
					: DEFAULT_TASKS_MODE_TASK_LIST_ID
				: undefined;
			if (process.env.USER_TYPE === "ant" && taskListId) {
				process.env.CLAUDE_CODE_TASK_LIST_ID = taskListId;
			}

			// Extract worktree option
			// worktree can be true (flag without value) or a string (custom name or PR reference)
			const worktreeOption = isWorktreeModeEnabled()
				? (options as { worktree?: boolean | string }).worktree
				: undefined;
			let worktreeName =
				typeof worktreeOption === "string" ? worktreeOption : undefined;
			const worktreeEnabled = worktreeOption !== undefined;

			// Check if worktree name is a PR reference (#N or GitHub PR URL)
			let worktreePRNumber: number | undefined;
			if (worktreeName) {
				const prNum = parsePRReference(worktreeName);
				if (prNum !== null) {
					worktreePRNumber = prNum;
					worktreeName = undefined; // slug will be generated in setup()
				}
			}

			// Extract tmux option (requires --worktree)
			const tmuxEnabled =
				isWorktreeModeEnabled() &&
				(options as { tmux?: boolean }).tmux === true;

			// Validate tmux option
			if (tmuxEnabled) {
				if (!worktreeEnabled) {
					process.stderr.write(
						chalk.red("Error: --tmux requires --worktree\n"),
					);
					process.exit(1);
				}
				if (getPlatform() === "windows") {
					process.stderr.write(
						chalk.red(
							"Error: --tmux is not supported on Windows\n",
						),
					);
					process.exit(1);
				}
				if (!(await isTmuxAvailable())) {
					process.stderr.write(
						chalk.red(
							`Error: tmux is not installed.\n${getTmuxInstallInstructions()}\n`,
						),
					);
					process.exit(1);
				}
			}

			// Extract teammate options (for tmux-spawned agents)
			// Declared outside the if block so it's accessible later for system prompt addendum
			let storedTeammateOpts: TeammateOptions | undefined;
			if (isAgentSwarmsEnabled()) {
				// Extract agent identity options (for tmux-spawned agents)
				// These replace the CLAUDE_CODE_* environment variables
				const teammateOpts = extractTeammateOptions(options);
				storedTeammateOpts = teammateOpts;

				// If any teammate identity option is provided, all three required ones must be present
				const hasAnyTeammateOpt =
					teammateOpts.agentId ||
					teammateOpts.agentName ||
					teammateOpts.teamName;
				const hasAllRequiredTeammateOpts =
					teammateOpts.agentId &&
					teammateOpts.agentName &&
					teammateOpts.teamName;

				if (hasAnyTeammateOpt && !hasAllRequiredTeammateOpts) {
					process.stderr.write(
						chalk.red(
							"Error: --agent-id, --agent-name, and --team-name must all be provided together\n",
						),
					);
					process.exit(1);
				}

				// If teammate identity is provided via CLI, set up dynamicTeamContext
				if (
					teammateOpts.agentId &&
					teammateOpts.agentName &&
					teammateOpts.teamName
				) {
					getTeammateUtils().setDynamicTeamContext?.({
						agentId: teammateOpts.agentId,
						agentName: teammateOpts.agentName,
						teamName: teammateOpts.teamName,
						color: teammateOpts.agentColor,
						planModeRequired:
							teammateOpts.planModeRequired ?? false,
						parentSessionId: teammateOpts.parentSessionId,
					});
				}

				// Set teammate mode CLI override if provided
				// This must be done before setup() captures the snapshot
				if (teammateOpts.teammateMode) {
					getTeammateModeSnapshot().setCliTeammateModeOverride?.(
						teammateOpts.teammateMode,
					);
				}
			}

			// Extract remote sdk options
			const sdkUrl = (options as { sdkUrl?: string }).sdkUrl ?? undefined;

			// Allow env var to enable partial messages (used by sandbox gateway for baku)
			const effectiveIncludePartialMessages =
				includePartialMessages ||
				isEnvTruthy(process.env.CLAUDE_CODE_INCLUDE_PARTIAL_MESSAGES);

			// Enable all hook event types when explicitly requested via SDK option
			// or when running in CLAUDE_CODE_REMOTE mode (CCR needs them).
			// Without this, only SessionStart and Setup events are emitted.
			if (
				includeHookEvents ||
				isEnvTruthy(process.env.CLAUDE_CODE_REMOTE)
			) {
				setAllHookEventsEnabled(true);
			}

			// Auto-set input/output formats, verbose mode, and print mode when SDK URL is provided
			if (sdkUrl) {
				// If SDK URL is provided, automatically use stream-json formats unless explicitly set
				if (!inputFormat) {
					inputFormat = "stream-json";
				}
				if (!outputFormat) {
					outputFormat = "stream-json";
				}
				// Auto-enable verbose mode unless explicitly disabled or already set
				if (options.verbose === undefined) {
					verbose = true;
				}
				// Auto-enable print mode unless explicitly disabled
				if (!options.print) {
					print = true;
				}
			}

			// Extract teleport option
			const teleport =
				(options as { teleport?: string | true }).teleport ?? null;

			// Extract remote option (can be true if no description provided, or a string)
			const remoteOption = (options as { remote?: string | true }).remote;
			const remote = remoteOption === true ? "" : (remoteOption ?? null);

			// Extract --remote-control / --rc flag (enable bridge in interactive session)
			const remoteControlOption =
				(options as { remoteControl?: string | true }).remoteControl ??
				(options as { rc?: string | true }).rc;
			// Actual bridge check is deferred to after showSetupScreens() so that
			// trust is established and GrowthBook has auth headers.
			let remoteControl = false;
			const remoteControlName =
				typeof remoteControlOption === "string" &&
				remoteControlOption.length > 0
					? remoteControlOption
					: undefined;

			// Validate session ID if provided
			if (sessionId) {
				// Check for conflicting flags
				// --session-id can be used with --continue or --resume when --fork-session is also provided
				// (to specify a custom ID for the forked session)
				if (
					(options.continue || options.resume) &&
					!options.forkSession
				) {
					process.stderr.write(
						chalk.red(
							"Error: --session-id can only be used with --continue or --resume if --fork-session is also specified.\n",
						),
					);
					process.exit(1);
				}

				// When --sdk-url is provided (bridge/remote mode), the session ID is a
				// server-assigned tagged ID (e.g. "session_local_01...") rather than a
				// UUID. Skip UUID validation and local existence checks in that case.
				if (!sdkUrl) {
					const validatedSessionId = validateUuid(sessionId);
					if (!validatedSessionId) {
						process.stderr.write(
							chalk.red(
								"Error: Invalid session ID. Must be a valid UUID.\n",
							),
						);
						process.exit(1);
					}

					// Check if session ID already exists
					if (sessionIdExists(validatedSessionId)) {
						process.stderr.write(
							chalk.red(
								`Error: Session ID ${validatedSessionId} is already in use.\n`,
							),
						);
						process.exit(1);
					}
				}
			}

			// Download file resources if specified via --file flag
			const fileSpecs = (options as { file?: string[] }).file;
			if (fileSpecs && fileSpecs.length > 0) {
				// Get session ingress token (provided by EnvManager via CLAUDE_CODE_SESSION_ACCESS_TOKEN)
				const sessionToken = getSessionIngressAuthToken();
				if (!sessionToken) {
					process.stderr.write(
						chalk.red(
							"Error: Session token required for file downloads. CLAUDE_CODE_SESSION_ACCESS_TOKEN must be set.\n",
						),
					);
					process.exit(1);
				}

				// Resolve session ID: prefer remote session ID, fall back to internal session ID
				const fileSessionId =
					process.env.CLAUDE_CODE_REMOTE_SESSION_ID || getSessionId();

				const files = parseFileSpecs(fileSpecs);
				if (files.length > 0) {
					// Use ANTHROPIC_BASE_URL if set (by EnvManager), otherwise use OAuth config
					// This ensures consistency with session ingress API in all environments
					const config: FilesApiConfig = {
						baseUrl:
							process.env.ANTHROPIC_BASE_URL ||
							getOauthConfig().BASE_API_URL,
						oauthToken: sessionToken,
						sessionId: fileSessionId,
					};

					// Start download without blocking startup - await before REPL renders
					fileDownloadPromise = downloadSessionFiles(files, config);
				}
			}

			// Get isNonInteractiveSession from state (was set before init())
			const isNonInteractiveSession = getIsNonInteractiveSession();

			// Validate that fallback model is different from main model
			if (
				fallbackModel &&
				options.model &&
				fallbackModel === options.model
			) {
				process.stderr.write(
					chalk.red(
						"Error: Fallback model cannot be the same as the main model. Please specify a different model for --fallback-model.\n",
					),
				);
				process.exit(1);
			}

			// Handle system prompt options
			let systemPrompt = options.systemPrompt;
			if (options.systemPromptFile) {
				if (options.systemPrompt) {
					process.stderr.write(
						chalk.red(
							"Error: Cannot use both --system-prompt and --system-prompt-file. Please use only one.\n",
						),
					);
					process.exit(1);
				}

				try {
					const filePath = resolve(options.systemPromptFile);
					systemPrompt = readFileSync(filePath, "utf8");
				} catch (error) {
					const code = getErrnoCode(error);
					if (code === "ENOENT") {
						process.stderr.write(
							chalk.red(
								`Error: System prompt file not found: ${resolve(options.systemPromptFile)}\n`,
							),
						);
						process.exit(1);
					}
					process.stderr.write(
						chalk.red(
							`Error reading system prompt file: ${errorMessage(error)}\n`,
						),
					);
					process.exit(1);
				}
			}

			// Handle append system prompt options
			let appendSystemPrompt = options.appendSystemPrompt;
			if (options.appendSystemPromptFile) {
				if (options.appendSystemPrompt) {
					process.stderr.write(
						chalk.red(
							"Error: Cannot use both --append-system-prompt and --append-system-prompt-file. Please use only one.\n",
						),
					);
					process.exit(1);
				}

				try {
					const filePath = resolve(options.appendSystemPromptFile);
					appendSystemPrompt = readFileSync(filePath, "utf8");
				} catch (error) {
					const code = getErrnoCode(error);
					if (code === "ENOENT") {
						process.stderr.write(
							chalk.red(
								`Error: Append system prompt file not found: ${resolve(options.appendSystemPromptFile)}\n`,
							),
						);
						process.exit(1);
					}
					process.stderr.write(
						chalk.red(
							`Error reading append system prompt file: ${errorMessage(error)}\n`,
						),
					);
					process.exit(1);
				}
			}

			// Add teammate-specific system prompt addendum for tmux teammates
			if (
				isAgentSwarmsEnabled() &&
				storedTeammateOpts?.agentId &&
				storedTeammateOpts?.agentName &&
				storedTeammateOpts?.teamName
			) {
				const addendum =
					getTeammatePromptAddendum().TEAMMATE_SYSTEM_PROMPT_ADDENDUM;
				appendSystemPrompt = appendSystemPrompt
					? `${appendSystemPrompt}\n\n${addendum}`
					: addendum;
			}

			const {
				mode: permissionMode,
				notification: permissionModeNotification,
			} = initialPermissionModeFromCLI({
				permissionModeCli,
				dangerouslySkipPermissions,
			});

			// Store session bypass permissions mode for trust dialog check
			setSessionBypassPermissionsMode(
				permissionMode === "bypassPermissions",
			);
			if (feature("TRANSCRIPT_CLASSIFIER")) {
				// autoModeFlagCli is the "did the user intend auto this session" signal.
				// Set when: --enable-auto-mode, --permission-mode auto, resolved mode
				// is auto, OR settings defaultMode is auto but the gate denied it
				// (permissionMode resolved to default with no explicit CLI override).
				// Used by verifyAutoModeGateAccess to decide whether to notify on
				// auto-unavailable, and by tengu_auto_mode_config opt-in carousel.
				if (
					(options as { enableAutoMode?: boolean }).enableAutoMode ||
					permissionModeCli === "auto" ||
					permissionMode === "auto" ||
					(!permissionModeCli && isDefaultPermissionModeAuto())
				) {
					autoModeStateModule?.setAutoModeFlagCli(true);
				}
			}

			// Parse the MCP config files/strings if provided
			let dynamicMcpConfig: Record<string, ScopedMcpServerConfig> = {
				// Built-in MCP servers (default disabled, user enables via /mcp)
				"mcp-chrome": {
					type: "http",
					url: "http://127.0.0.1:12306/mcp",
					scope: "dynamic",
					"headers": {
						"Authorization": "Bearer my-static-token",
					}
				},
			};

			if (mcpConfig && mcpConfig.length > 0) {
				// Process mcpConfig array
				const processedConfigs = mcpConfig
					.map((config) => config.trim())
					.filter((config) => config.length > 0);

				let allConfigs: Record<string, McpServerConfig> = {};
				const allErrors: ValidationError[] = [];

				for (const configItem of processedConfigs) {
					let configs: Record<string, McpServerConfig> | null = null;
					let errors: ValidationError[] = [];

					// First try to parse as JSON string
					const parsedJson = safeParseJSON(configItem);
					if (parsedJson) {
						const result = parseMcpConfig({
							configObject: parsedJson,
							filePath: "command line",
							expandVars: true,
							scope: "dynamic",
						});
						if (result.config) {
							configs = result.config.mcpServers;
						} else {
							errors = result.errors;
						}
					} else {
						// Try as file path
						const configPath = resolve(configItem);
						const result = parseMcpConfigFromFilePath({
							filePath: configPath,
							expandVars: true,
							scope: "dynamic",
						});
						if (result.config) {
							configs = result.config.mcpServers;
						} else {
							errors = result.errors;
						}
					}

					if (errors.length > 0) {
						allErrors.push(...errors);
					} else if (configs) {
						// Merge configs, later ones override earlier ones
						allConfigs = { ...allConfigs, ...configs };
					}
				}

				if (allErrors.length > 0) {
					const formattedErrors = allErrors
						.map(
							(err) =>
								`${err.path ? err.path + ": " : ""}${err.message}`,
						)
						.join("\n");
					logForDebugging(
						`--mcp-config validation failed (${allErrors.length} errors): ${formattedErrors}`,
						{
							level: "error",
						},
					);
					process.stderr.write(
						`Error: Invalid MCP configuration:\n${formattedErrors}\n`,
					);
					process.exit(1);
				}

				if (Object.keys(allConfigs).length > 0) {
					// SDK hosts (Nest/Desktop) own their server naming and may reuse
					// built-in names — skip reserved-name checks for type:'sdk'.
					const nonSdkConfigNames = Object.entries(allConfigs)
						.filter(([, config]) => config.type !== "sdk")
						.map(([name]) => name);

					let reservedNameError: string | null = null;
					if (nonSdkConfigNames.some(isClaudeInChromeMCPServer)) {
						reservedNameError = `Invalid MCP configuration: "${CLAUDE_IN_CHROME_MCP_SERVER_NAME}" is a reserved MCP name.`;
					} else if (feature("CHICAGO_MCP")) {
						const {
							isComputerUseMCPServer,
							COMPUTER_USE_MCP_SERVER_NAME,
						} = await import("src/utils/computerUse/common.js");
						if (nonSdkConfigNames.some(isComputerUseMCPServer)) {
							reservedNameError = `Invalid MCP configuration: "${COMPUTER_USE_MCP_SERVER_NAME}" is a reserved MCP name.`;
						}
					}
					if (reservedNameError) {
						// stderr+exit(1) — a throw here becomes a silent unhandled
						// rejection in stream-json mode (void main() in cli.tsx).
						process.stderr.write(`Error: ${reservedNameError}\n`);
						process.exit(1);
					}

					// Add dynamic scope to all configs. type:'sdk' entries pass through
					// unchanged — they're extracted into sdkMcpConfigs downstream and
					// passed to print.ts. The Python SDK relies on this path (it doesn't
					// send sdkMcpServers in the initialize message). Dropping them here
					// broke Coworker (inc-5122). The policy filter below already exempts
					// type:'sdk', and the entries are inert without an SDK transport on
					// stdin, so there's no bypass risk from letting them through.
					const scopedConfigs = mapValues(allConfigs, (config) => ({
						...config,
						scope: "dynamic" as const,
					}));

					// Enforce managed policy (allowedMcpServers / deniedMcpServers) on
					// --mcp-config servers. Without this, the CLI flag bypasses the
					// enterprise allowlist that user/project/local configs go through in
					// getClaudeCodeMcpConfigs — callers spread dynamicMcpConfig back on
					// top of filtered results. Filter here at the source so all
					// downstream consumers see the policy-filtered set.
					const { allowed, blocked } =
						filterMcpServersByPolicy(scopedConfigs);
					if (blocked.length > 0) {
						process.stderr.write(
							`Warning: MCP ${plural(blocked.length, "server")} blocked by enterprise policy: ${blocked.join(", ")}\n`,
						);
					}
					dynamicMcpConfig = { ...dynamicMcpConfig, ...(allowed as Record<string, ScopedMcpServerConfig>) };
				}
			}

			// Extract Claude in Chrome option and enforce claude.ai subscriber check (unless user is ant)
			const chromeOpts = options as { chrome?: boolean };
			// Store the explicit CLI flag so teammates can inherit it
			setChromeFlagOverride(chromeOpts.chrome);
			const enableClaudeInChrome =
				shouldEnableClaudeInChrome(chromeOpts.chrome) &&
				(process.env.USER_TYPE === "ant" || isClaudeAISubscriber());
			const autoEnableClaudeInChrome =
				!enableClaudeInChrome && shouldAutoEnableClaudeInChrome();

			if (enableClaudeInChrome) {
				const platform = getPlatform();
				try {
					logEvent("tengu_claude_in_chrome_setup", {
						platform:
							platform as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
					});

					const {
						mcpConfig: chromeMcpConfig,
						allowedTools: chromeMcpTools,
						systemPrompt: chromeSystemPrompt,
					} = setupClaudeInChrome();
					dynamicMcpConfig = {
						...dynamicMcpConfig,
						...chromeMcpConfig,
					};
					allowedTools.push(...chromeMcpTools);
					if (chromeSystemPrompt) {
						appendSystemPrompt = appendSystemPrompt
							? `${chromeSystemPrompt}\n\n${appendSystemPrompt}`
							: chromeSystemPrompt;
					}
				} catch (error) {
					logEvent("tengu_claude_in_chrome_setup_failed", {
						platform:
							platform as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
					});
					logForDebugging(`[Claude in Chrome] Error: ${error}`);
					logError(error);
					// biome-ignore lint/suspicious/noConsole:: intentional console output
					console.error(
						`Error: Failed to run with Claude in Chrome.`,
					);
					process.exit(1);
				}
			} else if (autoEnableClaudeInChrome) {
				try {
					const { mcpConfig: chromeMcpConfig } =
						setupClaudeInChrome();
					dynamicMcpConfig = {
						...dynamicMcpConfig,
						...chromeMcpConfig,
					};

					const hint =
						feature("WEB_BROWSER_TOOL") &&
						typeof Bun !== "undefined" &&
						"WebView" in Bun
							? CLAUDE_IN_CHROME_SKILL_HINT_WITH_WEBBROWSER
							: CLAUDE_IN_CHROME_SKILL_HINT;
					appendSystemPrompt = appendSystemPrompt
						? `${appendSystemPrompt}\n\n${hint}`
						: hint;
				} catch (error) {
					// Silently skip any errors for the auto-enable
					logForDebugging(
						`[Claude in Chrome] Error (auto-enable): ${error}`,
					);
				}
			}

			// Extract strict MCP config flag
			const strictMcpConfig = options.strictMcpConfig || false;

			// Check if enterprise MCP configuration exists. When it does, only allow dynamic MCP
			// configs that contain special server types (sdk)
			if (doesEnterpriseMcpConfigExist()) {
				if (strictMcpConfig) {
					process.stderr.write(
						chalk.red(
							"You cannot use --strict-mcp-config when an enterprise MCP config is present",
						),
					);
					process.exit(1);
				}

				// For --mcp-config, allow if all servers are internal types (sdk)
				if (
					dynamicMcpConfig &&
					!areMcpConfigsAllowedWithEnterpriseMcpConfig(
						dynamicMcpConfig,
					)
				) {
					process.stderr.write(
						chalk.red(
							"You cannot dynamically configure MCP servers when an enterprise MCP config is present",
						),
					);
					process.exit(1);
				}
			}

			// chicago MCP: guarded Computer Use (app allowlist + frontmost gate +
			// SCContentFilter screenshots). Ant-only, GrowthBook-gated — failures
			// are silent (this is dogfooding). Platform + interactive checks inline
			// so non-macOS / print-mode ants skip the heavy @ant/computer-use-mcp
			// import entirely. gates.js is light (type-only package import).
			//
			// Placed AFTER the enterprise-MCP-config check: that check rejects any
			// dynamicMcpConfig entry with `type !== 'sdk'`, and our config is
			// `type: 'stdio'`. An enterprise-config ant with the GB gate on would
			// otherwise process.exit(1). Chrome has the same latent issue but has
			// shipped without incident; chicago places itself correctly.
			if (
				feature("CHICAGO_MCP") &&
				getPlatform() !== "unknown" &&
				!getIsNonInteractiveSession()
			) {
				try {
					const { getChicagoEnabled } =
						await import("src/utils/computerUse/gates.js");
					if (getChicagoEnabled()) {
						const { setupComputerUseMCP } =
							await import("src/utils/computerUse/setup.js");
						const { mcpConfig, allowedTools: cuTools } =
							setupComputerUseMCP();
						dynamicMcpConfig = {
							...dynamicMcpConfig,
							...mcpConfig,
						};
						allowedTools.push(...cuTools);
					}
				} catch (error) {
					logForDebugging(
						`[Computer Use MCP] Setup failed: ${errorMessage(error)}`,
					);
				}
			}

			// Store additional directories for CLAUDE.md loading (controlled by env var)
			setAdditionalDirectoriesForClaudeMd(addDir);

			// Channel server allowlist from --channels flag — servers whose
			// inbound push notifications should register this session. The option
			// is added inside a feature() block so TS doesn't know about it
			// on the options type — same pattern as --assistant at main.tsx:1824.
			// devChannels is deferred: showSetupScreens shows a confirmation dialog
			// and only appends to allowedChannels on accept.
			let devChannels: ChannelEntry[] | undefined;
			// Parse plugin:name@marketplace / server:Y tags into typed entries.
			// Tag decides trust model downstream: plugin-kind hits marketplace
			// verification + GrowthBook allowlist, server-kind always fails
			// allowlist (schema is plugin-only) unless dev flag is set.
			// Untagged or marketplace-less plugin entries are hard errors —
			// silently not-matching in the gate would look like channels are
			// "on" but nothing ever fires.
			const parseChannelEntries = (
				raw: string[],
				flag: string,
			): ChannelEntry[] => {
				const entries: ChannelEntry[] = [];
				const bad: string[] = [];
				for (const c of raw) {
					if (c.startsWith("plugin:")) {
						const rest = c.slice(7);
						const at = rest.indexOf("@");
						if (at <= 0 || at === rest.length - 1) {
							bad.push(c);
						} else {
							entries.push({
								kind: "plugin",
								name: rest.slice(0, at),
								marketplace: rest.slice(at + 1),
							});
						}
					} else if (c.startsWith("server:") && c.length > 7) {
						entries.push({ kind: "server", name: c.slice(7) });
					} else {
						bad.push(c);
					}
				}
				if (bad.length > 0) {
					process.stderr.write(
						chalk.red(
							`${flag} entries must be tagged: ${bad.join(", ")}\n` +
								`  plugin:<name>@<marketplace>  — plugin-provided channel (allowlist enforced)\n` +
								`  server:<name>                — manually configured MCP server\n`,
						),
					);
					process.exit(1);
				}
				return entries;
			};

			const channelOpts = options as {
				channels?: string[];
				dangerouslyLoadDevelopmentChannels?: string[];
			};
			const rawChannels = channelOpts.channels;
			const rawDev = channelOpts.dangerouslyLoadDevelopmentChannels;
			// Always parse + set. ChannelsNotice reads getAllowedChannels() and
			// renders the appropriate branch (disabled/noAuth/policyBlocked/
			// listening) in the startup screen. gateChannelServer() enforces.
			// --channels works in both interactive and print/SDK modes; dev-channels
			// stays interactive-only (requires a confirmation dialog).
			let channelEntries: ChannelEntry[] = [];
			if (rawChannels && rawChannels.length > 0) {
				channelEntries = parseChannelEntries(
					rawChannels,
					"--channels",
				);
				setAllowedChannels(channelEntries);
			}
			if (!isNonInteractiveSession) {
				if (rawDev && rawDev.length > 0) {
					devChannels = parseChannelEntries(
						rawDev,
						"--dangerously-load-development-channels",
					);
				}
			}
			// Flag-usage telemetry. Plugin identifiers are logged (same tier as
			// tengu_plugin_installed — public-registry-style names); server-kind
			// names are not (MCP-server-name tier, opt-in-only elsewhere).
			// Per-server gate outcomes land in tengu_mcp_channel_gate once
			// servers connect. Dev entries go through a confirmation dialog after
			// this — dev_plugins captures what was typed, not what was accepted.
			if (
				channelEntries.length > 0 ||
				(devChannels?.length ?? 0) > 0
			) {
				const joinPluginIds = (entries: ChannelEntry[]) => {
					const ids = entries.flatMap((e) =>
						e.kind === "plugin"
							? [`${e.name}@${e.marketplace}`]
							: [],
					);
					return ids.length > 0
						? (ids
								.sort()
								.join(
									",",
								) as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS)
						: undefined;
				};
				logEvent("tengu_mcp_channel_flags", {
					channels_count: channelEntries.length,
					dev_count: devChannels?.length ?? 0,
					plugins: joinPluginIds(channelEntries),
					dev_plugins: joinPluginIds(devChannels ?? []),
				});
			}

			// SDK opt-in for SendUserMessage via --tools. All sessions require
			// explicit opt-in; listing it in --tools signals intent. Runs BEFORE
			// initializeToolPermissionContext so getToolsForDefaultPreset() sees
			// the tool as enabled when computing the base-tools disallow filter.
			// Conditional require avoids leaking the tool-name string into
			// external builds.
			if (
				(feature("KAIROS") || feature("KAIROS_BRIEF")) &&
				baseTools.length > 0
			) {
				/* eslint-disable @typescript-eslint/no-require-imports */
				const { BRIEF_TOOL_NAME, LEGACY_BRIEF_TOOL_NAME } =
					require("@claude-code-best/builtin-tools/tools/BriefTool/prompt.js") as typeof import("@claude-code-best/builtin-tools/tools/BriefTool/prompt.js");
				const { isBriefEntitled } =
					require("@claude-code-best/builtin-tools/tools/BriefTool/BriefTool.js") as typeof import("@claude-code-best/builtin-tools/tools/BriefTool/BriefTool.js");
				/* eslint-enable @typescript-eslint/no-require-imports */
				const parsed = parseToolListFromCLI(baseTools);
				if (
					(parsed.includes(BRIEF_TOOL_NAME) ||
						parsed.includes(LEGACY_BRIEF_TOOL_NAME)) &&
					isBriefEntitled()
				) {
					setUserMsgOptIn(true);
				}
			}

			// This await replaces blocking existsSync/statSync calls that were already in
			// the startup path. Wall-clock time is unchanged; we just yield to the event
			// loop during the fs I/O instead of blocking it. See #19661.
			const initResult = await initializeToolPermissionContext({
				allowedToolsCli: allowedTools,
				disallowedToolsCli: disallowedTools,
				baseToolsCli: baseTools,
				permissionMode,
				allowDangerouslySkipPermissions,
				addDirs: addDir,
			});
			let toolPermissionContext = initResult.toolPermissionContext;
			const {
				warnings,
				dangerousPermissions,
				overlyBroadBashPermissions,
			} = initResult;

			// Handle overly broad shell allow rules for ant users (Bash(*), PowerShell(*))
			if (
				process.env.USER_TYPE === "ant" &&
				overlyBroadBashPermissions.length > 0
			) {
				for (const permission of overlyBroadBashPermissions) {
					logForDebugging(
						`Ignoring overly broad shell permission ${permission.ruleDisplay} from ${permission.sourceDisplay}`,
					);
				}
				toolPermissionContext = removeDangerousPermissions(
					toolPermissionContext,
					overlyBroadBashPermissions,
				);
			}

			if (
				feature("TRANSCRIPT_CLASSIFIER") &&
				dangerousPermissions.length > 0
			) {
				toolPermissionContext = stripDangerousPermissionsForAutoMode(
					toolPermissionContext,
				);
			}

			// Print any warnings from initialization
			warnings.forEach((warning) => {
				// biome-ignore lint/suspicious/noConsole:: intentional console output
				console.error(warning);
			});


			// claude.ai config fetch: -p mode only (interactive uses useManageMCPConnections
			// two-phase loading). Kicked off here to overlap with setup(); awaited
			// before runHeadless so single-turn -p sees connectors. Skipped under
			// enterprise/strict MCP to preserve policy boundaries.
			const claudeaiConfigPromise: Promise<
				Record<string, ScopedMcpServerConfig>
			> =
				isNonInteractiveSession &&
				!strictMcpConfig &&
				!doesEnterpriseMcpConfigExist() &&
				// --bare / SIMPLE: skip claude.ai proxy servers (datadog, Gmail,
				// Slack, BigQuery, PubMed — 6-14s each to connect). Scripted calls
				// that need MCP pass --mcp-config explicitly.
				!isBareMode()
					? fetchClaudeAIMcpConfigsIfEligible().then((configs) => {
							const { allowed, blocked } =
								filterMcpServersByPolicy(configs);
							if (blocked.length > 0) {
								process.stderr.write(
									`Warning: claude.ai MCP ${plural(blocked.length, "server")} blocked by enterprise policy: ${blocked.join(", ")}\n`,
								);
							}
							return allowed;
						})
					: Promise.resolve({});

			// Kick off MCP config loading early (safe - just reads files, no execution).
			// Both interactive and -p use getClaudeCodeMcpConfigs (local file reads only).
			// The local promise is awaited later (before prefetchAllMcpResources) to
			// overlap config I/O with setup(), commands loading, and trust dialog.
			logForDebugging("[STARTUP] Loading MCP configs...");
			const mcpConfigStart = Date.now();
			let mcpConfigResolvedMs: number | undefined;
			// --bare skips auto-discovered MCP (.mcp.json, user settings, plugins) —
			// only explicit --mcp-config works. dynamicMcpConfig is spread onto
			// allMcpConfigs downstream so it survives this skip.
			const mcpConfigPromise = (
				strictMcpConfig || isBareMode()
					? Promise.resolve({
							servers: {} as Record<
								string,
								ScopedMcpServerConfig
							>,
						})
					: getClaudeCodeMcpConfigs(dynamicMcpConfig)
			).then((result) => {
				mcpConfigResolvedMs = Date.now() - mcpConfigStart;
				return result;
			});

			// NOTE: We do NOT call prefetchAllMcpResources here - that's deferred until after trust dialog

			if (
				inputFormat &&
				inputFormat !== "text" &&
				inputFormat !== "stream-json"
			) {
				// biome-ignore lint/suspicious/noConsole:: intentional console output
				console.error(`Error: Invalid input format "${inputFormat}".`);
				process.exit(1);
			}
			if (
				inputFormat === "stream-json" &&
				outputFormat !== "stream-json"
			) {
				// biome-ignore lint/suspicious/noConsole:: intentional console output
				console.error(
					`Error: --input-format=stream-json requires output-format=stream-json.`,
				);
				process.exit(1);
			}

			// Validate sdkUrl is only used with appropriate formats (formats are auto-set above)
			if (sdkUrl) {
				if (
					inputFormat !== "stream-json" ||
					outputFormat !== "stream-json"
				) {
					// biome-ignore lint/suspicious/noConsole:: intentional console output
					console.error(
						`Error: --sdk-url requires both --input-format=stream-json and --output-format=stream-json.`,
					);
					process.exit(1);
				}
			}

			// Validate replayUserMessages is only used with stream-json formats
			if (options.replayUserMessages) {
				if (
					inputFormat !== "stream-json" ||
					outputFormat !== "stream-json"
				) {
					// biome-ignore lint/suspicious/noConsole:: intentional console output
					console.error(
						`Error: --replay-user-messages requires both --input-format=stream-json and --output-format=stream-json.`,
					);
					process.exit(1);
				}
			}

			// Validate includePartialMessages is only used with print mode and stream-json output
			if (effectiveIncludePartialMessages) {
				if (
					!isNonInteractiveSession ||
					outputFormat !== "stream-json"
				) {
					writeToStderr(
						`Error: --include-partial-messages requires --print and --output-format=stream-json.`,
					);
					process.exit(1);
				}
			}

			// Validate --no-session-persistence is only used with print mode
			if (
				options.sessionPersistence === false &&
				!isNonInteractiveSession
			) {
				writeToStderr(
					`Error: --no-session-persistence can only be used with --print mode.`,
				);
				process.exit(1);
			}

			const effectivePrompt = prompt || "";
			let inputPrompt = await getInputPrompt(
				effectivePrompt,
				(inputFormat ?? "text") as "text" | "stream-json",
			);
			profileCheckpoint("action_after_input_prompt");

			// Activate proactive mode BEFORE getTools() so SleepTool.isEnabled()
			// (which returns isProactiveActive()) passes and Sleep is included.
			// The later REPL-path maybeActivateProactive() calls are idempotent.
			maybeActivateProactive(options);

			let tools = getTools(toolPermissionContext);

			// Apply coordinator mode tool filtering for headless path
			// (mirrors useMergedTools.ts filtering for REPL/interactive path)
			if (
				feature("COORDINATOR_MODE") &&
				isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE)
			) {
				const { applyCoordinatorToolFilter } =
					await import("./utils/toolPool.js");
				tools = applyCoordinatorToolFilter(tools);
			}

			profileCheckpoint("action_tools_loaded");

			let jsonSchema: ToolInputJSONSchema | undefined;
			if (
				isSyntheticOutputToolEnabled({ isNonInteractiveSession }) &&
				options.jsonSchema
			) {
				jsonSchema = jsonParse(
					options.jsonSchema,
				) as ToolInputJSONSchema;
			}

			if (jsonSchema) {
				const syntheticOutputResult =
					createSyntheticOutputTool(jsonSchema);
				if ("tool" in syntheticOutputResult) {
					// Add SyntheticOutputTool to the tools array AFTER getTools() filtering.
					// This tool is excluded from normal filtering (see tools.ts) because it's
					// an implementation detail for structured output, not a user-controlled tool.
					tools = [...tools, syntheticOutputResult.tool];

					logEvent("tengu_structured_output_enabled", {
						schema_property_count: Object.keys(
							(jsonSchema.properties as Record<
								string,
								unknown
							>) || {},
						)
							.length as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
						has_required_fields: Boolean(
							jsonSchema.required,
						) as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
					});
				} else {
					logEvent("tengu_structured_output_failure", {
						error: "Invalid JSON schema" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
					});
				}
			}

			// IMPORTANT: setup() must be called before any other code that depends on the cwd or worktree setup
			profileCheckpoint("action_before_setup");
			logForDebugging("[STARTUP] Running setup()...");
			const setupStart = Date.now();
			const { setup } = await import("./setup.js");
			const messagingSocketPath = feature("UDS_INBOX")
				? (options as { messagingSocketPath?: string })
						.messagingSocketPath
				: undefined;
			// Parallelize setup() with commands+agents loading. setup()'s ~28ms is
			// mostly startUdsMessaging (socket bind, ~20ms) — not disk-bound, so it
			// doesn't contend with getCommands' file reads. Gated on !worktreeEnabled
			// since --worktree makes setup() process.chdir() (setup.ts:203), and
			// commands/agents need the post-chdir cwd.
			const preSetupCwd = getCwd();
			// Register bundled skills/plugins before kicking getCommands() — they're
			// pure in-memory array pushes (<1ms, zero I/O) that getBundledSkills()
			// reads synchronously. Previously ran inside setup() after ~20ms of
			// await points, so the parallel getCommands() memoized an empty list.
			if (process.env.CLAUDE_CODE_ENTRYPOINT !== "local-agent") {
				initBuiltinPlugins();
				initBundledSkills();
			}
			const setupPromise = setup(
				preSetupCwd,
				permissionMode,
				allowDangerouslySkipPermissions,
				worktreeEnabled,
				worktreeName,
				tmuxEnabled,
				sessionId ? validateUuid(sessionId) : undefined,
				worktreePRNumber,
				messagingSocketPath,
			);
			const commandsPromise = worktreeEnabled
				? null
				: getCommands(preSetupCwd);
			const agentDefsPromise = worktreeEnabled
				? null
				: getAgentDefinitionsWithOverrides(preSetupCwd);
			// Suppress transient unhandledRejection if these reject during the
			// ~28ms setupPromise await before Promise.all joins them below.
			commandsPromise?.catch(() => {});
			agentDefsPromise?.catch(() => {});
			await setupPromise;
			logForDebugging(
				`[STARTUP] setup() completed in ${Date.now() - setupStart}ms`,
			);
			profileCheckpoint("action_after_setup");

			// Replay user messages into stream-json only when the socket was
			// explicitly requested. The auto-generated socket is passive — it
			// lets tools inject if they want to, but turning it on by default
			// shouldn't reshape stream-json for SDK consumers who never touch it.
			// Callers who inject and also want those injections visible in the
			// stream pass --messaging-socket-path explicitly (or --replay-user-messages).
			let effectiveReplayUserMessages = !!options.replayUserMessages;
			if (feature("UDS_INBOX")) {
				if (
					!effectiveReplayUserMessages &&
					outputFormat === "stream-json"
				) {
					effectiveReplayUserMessages = !!(
						options as { messagingSocketPath?: string }
					).messagingSocketPath;
				}
			}

			if (getIsNonInteractiveSession()) {
				// Apply full merged settings env now (including project-scoped
				// .claude/settings.json PATH/GIT_DIR/GIT_WORK_TREE) so gitExe() and
				// the git spawn below see it. Trust is implicit in -p mode; the
				// docstring at managedEnv.ts:96-97 says this applies "potentially
				// dangerous environment variables such as LD_PRELOAD, PATH" from all
				// sources. The later call in the isNonInteractiveSession block below
				// is idempotent (Object.assign, configureGlobalAgents ejects prior
				// interceptor) and picks up any plugin-contributed env after plugin
				// init. Project settings are already loaded here:
				// applySafeConfigEnvironmentVariables in init() called
				// getSettings_DEPRECATED at managedEnv.ts:86 which merges all enabled
				// sources including projectSettings/localSettings.
				applyConfigEnvironmentVariables();

				// Spawn git status/log/branch now so the subprocess execution overlaps
				// with the getCommands await below and startDeferredPrefetches. After
				// setup() so cwd is final (setup.ts:254 may process.chdir(worktreePath)
				// for --worktree) and after the applyConfigEnvironmentVariables above
				// so PATH/GIT_DIR/GIT_WORK_TREE from all sources (trusted + project)
				// are applied. getSystemContext is memoized; the
				// prefetchSystemContextIfSafe call in startDeferredPrefetches becomes
				// a cache hit. The microtask from await getIsGit() drains at the
				// getCommands Promise.all await below. Trust is implicit in -p mode
				// (same gate as prefetchSystemContextIfSafe).
				void getSystemContext();
				// Kick getUserContext now too — its first await (fs.readFile in
				// getMemoryFiles) yields naturally, so the CLAUDE.md directory walk
				// runs during the ~280ms overlap window before the context
				// Promise.all join in print.ts. The void getUserContext() in
				// startDeferredPrefetches becomes a memoize cache-hit.
				void getUserContext();
				// Kick ensureModelStringsInitialized now — for Bedrock this triggers
				// a 100-200ms profile fetch that was awaited serially at
				// print.ts:739. updateBedrockModelStrings is sequential()-wrapped so
				// the await joins the in-flight fetch. Non-Bedrock is a sync
				// early-return (zero-cost).
				void ensureModelStringsInitialized();
			}

			// Apply --name: cache-only so no orphan file is created before the
			// session ID is finalized by --continue/--resume. materializeSessionFile
			// persists it on the first user message; REPL's useTerminalTitle reads it
			// via getCurrentSessionTitle.
			const sessionNameArg = options.name?.trim();
			if (sessionNameArg) {
				cacheSessionTitle(sessionNameArg);
			}

			// Ant model aliases (capybara-fast etc.) resolve via the
			// tengu_ant_model_override GrowthBook flag. _CACHED_MAY_BE_STALE reads
			// disk synchronously; disk is populated by a fire-and-forget write. On a
			// cold cache, parseUserSpecifiedModel returns the unresolved alias, the
			// API 404s, and -p exits before the async write lands — crashloop on
			// fresh pods. Awaiting init here populates the in-memory payload map that
			// _CACHED_MAY_BE_STALE now checks first. Gated so the warm path stays
			// non-blocking:
			//  - explicit model via --model or ANTHROPIC_MODEL (both feed alias resolution)
			//  - no env override (which short-circuits _CACHED_MAY_BE_STALE before disk)
			//  - flag absent from disk (== null also catches pre-#22279 poisoned null)
			const explicitModel = options.model || process.env.ANTHROPIC_MODEL;
			if (
				process.env.USER_TYPE === "ant" &&
				explicitModel &&
				explicitModel !== "default" &&
				!hasGrowthBookEnvOverride("tengu_ant_model_override") &&
				getGlobalConfig().cachedGrowthBookFeatures?.[
					"tengu_ant_model_override"
				] == null
			) {
				await initializeGrowthBook();
			}

			// Special case the default model with the null keyword
			// NOTE: Model resolution happens after setup() to ensure trust is established before AWS auth
			const userSpecifiedModel =
				options.model === "default"
					? getDefaultMainLoopModel()
					: options.model;
			const userSpecifiedFallbackModel =
				fallbackModel === "default"
					? getDefaultMainLoopModel()
					: fallbackModel;

			// Reuse preSetupCwd unless setup() chdir'd (worktreeEnabled). Saves a
			// getCwd() syscall in the common path.
			const currentCwd = worktreeEnabled ? getCwd() : preSetupCwd;
			logForDebugging("[STARTUP] Loading commands and agents...");
			const commandsStart = Date.now();
			// Join the promises kicked before setup() (or start fresh if
			// worktreeEnabled gated the early kick). Both memoized by cwd.
			const [commands, agentDefinitionsResult] = await Promise.all([
				commandsPromise ?? getCommands(currentCwd),
				agentDefsPromise ??
					getAgentDefinitionsWithOverrides(currentCwd),
			]);
			logForDebugging(
				`[STARTUP] Commands and agents loaded in ${Date.now() - commandsStart}ms`,
			);
			profileCheckpoint("action_commands_loaded");

			// Parse CLI agents if provided via --agents flag
			let cliAgents: typeof agentDefinitionsResult.activeAgents = [];
			if (agentsJson) {
				try {
					const parsedAgents = safeParseJSON(agentsJson);
					if (parsedAgents) {
						cliAgents = parseAgentsFromJson(
							parsedAgents,
							"flagSettings",
						);
					}
				} catch (error) {
					logError(error);
				}
			}

			// Merge CLI agents with existing ones
			const allAgents = [
				...agentDefinitionsResult.allAgents,
				...cliAgents,
			];
			const agentDefinitions = {
				...agentDefinitionsResult,
				allAgents,
				activeAgents: getActiveAgentsFromList(allAgents),
			};

			// Look up main thread agent from CLI flag or settings
			const agentSetting = agentCli ?? getInitialSettings().agent;
			let mainThreadAgentDefinition:
				| (typeof agentDefinitions.activeAgents)[number]
				| undefined;
			if (agentSetting) {
				mainThreadAgentDefinition = agentDefinitions.activeAgents.find(
					(agent) => agent.agentType === agentSetting,
				);
				if (!mainThreadAgentDefinition) {
					logForDebugging(
						`Warning: agent "${agentSetting}" not found. ` +
							`Available agents: ${agentDefinitions.activeAgents.map((a) => a.agentType).join(", ")}. ` +
							`Using default behavior.`,
					);
				}
			}

			// Store the main thread agent type in bootstrap state so hooks can access it
			setMainThreadAgentType(mainThreadAgentDefinition?.agentType);

			// Log agent flag usage — only log agent name for built-in agents to avoid leaking custom agent names
			if (mainThreadAgentDefinition) {
				logEvent("tengu_agent_flag", {
					agentType: isBuiltInAgent(mainThreadAgentDefinition)
						? (mainThreadAgentDefinition.agentType as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS)
						: ("custom" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS),
					...(agentCli && {
						source: "cli" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
					}),
				});
			}

			// Persist agent setting to session transcript for resume view display and restoration
			if (mainThreadAgentDefinition?.agentType) {
				saveAgentSetting(mainThreadAgentDefinition.agentType);
			}

			// Apply the agent's system prompt for non-interactive sessions
			// (interactive mode uses buildEffectiveSystemPrompt instead)
			if (
				isNonInteractiveSession &&
				mainThreadAgentDefinition &&
				!systemPrompt &&
				!isBuiltInAgent(mainThreadAgentDefinition)
			) {
				const agentSystemPrompt =
					mainThreadAgentDefinition.getSystemPrompt();
				if (agentSystemPrompt) {
					systemPrompt = agentSystemPrompt;
				}
			}

			// initialPrompt goes first so its slash command (if any) is processed;
			// user-provided text becomes trailing context.
			// Only concatenate when inputPrompt is a string. When it's an
			// AsyncIterable (SDK stream-json mode), template interpolation would
			// call .toString() producing "[object Object]". The AsyncIterable case
			// is handled in print.ts via structuredIO.prependUserMessage().
			if (mainThreadAgentDefinition?.initialPrompt) {
				if (typeof inputPrompt === "string") {
					inputPrompt = inputPrompt
						? `${mainThreadAgentDefinition.initialPrompt}\n\n${inputPrompt}`
						: mainThreadAgentDefinition.initialPrompt;
				} else if (!inputPrompt) {
					inputPrompt = mainThreadAgentDefinition.initialPrompt;
				}
			}

			// Compute effective model early so hooks can run in parallel with MCP
			// If user didn't specify a model but agent has one, use the agent's model
			let effectiveModel = userSpecifiedModel;
			if (
				!effectiveModel &&
				mainThreadAgentDefinition?.model &&
				mainThreadAgentDefinition.model !== "inherit"
			) {
				effectiveModel = parseUserSpecifiedModel(
					mainThreadAgentDefinition.model,
				);
			}

			setMainLoopModelOverride(effectiveModel);

			// Compute resolved model for hooks (use user-specified model at launch)
			setInitialMainLoopModel(getUserSpecifiedModelSetting() || null);
			const initialMainLoopModel = getInitialMainLoopModel();
			const resolvedInitialModel = parseUserSpecifiedModel(
				initialMainLoopModel ?? getDefaultMainLoopModel(),
			);

			let advisorModel: string | undefined;
			if (isAdvisorEnabled()) {
				const advisorOption = canUserConfigureAdvisor()
					? (options as { advisor?: string }).advisor
					: undefined;
				if (advisorOption) {
					logForDebugging(`[AdvisorTool] --advisor ${advisorOption}`);
					if (!modelSupportsAdvisor(resolvedInitialModel)) {
						process.stderr.write(
							chalk.red(
								`Error: The model "${resolvedInitialModel}" does not support the advisor tool.\n`,
							),
						);
						process.exit(1);
					}
					const normalizedAdvisorModel = normalizeModelStringForAPI(
						parseUserSpecifiedModel(advisorOption),
					);
					if (!isValidAdvisorModel(normalizedAdvisorModel)) {
						process.stderr.write(
							chalk.red(
								`Error: The model "${advisorOption}" cannot be used as an advisor.\n`,
							),
						);
						process.exit(1);
					}
				}
				advisorModel = canUserConfigureAdvisor()
					? (advisorOption ?? getInitialAdvisorSetting())
					: advisorOption;
				if (advisorModel) {
					logForDebugging(
						`[AdvisorTool] Advisor model: ${advisorModel}`,
					);
				}
			}

			// For tmux teammates with --agent-type, append the custom agent's prompt
			if (
				isAgentSwarmsEnabled() &&
				storedTeammateOpts?.agentId &&
				storedTeammateOpts?.agentName &&
				storedTeammateOpts?.teamName &&
				storedTeammateOpts?.agentType
			) {
				// Look up the custom agent definition
				const customAgent = agentDefinitions.activeAgents.find(
					(a) => a.agentType === storedTeammateOpts.agentType,
				);
				if (customAgent) {
					// Get the prompt - need to handle both built-in and custom agents
					let customPrompt: string | undefined;
					if (customAgent.source === "built-in") {
						// Built-in agents have getSystemPrompt that takes toolUseContext
						// We can't access full toolUseContext here, so skip for now
						logForDebugging(
							`[teammate] Built-in agent ${storedTeammateOpts.agentType} - skipping custom prompt (not supported)`,
						);
					} else {
						// Custom agents have getSystemPrompt that takes no args
						customPrompt = customAgent.getSystemPrompt();
					}

					// Log agent memory loaded event for tmux teammates
					if (customAgent.memory) {
						logEvent("tengu_agent_memory_loaded", {
							...(process.env.USER_TYPE === "ant" && {
								agent_type:
									customAgent.agentType as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
							}),
							scope: customAgent.memory as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
							source: "teammate" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
						});
					}

					if (customPrompt) {
						const customInstructions = `\n# Custom Agent Instructions\n${customPrompt}`;
						appendSystemPrompt = appendSystemPrompt
							? `${appendSystemPrompt}\n\n${customInstructions}`
							: customInstructions;
					}
				} else {
					logForDebugging(
						`[teammate] Custom agent ${storedTeammateOpts.agentType} not found in available agents`,
					);
				}
			}

			maybeActivateBrief(options);
			// defaultView: 'chat' is a persisted opt-in — check entitlement and set
			// userMsgOptIn so the tool + prompt section activate. Interactive-only:
			// defaultView is a display preference; SDK sessions have no display, and
			// the assistant installer writes defaultView:'chat' to settings.local.json
			// which would otherwise leak into --print sessions in the same directory.
			// Runs right after maybeActivateBrief() so all startup opt-in paths fire
			// BEFORE any isBriefEnabled() read below (proactive prompt's
			// briefVisibility). A persisted 'chat' after a GB kill-switch falls
			// through (entitlement fails).
			if (
				(feature("KAIROS") || feature("KAIROS_BRIEF")) &&
				!getIsNonInteractiveSession() &&
				!getUserMsgOptIn() &&
				getInitialSettings().defaultView === "chat"
			) {
				/* eslint-disable @typescript-eslint/no-require-imports */
				const { isBriefEntitled } =
					require("@claude-code-best/builtin-tools/tools/BriefTool/BriefTool.js") as typeof import("@claude-code-best/builtin-tools/tools/BriefTool/BriefTool.js");
				/* eslint-enable @typescript-eslint/no-require-imports */
				if (isBriefEntitled()) {
					setUserMsgOptIn(true);
				}
			}
			// Coordinator mode has its own system prompt and filters out Sleep, so
			// the generic proactive prompt would tell it to call a tool it can't
			// access and conflict with delegation instructions.
			if (
				(feature("PROACTIVE") || feature("KAIROS")) &&
				((options as { proactive?: boolean }).proactive ||
					isEnvTruthy(process.env.CLAUDE_CODE_PROACTIVE)) &&
				!coordinatorModeModule?.isCoordinatorMode()
			) {
				/* eslint-disable @typescript-eslint/no-require-imports */
				const briefVisibility =
					feature("KAIROS") || feature("KAIROS_BRIEF")
						? (
								require("@claude-code-best/builtin-tools/tools/BriefTool/BriefTool.js") as typeof import("@claude-code-best/builtin-tools/tools/BriefTool/BriefTool.js")
							).isBriefEnabled()
							? "Call SendUserMessage at checkpoints to mark where things stand."
							: "The user will see any text you output."
						: "The user will see any text you output.";
				/* eslint-enable @typescript-eslint/no-require-imports */
				const proactivePrompt = `\n# Proactive Mode\n\nYou are in proactive mode. Take initiative — explore, act, and make progress without waiting for instructions.\n\nStart by briefly greeting the user.\n\nYou will receive periodic <tick> prompts. These are check-ins. Do whatever seems most useful, or call Sleep if there's nothing to do. ${briefVisibility}`;
				appendSystemPrompt = appendSystemPrompt
					? `${appendSystemPrompt}\n\n${proactivePrompt}`
					: proactivePrompt;
			}

			if (feature("KAIROS") && kairosEnabled && assistantModule) {
				const assistantAddendum =
					assistantModule.getAssistantSystemPromptAddendum();
				appendSystemPrompt = appendSystemPrompt
					? `${appendSystemPrompt}\n\n${assistantAddendum}`
					: assistantAddendum;
			}

			// Ink root is only needed for interactive sessions — patchConsole in the
			// Ink constructor would swallow console output in headless mode.
			let root!: Root;
			let getFpsMetrics!: () => FpsMetrics | undefined;
			let stats!: StatsStore;

			// Show setup screens after commands are loaded
			if (!isNonInteractiveSession) {
				const ctx = getRenderContext(false);
				getFpsMetrics = ctx.getFpsMetrics;
				stats = ctx.stats;
				// Install asciicast recorder before Ink mounts (ant-only, opt-in via CLAUDE_CODE_TERMINAL_RECORDING=1)
				if (process.env.USER_TYPE === "ant") {
					installAsciicastRecorder();
				}

				const { createRoot } = await import('@anthropic/ink')
				root = await createRoot(ctx.renderOptions)

				// Log startup time now, before any blocking dialog renders. Logging
				// from REPL's first render (the old location) included however long
				// the user sat on trust/OAuth/onboarding/resume-picker — p99 was ~70s
				// dominated by dialog-wait time, not code-path startup.
				logEvent("tengu_timer", {
					event: "startup" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
					durationMs: Math.round(process.uptime() * 1000),
				});

				logForDebugging("[STARTUP] Running showSetupScreens()...");
				const setupScreensStart = Date.now();
				const onboardingShown = await showSetupScreens(
					root,
					permissionMode,
					allowDangerouslySkipPermissions,
					commands,
					enableClaudeInChrome,
					devChannels,
				);
				logForDebugging(
					`[STARTUP] showSetupScreens() completed in ${Date.now() - setupScreensStart}ms`,
				);

				// Now that trust is established and GrowthBook has auth headers,
				// resolve the --remote-control / --rc entitlement gate.
				if (
					feature("BRIDGE_MODE") &&
					remoteControlOption !== undefined
				) {
					const { getBridgeDisabledReason } =
						await import("./bridge/bridgeEnabled.js");
					const disabledReason = await getBridgeDisabledReason();
					remoteControl = disabledReason === null;
					if (disabledReason) {
						process.stderr.write(
							chalk.yellow(
								`${disabledReason}\n--rc flag ignored.\n`,
							),
						);
					}
				}

				// Check for pending agent memory snapshot updates (only for --agent mode, ant-only)
				if (
					feature("AGENT_MEMORY_SNAPSHOT") &&
					mainThreadAgentDefinition &&
					isCustomAgent(mainThreadAgentDefinition) &&
					mainThreadAgentDefinition.memory &&
					mainThreadAgentDefinition.pendingSnapshotUpdate
				) {
					const agentDef = mainThreadAgentDefinition;
					const choice = await launchSnapshotUpdateDialog(root, {
						agentType: agentDef.agentType,
						scope: agentDef.memory!,
						snapshotTimestamp:
							agentDef.pendingSnapshotUpdate!.snapshotTimestamp,
					});
					if (choice === "merge") {
						const { buildMergePrompt } =
							await import("./components/agents/SnapshotUpdateDialog.js");
						const mergePrompt = buildMergePrompt(
							agentDef.agentType,
							agentDef.memory!,
						);
						inputPrompt = inputPrompt
							? `${mergePrompt}\n\n${inputPrompt}`
							: mergePrompt;
					}
					agentDef.pendingSnapshotUpdate = undefined;
				}

				// Skip executing /login if we just completed onboarding for it
				if (
					onboardingShown &&
					prompt?.trim().toLowerCase() === "/login"
				) {
					prompt = "";
				}

				if (onboardingShown) {
					// Refresh auth-dependent services now that the user has logged in during onboarding.
					// Keep in sync with the post-login logic in src/commands/login.tsx
					void refreshRemoteManagedSettings();
					void refreshPolicyLimits();
					// Clear user data cache BEFORE GrowthBook refresh so it picks up fresh credentials
					resetUserCache();
					// Refresh GrowthBook after login to get updated feature flags (e.g., for claude.ai MCPs)
					refreshGrowthBookAfterAuthChange();
					// Clear any stale trusted device token then enroll for Remote Control.
					// Both self-gate on tengu_sessions_elevated_auth_enforcement internally
					// — enrollTrustedDevice() via checkGate_CACHED_OR_BLOCKING (awaits
					// the GrowthBook reinit above), clearTrustedDeviceToken() via the
					// sync cached check (acceptable since clear is idempotent).
					void import("./bridge/trustedDevice.js").then((m) => {
						m.clearTrustedDeviceToken();
						return m.enrollTrustedDevice();
					});
				}

				// Validate that the active token's org matches forceLoginOrgUUID (if set
				// in managed settings). Runs after onboarding so managed settings and
				// login state are fully loaded.
				const orgValidation = await validateForceLoginOrg();
				if (!orgValidation.valid) {
					await exitWithError(root, (orgValidation as { valid: false; message: string }).message);
				}
			}

			// If gracefulShutdown was initiated (e.g., user rejected trust dialog),
			// process.exitCode will be set. Skip all subsequent operations that could
			// trigger code execution before the process exits (e.g. we don't want apiKeyHelper
			// to run if trust was not established).
			if (process.exitCode !== undefined) {
				logForDebugging(
					"Graceful shutdown initiated, skipping further initialization",
				);
				return;
			}

			// Initialize LSP manager AFTER trust is established (or in non-interactive mode
			// where trust is implicit). This prevents plugin LSP servers from executing
			// code in untrusted directories before user consent.
			// Must be after inline plugins are set (if any) so --plugin-dir LSP servers are included.
			initializeLspServerManager();

			// Show settings validation errors after trust is established
			// MCP config errors don't block settings from loading, so exclude them
			if (!isNonInteractiveSession) {
				const { errors } = getSettingsWithErrors();
				const nonMcpErrors = errors.filter((e) => !e.mcpErrorMetadata);
				if (nonMcpErrors.length > 0) {
					await launchInvalidSettingsDialog(root, {
						settingsErrors: nonMcpErrors,
						onExit: () => gracefulShutdownSync(1),
					});
				}
			}

			// Check quota status, fast mode, passes eligibility, and bootstrap data
			// after trust is established. These make API calls which could trigger
			// apiKeyHelper execution.
			// --bare / SIMPLE: skip — these are cache-warms for the REPL's
			// first-turn responsiveness (quota, passes, fastMode, bootstrap data). Fast
			// mode doesn't apply to the Agent SDK anyway (see getFastModeUnavailableReason).
			const bgRefreshThrottleMs = getFeatureValue_CACHED_MAY_BE_STALE(
				"tengu_cicada_nap_ms",
				0,
			);
			const lastPrefetched = getGlobalConfig().startupPrefetchedAt ?? 0;
			const skipStartupPrefetches =
				isBareMode() ||
				(bgRefreshThrottleMs > 0 &&
					Date.now() - lastPrefetched < bgRefreshThrottleMs);

			if (!skipStartupPrefetches) {
				const lastPrefetchedInfo =
					lastPrefetched > 0
						? ` last ran ${Math.round((Date.now() - lastPrefetched) / 1000)}s ago`
						: "";
				logForDebugging(
					`Starting background startup prefetches${lastPrefetchedInfo}`,
				);

				checkQuotaStatus().catch((error) => logError(error));

				// Fetch bootstrap data from the server and update all cache values.
				void fetchBootstrapData();

				// TODO: Consolidate other prefetches into a single bootstrap request.
				void prefetchPassesEligibility();
				if (
					!getFeatureValue_CACHED_MAY_BE_STALE(
						"tengu_miraculo_the_bard",
						false,
					)
				) {
					void prefetchFastModeStatus();
				} else {
					// Kill switch skips the network call, not org-policy enforcement.
					// Resolve from cache so orgStatus doesn't stay 'pending' (which
					// getFastModeUnavailableReason treats as permissive).
					resolveFastModeStatusFromCache();
				}
				if (bgRefreshThrottleMs > 0) {
					saveGlobalConfig((current) => ({
						...current,
						startupPrefetchedAt: Date.now(),
					}));
				}
			} else {
				logForDebugging(
					`Skipping startup prefetches, last ran ${Math.round((Date.now() - lastPrefetched) / 1000)}s ago`,
				);
				// Resolve fast mode org status from cache (no network)
				resolveFastModeStatusFromCache();
			}

			if (!isNonInteractiveSession) {
				void refreshExampleCommands(); // Pre-fetch example commands (runs git log, no API call)
			}

			// Resolve MCP configs (started early, overlaps with setup/trust dialog work)
			const { servers: existingMcpConfigs } = await mcpConfigPromise;
			logForDebugging(
				`[STARTUP] MCP configs resolved in ${mcpConfigResolvedMs}ms (awaited at +${Date.now() - mcpConfigStart}ms)`,
			);
			// CLI flag (--mcp-config) should override file-based configs, matching settings precedence
			const allMcpConfigs = {
				...existingMcpConfigs,
				...dynamicMcpConfig,
			};

			// Separate SDK configs from regular MCP configs
			const sdkMcpConfigs: Record<string, McpSdkServerConfig> = {};
			const regularMcpConfigs: Record<string, ScopedMcpServerConfig> = {};

			for (const [name, config] of Object.entries(allMcpConfigs)) {
				const typedConfig = config as
					| ScopedMcpServerConfig
					| McpSdkServerConfig;
				if (typedConfig.type === "sdk") {
					sdkMcpConfigs[name] = typedConfig as McpSdkServerConfig;
				} else {
					regularMcpConfigs[name] =
						typedConfig as ScopedMcpServerConfig;
				}
			}

			profileCheckpoint("action_mcp_configs_loaded");

			// Prefetch MCP resources after trust dialog (this is where execution happens).
			// Interactive mode only: print mode defers connects until headlessStore exists
			// and pushes per-server (below), so ToolSearch's pending-client handling works
			// and one slow server doesn't block the batch.
			const localMcpPromise = isNonInteractiveSession
				? Promise.resolve({ clients: [], tools: [], commands: [] })
				: prefetchAllMcpResources(regularMcpConfigs);
			const claudeaiMcpPromise = isNonInteractiveSession
				? Promise.resolve({ clients: [], tools: [], commands: [] })
				: claudeaiConfigPromise.then((configs) =>
						Object.keys(configs).length > 0
							? prefetchAllMcpResources(configs)
							: { clients: [], tools: [], commands: [] },
					);
			// Merge with dedup by name: each prefetchAllMcpResources call independently
			// adds helper tools (ListMcpResourcesTool, ReadMcpResourceTool) via
			// local dedup flags, so merging two calls can yield duplicates. print.ts
			// already uniqBy's the final tool pool, but dedup here keeps appState clean.
			const mcpPromise = Promise.all([
				localMcpPromise,
				claudeaiMcpPromise,
			]).then(([local, claudeai]) => ({
				clients: [...local.clients, ...claudeai.clients],
				tools: uniqBy([...local.tools, ...claudeai.tools], "name"),
				commands: uniqBy(
					[...local.commands, ...claudeai.commands],
					"name",
				),
			}));

			// Start hooks early so they run in parallel with MCP connections.
			// Skip for initOnly/init/maintenance (handled separately), non-interactive
			// (handled via setupTrigger), and resume/continue (conversationRecovery.ts
			// fires 'resume' instead — without this guard, hooks fire TWICE on /resume
			// and the second systemMessage clobbers the first. gh-30825)
			const hooksPromise =
				initOnly ||
				init ||
				maintenance ||
				isNonInteractiveSession ||
				options.continue ||
				options.resume
					? null
					: processSessionStartHooks("startup", {
							agentType: mainThreadAgentDefinition?.agentType,
							model: resolvedInitialModel,
						});

			// MCP never blocks REPL render OR turn 1 TTFT. useManageMCPConnections
			// populates appState.mcp async as servers connect (connectToServer is
			// memoized — the prefetch calls above and the hook converge on the same
			// connections). getToolUseContext reads store.getState() fresh via
			// computeTools(), so turn 1 sees whatever's connected by query time.
			// Slow servers populate for turn 2+. Matches interactive-no-prompt
			// behavior. Print mode: per-server push into headlessStore (below).
			const hookMessages: Awaited<NonNullable<typeof hooksPromise>> = [];
			// Suppress transient unhandledRejection — the prefetch warms the
			// memoized connectToServer cache but nobody awaits it in interactive.
			mcpPromise.catch(() => {});

			const mcpClients: Awaited<typeof mcpPromise>["clients"] = [];
			const mcpTools: Awaited<typeof mcpPromise>["tools"] = [];
			const mcpCommands: Awaited<typeof mcpPromise>["commands"] = [];

			let thinkingEnabled = shouldEnableThinkingByDefault();
			let thinkingConfig: ThinkingConfig =
				thinkingEnabled !== false
					? { type: "adaptive" }
					: { type: "disabled" };

			if (
				options.thinking === "adaptive" ||
				options.thinking === "enabled"
			) {
				thinkingEnabled = true;
				thinkingConfig = { type: "adaptive" };
			} else if (options.thinking === "disabled") {
				thinkingEnabled = false;
				thinkingConfig = { type: "disabled" };
			} else {
				const maxThinkingTokens = process.env.MAX_THINKING_TOKENS
					? parseInt(process.env.MAX_THINKING_TOKENS, 10)
					: options.maxThinkingTokens;
				if (maxThinkingTokens !== undefined) {
					if (maxThinkingTokens > 0) {
						thinkingEnabled = true;
						thinkingConfig = {
							type: "enabled",
							budgetTokens: maxThinkingTokens,
						};
					} else if (maxThinkingTokens === 0) {
						thinkingEnabled = false;
						thinkingConfig = { type: "disabled" };
					}
				}
			}

			logForDiagnosticsNoPII("info", "started", {
				version: MACRO.VERSION,
				is_native_binary: isInBundledMode(),
			});

			registerCleanup(async () => {
				logForDiagnosticsNoPII("info", "exited");
			});

			void logTenguInit({
				hasInitialPrompt: Boolean(prompt),
				hasStdin: Boolean(inputPrompt),
				verbose,
				debug,
				debugToStderr,
				print: print ?? false,
				outputFormat: outputFormat ?? "text",
				inputFormat: inputFormat ?? "text",
				numAllowedTools: allowedTools.length,
				numDisallowedTools: disallowedTools.length,
				mcpClientCount: Object.keys(allMcpConfigs).length,
				worktreeEnabled,
				skipWebFetchPreflight:
					getInitialSettings().skipWebFetchPreflight,
				githubActionInputs: process.env.GITHUB_ACTION_INPUTS,
				dangerouslySkipPermissionsPassed:
					dangerouslySkipPermissions ?? false,
				permissionMode,
				modeIsBypass: permissionMode === "bypassPermissions",
				allowDangerouslySkipPermissionsPassed:
					allowDangerouslySkipPermissions,
				systemPromptFlag: systemPrompt
					? options.systemPromptFile
						? "file"
						: "flag"
					: undefined,
				appendSystemPromptFlag: appendSystemPrompt
					? options.appendSystemPromptFile
						? "file"
						: "flag"
					: undefined,
				thinkingConfig,
				assistantActivationPath:
					feature("KAIROS") && kairosEnabled
						? assistantModule?.getAssistantActivationPath()
						: undefined,
			});

			// Log context metrics once at initialization
			void logContextMetrics(regularMcpConfigs, toolPermissionContext);

			void logPermissionContextForAnts(null, "initialization");

			logManagedSettings();

			// Register PID file for concurrent-session detection (~/.claude/sessions/)
			// and fire multi-clauding telemetry. Lives here (not init.ts) so only the
			// REPL path registers — not subcommands like `claude doctor`. Chained:
			// count must run after register's write completes or it misses our own file.
			void registerSession().then((registered) => {
				if (!registered) return;
				if (sessionNameArg) {
					void updateSessionName(sessionNameArg);
				}
				void countConcurrentSessions().then((count) => {
					if (count >= 2) {
						logEvent("tengu_concurrent_sessions", {
							num_sessions: count,
						});
					}
				});
			});

			// Initialize versioned plugins system (triggers V1→V2 migration if
			// needed). Then run orphan GC, THEN warm the Grep/Glob exclusion cache.
			// Sequencing matters: the warmup scans disk for .orphaned_at markers,
			// so it must see the GC's Pass 1 (remove markers from reinstalled
			// versions) and Pass 2 (stamp unmarked orphans) already applied. The
			// warm also lands before autoupdate (fires on first submit in REPL)
			// can orphan this session's active version underneath us.
			// --bare / SIMPLE: skip plugin version sync + orphan cleanup. These
			// are install/upgrade bookkeeping that scripted calls don't need —
			// the next interactive session will reconcile. The await here was
			// blocking -p on a marketplace round-trip.
			if (isBareMode()) {
				// skip — no-op
			} else if (isNonInteractiveSession) {
				// In headless mode, await to ensure plugin sync completes before CLI exits
				await initializeVersionedPlugins();
				profileCheckpoint("action_after_plugins_init");
				void cleanupOrphanedPluginVersionsInBackground().then(() =>
					getGlobExclusionsForPluginCache(),
				);
			} else {
				// In interactive mode, fire-and-forget — this is purely bookkeeping
				// that doesn't affect runtime behavior of the current session
				void initializeVersionedPlugins().then(async () => {
					profileCheckpoint("action_after_plugins_init");
					await cleanupOrphanedPluginVersionsInBackground();
					void getGlobExclusionsForPluginCache();
				});
			}

			const setupTrigger =
				initOnly || init ? "init" : maintenance ? "maintenance" : null;
			if (initOnly) {
				applyConfigEnvironmentVariables();
				await processSetupHooks("init", { forceSyncExecution: true });
				await processSessionStartHooks("startup", {
					forceSyncExecution: true,
				});
				gracefulShutdownSync(0);
				return;
			}

			// --print mode
			if (isNonInteractiveSession) {
				if (outputFormat === "stream-json" || outputFormat === "json") {
					setHasFormattedOutput(true);
				}

				// Apply full environment variables in print mode since trust dialog is bypassed
				// This includes potentially dangerous environment variables from untrusted sources
				// but print mode is considered trusted (as documented in help text)
				applyConfigEnvironmentVariables();

				// Initialize telemetry after env vars are applied so OTEL endpoint env vars and
				// otelHeadersHelper (which requires trust to execute) are available.
				initializeTelemetryAfterTrust();

				// Kick SessionStart hooks now so the subprocess spawn overlaps with
				// MCP connect + plugin init + print.ts import below. loadInitialMessages
				// joins this at print.ts:4397. Guarded same as loadInitialMessages —
				// continue/resume/teleport paths don't fire startup hooks (or fire them
				// conditionally inside the resume branch, where this promise is
				// undefined and the ?? fallback runs). Also skip when setupTrigger is
				// set — those paths run setup hooks first (print.ts:544), and session
				// start hooks must wait until setup completes.
				const sessionStartHooksPromise =
					options.continue ||
					options.resume ||
					teleport ||
					setupTrigger
						? undefined
						: processSessionStartHooks("startup");
				// Suppress transient unhandledRejection if this rejects before
				// loadInitialMessages awaits it. Downstream await still observes the
				// rejection — this just prevents the spurious global handler fire.
				sessionStartHooksPromise?.catch(() => {});

				profileCheckpoint("before_validateForceLoginOrg");
				// Validate org restriction for non-interactive sessions
				const orgValidation = await validateForceLoginOrg();
				if (!orgValidation.valid) {
					process.stderr.write((orgValidation as { valid: false; message: string }).message + "\n");
					process.exit(1);
				}

				// Headless mode supports all prompt commands and some local commands
				// If disableSlashCommands is true, return empty array
				const commandsHeadless = disableSlashCommands
					? []
					: commands.filter(
							(command) =>
								(command.type === "prompt" &&
									!command.disableNonInteractive) ||
								(command.type === "local" &&
									command.supportsNonInteractive),
						);

				const defaultState = getDefaultAppState();
				const headlessInitialState: AppState = {
					...defaultState,
					mcp: {
						...defaultState.mcp,
						clients: mcpClients,
						commands: mcpCommands,
						tools: mcpTools,
					},
					toolPermissionContext,
					effortValue:
						parseEffortValue(options.effort) ??
						getInitialEffortSetting(),
					...(isFastModeEnabled() && {
						fastMode: getInitialFastModeSetting(
							effectiveModel ?? null,
						),
					}),
					...(isAdvisorEnabled() && advisorModel && { advisorModel }),
					// kairosEnabled gates the async fire-and-forget path in
					// executeForkedSlashCommand (processSlashCommand.tsx:132) and
					// AgentTool's shouldRunAsync. The REPL initialState sets this at
					// ~3459; headless was defaulting to false, so the daemon child's
					// scheduled tasks and Agent-tool calls ran synchronously — N
					// overdue cron tasks on spawn = N serial subagent turns blocking
					// user input. Computed at :1620, well before this branch.
					...(feature("KAIROS") ? { kairosEnabled } : {}),
				};

				// Init app state
				const headlessStore = createStore(
					headlessInitialState,
					onChangeAppState,
				);

				// Async check of auto mode gate — corrects state and disables auto if needed.
				if (feature("TRANSCRIPT_CLASSIFIER")) {
					void verifyAutoModeGateAccess(
						toolPermissionContext,
						headlessStore.getState().fastMode,
					).then(({ updateContext }) => {
						headlessStore.setState((prev) => {
							const nextCtx = updateContext(
								prev.toolPermissionContext,
							);
							if (nextCtx === prev.toolPermissionContext)
								return prev;
							return { ...prev, toolPermissionContext: nextCtx };
						});
					});
				}

				// Set global state for session persistence
				if (options.sessionPersistence === false) {
					setSessionPersistenceDisabled(true);
				}

				// Store SDK betas in global state for context window calculation
				// Only store allowed betas (filters by allowlist and subscriber status)
				setSdkBetas(filterAllowedSdkBetas(betas));

				// Print-mode MCP: per-server incremental push into headlessStore.
				// Mirrors useManageMCPConnections — push pending first (so ToolSearch's
				// pending-check at ToolSearchTool.ts:334 sees them), then replace with
				// connected/failed as each server settles.
				const connectMcpBatch = (
					configs: Record<string, ScopedMcpServerConfig>,
					label: string,
				): Promise<void> => {
					if (Object.keys(configs).length === 0)
						return Promise.resolve();
					headlessStore.setState((prev) => ({
						...prev,
						mcp: {
							...prev.mcp,
							clients: [
								...prev.mcp.clients,
								...Object.entries(configs).map(
									([name, config]) => ({
										name,
										type: "pending" as const,
										config,
									}),
								),
							],
						},
					}));
					return getMcpToolsCommandsAndResources(
						({ client, tools, commands }) => {
							headlessStore.setState((prev) => ({
								...prev,
								mcp: {
									...prev.mcp,
									clients: prev.mcp.clients.some(
										(c) => c.name === client.name,
									)
										? prev.mcp.clients.map((c) =>
												c.name === client.name
													? client
													: c,
											)
										: [...prev.mcp.clients, client],
									tools: uniqBy(
										[...prev.mcp.tools, ...tools],
										"name",
									),
									commands: uniqBy(
										[...prev.mcp.commands, ...commands],
										"name",
									),
								},
							}));
						},
						configs,
					).catch((err) =>
						logForDebugging(`[MCP] ${label} connect error: ${err}`),
					);
				};
				// Await all MCP configs — print mode is often single-turn, so
				// "late-connecting servers visible next turn" doesn't help. SDK init
				// message and turn-1 tool list both need configured MCP tools present.
				// Zero-server case is free via the early return in connectMcpBatch.
				// Connectors parallelize inside getMcpToolsCommandsAndResources
				// (processBatched with Promise.all). claude.ai is awaited too — its
				// fetch was kicked off early (line ~2558) so only residual time blocks
				// here. --bare skips claude.ai entirely for perf-sensitive scripts.
				profileCheckpoint("before_connectMcp");
				await connectMcpBatch(regularMcpConfigs, "regular");
				profileCheckpoint("after_connectMcp");
				// Dedup: suppress plugin MCP servers that duplicate a claude.ai
				// connector (connector wins), then connect claude.ai servers.
				// Bounded wait — #23725 made this blocking so single-turn -p sees
				// connectors, but with 40+ slow connectors tengu_startup_perf p99
				// climbed to 76s. If fetch+connect doesn't finish in time, proceed;
				// the promise keeps running and updates headlessStore in the
				// background so turn 2+ still sees connectors.
				const CLAUDE_AI_MCP_TIMEOUT_MS = 5_000;
				const claudeaiConnect = claudeaiConfigPromise.then(
					(claudeaiConfigs) => {
						if (Object.keys(claudeaiConfigs).length > 0) {
							const claudeaiSigs = new Set<string>();
							for (const config of Object.values(
								claudeaiConfigs,
							)) {
								const sig = getMcpServerSignature(config);
								if (sig) claudeaiSigs.add(sig);
							}
							const suppressed = new Set<string>();
							for (const [name, config] of Object.entries(
								regularMcpConfigs,
							)) {
								if (!name.startsWith("plugin:")) continue;
								const sig = getMcpServerSignature(config);
								if (sig && claudeaiSigs.has(sig))
									suppressed.add(name);
							}
							if (suppressed.size > 0) {
								logForDebugging(
									`[MCP] Lazy dedup: suppressing ${suppressed.size} plugin server(s) that duplicate claude.ai connectors: ${[...suppressed].join(", ")}`,
								);
								// Disconnect before filtering from state. Only connected
								// servers need cleanup — clearServerCache on a never-connected
								// server triggers a real connect just to kill it (memoize
								// cache-miss path, see useManageMCPConnections.ts:870).
								for (const c of headlessStore.getState().mcp
									.clients) {
									if (
										!suppressed.has(c.name) ||
										c.type !== "connected"
									)
										continue;
									c.client.onclose = undefined;
									void clearServerCache(
										c.name,
										c.config,
									).catch(() => {});
								}
								headlessStore.setState((prev) => {
									let {
										clients,
										tools,
										commands,
										resources,
									} = prev.mcp;
									clients = clients.filter(
										(c) => !suppressed.has(c.name),
									);
									tools = tools.filter(
										(t) =>
											!t.mcpInfo ||
											!suppressed.has(
												t.mcpInfo.serverName,
											),
									);
									for (const name of suppressed) {
										commands = excludeCommandsByServer(
											commands,
											name,
										);
										resources = excludeResourcesByServer(
											resources,
											name,
										);
									}
									return {
										...prev,
										mcp: {
											...prev.mcp,
											clients,
											tools,
											commands,
											resources,
										},
									};
								});
							}
						}
						// Suppress claude.ai connectors that duplicate an enabled
						// manual server (URL-signature match). Plugin dedup above only
						// handles `plugin:*` keys; this catches manual `.mcp.json` entries.
						// plugin:* must be excluded here — step 1 already suppressed
						// those (claude.ai wins); leaving them in suppresses the
						// connector too, and neither survives (gh-39974).
						const nonPluginConfigs = pickBy(
							regularMcpConfigs,
							(_, n) => !n.startsWith("plugin:"),
						);
						const { servers: dedupedClaudeAi } =
							dedupClaudeAiMcpServers(
								claudeaiConfigs,
								nonPluginConfigs,
							);
						return connectMcpBatch(dedupedClaudeAi, "claudeai");
					},
				);
				let claudeaiTimer: ReturnType<typeof setTimeout> | undefined;
				const claudeaiTimedOut = await Promise.race([
					claudeaiConnect.then(() => false),
					new Promise<boolean>((resolve) => {
						claudeaiTimer = setTimeout(
							(r) => r(true),
							CLAUDE_AI_MCP_TIMEOUT_MS,
							resolve,
						);
					}),
				]);
				if (claudeaiTimer) clearTimeout(claudeaiTimer);
				if (claudeaiTimedOut) {
					logForDebugging(
						`[MCP] claude.ai connectors not ready after ${CLAUDE_AI_MCP_TIMEOUT_MS}ms — proceeding; background connection continues`,
					);
				}
				profileCheckpoint("after_connectMcp_claudeai");

				// In headless mode, start deferred prefetches immediately (no user typing delay)
				// --bare / SIMPLE: startDeferredPrefetches early-returns internally.
				// backgroundHousekeeping (initExtractMemories, pruneShellSnapshots,
				// cleanupOldMessageFiles) and sdkHeapDumpMonitor are all bookkeeping
				// that scripted calls don't need — the next interactive session reconciles.
				if (!isBareMode()) {
					startDeferredPrefetches();
					void import("./utils/backgroundHousekeeping.js").then((m) =>
						m.startBackgroundHousekeeping(),
					);
					if (process.env.USER_TYPE === "ant") {
						void import("./utils/sdkHeapDumpMonitor.js").then((m) =>
							m.startSdkMemoryMonitor(),
						);
					}
				}

				logSessionTelemetry();
				profileCheckpoint("before_print_import");
				const { runHeadless } = await import("src/cli/print.js");
				profileCheckpoint("after_print_import");
				void runHeadless(
					inputPrompt,
					() => headlessStore.getState(),
					headlessStore.setState,
					commandsHeadless,
					tools,
					sdkMcpConfigs,
					agentDefinitions.activeAgents,
					{
						continue: options.continue,
						resume: options.resume,
						verbose: verbose,
						outputFormat: outputFormat,
						jsonSchema,
						permissionPromptToolName: options.permissionPromptTool,
						allowedTools,
						thinkingConfig,
						maxTurns: options.maxTurns,
						maxBudgetUsd: options.maxBudgetUsd,
						taskBudget: options.taskBudget
							? { total: options.taskBudget }
							: undefined,
						systemPrompt,
						appendSystemPrompt,
						userSpecifiedModel: effectiveModel,
						fallbackModel: userSpecifiedFallbackModel,
						teleport,
						sdkUrl,
						replayUserMessages: effectiveReplayUserMessages,
						includePartialMessages: effectiveIncludePartialMessages,
						forkSession: options.forkSession || false,
						resumeSessionAt: options.resumeSessionAt || undefined,
						rewindFiles: options.rewindFiles,
						enableAuthStatus: options.enableAuthStatus,
						agent: agentCli,
						workload: options.workload,
						setupTrigger: setupTrigger ?? undefined,
						sessionStartHooksPromise,
					},
				);
				return;
			}

			// Log model config at startup
			logEvent("tengu_startup_manual_model_config", {
				cli_flag:
					options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
				env_var: process.env
					.ANTHROPIC_MODEL as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
				settings_file: (getInitialSettings() || {})
					.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
				subscriptionType:
					getSubscriptionType() as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
				agent: agentSetting as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
			});

			// Get deprecation warning for the initial model (resolvedInitialModel computed earlier for hooks parallelization)
			const deprecationWarning =
				getModelDeprecationWarning(resolvedInitialModel);

			// Build initial notification queue
			const initialNotifications: Array<{
				key: string;
				text: string;
				color?: "warning";
				priority: "high";
			}> = [];
			if (permissionModeNotification) {
				initialNotifications.push({
					key: "permission-mode-notification",
					text: permissionModeNotification,
					priority: "high",
				});
			}
			if (deprecationWarning) {
				initialNotifications.push({
					key: "model-deprecation-warning",
					text: deprecationWarning,
					color: "warning",
					priority: "high",
				});
			}
			if (overlyBroadBashPermissions.length > 0) {
				const displayList = uniq(
					overlyBroadBashPermissions.map((p) => p.ruleDisplay),
				);
				const displays = displayList.join(", ");
				const sources = uniq(
					overlyBroadBashPermissions.map((p) => p.sourceDisplay),
				).join(", ");
				const n = displayList.length;
				initialNotifications.push({
					key: "overly-broad-bash-notification",
					text: `${displays} allow ${plural(n, "rule")} from ${sources} ${plural(n, "was", "were")} ignored \u2014 not available for Ants, please use auto-mode instead`,
					color: "warning",
					priority: "high",
				});
			}

			const teammateUtils = getTeammateUtils();
			const effectiveToolPermissionContext = {
				...toolPermissionContext,
				mode:
					isAgentSwarmsEnabled() &&
					teammateUtils?.isPlanModeRequired?.()
						? ("plan" as const)
						: toolPermissionContext.mode,
			};
			// All startup opt-in paths (--tools, --brief, defaultView) have fired
			// above; initialIsBriefOnly just reads the resulting state.
			const initialIsBriefOnly =
				feature("KAIROS") || feature("KAIROS_BRIEF")
					? getUserMsgOptIn()
					: false;
			const fullRemoteControl =
				remoteControl || getRemoteControlAtStartup() || kairosEnabled;
			let ccrMirrorEnabled = false;
			if (feature("CCR_MIRROR") && !fullRemoteControl) {
				/* eslint-disable @typescript-eslint/no-require-imports */
				const { isCcrMirrorEnabled } =
					require("./bridge/bridgeEnabled.js") as typeof import("./bridge/bridgeEnabled.js");
				/* eslint-enable @typescript-eslint/no-require-imports */
				ccrMirrorEnabled = isCcrMirrorEnabled();
			}

			const initialState: AppState = {
				settings: getInitialSettings(),
				tasks: {},
				agentNameRegistry: new Map(),
				verbose: verbose ?? getGlobalConfig().verbose ?? false,
				mainLoopModel: initialMainLoopModel,
				mainLoopModelForSession: null,
				isBriefOnly: initialIsBriefOnly,
				expandedView: getGlobalConfig().showSpinnerTree
					? "teammates"
					: getGlobalConfig().showExpandedTodos
						? "tasks"
						: "none",
				showTeammateMessagePreview: isAgentSwarmsEnabled()
					? false
					: undefined,
				selectedIPAgentIndex: -1,
				coordinatorTaskIndex: -1,
				viewSelectionMode: "none",
				footerSelection: null,
				toolPermissionContext: effectiveToolPermissionContext,
				agent: mainThreadAgentDefinition?.agentType,
				agentDefinitions,
				mcp: {
					clients: [],
					tools: [],
					commands: [],
					resources: {},
					pluginReconnectKey: 0,
				},
				plugins: {
					enabled: [],
					disabled: [],
					commands: [],
					errors: [],
					installationStatus: {
						marketplaces: [],
						plugins: [],
					},
					needsRefresh: false,
				},
				statusLineText: undefined,
				kairosEnabled,
				remoteSessionUrl: undefined,
				remoteConnectionStatus: "connecting",
				remoteBackgroundTaskCount: 0,
				replBridgeEnabled: fullRemoteControl || ccrMirrorEnabled,
				replBridgeExplicit: remoteControl,
				replBridgeOutboundOnly: ccrMirrorEnabled,
				replBridgeConnected: false,
				replBridgeSessionActive: false,
				replBridgeReconnecting: false,
				replBridgeConnectUrl: undefined,
				replBridgeSessionUrl: undefined,
				replBridgeEnvironmentId: undefined,
				replBridgeSessionId: undefined,
				replBridgeError: undefined,
				replBridgeInitialName: remoteControlName,
				showRemoteCallout: false,
				notifications: {
					current: null,
					queue: initialNotifications,
				},
				elicitation: {
					queue: [],
				},
				todos: {},
				remoteAgentTaskSuggestions: [],
				fileHistory: {
					snapshots: [],
					trackedFiles: new Set(),
					snapshotSequence: 0,
				},
				attribution: createEmptyAttributionState(),
				thinkingEnabled,
				promptSuggestionEnabled: shouldEnablePromptSuggestion(),
				sessionHooks: new Map(),
				inbox: {
					messages: [],
				},
				promptSuggestion: {
					text: null,
					promptId: null,
					shownAt: 0,
					acceptedAt: 0,
					generationRequestId: null,
				},
				speculation: IDLE_SPECULATION_STATE,
				speculationSessionTimeSavedMs: 0,
				skillImprovement: {
					suggestion: null,
				},
				workerSandboxPermissions: {
					queue: [],
					selectedIndex: 0,
				},
				pendingWorkerRequest: null,
				pendingSandboxRequest: null,
				authVersion: 0,
				initialMessage: inputPrompt
					? {
							message: createUserMessage({
								content: String(inputPrompt),
							}),
						}
					: null,
				effortValue:
					parseEffortValue(options.effort) ??
					getInitialEffortSetting(),
				activeOverlays: new Set<string>(),
				fastMode: getInitialFastModeSetting(resolvedInitialModel),
				...(isAdvisorEnabled() && advisorModel && { advisorModel }),
				// Compute teamContext synchronously to avoid useEffect setState during render.
				// KAIROS: assistantTeamContext takes precedence — set earlier in the
				// KAIROS block so Agent(name: "foo") can spawn in-process teammates
				// without TeamCreate. computeInitialTeamContext() is for tmux-spawned
				// teammates reading their own identity, not the assistant-mode leader.
				teamContext: (feature("KAIROS")
					? (assistantTeamContext ?? computeInitialTeamContext())
					: computeInitialTeamContext()) as AppState["teamContext"],
			};

			// Add CLI initial prompt to history
			if (inputPrompt) {
				addToHistory(String(inputPrompt));
			}

			const initialTools = mcpTools;

			// Increment numStartups synchronously — first-render readers like
			// shouldShowEffortCallout (via useState initializer) need the updated
			// value before setImmediate fires. Defer only telemetry.
			saveGlobalConfig((current) => ({
				...current,
				numStartups: (current.numStartups ?? 0) + 1,
			}));
			setImmediate(() => {
				void logStartupTelemetry();
				logSessionTelemetry();
			});

			// Set up per-turn session environment data uploader (ant-only build).
			// Default-enabled for all ant users when working in an Anthropic-owned
			// repo. Captures git/filesystem state (NOT transcripts) at each turn so
			// environments can be recreated at any user message index. Gating:
			//   - Build-time: this import is stubbed in external builds.
			//   - Runtime: uploader checks github.com/anthropics/* remote + gcloud auth.
			//   - Safety: CLAUDE_CODE_DISABLE_SESSION_DATA_UPLOAD=1 bypasses (tests set this).
			// Import is dynamic + async to avoid adding startup latency.
			const sessionUploaderPromise =
				process.env.USER_TYPE === "ant"
					? import("./utils/sessionDataUploader.js")
					: null;

			// Defer session uploader resolution to the onTurnComplete callback to avoid
			// adding a new top-level await in main.tsx (performance-critical path).
			// The per-turn auth logic in sessionDataUploader.ts handles unauthenticated
			// state gracefully (re-checks each turn, so auth recovery mid-session works).
			const uploaderReady = sessionUploaderPromise
				? sessionUploaderPromise
						.then((mod) => mod.createSessionTurnUploader())
						.catch(() => null)
				: null;

			const sessionConfig = {
				debug: debug || debugToStderr,
				commands: [...commands, ...mcpCommands],
				initialTools,
				mcpClients,
				autoConnectIdeFlag: ide,
				mainThreadAgentDefinition,
				disableSlashCommands,
				dynamicMcpConfig,
				strictMcpConfig,
				systemPrompt,
				appendSystemPrompt,
				taskListId,
				thinkingConfig,
				...(uploaderReady && {
					onTurnComplete: (messages: MessageType[]) => {
						void uploaderReady.then((uploader) =>
							(uploader as ((msgs: MessageType[]) => void) | null)?.(messages),
						);
					},
				}),
			};

			// Shared context for processResumedConversation calls
			const resumeContext = {
				modeApi: coordinatorModeModule,
				mainThreadAgentDefinition,
				agentDefinitions,
				currentCwd,
				cliAgents,
				initialState,
			};

			if (options.continue) {
				// Continue the most recent conversation directly
				let resumeSucceeded = false;
				try {
					const resumeStart = performance.now();

					// Clear stale caches before resuming to ensure fresh file/skill discovery
					const { clearSessionCaches } =
						await import("./commands/clear/caches.js");
					clearSessionCaches();

					const result = await loadConversationForResume(
						undefined /* sessionId */,
						undefined /* sourceFile */,
					);
					if (!result) {
						logEvent("tengu_continue", {
							success: false,
						});
						return await exitWithError(
							root,
							"No conversation found to continue",
						);
					}

					const loaded = await processResumedConversation(
						result,
						{
							forkSession: !!options.forkSession,
							includeAttribution: true,
							transcriptPath: result.fullPath,
						},
						resumeContext,
					);

					if (loaded.restoredAgentDef) {
						mainThreadAgentDefinition = loaded.restoredAgentDef;
					}

					maybeActivateProactive(options);
					maybeActivateBrief(options);

					logEvent("tengu_continue", {
						success: true,
						resume_duration_ms: Math.round(
							performance.now() - resumeStart,
						),
					});
					resumeSucceeded = true;

					await launchRepl(
						root,
						{
							getFpsMetrics,
							stats,
							initialState: loaded.initialState,
						},
						{
							...sessionConfig,
							mainThreadAgentDefinition:
								loaded.restoredAgentDef ??
								mainThreadAgentDefinition,
							initialMessages: loaded.messages,
							initialFileHistorySnapshots:
								loaded.fileHistorySnapshots,
							initialContentReplacements:
								loaded.contentReplacements,
							initialAgentName: loaded.agentName,
							initialAgentColor: loaded.agentColor,
						},
						renderAndRun,
					);
				} catch (error) {
					if (!resumeSucceeded) {
						logEvent("tengu_continue", {
							success: false,
						});
					}
					logError(error);
					process.exit(1);
				}
			} else if (feature("DIRECT_CONNECT") && _pendingConnect?.url) {
				// `claude connect <url>` — full interactive TUI connected to a remote server
				let directConnectConfig;
				try {
					const session = await createDirectConnectSession({
						serverUrl: _pendingConnect.url,
						authToken: _pendingConnect.authToken,
						cwd: getOriginalCwd(),
						dangerouslySkipPermissions:
							_pendingConnect.dangerouslySkipPermissions,
					});
					if (session.workDir) {
						setOriginalCwd(session.workDir);
						setCwdState(session.workDir);
					}
					setDirectConnectServerUrl(_pendingConnect.url);
					directConnectConfig = session.config;
				} catch (err) {
					return await exitWithError(
						root,
						err instanceof DirectConnectError
							? err.message
							: String(err),
						() => gracefulShutdown(1),
					);
				}

				const connectInfoMessage = createSystemMessage(
					`Connected to server at ${_pendingConnect.url}\nSession: ${directConnectConfig.sessionId}`,
					"info",
				);

				await launchRepl(
					root,
					{ getFpsMetrics, stats, initialState },
					{
						debug: debug || debugToStderr,
						commands,
						initialTools: [],
						initialMessages: [connectInfoMessage],
						mcpClients: [],
						autoConnectIdeFlag: ide,
						mainThreadAgentDefinition,
						disableSlashCommands,
						directConnectConfig,
						thinkingConfig,
					},
					renderAndRun,
				);
				return;
			} else if (feature("SSH_REMOTE") && _pendingSSH?.host) {
				// `claude ssh <host> [dir]` — probe remote, deploy binary if needed,
				// spawn ssh with unix-socket -R forward to a local auth proxy, hand
				// the REPL an SSHSession. Tools run remotely, UI renders locally.
				// `--local` skips probe/deploy/ssh and spawns the current binary
				// directly with the same env — e2e test of the proxy/auth plumbing.
				const {
					createSSHSession,
					createLocalSSHSession,
					SSHSessionError,
				} = await import("./ssh/createSSHSession.js");
				let sshSession: import('./ssh/createSSHSession.js').SSHSession | undefined;
				try {
					if (_pendingSSH.local) {
						process.stderr.write(
							"Starting local ssh-proxy test session...\n",
						);
						sshSession = await createLocalSSHSession({
							cwd: _pendingSSH.cwd,
							permissionMode: _pendingSSH.permissionMode,
							dangerouslySkipPermissions:
								_pendingSSH.dangerouslySkipPermissions,
						});
					} else {
						process.stderr.write(
							`Connecting to ${_pendingSSH.host}…\n`,
						);
						// In-place progress: \r + EL0 (erase to end of line). Final \n on
						// success so the next message lands on a fresh line. No-op when
						// stderr isn't a TTY (piped/redirected) — \r would just emit noise.
						const isTTY = process.stderr.isTTY;
						let hadProgress = false;
						sshSession = await createSSHSession(
							{
								host: _pendingSSH.host,
								cwd: _pendingSSH.cwd,
								localVersion: MACRO.VERSION,
								permissionMode: _pendingSSH.permissionMode,
								dangerouslySkipPermissions:
									_pendingSSH.dangerouslySkipPermissions,
								extraCliArgs: _pendingSSH.extraCliArgs,
								remoteBin: _pendingSSH.remoteBin,
							},
							isTTY
								? {
										onProgress: (msg: string) => {
											hadProgress = true;
											process.stderr.write(
												`\r  ${msg}\x1b[K`,
											);
										},
									}
								: {},
						);
						if (hadProgress) process.stderr.write("\n");
					}
					setOriginalCwd(sshSession.remoteCwd);
					setCwdState(sshSession.remoteCwd);
					setDirectConnectServerUrl(
						_pendingSSH.local ? "local" : _pendingSSH.host,
					);
				} catch (err) {
					return await exitWithError(
						root,
						err instanceof SSHSessionError
							? err.message
							: String(err),
						() => gracefulShutdown(1),
					);
				}

				const sshInfoMessage = createSystemMessage(
					_pendingSSH.local
						? `Local ssh-proxy test session\ncwd: ${sshSession.remoteCwd}\nAuth: unix socket → local proxy`
						: `SSH session to ${_pendingSSH.host}\nRemote cwd: ${sshSession.remoteCwd}\nAuth: unix socket -R → local proxy`,
					"info",
				);

				await launchRepl(
					root,
					{ getFpsMetrics, stats, initialState },
					{
						debug: debug || debugToStderr,
						commands,
						initialTools: [],
						initialMessages: [sshInfoMessage],
						mcpClients: [],
						autoConnectIdeFlag: ide,
						mainThreadAgentDefinition,
						disableSlashCommands,
						sshSession,
						thinkingConfig,
					},
					renderAndRun,
				);
				return;
			} else if (
				feature("KAIROS") &&
				_pendingAssistantChat &&
				(_pendingAssistantChat.sessionId ||
					_pendingAssistantChat.discover)
			) {
				// `claude assistant [sessionId]` — REPL as a pure viewer client
				// of a remote assistant session. The agentic loop runs remotely; this
				// process streams live events and POSTs messages. History is lazy-
				// loaded by useAssistantHistory on scroll-up (no blocking fetch here).
				const { discoverAssistantSessions } =
					await import("./assistant/sessionDiscovery.js");

				let targetSessionId = _pendingAssistantChat.sessionId;

				// Discovery flow — list bridge environments, filter sessions
				if (!targetSessionId) {
					let sessions;
					try {
						sessions = await discoverAssistantSessions();
					} catch (e) {
						return await exitWithError(
							root,
							`Failed to discover sessions: ${e instanceof Error ? e.message : e}`,
							() => gracefulShutdown(1),
						);
					}
					if (sessions.length === 0) {
						let installedDir: string | null;
						try {
							installedDir =
								await launchAssistantInstallWizard(root);
						} catch (e) {
							return await exitWithError(
								root,
								`Assistant installation failed: ${e instanceof Error ? e.message : e}`,
								() => gracefulShutdown(1),
							);
						}
						if (installedDir === null) {
							await gracefulShutdown(0);
							process.exit(0);
						}
						// The daemon needs a few seconds to spin up its worker and
						// establish a bridge session before discovery will find it.
						return await exitWithMessage(
							root,
							`Assistant installed in ${installedDir}. The daemon is starting up — run \`claude assistant\` again in a few seconds to connect.`,
							{
								exitCode: 0,
								beforeExit: () => gracefulShutdown(0),
							},
						);
					}
					if (sessions.length === 1) {
						targetSessionId = sessions[0]!.id;
					} else {
						const picked = await launchAssistantSessionChooser(
							root,
							{
								sessions,
							},
						);
						if (!picked) {
							await gracefulShutdown(0);
							process.exit(0);
						}
						targetSessionId = picked;
					}
				}

				// Auth — call prepareApiRequest() once for orgUUID, but use a
				// getAccessToken closure for the token so reconnects get fresh tokens.
				const {
					checkAndRefreshOAuthTokenIfNeeded,
					getClaudeAIOAuthTokens,
				} = await import("./utils/auth.js");
				await checkAndRefreshOAuthTokenIfNeeded();
				let apiCreds;
				try {
					apiCreds = await prepareApiRequest();
				} catch (e) {
					return await exitWithError(
						root,
						`Error: ${e instanceof Error ? e.message : "Failed to authenticate"}`,
						() => gracefulShutdown(1),
					);
				}
				const getAccessToken = (): string =>
					getClaudeAIOAuthTokens()?.accessToken ??
					apiCreds.accessToken;

				// Brief mode activation: setKairosActive(true) satisfies BOTH opt-in
				// and entitlement for isBriefEnabled() (BriefTool.ts:124-132).
				setKairosActive(true);
				setUserMsgOptIn(true);
				setIsRemoteMode(true);

				const remoteSessionConfig = createRemoteSessionConfig(
					targetSessionId,
					getAccessToken,
					apiCreds.orgUUID,
					/* hasInitialPrompt */ false,
					/* viewerOnly */ true,
				);

				const infoMessage = createSystemMessage(
					`Attached to assistant session ${targetSessionId.slice(0, 8)}…`,
					"info",
				);

				const assistantInitialState: AppState = {
					...initialState,
					isBriefOnly: true,
					kairosEnabled: false,
					replBridgeEnabled: false,
				};

				const remoteCommands = filterCommandsForRemoteMode(commands);
				await launchRepl(
					root,
					{
						getFpsMetrics,
						stats,
						initialState: assistantInitialState,
					},
					{
						debug: debug || debugToStderr,
						commands: remoteCommands,
						initialTools: [],
						initialMessages: [infoMessage],
						mcpClients: [],
						autoConnectIdeFlag: ide,
						mainThreadAgentDefinition,
						disableSlashCommands,
						remoteSessionConfig,
						thinkingConfig,
					},
					renderAndRun,
				);
				return;
			} else if (
				options.resume ||
				options.fromPr ||
				teleport ||
				remote !== null
			) {
				// Handle resume flow - from file (ant-only), session ID, or interactive selector

				// Clear stale caches before resuming to ensure fresh file/skill discovery
				const { clearSessionCaches } =
					await import("./commands/clear/caches.js");
				clearSessionCaches();

				let messages: MessageType[] | null = null;
				let processedResume: ProcessedResume | undefined;

				let maybeSessionId = validateUuid(options.resume);
				let searchTerm: string | undefined;
				// Store full LogOption when found by custom title (for cross-worktree resume)
				let matchedLog: LogOption | null = null;
				// PR filter for --from-pr flag
				let filterByPr: boolean | number | string | undefined;

				// Handle --from-pr flag
				if (options.fromPr) {
					if (options.fromPr === true) {
						// Show all sessions with linked PRs
						filterByPr = true;
					} else if (typeof options.fromPr === "string") {
						// Could be a PR number or URL
						filterByPr = options.fromPr;
					}
				}

				// If resume value is not a UUID, try exact match by custom title first
				if (
					options.resume &&
					typeof options.resume === "string" &&
					!maybeSessionId
				) {
					const trimmedValue = options.resume.trim();
					if (trimmedValue) {
						const matches = await searchSessionsByCustomTitle(
							trimmedValue,
							{
								exact: true,
							},
						);

						if (matches.length === 1) {
							// Exact match found - store full LogOption for cross-worktree resume
							matchedLog = matches[0]!;
							maybeSessionId =
								getSessionIdFromLog(matchedLog) ?? null;
						} else {
							// No match or multiple matches - use as search term for picker
							searchTerm = trimmedValue;
						}
					}
				}

				// --remote and --teleport both create/resume Claude Code Web (CCR) sessions.
				// Remote Control (--rc) is a separate feature gated in initReplBridge.ts.
				if (remote !== null || teleport) {
					await waitForPolicyLimitsToLoad();
					if (!isPolicyAllowed("allow_remote_sessions")) {
						return await exitWithError(
							root,
							"Error: Remote sessions are disabled by your organization's policy.",
							() => gracefulShutdown(1),
						);
					}
				}

				if (remote !== null) {
					// Create remote session (optionally with initial prompt)
					const hasInitialPrompt = remote.length > 0;

					// Check if TUI mode is enabled - description is only optional in TUI mode
					const isRemoteTuiEnabled =
						getFeatureValue_CACHED_MAY_BE_STALE(
							"tengu_remote_backend",
							false,
						);
					if (!isRemoteTuiEnabled && !hasInitialPrompt) {
						return await exitWithError(
							root,
							'Error: --remote requires a description.\nUsage: claude --remote "your task description"',
							() => gracefulShutdown(1),
						);
					}

					logEvent("tengu_remote_create_session", {
						has_initial_prompt: String(
							hasInitialPrompt,
						) as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
					});

					// Pass current branch so CCR clones the repo at the right revision
					const currentBranch = await getBranch();
					const createdSession =
						await teleportToRemoteWithErrorHandling(
							root,
							hasInitialPrompt ? remote : null,
							new AbortController().signal,
							currentBranch || undefined,
						);
					if (!createdSession) {
						logEvent("tengu_remote_create_session_error", {
							error: "unable_to_create_session" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
						});
						return await exitWithError(
							root,
							"Error: Unable to create remote session",
							() => gracefulShutdown(1),
						);
					}
					logEvent("tengu_remote_create_session_success", {
						session_id:
							createdSession.id as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
					});

					// Check if new remote TUI mode is enabled via feature gate
					if (!isRemoteTuiEnabled) {
						// Original behavior: print session info and exit
						process.stdout.write(
							`Created remote session: ${createdSession.title}\n`,
						);
						process.stdout.write(
							`View: ${getRemoteSessionUrl(createdSession.id)}?m=0\n`,
						);
						process.stdout.write(
							`Resume with: claude --teleport ${createdSession.id}\n`,
						);
						await gracefulShutdown(0);
						process.exit(0);
					}

					// New behavior: start local TUI with CCR engine
					// Mark that we're in remote mode for command visibility
					setIsRemoteMode(true);
					switchSession(asSessionId(createdSession.id));

					// Get OAuth credentials for remote session
					let apiCreds: { accessToken: string; orgUUID: string };
					try {
						apiCreds = await prepareApiRequest();
					} catch (error) {
						logError(toError(error));
						return await exitWithError(
							root,
							`Error: ${errorMessage(error) || "Failed to authenticate"}`,
							() => gracefulShutdown(1),
						);
					}

					// Create remote session config for the REPL
					const { getClaudeAIOAuthTokens: getTokensForRemote } =
						await import("./utils/auth.js");
					const getAccessTokenForRemote = (): string =>
						getTokensForRemote()?.accessToken ??
						apiCreds.accessToken;
					const remoteSessionConfig = createRemoteSessionConfig(
						createdSession.id,
						getAccessTokenForRemote,
						apiCreds.orgUUID,
						hasInitialPrompt,
					);

					// Add remote session info as initial system message
					const remoteSessionUrl = `${getRemoteSessionUrl(createdSession.id)}?m=0`;
					const remoteInfoMessage = createSystemMessage(
						`/remote-control is active. Code in CLI or at ${remoteSessionUrl}`,
						"info",
					);

					// Create initial user message from the prompt if provided (CCR echoes it back but we ignore that)
					const initialUserMessage = hasInitialPrompt
						? createUserMessage({ content: remote })
						: null;

					// Set remote session URL in app state for footer indicator
					const remoteInitialState = {
						...initialState,
						remoteSessionUrl,
					};

					// Pre-filter commands to only include remote-safe ones.
					// CCR's init response may further refine the list (via handleRemoteInit in REPL).
					const remoteCommands =
						filterCommandsForRemoteMode(commands);
					await launchRepl(
						root,
						{
							getFpsMetrics,
							stats,
							initialState: remoteInitialState,
						},
						{
							debug: debug || debugToStderr,
							commands: remoteCommands,
							initialTools: [],
							initialMessages: initialUserMessage
								? [remoteInfoMessage, initialUserMessage]
								: [remoteInfoMessage],
							mcpClients: [],
							autoConnectIdeFlag: ide,
							mainThreadAgentDefinition,
							disableSlashCommands,
							remoteSessionConfig,
							thinkingConfig,
						},
						renderAndRun,
					);
					return;
				} else if (teleport) {
					if (teleport === true || teleport === "") {
						// Interactive mode: show task selector and handle resume
						logEvent("tengu_teleport_interactive_mode", {});
						logForDebugging(
							"selectAndResumeTeleportTask: Starting teleport flow...",
						);
						const teleportResult =
							await launchTeleportResumeWrapper(root);
						if (!teleportResult) {
							// User cancelled or error occurred
							await gracefulShutdown(0);
							process.exit(0);
						}
						const { branchError } =
							await checkOutTeleportedSessionBranch(
								teleportResult.branch,
							);
						messages = processMessagesForTeleportResume(
							teleportResult.log,
							branchError,
						);
					} else if (typeof teleport === "string") {
						logEvent("tengu_teleport_resume_session", {
							mode: "direct" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
						});
						try {
							// First, fetch session and validate repository before checking git state
							const sessionData = await fetchSession(teleport);
							const repoValidation =
								await validateSessionRepository(sessionData);

							// Handle repo mismatch or not in repo cases
							if (
								repoValidation.status === "mismatch" ||
								repoValidation.status === "not_in_repo"
							) {
								const sessionRepo = repoValidation.sessionRepo;
								if (sessionRepo) {
									// Check for known paths
									const knownPaths =
										getKnownPathsForRepo(sessionRepo);
									const existingPaths =
										await filterExistingPaths(knownPaths);

									if (existingPaths.length > 0) {
										// Show directory switch dialog
										const selectedPath =
											await launchTeleportRepoMismatchDialog(
												root,
												{
													targetRepo: sessionRepo,
													initialPaths: existingPaths,
												},
											);

										if (selectedPath) {
											// Change to the selected directory
											process.chdir(selectedPath);
											setCwd(selectedPath);
											setOriginalCwd(selectedPath);
										} else {
											// User cancelled
											await gracefulShutdown(0);
										}
									} else {
										// No known paths - show original error
										throw new TeleportOperationError(
											`You must run claude --teleport ${teleport} from a checkout of ${sessionRepo}.`,
											chalk.red(
												`You must run claude --teleport ${teleport} from a checkout of ${chalk.bold(sessionRepo)}.\n`,
											),
										);
									}
								}
							} else if (repoValidation.status === "error") {
								throw new TeleportOperationError(
									repoValidation.errorMessage ||
										"Failed to validate session",
									chalk.red(
										`Error: ${repoValidation.errorMessage || "Failed to validate session"}\n`,
									),
								);
							}

							await validateGitState();

							// Use progress UI for teleport
							const { teleportWithProgress } =
								await import("./components/TeleportProgress.js");
							const result = await teleportWithProgress(
								root,
								teleport,
							);
							// Track teleported session for reliability logging
							setTeleportedSessionInfo({ sessionId: teleport });
							messages = result.messages;
						} catch (error) {
							if (error instanceof TeleportOperationError) {
								process.stderr.write(
									error.formattedMessage + "\n",
								);
							} else {
								logError(error);
								process.stderr.write(
									chalk.red(
										`Error: ${errorMessage(error)}\n`,
									),
								);
							}
							await gracefulShutdown(1);
						}
					}
				}
				if (process.env.USER_TYPE === "ant") {
					if (
						options.resume &&
						typeof options.resume === "string" &&
						!maybeSessionId
					) {
						// Check for ccshare URL (e.g. https://go/ccshare/boris-20260311-211036)
						const { parseCcshareId, loadCcshare } =
							await import("./utils/ccshareResume.js");
						const ccshareId = parseCcshareId(options.resume);
						if (ccshareId) {
							try {
								const resumeStart = performance.now();
								const logOption = await loadCcshare(ccshareId);
								const result = await loadConversationForResume(
									logOption,
									undefined,
								);
								if (result) {
									processedResume =
										await processResumedConversation(
											result,
											{
												forkSession: true,
												transcriptPath: result.fullPath,
											},
											resumeContext,
										);
									if (processedResume.restoredAgentDef) {
										mainThreadAgentDefinition =
											processedResume.restoredAgentDef;
									}
									logEvent("tengu_session_resumed", {
										entrypoint:
											"ccshare" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
										success: true,
										resume_duration_ms: Math.round(
											performance.now() - resumeStart,
										),
									});
								} else {
									logEvent("tengu_session_resumed", {
										entrypoint:
											"ccshare" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
										success: false,
									});
								}
							} catch (error) {
								logEvent("tengu_session_resumed", {
									entrypoint:
										"ccshare" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
									success: false,
								});
								logError(error);
								await exitWithError(
									root,
									`Unable to resume from ccshare: ${errorMessage(error)}`,
									() => gracefulShutdown(1),
								);
							}
						} else {
							const resolvedPath = resolve(options.resume);
							try {
								const resumeStart = performance.now();
								let logOption;
								try {
									// Attempt to load as a transcript file; ENOENT falls through to session-ID handling
									logOption =
										await loadTranscriptFromFile(
											resolvedPath,
										);
								} catch (error) {
									if (!isENOENT(error)) throw error;
									// ENOENT: not a file path — fall through to session-ID handling
								}
								if (logOption) {
									const result =
										await loadConversationForResume(
											logOption,
											undefined /* sourceFile */,
										);
									if (result) {
										processedResume =
											await processResumedConversation(
												result,
												{
													forkSession:
														!!options.forkSession,
													transcriptPath:
														result.fullPath,
												},
												resumeContext,
											);
										if (processedResume.restoredAgentDef) {
											mainThreadAgentDefinition =
												processedResume.restoredAgentDef;
										}
										logEvent("tengu_session_resumed", {
											entrypoint:
												"file" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
											success: true,
											resume_duration_ms: Math.round(
												performance.now() - resumeStart,
											),
										});
									} else {
										logEvent("tengu_session_resumed", {
											entrypoint:
												"file" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
											success: false,
										});
									}
								}
							} catch (error) {
								logEvent("tengu_session_resumed", {
									entrypoint:
										"file" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
									success: false,
								});
								logError(error);
								await exitWithError(
									root,
									`Unable to load transcript from file: ${options.resume}`,
									() => gracefulShutdown(1),
								);
							}
						}
					}
				}

				// If not loaded as a file, try as session ID
				if (maybeSessionId) {
					// Resume specific session by ID
					const sessionId = maybeSessionId;
					try {
						const resumeStart = performance.now();
						// Use matchedLog if available (for cross-worktree resume by custom title)
						// Otherwise fall back to sessionId string (for direct UUID resume)
						const result = await loadConversationForResume(
							matchedLog ?? sessionId,
							undefined,
						);

						if (!result) {
							logEvent("tengu_session_resumed", {
								entrypoint:
									"cli_flag" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
								success: false,
							});
							return await exitWithError(
								root,
								`No conversation found with session ID: ${sessionId}`,
							);
						}

						const fullPath =
							matchedLog?.fullPath ?? result.fullPath;
						processedResume = await processResumedConversation(
							result,
							{
								forkSession: !!options.forkSession,
								sessionIdOverride: sessionId,
								transcriptPath: fullPath,
							},
							resumeContext,
						);

						if (processedResume.restoredAgentDef) {
							mainThreadAgentDefinition =
								processedResume.restoredAgentDef;
						}
						logEvent("tengu_session_resumed", {
							entrypoint:
								"cli_flag" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
							success: true,
							resume_duration_ms: Math.round(
								performance.now() - resumeStart,
							),
						});
					} catch (error) {
						logEvent("tengu_session_resumed", {
							entrypoint:
								"cli_flag" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
							success: false,
						});
						logError(error);
						await exitWithError(
							root,
							`Failed to resume session ${sessionId}`,
						);
					}
				}

				// Await file downloads before rendering REPL (files must be available)
				if (fileDownloadPromise) {
					try {
						const results = await fileDownloadPromise;
						const failedCount = count(results, (r) => !r.success);
						if (failedCount > 0) {
							process.stderr.write(
								chalk.yellow(
									`Warning: ${failedCount}/${results.length} file(s) failed to download.\n`,
								),
							);
						}
					} catch (error) {
						return await exitWithError(
							root,
							`Error downloading files: ${errorMessage(error)}`,
						);
					}
				}

				// If we have a processed resume or teleport messages, render the REPL
				const resumeData =
					processedResume ??
					(Array.isArray(messages)
						? {
								messages,
								fileHistorySnapshots: undefined,
								agentName: undefined,
								agentColor: undefined as
									| AgentColorName
									| undefined,
								restoredAgentDef: mainThreadAgentDefinition,
								initialState,
								contentReplacements: undefined,
							}
						: undefined);
				if (resumeData) {
					maybeActivateProactive(options);
					maybeActivateBrief(options);

					await launchRepl(
						root,
						{
							getFpsMetrics,
							stats,
							initialState: resumeData.initialState,
						},
						{
							...sessionConfig,
							mainThreadAgentDefinition:
								resumeData.restoredAgentDef ??
								mainThreadAgentDefinition,
							initialMessages: resumeData.messages,
							initialFileHistorySnapshots:
								resumeData.fileHistorySnapshots,
							initialContentReplacements:
								resumeData.contentReplacements,
							initialAgentName: resumeData.agentName,
							initialAgentColor: resumeData.agentColor,
						},
						renderAndRun,
					);
				} else {
					// Show interactive selector (includes same-repo worktrees)
					// Note: ResumeConversation loads logs internally to ensure proper GC after selection
					await launchResumeChooser(
						root,
						{ getFpsMetrics, stats, initialState },
						getWorktreePaths(getOriginalCwd()),
						{
							...sessionConfig,
							initialSearchQuery: searchTerm,
							forkSession: options.forkSession,
							filterByPr,
						},
					);
				}
			} else {
				// Pass unresolved hooks promise to REPL so it can render immediately
				// instead of blocking ~500ms waiting for SessionStart hooks to finish.
				// REPL will inject hook messages when they resolve and await them before
				// the first API call so the model always sees hook context.
				const pendingHookMessages =
					hooksPromise && hookMessages.length === 0
						? hooksPromise
						: undefined;

				profileCheckpoint("action_after_hooks");
				maybeActivateProactive(options);
				maybeActivateBrief(options);
				// Persist the current mode for fresh sessions so future resumes know what mode was used
				if (feature("COORDINATOR_MODE")) {
					saveMode(
						coordinatorModeModule?.isCoordinatorMode()
							? "coordinator"
							: "normal",
					);
				}

				// If launched via a deep link, show a provenance banner so the user
				// knows the session originated externally. Linux xdg-open and
				// browsers with "always allow" set dispatch the link with no OS-level
				// confirmation, so this is the only signal the user gets that the
				// prompt — and the working directory / CLAUDE.md it implies — came
				// from an external source rather than something they typed.
				let deepLinkBanner: ReturnType<
					typeof createSystemMessage
				> | null = null;
				if (feature("LODESTONE")) {
					if (options.deepLinkOrigin) {
						logEvent("tengu_deep_link_opened", {
							has_prefill: Boolean(options.prefill),
							has_repo: Boolean(options.deepLinkRepo),
						});
						deepLinkBanner = createSystemMessage(
							buildDeepLinkBanner({
								cwd: getCwd(),
								prefillLength: options.prefill?.length,
								repo: options.deepLinkRepo,
								lastFetch:
									options.deepLinkLastFetch !== undefined
										? new Date(options.deepLinkLastFetch)
										: undefined,
							}),
							"warning",
						);
					} else if (options.prefill) {
						deepLinkBanner = createSystemMessage(
							"Launched with a pre-filled prompt — review it before pressing Enter.",
							"warning",
						);
					}
				}
				const initialMessages = deepLinkBanner
					? [deepLinkBanner, ...hookMessages]
					: hookMessages.length > 0
						? hookMessages
						: undefined;

				await launchRepl(
					root,
					{ getFpsMetrics, stats, initialState },
					{
						...sessionConfig,
						initialMessages,
						pendingHookMessages,
					},
					renderAndRun,
				);
			}
		})
		.version(
			`${MACRO.VERSION} (Claude Code)`,
			"-v, --version",
			"Output the version number",
		);

	// Worktree flags
	program.option(
		"-w, --worktree [name]",
		"Create a new git worktree for this session (optionally specify a name)",
	);
	program.option(
		"--tmux",
		"Create a tmux session for the worktree (requires --worktree). Uses iTerm2 native panes when available; use --tmux=classic for traditional tmux.",
	);

	if (canUserConfigureAdvisor()) {
		program.addOption(
			new Option(
				"--advisor <model>",
				"Enable the server-side advisor tool with the specified model (alias or full ID).",
			).hideHelp(),
		);
	}

	if (process.env.USER_TYPE === "ant") {
		program.addOption(
			new Option(
				"--delegate-permissions",
				"[ANT-ONLY] Alias for --permission-mode auto.",
			).implies({
				permissionMode: "auto",
			}),
		);
		program.addOption(
			new Option(
				"--dangerously-skip-permissions-with-classifiers",
				"[ANT-ONLY] Deprecated alias for --permission-mode auto.",
			)
				.hideHelp()
				.implies({ permissionMode: "auto" }),
		);
		program.addOption(
			new Option(
				"--afk",
				"[ANT-ONLY] Deprecated alias for --permission-mode auto.",
			)
				.hideHelp()
				.implies({ permissionMode: "auto" }),
		);
		program.addOption(
			new Option(
				"--tasks [id]",
				'[ANT-ONLY] Tasks mode: watch for tasks and auto-process them. Optional id is used as both the task list ID and agent ID (defaults to "tasklist").',
			)
				.argParser(String)
				.hideHelp(),
		);
		program.option(
			"--agent-teams",
			"[ANT-ONLY] Force Claude to use multi-agent mode for solving problems",
			() => true,
		);
	}

	if (feature("TRANSCRIPT_CLASSIFIER")) {
		program.addOption(
			new Option("--enable-auto-mode", "Opt in to auto mode").hideHelp(),
		);
	}

	if (feature("PROACTIVE") || feature("KAIROS")) {
		program.addOption(
			new Option("--proactive", "Start in proactive autonomous mode"),
		);
	}

	if (feature("UDS_INBOX")) {
		program.addOption(
			new Option(
				"--messaging-socket-path <path>",
				"Unix domain socket path for the UDS messaging server (defaults to a tmp path)",
			),
		);
	}

	if (feature("KAIROS") || feature("KAIROS_BRIEF")) {
		program.addOption(
			new Option(
				"--brief",
				"Enable SendUserMessage tool for agent-to-user communication",
			),
		);
	}
	if (feature("KAIROS")) {
		program.addOption(
			new Option(
				"--assistant",
				"Force assistant mode (Agent SDK daemon use)",
			).hideHelp(),
		);
	}
	program.addOption(
		new Option(
			"--channels <servers...>",
			"MCP servers whose channel notifications (inbound push) should register this session. Space-separated server names.",
		).hideHelp(),
	);
	program.addOption(
		new Option(
			"--dangerously-load-development-channels <servers...>",
			"Load channel servers not on the approved allowlist. For local channel development only. Shows a confirmation dialog at startup.",
		).hideHelp(),
	);

	// Teammate identity options (set by leader when spawning tmux teammates)
	// These replace the CLAUDE_CODE_* environment variables
	program.addOption(
		new Option("--agent-id <id>", "Teammate agent ID").hideHelp(),
	);
	program.addOption(
		new Option("--agent-name <name>", "Teammate display name").hideHelp(),
	);
	program.addOption(
		new Option(
			"--team-name <name>",
			"Team name for swarm coordination",
		).hideHelp(),
	);
	program.addOption(
		new Option("--agent-color <color>", "Teammate UI color").hideHelp(),
	);
	program.addOption(
		new Option(
			"--plan-mode-required",
			"Require plan mode before implementation",
		).hideHelp(),
	);
	program.addOption(
		new Option(
			"--parent-session-id <id>",
			"Parent session ID for analytics correlation",
		).hideHelp(),
	);
	program.addOption(
		new Option(
			"--teammate-mode <mode>",
			'How to spawn teammates: "tmux", "in-process", or "auto"',
		)
			.choices(["auto", "tmux", "in-process"])
			.hideHelp(),
	);
	program.addOption(
		new Option(
			"--agent-type <type>",
			"Custom agent type for this teammate",
		).hideHelp(),
	);

	// Enable SDK URL for all builds but hide from help
	program.addOption(
		new Option(
			"--sdk-url <url>",
			"Use remote WebSocket endpoint for SDK I/O streaming (only with -p and stream-json format)",
		).hideHelp(),
	);

	// Enable teleport/remote flags for all builds but keep them undocumented until GA
	program.addOption(
		new Option(
			"--teleport [session]",
			"Resume a teleport session, optionally specify session ID",
		).hideHelp(),
	);
	program.addOption(
		new Option(
			"--remote [description]",
			"Create a remote session with the given description",
		).hideHelp(),
	);
	if (feature("BRIDGE_MODE")) {
		program.addOption(
			new Option(
				"--remote-control [name]",
				"Start an interactive session with Remote Control enabled (optionally named)",
			)
				.argParser((value) => value || true)
				.hideHelp(),
		);
		program.addOption(
			new Option("--rc [name]", "Alias for --remote-control")
				.argParser((value) => value || true)
				.hideHelp(),
		);
	}

	if (feature("HARD_FAIL")) {
		program.addOption(
			new Option(
				"--hard-fail",
				"Crash on logError calls instead of silently logging",
			).hideHelp(),
		);
	}

	profileCheckpoint("run_main_options_built");

	// -p/--print mode: skip subcommand registration. The 52 subcommands
	// (mcp, auth, plugin, skill, task, config, doctor, update, etc.) are
	// never dispatched in print mode — commander routes the prompt to the
	// default action. The subcommand registration path was measured at ~65ms
	// on baseline — mostly the isBridgeEnabled() call (25ms settings Zod parse
	// + 40ms sync keychain subprocess), both hidden by the try/catch that
	// always returns false before enableConfigs(). cc:// URLs are rewritten to
	// `open` at main() line ~851 BEFORE this runs, so argv check is safe here.
	const isPrintMode =
		process.argv.includes("-p") || process.argv.includes("--print");
	const isCcUrl = process.argv.some(
		(a) => a.startsWith("cc://") || a.startsWith("cc+unix://"),
	);
	if (isPrintMode && !isCcUrl) {
		profileCheckpoint("run_before_parse");
		await program.parseAsync(process.argv);
		profileCheckpoint("run_after_parse");
		return program;
	}

	// claude mcp

	const mcp = program
		.command("mcp")
		.description("Configure and manage MCP servers")
		.configureHelp(createSortedHelpConfig())
		.enablePositionalOptions();

	mcp.command("serve")
		.description(`Start the Claude Code MCP server`)
		.option("-d, --debug", "Enable debug mode", () => true)
		.option(
			"--verbose",
			"Override verbose mode setting from config",
			() => true,
		)
		.action(
			async ({
				debug,
				verbose,
			}: {
				debug?: boolean;
				verbose?: boolean;
			}) => {
				const { mcpServeHandler } =
					await import("./cli/handlers/mcp.js");
				await mcpServeHandler({ debug, verbose });
			},
		);

	// Register the mcp add subcommand (extracted for testability)
	registerMcpAddCommand(mcp);

	if (isXaaEnabled()) {
		registerMcpXaaIdpCommand(mcp);
	}

	mcp.command("remove <name>")
		.description("Remove an MCP server")
		.option(
			"-s, --scope <scope>",
			"Configuration scope (local, user, or project) - if not specified, removes from whichever scope it exists in",
		)
		.action(async (name: string, options: { scope?: string }) => {
			const { mcpRemoveHandler } = await import("./cli/handlers/mcp.js");
			await mcpRemoveHandler(name, options);
		});

	mcp.command("list")
		.description(
			"List configured MCP servers. Note: The workspace trust dialog is skipped and stdio servers from .mcp.json are spawned for health checks. Only use this command in directories you trust.",
		)
		.action(async () => {
			const { mcpListHandler } = await import("./cli/handlers/mcp.js");
			await mcpListHandler();
		});

	mcp.command("get <name>")
		.description(
			"Get details about an MCP server. Note: The workspace trust dialog is skipped and stdio servers from .mcp.json are spawned for health checks. Only use this command in directories you trust.",
		)
		.action(async (name: string) => {
			const { mcpGetHandler } = await import("./cli/handlers/mcp.js");
			await mcpGetHandler(name);
		});

	mcp.command("add-json <name> <json>")
		.description("Add an MCP server (stdio or SSE) with a JSON string")
		.option(
			"-s, --scope <scope>",
			"Configuration scope (local, user, or project)",
			"local",
		)
		.option(
			"--client-secret",
			"Prompt for OAuth client secret (or set MCP_CLIENT_SECRET env var)",
		)
		.action(
			async (
				name: string,
				json: string,
				options: { scope?: string; clientSecret?: true },
			) => {
				const { mcpAddJsonHandler } =
					await import("./cli/handlers/mcp.js");
				await mcpAddJsonHandler(name, json, options);
			},
		);

	mcp.command("add-from-claude-desktop")
		.description(
			"Import MCP servers from Claude Desktop (Mac and WSL only)",
		)
		.option(
			"-s, --scope <scope>",
			"Configuration scope (local, user, or project)",
			"local",
		)
		.action(async (options: { scope?: string }) => {
			const { mcpAddFromDesktopHandler } =
				await import("./cli/handlers/mcp.js");
			await mcpAddFromDesktopHandler(options);
		});

	mcp.command("reset-project-choices")
		.description(
			"Reset all approved and rejected project-scoped (.mcp.json) servers within this project",
		)
		.action(async () => {
			const { mcpResetChoicesHandler } =
				await import("./cli/handlers/mcp.js");
			await mcpResetChoicesHandler();
		});

	// claude server
	if (feature("DIRECT_CONNECT")) {
		program
			.command("server")
			.description("Start a Claude Code session server")
			.option("--port <number>", "HTTP port", "0")
			.option("--host <string>", "Bind address", "0.0.0.0")
			.option("--auth-token <token>", "Bearer token for auth")
			.option("--unix <path>", "Listen on a unix domain socket")
			.option(
				"--workspace <dir>",
				"Default working directory for sessions that do not specify cwd",
			)
			.option(
				"--idle-timeout <ms>",
				"Idle timeout for detached sessions in ms (0 = never expire)",
				"600000",
			)
			.option(
				"--max-sessions <n>",
				"Maximum concurrent sessions (0 = unlimited)",
				"32",
			)
			.action(
				async (opts: {
					port: string;
					host: string;
					authToken?: string;
					unix?: string;
					workspace?: string;
					idleTimeout: string;
					maxSessions: string;
				}) => {
					const { randomBytes } = await import("crypto");
					const { startServer } = await import("./server/server.js");
					const { SessionManager } =
						await import("./server/sessionManager.js");
					const { DangerousBackend } =
						await import("./server/backends/dangerousBackend.js");
					const { printBanner } =
						await import("./server/serverBanner.js");
					const { createServerLogger } =
						await import("./server/serverLog.js");
					const {
						writeServerLock,
						removeServerLock,
						probeRunningServer,
					} = await import("./server/lockfile.js");

					const existing = await probeRunningServer();
					if (existing) {
						process.stderr.write(
							`A claude server is already running (pid ${existing.pid}) at ${existing.httpUrl}\n`,
						);
						process.exit(1);
					}

					const authToken =
						opts.authToken ??
						`sk-ant-cc-${randomBytes(16).toString("base64url")}`;

					const config = {
						port: parseInt(opts.port, 10),
						host: opts.host,
						authToken,
						unix: opts.unix,
						workspace: opts.workspace,
						idleTimeoutMs: parseInt(opts.idleTimeout, 10),
						maxSessions: parseInt(opts.maxSessions, 10),
					};

					const backend = new DangerousBackend();
					const sessionManager = new SessionManager(backend, {
						idleTimeoutMs: config.idleTimeoutMs,
						maxSessions: config.maxSessions,
					});
					const logger = createServerLogger();

					const server = startServer(config, sessionManager, logger);
					const actualPort = server.port ?? config.port;
					printBanner(config, authToken, actualPort);

					await writeServerLock({
						pid: process.pid,
						port: actualPort,
						host: config.host,
						httpUrl: config.unix
							? `unix:${config.unix}`
							: `http://${config.host}:${actualPort}`,
						startedAt: Date.now(),
					});

					let shuttingDown = false;
					const shutdown = async () => {
						if (shuttingDown) return;
						shuttingDown = true;
						// Stop accepting new connections before tearing down sessions.
						server.stop(true);
						await sessionManager.destroyAll();
						await removeServerLock();
						process.exit(0);
					};
					process.once("SIGINT", () => void shutdown());
					process.once("SIGTERM", () => void shutdown());
				},
			);
	}

	// `claude ssh <host> [dir]` — registered here only so --help shows it.
	// The actual interactive flow is handled by early argv rewriting in main()
	// (parallels the DIRECT_CONNECT/cc:// pattern above). If commander reaches
	// this action it means the argv rewrite didn't fire (e.g. user ran
	// `claude ssh` with no host) — just print usage.
	if (feature("SSH_REMOTE")) {
		program
			.command("ssh <host> [dir]")
			.description(
				"Run Claude Code on a remote host over SSH. Deploys the binary and " +
					"tunnels API auth back through your local machine — no remote setup needed.",
			)
			.option(
				"--permission-mode <mode>",
				"Permission mode for the remote session",
			)
			.option(
				"--dangerously-skip-permissions",
				"Skip all permission prompts on the remote (dangerous)",
			)
			.option(
				"--remote-bin <command>",
				"Custom remote binary command (skips probe/deploy). " +
					"Example: --remote-bin 'bun /path/to/project/dist/cli.js'",
			)
			.option(
				"--local",
				"e2e test mode — spawn the child CLI locally (skip ssh/deploy). " +
					"Exercises the auth proxy and unix-socket plumbing without a remote host.",
			)
			.action(async () => {
				// Argv rewriting in main() should have consumed `ssh <host>` before
				// commander runs. Reaching here means host was missing or the
				// rewrite predicate didn't match.
				process.stderr.write(
					"Usage: claude ssh <user@host | ssh-config-alias> [dir]\n\n" +
						"Runs Claude Code on a remote Linux host. You don't need to install\n" +
						"anything on the remote or run `claude auth login` there — the binary is\n" +
						"deployed over SSH and API auth tunnels back through your local machine.\n",
				);
				process.exit(1);
			});
	}

	// claude connect — subcommand only handles -p (headless) mode.
	// Interactive mode (without -p) is handled by early argv rewriting in main()
	// which redirects to the main command with full TUI support.
	if (feature("DIRECT_CONNECT")) {
		program
			.command("open <cc-url>")
			.description(
				"Connect to a Claude Code server (internal — use cc:// URLs)",
			)
			.option("-p, --print [prompt]", "Print mode (headless)")
			.option(
				"--output-format <format>",
				"Output format: text, json, stream-json",
				"text",
			)
			.action(
				async (
					ccUrl: string,
					opts: {
						print?: string | true;
						outputFormat?: string;
					},
				) => {
					const { parseConnectUrl } =
						await import("./server/parseConnectUrl.js");
					const { serverUrl, authToken } = parseConnectUrl(ccUrl);

					let connectConfig;
					try {
						const session = await createDirectConnectSession({
							serverUrl,
							authToken,
							cwd: getOriginalCwd(),
							dangerouslySkipPermissions:
								_pendingConnect?.dangerouslySkipPermissions,
						});
						if (session.workDir) {
							setOriginalCwd(session.workDir);
							setCwdState(session.workDir);
						}
						setDirectConnectServerUrl(serverUrl);
						connectConfig = session.config;
					} catch (err) {
						// biome-ignore lint/suspicious/noConsole: intentional error output
						console.error(
							err instanceof DirectConnectError
								? err.message
								: String(err),
						);
						process.exit(1);
					}

					const { runConnectHeadless } =
						await import("./server/connectHeadless.js");

					const prompt =
						typeof opts.print === "string" ? opts.print : "";
					const interactive = opts.print === true;
					await runConnectHeadless(
						connectConfig,
						prompt,
						opts.outputFormat,
						interactive,
					);
				},
			);
	}

	// claude auth

	const auth = program
		.command("auth")
		.description("Manage authentication")
		.configureHelp(createSortedHelpConfig());

	auth.command("login")
		.description("Sign in to your Anthropic account")
		.option(
			"--email <email>",
			"Pre-populate email address on the login page",
		)
		.option("--sso", "Force SSO login flow")
		.option(
			"--console",
			"Use Anthropic Console (API usage billing) instead of Claude subscription",
		)
		.option("--claudeai", "Use Claude subscription (default)")
		.action(
			async ({
				email,
				sso,
				console: useConsole,
				claudeai,
			}: {
				email?: string;
				sso?: boolean;
				console?: boolean;
				claudeai?: boolean;
			}) => {
				const { authLogin } = await import("./cli/handlers/auth.js");
				await authLogin({ email, sso, console: useConsole, claudeai });
			},
		);

	auth.command("status")
		.description("Show authentication status")
		.option("--json", "Output as JSON (default)")
		.option("--text", "Output as human-readable text")
		.action(async (opts: { json?: boolean; text?: boolean }) => {
			const { authStatus } = await import("./cli/handlers/auth.js");
			await authStatus(opts);
		});

	auth.command("logout")
		.description("Log out from your Anthropic account")
		.action(async () => {
			const { authLogout } = await import("./cli/handlers/auth.js");
			await authLogout();
		});

	/**
	 * Helper function to handle marketplace command errors consistently.
	 * Logs the error and exits the process with status 1.
	 * @param error The error that occurred
	 * @param action Description of the action that failed
	 */
	// Hidden flag on all plugin/marketplace subcommands to target cowork_plugins.
	const coworkOption = () =>
		new Option("--cowork", "Use cowork_plugins directory").hideHelp();

	// Plugin validate command
	const pluginCmd = program
		.command("plugin")
		.alias("plugins")
		.description("Manage Claude Code plugins")
		.configureHelp(createSortedHelpConfig());

	pluginCmd
		.command("validate <path>")
		.description("Validate a plugin or marketplace manifest")
		.addOption(coworkOption())
		.action(async (manifestPath: string, options: { cowork?: boolean }) => {
			const { pluginValidateHandler } =
				await import("./cli/handlers/plugins.js");
			await pluginValidateHandler(manifestPath, options);
		});

	// Plugin list command
	pluginCmd
		.command("list")
		.description("List installed plugins")
		.option("--json", "Output as JSON")
		.option(
			"--available",
			"Include available plugins from marketplaces (requires --json)",
		)
		.addOption(coworkOption())
		.action(
			async (options: {
				json?: boolean;
				available?: boolean;
				cowork?: boolean;
			}) => {
				const { pluginListHandler } =
					await import("./cli/handlers/plugins.js");
				await pluginListHandler(options);
			},
		);

	// Marketplace subcommands
	const marketplaceCmd = pluginCmd
		.command("marketplace")
		.description("Manage Claude Code marketplaces")
		.configureHelp(createSortedHelpConfig());

	marketplaceCmd
		.command("add <source>")
		.description("Add a marketplace from a URL, path, or GitHub repo")
		.addOption(coworkOption())
		.option(
			"--sparse <paths...>",
			"Limit checkout to specific directories via git sparse-checkout (for monorepos). Example: --sparse .claude-plugin plugins",
		)
		.option(
			"--scope <scope>",
			"Where to declare the marketplace: user (default), project, or local",
		)
		.action(
			async (
				source: string,
				options: {
					cowork?: boolean;
					sparse?: string[];
					scope?: string;
				},
			) => {
				const { marketplaceAddHandler } =
					await import("./cli/handlers/plugins.js");
				await marketplaceAddHandler(source, options);
			},
		);

	marketplaceCmd
		.command("list")
		.description("List all configured marketplaces")
		.option("--json", "Output as JSON")
		.addOption(coworkOption())
		.action(async (options: { json?: boolean; cowork?: boolean }) => {
			const { marketplaceListHandler } =
				await import("./cli/handlers/plugins.js");
			await marketplaceListHandler(options);
		});

	marketplaceCmd
		.command("remove <name>")
		.alias("rm")
		.description("Remove a configured marketplace")
		.addOption(coworkOption())
		.action(async (name: string, options: { cowork?: boolean }) => {
			const { marketplaceRemoveHandler } =
				await import("./cli/handlers/plugins.js");
			await marketplaceRemoveHandler(name, options);
		});

	marketplaceCmd
		.command("update [name]")
		.description(
			"Update marketplace(s) from their source - updates all if no name specified",
		)
		.addOption(coworkOption())
		.action(
			async (name: string | undefined, options: { cowork?: boolean }) => {
				const { marketplaceUpdateHandler } =
					await import("./cli/handlers/plugins.js");
				await marketplaceUpdateHandler(name, options);
			},
		);

	// Plugin install command
	pluginCmd
		.command("install <plugin>")
		.alias("i")
		.description(
			"Install a plugin from available marketplaces (use plugin@marketplace for specific marketplace)",
		)
		.option(
			"-s, --scope <scope>",
			"Installation scope: user, project, or local",
			"user",
		)
		.addOption(coworkOption())
		.action(
			async (
				plugin: string,
				options: { scope?: string; cowork?: boolean },
			) => {
				const { pluginInstallHandler } =
					await import("./cli/handlers/plugins.js");
				await pluginInstallHandler(plugin, options);
			},
		);

	// Plugin uninstall command
	pluginCmd
		.command("uninstall <plugin>")
		.alias("remove")
		.alias("rm")
		.description("Uninstall an installed plugin")
		.option(
			"-s, --scope <scope>",
			"Uninstall from scope: user, project, or local",
			"user",
		)
		.option(
			"--keep-data",
			"Preserve the plugin's persistent data directory (~/.claude/plugins/data/{id}/)",
		)
		.addOption(coworkOption())
		.action(
			async (
				plugin: string,
				options: {
					scope?: string;
					cowork?: boolean;
					keepData?: boolean;
				},
			) => {
				const { pluginUninstallHandler } =
					await import("./cli/handlers/plugins.js");
				await pluginUninstallHandler(plugin, options);
			},
		);

	// Plugin enable command
	pluginCmd
		.command("enable <plugin>")
		.description("Enable a disabled plugin")
		.option(
			"-s, --scope <scope>",
			`Installation scope: ${VALID_INSTALLABLE_SCOPES.join(", ")} (default: auto-detect)`,
		)
		.addOption(coworkOption())
		.action(
			async (
				plugin: string,
				options: { scope?: string; cowork?: boolean },
			) => {
				const { pluginEnableHandler } =
					await import("./cli/handlers/plugins.js");
				await pluginEnableHandler(plugin, options);
			},
		);

	// Plugin disable command
	pluginCmd
		.command("disable [plugin]")
		.description("Disable an enabled plugin")
		.option("-a, --all", "Disable all enabled plugins")
		.option(
			"-s, --scope <scope>",
			`Installation scope: ${VALID_INSTALLABLE_SCOPES.join(", ")} (default: auto-detect)`,
		)
		.addOption(coworkOption())
		.action(
			async (
				plugin: string | undefined,
				options: { scope?: string; cowork?: boolean; all?: boolean },
			) => {
				const { pluginDisableHandler } =
					await import("./cli/handlers/plugins.js");
				await pluginDisableHandler(plugin, options);
			},
		);

	// Plugin update command
	pluginCmd
		.command("update <plugin>")
		.description(
			"Update a plugin to the latest version (restart required to apply)",
		)
		.option(
			"-s, --scope <scope>",
			`Installation scope: ${VALID_UPDATE_SCOPES.join(", ")} (default: user)`,
		)
		.addOption(coworkOption())
		.action(
			async (
				plugin: string,
				options: { scope?: string; cowork?: boolean },
			) => {
				const { pluginUpdateHandler } =
					await import("./cli/handlers/plugins.js");
				await pluginUpdateHandler(plugin, options);
			},
		);
	// END ANT-ONLY

  // Setup token command
  program
    .command('setup-token')
    .description(
      'Set up a long-lived authentication token (requires Claude subscription)',
    )
    .action(async () => {
      const [{ setupTokenHandler }, { createRoot }] = await Promise.all([
        import('./cli/handlers/util.js'),
        import('@anthropic/ink'),
      ])
      const root = await createRoot(getBaseRenderOptions(false))
      await setupTokenHandler(root)
    })

	// Agents command - list configured agents
	program
		.command("agents")
		.description("List configured agents")
		.option(
			"--setting-sources <sources>",
			"Comma-separated list of setting sources to load (user, project, local).",
		)
		.action(async () => {
			const { agentsHandler } = await import("./cli/handlers/agents.js");
			await agentsHandler();
			process.exit(0);
		});

	if (feature("TRANSCRIPT_CLASSIFIER")) {
		// Skip when tengu_auto_mode_config.enabled === 'disabled' (circuit breaker).
		// Reads from disk cache — GrowthBook isn't initialized at registration time.
		if (getAutoModeEnabledStateIfCached() !== "disabled") {
			const autoModeCmd = program
				.command("auto-mode")
				.description("Inspect auto mode classifier configuration");

			autoModeCmd
				.command("defaults")
				.description(
					"Print the default auto mode environment, allow, and deny rules as JSON",
				)
				.action(async () => {
					const { autoModeDefaultsHandler } =
						await import("./cli/handlers/autoMode.js");
					autoModeDefaultsHandler();
					process.exit(0);
				});

			autoModeCmd
				.command("config")
				.description(
					"Print the effective auto mode config as JSON: your settings where set, defaults otherwise",
				)
				.action(async () => {
					const { autoModeConfigHandler } =
						await import("./cli/handlers/autoMode.js");
					autoModeConfigHandler();
					process.exit(0);
				});

			autoModeCmd
				.command("critique")
				.description("Get AI feedback on your custom auto mode rules")
				.option("--model <model>", "Override which model is used")
				.action(async (options) => {
					const { autoModeCritiqueHandler } =
						await import("./cli/handlers/autoMode.js");
					await autoModeCritiqueHandler(options);
					process.exit();
				});
		}
	}

	// claude autonomy — CLI subcommands mirroring /autonomy slash command
	{
		const autonomyCmd = program
			.command("autonomy")
			.description("Inspect and manage automatic autonomy runs and flows");

		autonomyCmd
			.command("status")
			.description("Print autonomy run, flow, team, pipe, and remote-control status")
			.option("--deep", "Include teams, pipes, daemon, and remote-control sections")
			.action(async (options: { deep?: boolean }) => {
				const { autonomyStatusHandler } = await import("./cli/handlers/autonomy.js");
				await autonomyStatusHandler(options);
				process.exit(0);
			});

		autonomyCmd
			.command("runs [limit]")
			.description("List recent autonomy runs")
			.action(async (limit?: string) => {
				const { autonomyRunsHandler } = await import("./cli/handlers/autonomy.js");
				await autonomyRunsHandler(limit);
				process.exit(0);
			});

		autonomyCmd
			.command("flows [limit]")
			.description("List recent autonomy flows")
			.action(async (limit?: string) => {
				const { autonomyFlowsHandler } = await import("./cli/handlers/autonomy.js");
				await autonomyFlowsHandler(limit);
				process.exit(0);
			});

		const flowCmd = autonomyCmd
			.command("flow <flowId>")
			.description("Inspect a single autonomy flow")
			.action(async (flowId: string) => {
				const { autonomyFlowHandler } = await import("./cli/handlers/autonomy.js");
				await autonomyFlowHandler(flowId);
				process.exit(0);
			});

		flowCmd
			.command("cancel <flowId>")
			.description("Cancel a queued, waiting, or running autonomy flow")
			.action(async (flowId: string) => {
				const { autonomyFlowCancelHandler } = await import("./cli/handlers/autonomy.js");
				await autonomyFlowCancelHandler(flowId);
				process.exit(0);
			});

		flowCmd
			.command("resume <flowId>")
			.description("Resume a waiting autonomy flow")
			.action(async (flowId: string) => {
				const { autonomyFlowResumeHandler } = await import("./cli/handlers/autonomy.js");
				await autonomyFlowResumeHandler(flowId);
				process.exit(0);
			});
	}

	// Remote Control command — connect local environment to claude.ai/code.
	// The actual command is intercepted by the fast-path in cli.tsx before
	// Commander.js runs, so this registration exists only for help output.
	// Always hidden: isBridgeEnabled() at this point (before enableConfigs)
	// would throw inside isClaudeAISubscriber → getGlobalConfig and return
	// false via the try/catch — but not before paying ~65ms of side effects
	// (25ms settings Zod parse + 40ms sync `security` keychain subprocess).
	// The dynamic visibility never worked; the command was always hidden.
	if (feature("BRIDGE_MODE")) {
		program
			.command("remote-control", { hidden: true })
			.alias("rc")
			.description(
				"Connect your local environment for remote-control sessions via claude.ai/code",
			)
			.action(async () => {
				// Unreachable — cli.tsx fast-path handles this command before main.tsx loads.
				// If somehow reached, delegate to bridgeMain.
				const { bridgeMain } = await import("./bridge/bridgeMain.js");
				await bridgeMain(process.argv.slice(3));
			});
	}

	if (feature("KAIROS")) {
		program
			.command("assistant [sessionId]")
			.description(
				"Attach the REPL as a client to a running bridge session. Discovers sessions via API if no sessionId given.",
			)
			.action(() => {
				// Argv rewriting above should have consumed `assistant [id]`
				// before commander runs. Reaching here means a root flag came first
				// (e.g. `--debug assistant`) and the position-0 predicate
				// didn't match. Print usage like the ssh stub does.
				process.stderr.write(
					"Usage: claude assistant [sessionId]\n\n" +
						"Attach the REPL as a viewer client to a running bridge session.\n" +
						"Omit sessionId to discover and pick from available sessions.\n",
				);
				process.exit(1);
			});
	}

  // Doctor command - check installation health
  program
    .command('doctor')
    .description(
      'Check the health of your Claude Code auto-updater. Note: The workspace trust dialog is skipped and stdio servers from .mcp.json are spawned for health checks. Only use this command in directories you trust.',
    )
    .action(async () => {
      const [{ doctorHandler }, { createRoot }] = await Promise.all([
        import('./cli/handlers/util.js'),
        import('@anthropic/ink'),
      ])
      const root = await createRoot(getBaseRenderOptions(false))
      await doctorHandler(root)
    })


	// claude up — run the project's CLAUDE.md "# claude up" setup instructions.
	if (process.env.USER_TYPE === "ant") {
		program
			.command("up")
			.description(
				'[ANT-ONLY] Initialize or upgrade the local dev environment using the "# claude up" section of the nearest CLAUDE.md',
			)
			.action(async () => {
				const { up } = await import("src/cli/up.js");
				await up();
			});
	}

	// claude rollback (ant-only)
	// Rolls back to previous releases
	if (process.env.USER_TYPE === "ant") {
		program
			.command("rollback [target]")
			.description(
				"[ANT-ONLY] Roll back to a previous release\n\nExamples:\n  claude rollback                                    Go 1 version back from current\n  claude rollback 3                                  Go 3 versions back from current\n  claude rollback 2.0.73-dev.20251217.t190658        Roll back to a specific version",
			)
			.option("-l, --list", "List recent published versions with ages")
			.option(
				"--dry-run",
				"Show what would be installed without installing",
			)
			.option(
				"--safe",
				"Roll back to the server-pinned safe version (set by oncall during incidents)",
			)
			.action(
				async (
					target?: string,
					options?: {
						list?: boolean;
						dryRun?: boolean;
						safe?: boolean;
					},
				) => {
					const { rollback } = await import("src/cli/rollback.js");
					await rollback(target, options);
				},
			);
	}

	// claude install
	program
		.command("install [target]")
		.description(
			"Install Claude Code native build. Use [target] to specify version (stable, latest, or specific version)",
		)
		.option("--force", "Force installation even if already installed")
		.action(
			async (
				target: string | undefined,
				options: { force?: boolean },
			) => {
				const { installHandler } =
					await import("./cli/handlers/util.js");
				await installHandler(target, options);
			},
		);

	// claude update — update ccb to the latest version via npm or bun
	program
		.command("update")
		.description("Update claude-code-best (ccb) to the latest version")
		.action(async () => {
			const { updateCCB } = await import("./cli/updateCCB.js");
			await updateCCB();
		});

	// ant-only commands
	if (process.env.USER_TYPE === "ant") {
		const validateLogId = (value: string) => {
			const maybeSessionId = validateUuid(value);
			if (maybeSessionId) return maybeSessionId;
			return Number(value);
		};
		// claude log
		program
			.command("log")
			.description("[ANT-ONLY] Manage conversation logs.")
			.argument(
				"[number|sessionId]",
				"A number (0, 1, 2, etc.) to display a specific log, or the sesssion ID (uuid) of a log",
				validateLogId,
			)
			.action(async (logId: string | number | undefined) => {
				const { logHandler } = await import("./cli/handlers/ant.js");
				await logHandler(logId);
			});

		// claude error
		program
			.command("error")
			.description(
				"[ANT-ONLY] View error logs. Optionally provide a number (0, -1, -2, etc.) to display a specific log.",
			)
			.argument(
				"[number]",
				"A number (0, 1, 2, etc.) to display a specific log",
				parseInt,
			)
			.action(async (number: number | undefined) => {
				const { errorHandler } = await import("./cli/handlers/ant.js");
				await errorHandler(number);
			});

		// claude export
		program
			.command("export")
			.description("[ANT-ONLY] Export a conversation to a text file.")
			.usage("<source> <outputFile>")
			.argument(
				"<source>",
				"Session ID, log index (0, 1, 2...), or path to a .json/.jsonl log file",
			)
			.argument("<outputFile>", "Output file path for the exported text")
			.addHelpText(
				"after",
				`
Examples:
  $ claude export 0 conversation.txt                Export conversation at log index 0
  $ claude export <uuid> conversation.txt           Export conversation by session ID
  $ claude export input.json output.txt             Render JSON log file to text
  $ claude export <uuid>.jsonl output.txt           Render JSONL session file to text`,
			)
			.action(async (source: string, outputFile: string) => {
				const { exportHandler } = await import("./cli/handlers/ant.js");
				await exportHandler(source, outputFile);
			});

		if (process.env.USER_TYPE === "ant") {
			const taskCmd = program
				.command("task")
				.description("[ANT-ONLY] Manage task list tasks");

			taskCmd
				.command("create <subject>")
				.description("Create a new task")
				.option("-d, --description <text>", "Task description")
				.option(
					"-l, --list <id>",
					'Task list ID (defaults to "tasklist")',
				)
				.action(
					async (
						subject: string,
						opts: { description?: string; list?: string },
					) => {
						const { taskCreateHandler } =
							await import("./cli/handlers/ant.js");
						await taskCreateHandler(subject, opts);
					},
				);

			taskCmd
				.command("list")
				.description("List all tasks")
				.option(
					"-l, --list <id>",
					'Task list ID (defaults to "tasklist")',
				)
				.option("--pending", "Show only pending tasks")
				.option("--json", "Output as JSON")
				.action(
					async (opts: {
						list?: string;
						pending?: boolean;
						json?: boolean;
					}) => {
						const { taskListHandler } =
							await import("./cli/handlers/ant.js");
						await taskListHandler(opts);
					},
				);

			taskCmd
				.command("get <id>")
				.description("Get details of a task")
				.option(
					"-l, --list <id>",
					'Task list ID (defaults to "tasklist")',
				)
				.action(async (id: string, opts: { list?: string }) => {
					const { taskGetHandler } =
						await import("./cli/handlers/ant.js");
					await taskGetHandler(id, opts);
				});

			taskCmd
				.command("update <id>")
				.description("Update a task")
				.option(
					"-l, --list <id>",
					'Task list ID (defaults to "tasklist")',
				)
				.option(
					"-s, --status <status>",
					`Set status (${TASK_STATUSES.join(", ")})`,
				)
				.option("--subject <text>", "Update subject")
				.option("-d, --description <text>", "Update description")
				.option("--owner <agentId>", "Set owner")
				.option("--clear-owner", "Clear owner")
				.action(
					async (
						id: string,
						opts: {
							list?: string;
							status?: string;
							subject?: string;
							description?: string;
							owner?: string;
							clearOwner?: boolean;
						},
					) => {
						const { taskUpdateHandler } =
							await import("./cli/handlers/ant.js");
						await taskUpdateHandler(id, opts);
					},
				);

			taskCmd
				.command("dir")
				.description("Show the tasks directory path")
				.option(
					"-l, --list <id>",
					'Task list ID (defaults to "tasklist")',
				)
				.action(async (opts: { list?: string }) => {
					const { taskDirHandler } =
						await import("./cli/handlers/ant.js");
					await taskDirHandler(opts);
				});
		}

		// claude completion <shell>
		program
			.command("completion <shell>", { hidden: true })
			.description(
				"Generate shell completion script (bash, zsh, or fish)",
			)
			.option(
				"--output <file>",
				"Write completion script directly to a file instead of stdout",
			)
			.action(async (shell: string, opts: { output?: string }) => {
				const { completionHandler } =
					await import("./cli/handlers/ant.js");
				await completionHandler(shell, opts, program);
			});
	}

	profileCheckpoint("run_before_parse");
	await program.parseAsync(process.argv);
	profileCheckpoint("run_after_parse");

	// Record final checkpoint for total_time calculation
	profileCheckpoint("main_after_run");

	// Log startup perf to Statsig (sampled) and output detailed report if enabled
	profileReport();

	return program;
}

async function logTenguInit({
	hasInitialPrompt,
	hasStdin,
	verbose,
	debug,
	debugToStderr,
	print,
	outputFormat,
	inputFormat,
	numAllowedTools,
	numDisallowedTools,
	mcpClientCount,
	worktreeEnabled,
	skipWebFetchPreflight,
	githubActionInputs,
	dangerouslySkipPermissionsPassed,
	permissionMode,
	modeIsBypass,
	allowDangerouslySkipPermissionsPassed,
	systemPromptFlag,
	appendSystemPromptFlag,
	thinkingConfig,
	assistantActivationPath,
}: {
	hasInitialPrompt: boolean;
	hasStdin: boolean;
	verbose: boolean;
	debug: boolean;
	debugToStderr: boolean;
	print: boolean;
	outputFormat: string;
	inputFormat: string;
	numAllowedTools: number;
	numDisallowedTools: number;
	mcpClientCount: number;
	worktreeEnabled: boolean;
	skipWebFetchPreflight: boolean | undefined;
	githubActionInputs: string | undefined;
	dangerouslySkipPermissionsPassed: boolean;
	permissionMode: string;
	modeIsBypass: boolean;
	allowDangerouslySkipPermissionsPassed: boolean;
	systemPromptFlag: "file" | "flag" | undefined;
	appendSystemPromptFlag: "file" | "flag" | undefined;
	thinkingConfig: ThinkingConfig;
	assistantActivationPath: string | undefined;
}): Promise<void> {
	try {
		logEvent("tengu_init", {
			entrypoint:
				"claude" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
			hasInitialPrompt,
			hasStdin,
			verbose,
			debug,
			debugToStderr,
			print,
			outputFormat:
				outputFormat as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
			inputFormat:
				inputFormat as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
			numAllowedTools,
			numDisallowedTools,
			mcpClientCount,
			worktree: worktreeEnabled,
			skipWebFetchPreflight,
			...(githubActionInputs && {
				githubActionInputs:
					githubActionInputs as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
			}),
			dangerouslySkipPermissionsPassed,
			permissionMode:
				permissionMode as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
			modeIsBypass,
			inProtectedNamespace: isInProtectedNamespace(),
			allowDangerouslySkipPermissionsPassed,
			thinkingType:
				thinkingConfig.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
			...(systemPromptFlag && {
				systemPromptFlag:
					systemPromptFlag as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
			}),
			...(appendSystemPromptFlag && {
				appendSystemPromptFlag:
					appendSystemPromptFlag as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
			}),
			is_simple: isBareMode() || undefined,
			is_coordinator:
				feature("COORDINATOR_MODE") &&
				coordinatorModeModule?.isCoordinatorMode()
					? true
					: undefined,
			...(assistantActivationPath && {
				assistantActivationPath:
					assistantActivationPath as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
			}),
			autoUpdatesChannel: (getInitialSettings().autoUpdatesChannel ??
				"latest") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
			...(process.env.USER_TYPE === "ant"
				? (() => {
						const cwd = getCwd();
						const gitRoot = findGitRoot(cwd);
						const rp = gitRoot
							? relative(gitRoot, cwd) || "."
							: undefined;
						return rp
							? {
									relativeProjectPath:
										rp as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
								}
							: {};
					})()
				: {}),
		});
	} catch (error) {
		logError(error);
	}
}

function maybeActivateProactive(options: unknown): void {
	if (
		(feature("PROACTIVE") || feature("KAIROS")) &&
		((options as { proactive?: boolean }).proactive ||
			isEnvTruthy(process.env.CLAUDE_CODE_PROACTIVE))
	) {
		// eslint-disable-next-line @typescript-eslint/no-require-imports
		const proactiveModule = require("./proactive/index.js");
		if (!proactiveModule.isProactiveActive()) {
			proactiveModule.activateProactive("command");
		}
	}
}

function maybeActivateBrief(options: unknown): void {
	if (!(feature("KAIROS") || feature("KAIROS_BRIEF"))) return;
	const briefFlag = (options as { brief?: boolean }).brief;
	const briefEnv = isEnvTruthy(process.env.CLAUDE_CODE_BRIEF);
	if (!briefFlag && !briefEnv) return;
	// --brief / CLAUDE_CODE_BRIEF are explicit opt-ins: check entitlement,
	// then set userMsgOptIn to activate the tool + prompt section. The env
	// var also grants entitlement (isBriefEntitled() reads it), so setting
	// CLAUDE_CODE_BRIEF=1 alone force-enables for dev/testing — no GB gate
	// needed. initialIsBriefOnly reads getUserMsgOptIn() directly.
	// Conditional require: static import would leak the tool name string
	// into external builds via BriefTool.ts → prompt.ts.
	/* eslint-disable @typescript-eslint/no-require-imports */
	const { isBriefEntitled } =
		require("@claude-code-best/builtin-tools/tools/BriefTool/BriefTool.js") as typeof import("@claude-code-best/builtin-tools/tools/BriefTool/BriefTool.js");
	/* eslint-enable @typescript-eslint/no-require-imports */
	const entitled = isBriefEntitled();
	if (entitled) {
		setUserMsgOptIn(true);
	}
	// Fire unconditionally once intent is seen: enabled=false captures the
	// "user tried but was gated" failure mode in Datadog.
	logEvent("tengu_brief_mode_enabled", {
		enabled: entitled,
		gated: !entitled,
		source: (briefEnv
			? "env"
			: "flag") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
	});
}

function resetCursor() {
	const terminal = process.stderr.isTTY
		? process.stderr
		: process.stdout.isTTY
			? process.stdout
			: undefined;
	terminal?.write(SHOW_CURSOR);
}

type TeammateOptions = {
	agentId?: string;
	agentName?: string;
	teamName?: string;
	agentColor?: string;
	planModeRequired?: boolean;
	parentSessionId?: string;
	teammateMode?: "auto" | "tmux" | "in-process";
	agentType?: string;
};

function extractTeammateOptions(options: unknown): TeammateOptions {
	if (typeof options !== "object" || options === null) {
		return {};
	}
	const opts = options as Record<string, unknown>;
	const teammateMode = opts.teammateMode;
	return {
		agentId: typeof opts.agentId === "string" ? opts.agentId : undefined,
		agentName:
			typeof opts.agentName === "string" ? opts.agentName : undefined,
		teamName: typeof opts.teamName === "string" ? opts.teamName : undefined,
		agentColor:
			typeof opts.agentColor === "string" ? opts.agentColor : undefined,
		planModeRequired:
			typeof opts.planModeRequired === "boolean"
				? opts.planModeRequired
				: undefined,
		parentSessionId:
			typeof opts.parentSessionId === "string"
				? opts.parentSessionId
				: undefined,
		teammateMode:
			teammateMode === "auto" ||
			teammateMode === "tmux" ||
			teammateMode === "in-process"
				? teammateMode
				: undefined,
		agentType:
			typeof opts.agentType === "string" ? opts.agentType : undefined,
	};
}