@sayknow-cli/coding-agent 0.3.4 → 0.3.6

package/src/cli/update-cli.ts

@@ -14,6 +14,8 @@ import { theme } from "../modes/theme/theme";
 
 const RELEASE_REPO = "jaybeyond/Sayknow_CLI";
 const PACKAGE = "@sayknow-cli/coding-agent";
+const NPM_WRAPPER_PACKAGE = "sayknow-cli";
+const NPM_MANAGED_PACKAGES = [NPM_WRAPPER_PACKAGE, PACKAGE] as const;
 
 interface ReleaseInfo {
 	tag: string;
@@ -27,6 +29,23 @@ export interface InstalledVersionVerification {
 	path?: string;
 	smokeTestFailed?: boolean;
 	smokeTestOutput?: string;
+	cleanupWarning?: string;
+}
+
+export interface PackageManagerUpdateResult {
+	exitCode: number | null;
+	text: () => string;
+}
+
+export type PackageManagerUpdateRunner = (expectedVersion: string) => Promise<PackageManagerUpdateResult>;
+
+export interface PackageManagerUpdateOptions {
+	managerName: string;
+	expectedVersion: string;
+	runInstall: PackageManagerUpdateRunner;
+	verifyInstalledRuntime: (expectedVersion: string) => Promise<InstalledVersionVerification>;
+	printVerificationResult?: (expectedVersion: string) => Promise<void>;
+	printRecoveredVerification?: (expectedVersion: string) => void;
 }
 
 /** Paths and verifier used while replacing a downloaded binary update. */
@@ -102,23 +121,76 @@ function isPathInDirectory(filePath: string, directoryPath: string): boolean {
 	return isPathInDirectoryLexical(resolvedFile, dirReal);
 }
 
-type UpdateTarget = { method: "bun" } | { method: "binary"; path: string };
+type PackageManagerTarget = { manager: "npm"; packageName: string };
+type UpdateTarget = { method: "bun" } | { method: "npm"; packageName: string } | { method: "binary"; path: string };
+
+type PathPlatform = NodeJS.Platform;
+type PackageExists = (packageName: string, packageRoot: string) => boolean;
+
+function pathApiForPlatform(platform: PathPlatform): typeof path.posix | typeof path.win32 {
+	return platform === "win32" ? path.win32 : path.posix;
+}
+
+function defaultPackageExists(_packageName: string, packageRoot: string): boolean {
+	return fs.existsSync(path.join(packageRoot, "package.json"));
+}
+
+function npmPackageRootForBinPath(binPath: string, packageName: string, platform: PathPlatform): string {
+	const pathApi = pathApiForPlatform(platform);
+	const segments = packageName.split("/");
+	return pathApi.join(pathApi.dirname(binPath), "node_modules", ...segments);
+}
+
+function resolveNpmManagedTarget(
+	ompPath: string,
+	platform: PathPlatform = process.platform,
+	packageExists: PackageExists = defaultPackageExists,
+): PackageManagerTarget | undefined {
+	if (platform !== "win32") return undefined;
+	const pathApi = pathApiForPlatform(platform);
+	const extension = pathApi.extname(ompPath).toLowerCase();
+	if (extension !== ".cmd" && extension !== ".ps1") return undefined;
+	const basename = pathApi.basename(ompPath, extension).toLowerCase();
+	if (basename !== APP_NAME.toLowerCase()) return undefined;
 
-function resolveUpdateMethod(ompPath: string, bunBinDir: string | undefined): "bun" | "binary" {
+	for (const packageName of NPM_MANAGED_PACKAGES) {
+		const packageRoot = npmPackageRootForBinPath(ompPath, packageName, platform);
+		if (packageExists(packageName, packageRoot)) return { manager: "npm", packageName };
+	}
+	return undefined;
+}
+
+function resolveUpdateMethod(ompPath: string, bunBinDir: string | undefined): "bun" | "npm" | "binary" {
+	if (resolveNpmManagedTarget(ompPath)) return "npm";
 	if (!bunBinDir) return "binary";
 	return isPathInDirectory(ompPath, bunBinDir) ? "bun" : "binary";
 }
 
-export function resolveUpdateMethodForTest(ompPath: string, bunBinDir: string | undefined): "bun" | "binary" {
+export function resolveUpdateMethodForTest(ompPath: string, bunBinDir: string | undefined): "bun" | "npm" | "binary" {
 	return resolveUpdateMethod(ompPath, bunBinDir);
 }
+
+export function resolveNpmManagedTargetForTest(
+	ompPath: string,
+	platform: PathPlatform,
+	packageExists: PackageExists,
+): PackageManagerTarget | undefined {
+	return resolveNpmManagedTarget(ompPath, platform, packageExists);
+}
 async function resolveUpdateTarget(): Promise<UpdateTarget> {
 	const bunBinDir = await getBunGlobalBinDir();
 	const ompPath = resolveSkcPath();
 
 	if (ompPath) {
+		const npmTarget = resolveNpmManagedTarget(ompPath);
+		if (npmTarget) return { method: "npm", packageName: npmTarget.packageName };
 		const method = resolveUpdateMethod(ompPath, bunBinDir);
 		if (method === "bun") return { method };
+		if (method === "npm") {
+			throw new Error(
+				formatUnsupportedTargetMessage(`Could not resolve npm package root for ${APP_NAME} shim ${ompPath}`),
+			);
+		}
 		return { method, path: ompPath };
 	}
 
@@ -262,6 +334,11 @@ function printVerifiedVersion(expectedVersion: string): void {
 	console.log(chalk.green(`\n${theme.status.success} Updated to ${expectedVersion}`));
 }
 
+function printSuccessfulVerification(expectedVersion: string): void {
+	printVerifiedVersion(expectedVersion);
+	printRestartGuidance();
+}
+
 function formatBinaryInstallInstruction(platform: NodeJS.Platform = process.platform): string {
 	if (platform === "win32") {
 		return `For a supported binary install, reinstall with PowerShell: irm https://raw.githubusercontent.com/${RELEASE_REPO}/main/scripts/install.ps1 | iex`;
@@ -351,8 +428,7 @@ export function formatVerificationFailureForTest(
 async function printVerification(expectedVersion: string): Promise<void> {
 	const result = await verifyInstalledRuntime(expectedVersion);
 	if (result.ok) {
-		printVerifiedVersion(expectedVersion);
-		printRestartGuidance();
+		printSuccessfulVerification(expectedVersion);
 		return;
 	}
 	console.log(chalk.yellow(`\nWarning: ${formatVerificationFailure(result, expectedVersion)}`));
@@ -367,6 +443,19 @@ async function unlinkIfExists(filePath: string): Promise<void> {
 	}
 }
 
+function formatBackupCleanupWarning(backupPath: string, err: unknown): string {
+	return `Installed update, but could not remove backup file ${backupPath}: ${err}. You can delete it manually after closing shells or antivirus processes that may still hold it.`;
+}
+
+async function cleanupVerifiedBackup(backupPath: string): Promise<string | undefined> {
+	try {
+		await unlinkIfExists(backupPath);
+		return undefined;
+	} catch (err) {
+		return formatBackupCleanupWarning(backupPath, err);
+	}
+}
+
 /**
  * Atomically replace the installed binary and roll back if version verification fails.
  */
@@ -386,8 +475,8 @@ export async function replaceBinaryForUpdate(options: BinaryReplacementOptions):
 		}
 
 		backupReady = false;
-		await unlinkIfExists(options.backupPath);
-		return verification;
+		const cleanupWarning = await cleanupVerifiedBackup(options.backupPath);
+		return cleanupWarning ? { ...verification, cleanupWarning } : verification;
 	} catch (err) {
 		if (backupReady) {
 			await unlinkIfExists(options.targetPath);
@@ -398,17 +487,67 @@ export async function replaceBinaryForUpdate(options: BinaryReplacementOptions):
 	}
 }
 
+function formatPackageManagerInstallFailure(
+	managerName: string,
+	result: PackageManagerUpdateResult,
+	verification: InstalledVersionVerification,
+	expectedVersion: string,
+): string {
+	const output = normalizeVerificationOutput(result.text());
+	const outputSuffix = output ? `: ${output}` : "";
+	return `${managerName} install failed with exit code ${result.exitCode ?? "unknown"}${outputSuffix}. ${formatVerificationFailure(verification, expectedVersion)}`;
+}
+
+export async function runPackageManagerUpdateForTest(
+	options: PackageManagerUpdateOptions,
+): Promise<InstalledVersionVerification> {
+	return updateViaPackageManager(options);
+}
+
+async function updateViaPackageManager(options: PackageManagerUpdateOptions): Promise<InstalledVersionVerification> {
+	const result = await options.runInstall(options.expectedVersion);
+	if (result.exitCode === 0) {
+		await (options.printVerificationResult ?? printVerification)(options.expectedVersion);
+		return await options.verifyInstalledRuntime(options.expectedVersion);
+	}
+
+	const verification = await options.verifyInstalledRuntime(options.expectedVersion);
+	if (verification.ok) {
+		console.warn(
+			chalk.yellow(
+				`${options.managerName} exited with ${result.exitCode ?? "unknown"}, but ${APP_NAME} now verifies as ${options.expectedVersion}. Treating the update as installed.`,
+			),
+		);
+		(options.printRecoveredVerification ?? printSuccessfulVerification)(options.expectedVersion);
+		return verification;
+	}
+
+	throw new Error(
+		formatPackageManagerInstallFailure(options.managerName, result, verification, options.expectedVersion),
+	);
+}
+
 /**
  * Update via bun package manager.
  */
 async function updateViaBun(expectedVersion: string): Promise<void> {
 	console.log(chalk.dim("Updating via bun..."));
-	const result = await $`bun install -g ${PACKAGE}@${expectedVersion}`.nothrow();
-	if (result.exitCode !== 0) {
-		throw new Error(`bun install failed with exit code ${result.exitCode}`);
-	}
+	await updateViaPackageManager({
+		managerName: "bun",
+		expectedVersion,
+		runInstall: async version => await $`bun install -g ${PACKAGE}@${version}`.nothrow(),
+		verifyInstalledRuntime,
+	});
+}
 
-	await printVerification(expectedVersion);
+async function updateViaNpm(packageName: string, expectedVersion: string): Promise<void> {
+	console.log(chalk.dim(`Updating npm-managed install via npm (${packageName})...`));
+	await updateViaPackageManager({
+		managerName: "npm",
+		expectedVersion,
+		runInstall: async version => await $`npm install -g ${packageName}@${version}`.nothrow(),
+		verifyInstalledRuntime,
+	});
 }
 
 /**
@@ -430,7 +569,7 @@ async function updateViaBinaryAt(targetPath: string, expectedVersion: string): P
 	await pipeline(response.body, fileStream);
 
 	console.log(chalk.dim("Installing update..."));
-	await replaceBinaryForUpdate({
+	const verification = await replaceBinaryForUpdate({
 		targetPath,
 		tempPath,
 		backupPath,
@@ -438,6 +577,7 @@ async function updateViaBinaryAt(targetPath: string, expectedVersion: string): P
 		verifyInstalledVersion: verifyInstalledRuntime,
 	});
 	printVerifiedVersion(expectedVersion);
+	if (verification.cleanupWarning) console.warn(chalk.yellow(verification.cleanupWarning));
 	printRestartGuidance();
 }
 
@@ -479,6 +619,8 @@ export async function runUpdateCommand(opts: { force: boolean; check: boolean })
 		const target = await resolveUpdateTarget();
 		if (target.method === "bun") {
 			await updateViaBun(release.version);
+		} else if (target.method === "npm") {
+			await updateViaNpm(target.packageName, release.version);
 		} else {
 			await updateViaBinaryAt(target.path, release.version);
 		}

package/src/cli.ts

@@ -38,6 +38,7 @@ export const commands: CommandEntry[] = [
 	{ name: "notify", load: () => import("./commands/notify").then(m => m.default) },
 	{ name: "daemon", load: () => import("./commands/daemon").then(m => m.default) },
 	{ name: "web-search", aliases: ["q"], load: () => import("./commands/web-search").then(m => m.default) },
+	{ name: "local-provider", load: () => import("./commands/local-provider").then(m => m.default) },
 	{ name: "mcp-serve", load: () => import("./commands/mcp-serve").then(m => m.default) },
 	{ name: "mcp", load: () => import("./commands/mcp").then(m => m.default) },
 	{
@@ -79,6 +80,19 @@ async function installRuntimeGlobals(): Promise<void> {
 	delete process.env.MallocStackLoggingNoCompact;
 }
 
+function isNotifyDaemonInternalFastPath(argv: string[]): boolean {
+	return argv[0] === "notify" && argv[1] === "daemon-internal";
+}
+
+async function runNotifyDaemonInternalFastPath(argv: string[]): Promise<void> {
+	const { parseNotifyArgs, runNotifyCommand } = await import("./cli/notify-cli");
+	const cmd = parseNotifyArgs(argv);
+	if (cmd?.action !== "daemon-internal") {
+		throw new Error("invalid notify daemon-internal fast path");
+	}
+	await runNotifyCommand(cmd);
+}
+
 function hasRootFastFlag(argv: string[], flags: readonly string[]): boolean {
 	for (const arg of argv) {
 		if (isSubcommand(arg)) return false;
@@ -208,6 +222,10 @@ async function runSmokeTest(): Promise<void> {
 
 /** Run the CLI with the given argv (no `process.argv` prefix). */
 export async function runCli(argv: string[]): Promise<void> {
+	if (isNotifyDaemonInternalFastPath(argv)) {
+		await runNotifyDaemonInternalFastPath(argv);
+		return;
+	}
 	if (argv[0] === "--smoke-test") {
 		await runSmokeTest();
 		return;

package/src/commands/launch.ts

@@ -2,6 +2,8 @@
  * Root command for the coding agent CLI.
  */
 
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
 import { THINKING_EFFORTS } from "@sayknow-cli/ai";
 import { APP_NAME, setProjectDir } from "@sayknow-cli/utils";
 import { Args, Command, Flags } from "@sayknow-cli/utils/cli";
@@ -10,6 +12,43 @@ import { runRootCommand } from "../main";
 import { prepareAcpTerminalAuthArgs } from "../modes/acp/terminal-auth";
 import { launchDefaultTmuxIfNeeded } from "../skc-runtime/launch-tmux";
 import { prepareLaunchWorktree } from "../skc-runtime/launch-worktree";
+import {
+	SKC_COORDINATOR_SESSION_ID_ENV,
+	SKC_COORDINATOR_SESSION_STATE_FILE_ENV,
+} from "../skc-runtime/session-state-sidecar";
+
+async function persistCoordinatorLaunchFailure(error: unknown, cwd: string): Promise<void> {
+	const stateFile = process.env[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim();
+	if (!stateFile) return;
+	const message = error instanceof Error ? error.message : String(error);
+	const code = message.split(":", 1)[0] || "launch_failed";
+	const now = new Date().toISOString();
+	const payload = {
+		schema_version: 1,
+		session_id: process.env[SKC_COORDINATOR_SESSION_ID_ENV]?.trim() || null,
+		state: "errored",
+		ready_for_input: false,
+		updated_at: now,
+		current_turn_id: null,
+		last_turn_id: null,
+		live: false,
+		reason: code,
+		source: "agent_session_event",
+		event: "launch_error",
+		cwd,
+		session_file: null,
+		final_response: {
+			text: message,
+			format: "markdown",
+			source: "launch_error",
+			artifact_path: null,
+			truncated: false,
+		},
+		error: { code, message, recoverable: true },
+	};
+	await fs.mkdir(path.dirname(stateFile), { recursive: true });
+	await Bun.write(stateFile, `${JSON.stringify(payload, null, 2)}\n`);
+}
 
 export default class Index extends Command {
 	static description = "Sayknow-CLI — an AI coding assistant";
@@ -157,7 +196,13 @@ export default class Index extends Command {
 			return;
 		}
 
-		const launch = prepareLaunchWorktree(process.cwd(), args);
+		let launch: ReturnType<typeof prepareLaunchWorktree>;
+		try {
+			launch = prepareLaunchWorktree(process.cwd(), args);
+		} catch (error) {
+			await persistCoordinatorLaunchFailure(error, process.cwd());
+			throw error;
+		}
 		if (launch.worktree.enabled) {
 			process.chdir(launch.cwd);
 			setProjectDir(launch.cwd);

package/src/commands/local-provider.ts

@@ -0,0 +1,62 @@
+/**
+ * Test configured local OpenAI-compatible providers.
+ */
+import { Args, Command, Flags } from "@sayknow-cli/utils/cli";
+import {
+	runLocalProviderDiscoverCommand,
+	runLocalProviderSmokeCommand,
+	runLocalProviderStatusCommand,
+} from "../cli/local-provider-smoke";
+
+export const LOCAL_PROVIDER_ACTIONS = ["status", "diagnose", "discover", "models", "smoke"] as const;
+export const LOCAL_PROVIDER_DEFAULT_ACTION = "status";
+
+export default class LocalProvider extends Command {
+	static description = "Diagnose configured local OpenAI-compatible providers";
+
+	static args = {
+		action: Args.string({ description: "Action", required: false, options: LOCAL_PROVIDER_ACTIONS }),
+	};
+
+	static flags = {
+		model: Flags.string({ description: "Model id to use for smoke (otherwise uses the first /models id)" }),
+		"models-path": Flags.string({ description: "Override models config path" }),
+		"timeout-ms": Flags.integer({ description: "Request timeout in milliseconds" }),
+		smoke: Flags.boolean({ description: "Run optional streaming chat smoke during status/diagnose" }),
+		json: Flags.boolean({ description: "Output JSON" }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(LocalProvider);
+		const action = args.action ?? LOCAL_PROVIDER_DEFAULT_ACTION;
+		if (action === "status" || action === "diagnose") {
+			await runLocalProviderStatusCommand({
+				model: flags.model,
+				modelsPath: flags["models-path"],
+				timeoutMs: flags["timeout-ms"],
+				smoke: flags.smoke,
+				json: flags.json,
+			});
+			return;
+		}
+		if (action === "discover" || action === "models") {
+			await runLocalProviderDiscoverCommand({
+				modelsPath: flags["models-path"],
+				timeoutMs: flags["timeout-ms"],
+				json: flags.json,
+			});
+			return;
+		}
+		if (action === "smoke") {
+			await runLocalProviderSmokeCommand({
+				model: flags.model,
+				modelsPath: flags["models-path"],
+				timeoutMs: flags["timeout-ms"],
+				json: flags.json,
+			});
+			return;
+		}
+		process.stderr.write(`Unsupported local-provider action: ${action}\n`);
+		process.exitCode = 1;
+	}
+}

package/src/commands/notify.ts

@@ -55,7 +55,7 @@ export default class Notify extends Command {
 			redact: Boolean(flags.redact),
 		};
 
-		await initTheme();
+		if (action !== "daemon-internal") await initTheme();
 		await runNotifyCommand(cmd);
 	}
 }

package/src/config/model-registry.ts

@@ -243,6 +243,7 @@ interface ProviderValidationConfig {
 	requestTransform?: ModelRequestTransform;
 	disableStrictTools?: boolean;
 	cacheRetention?: CacheRetention;
+	openaiCompat?: { baseUrl: string; apiKey?: string; apiKeyEnv?: string };
 	modelOverrides?: Record<string, unknown>;
 	models: ProviderValidationModel[];
 }
@@ -271,11 +272,12 @@ function validateProviderConfiguration(
 				!config.disableStrictTools &&
 				!config.requestTransform &&
 				!config.cacheRetention &&
+				!config.openaiCompat &&
 				!hasModelOverrides &&
 				!config.discovery
 			) {
 				throw new Error(
-					`Provider ${providerName}: must specify "baseUrl", "headers", "apiKey", "compat", "requestTransform", "cacheRetention", "disableStrictTools", "modelOverrides", "discovery", or "models"`,
+					`Provider ${providerName}: must specify "baseUrl", "headers", "apiKey", "compat", "requestTransform", "cacheRetention", "disableStrictTools", "modelOverrides", "discovery", "openaiCompat", or "models"`,
 				);
 			}
 		}
@@ -389,6 +391,7 @@ export const ModelsConfigFile = new ConfigFile<ModelsConfig>("models", ModelsCon
 					requestTransform: providerConfig.requestTransform,
 					disableStrictTools: providerConfig.disableStrictTools,
 					cacheRetention: providerConfig.cacheRetention,
+					openaiCompat: providerConfig.openaiCompat,
 					modelOverrides: providerConfig.modelOverrides,
 					models: (providerConfig.models ?? []) as ProviderValidationModel[],
 				},
@@ -436,6 +439,18 @@ function resolveProviderBaseUrlFromEnv(provider: string): string | undefined {
 	return $pickenv(...getProviderBaseUrlEnvKeys(provider));
 }
 
+function normalizeLocalOpenAICompatBaseUrl(baseUrl: string): string {
+	try {
+		const parsed = new URL(baseUrl);
+		const trimmedPath = parsed.pathname.replace(/\/+$/g, "");
+		parsed.pathname = trimmedPath.endsWith("/v1") ? trimmedPath || "/v1" : `${trimmedPath}/v1`;
+		return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+	} catch {
+		const trimmed = baseUrl.replace(/\/+$/g, "");
+		return trimmed.endsWith("/v1") ? trimmed : `${trimmed}/v1`;
+	}
+}
+
 /**
  * Merge a freshly discovered model with the matching bundled/configured entry
  * (or a runtime provider override when no bundled entry exists).
@@ -1409,6 +1424,45 @@ export class ModelRegistry {
 		for (const [providerName, providerConfig] of providerEntries) {
 			if (providerConfig.webSearch) this.#providerWebSearchModes.set(providerName, providerConfig.webSearch);
 			const providerApiKeyConfig = providerConfig.apiKey ?? resolveApiKeyEnvConfig(providerConfig.apiKeyEnv);
+			const localOpenAICompat = providerConfig.openaiCompat;
+			const localOpenAICompatApiKeyConfig = localOpenAICompat
+				? (localOpenAICompat.apiKey ?? resolveApiKeyEnvConfig(localOpenAICompat.apiKeyEnv))
+				: undefined;
+			if (localOpenAICompat) {
+				const localOpenAICompatBaseUrl = normalizeLocalOpenAICompatBaseUrl(localOpenAICompat.baseUrl);
+				const localCompatResolvedKey = localOpenAICompat.apiKeyEnv
+					? resolveApiKeyEnvConfig(localOpenAICompat.apiKeyEnv)
+					: localOpenAICompat.apiKey
+						? resolveApiKeyConfig(localOpenAICompat.apiKey)
+						: undefined;
+				overrides.set(providerName, {
+					baseUrl: localOpenAICompatBaseUrl,
+					apiKey: localOpenAICompatApiKeyConfig,
+					compat: {
+						supportsStore: false,
+						supportsDeveloperRole: false,
+						supportsReasoningEffort: false,
+					},
+				});
+				discoverableProviders.push({
+					provider: providerName,
+					api: "openai-completions",
+					baseUrl: localOpenAICompatBaseUrl,
+					compat: {
+						supportsStore: false,
+						supportsDeveloperRole: false,
+						supportsReasoningEffort: false,
+					},
+					discovery: { type: "openai-models-list" },
+					optional: false,
+				});
+				if (localCompatResolvedKey) {
+					this.#customProviderApiKeys.set(providerName, localCompatResolvedKey);
+					this.authStorage.setConfigApiKey(providerName, localCompatResolvedKey);
+				} else {
+					keylessProviders.add(providerName);
+				}
+			}
 			// Always set overrides when baseUrl/headers/apiKey/authHeader/compat/disableStrictTools/transport are present
 			if (
 				providerConfig.baseUrl ||

package/src/config/models-config-schema.ts

@@ -193,6 +193,14 @@ export const ProviderDiscoverySchema = z.object({
 	type: z.enum(["ollama", "llama.cpp", "lm-studio", "openai-models-list"]),
 });
 
+const LocalOpenAICompatSchema = z
+	.object({
+		baseUrl: z.string().min(1),
+		apiKey: z.string().min(1).optional(),
+		apiKeyEnv: z.string().min(1).optional(),
+	})
+	.strict();
+
 export const ProviderAuthSchema = z.enum(["apiKey", "none", "oauth"]);
 
 export type ProviderAuthMode = z.infer<typeof ProviderAuthSchema>;
@@ -237,6 +245,7 @@ const ProviderConfigSchema = z
 		 */
 		transport: z.literal("pi-native").optional(),
 		cacheRetention: CacheRetentionSchema.optional(),
+		openaiCompat: LocalOpenAICompatSchema.optional(),
 	})
 	.strict();
 

package/src/config/settings-schema.ts

@@ -275,6 +275,43 @@ export const SETTINGS_SCHEMA = {
 		validate: (value: number) => Number.isFinite(value) && value > 0,
 	},
 
+	"notifications.terminalBell": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "interaction",
+			label: "Terminal Bell",
+			description: "Emit a BEL character for local terminal notifications",
+		},
+	},
+	"notifications.bellOnComplete": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "interaction",
+			label: "Bell on Completion",
+			description: "Ring the terminal bell when an agent turn completes",
+		},
+	},
+	"notifications.bellOnApproval": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "interaction",
+			label: "Bell on Approval",
+			description: "Ring the terminal bell when a plan or approval prompt needs attention",
+		},
+	},
+	"notifications.bellOnAsk": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "interaction",
+			label: "Bell on Ask",
+			description: "Ring the terminal bell when an ask/user-input prompt needs attention",
+		},
+	},
+
 	autoResume: {
 		type: "boolean",
 		default: false,
@@ -1157,6 +1194,16 @@ export const SETTINGS_SCHEMA = {
 		default: "on",
 		ui: { tab: "interaction", label: "Completion Notification", description: "Notify when the agent completes" },
 	},
+	"completion.notifyCommand": {
+		type: "string",
+		default: "",
+		ui: {
+			tab: "interaction",
+			label: "Completion Notification Command",
+			description:
+				"Optional user-level shell command to run when an agent turn completes; receives SKC_NOTIFICATION_* environment variables.",
+		},
+	},
 
 	"ask.timeout": {
 		type: "number",

package/src/config/settings.ts

@@ -298,6 +298,17 @@ export class Settings {
 		return getDefault(path);
 	}
 
+	/**
+	 * Get a setting value from the user/global config only.
+	 *
+	 * Use for machine-local command hooks and other settings that must not be
+	 * activated by project-scoped config files.
+	 */
+	getGlobal<P extends SettingPath>(path: P): SettingValue<P> | undefined {
+		const value = getByPath(this.#global, path.split("."));
+		return value === undefined ? undefined : (value as SettingValue<P>);
+	}
+
 	/** Check whether a setting is present in loaded settings/overrides rather than coming from schema defaults. */
 	has(path: SettingPath): boolean {
 		return getByPath(this.#merged, path.split(".")) !== undefined;