@clinebot/core 0.0.28 → 0.0.29

package/src/index.ts

@@ -4,24 +4,19 @@
  * Core contracts, shared state utilities, and Node runtime services.
  */
 
-export {
-	type AgentConfig,
-	type CreateMcpToolsOptions,
-	createMcpTools,
-	createTool,
-	getClineDefaultSystemPrompt,
-	type Tool,
-	type ToolApprovalRequest,
-	type ToolApprovalResult,
-	type ToolContext,
-} from "@clinebot/agents";
-export * as LlmsModels from "@clinebot/llms/models";
-export * as LlmsProviders from "@clinebot/llms/providers";
+export * as Llms from "@clinebot/llms";
 // Shared contracts and path helpers re-exported for app consumers.
 export type {
+	AgentConfig,
+	AgentEvent,
+	AgentExtension,
+	AgentExtensionCommand,
+	AgentHooks,
 	AgentMode,
+	AgentResult,
 	BasicLogger,
 	ConnectorHookEvent,
+	emptyWorkspaceManifest,
 	HookSessionContext,
 	ITelemetryService,
 	RpcAddProviderActionRequest,
@@ -33,6 +28,12 @@ export type {
 	RpcChatStartSessionRequest,
 	RpcChatTurnResult,
 	RpcClineAccountActionRequest,
+	RpcEnterpriseAuthenticateRequest,
+	RpcEnterpriseAuthenticateResponse,
+	RpcEnterpriseStatusRequest,
+	RpcEnterpriseStatusResponse,
+	RpcEnterpriseSyncRequest,
+	RpcEnterpriseSyncResponse,
 	RpcOAuthProviderId,
 	RpcProviderActionRequest,
 	RpcProviderCapability,
@@ -49,9 +50,21 @@ export type {
 	TelemetryPrimitive,
 	TelemetryProperties,
 	TelemetryValue,
+	Tool,
+	ToolApprovalRequest,
+	ToolApprovalResult,
+	ToolContext,
 	ToolPolicy,
+	WorkspaceInfo,
+	WorkspaceInfoSchema,
+	WorkspaceManifest,
+	WorkspaceManifestSchema,
 } from "@clinebot/shared";
 export {
+	ContributionRegistry,
+	createContributionRegistry,
+	createTool,
+	noopBasicLogger,
 	normalizeUserInput,
 	RPC_TEAM_LIFECYCLE_EVENT_TYPE,
 	RPC_TEAM_PROGRESS_EVENT_TYPE,
@@ -75,84 +88,20 @@ export {
 	isRpcClineAccountActionRequest,
 	RpcClineAccountService,
 	type RpcProviderActionExecutor,
+	type UserRemoteConfigOrganization,
 	type UserRemoteConfigResponse,
 } from "./account";
-export type {
-	AgentConfigWatcher,
-	AgentConfigWatcherEvent,
-	AgentYamlConfig,
-	BuildAgentConfigOverridesOptions,
-	CreateAgentConfigWatcherOptions,
-	CreateInstructionWatcherOptions,
-	CreateRulesConfigDefinitionOptions,
-	CreateSkillsConfigDefinitionOptions,
-	CreateUserInstructionConfigWatcherOptions,
-	CreateWorkflowsConfigDefinitionOptions,
-	HookConfigFileEntry,
-	LoadAgentPluginFromPathOptions,
-	ParseMarkdownFrontmatterResult,
-	ParseYamlFrontmatterResult,
-	ResolveAgentPluginPathsOptions,
-	RuleConfig,
-	SkillConfig,
-	UnifiedConfigDefinition,
-	UnifiedConfigFileCandidate,
-	UnifiedConfigFileContext,
-	UnifiedConfigRecord,
-	UnifiedConfigWatcherEvent,
-	UnifiedConfigWatcherOptions,
-	UserInstructionConfig,
-	UserInstructionConfigType,
-	UserInstructionConfigWatcher,
-	UserInstructionConfigWatcherEvent,
-	WorkflowConfig,
-} from "./agents";
-export {
-	createAgentConfigDefinition,
-	createAgentConfigWatcher,
-	createRulesConfigDefinition,
-	createSkillsConfigDefinition,
-	createUserInstructionConfigWatcher,
-	createWorkflowsConfigDefinition,
-	discoverPluginModulePaths,
-	HOOK_CONFIG_FILE_EVENT_MAP,
-	HOOKS_CONFIG_DIRECTORY_NAME,
-	HookConfigFileName,
-	listHookConfigFiles,
-	loadAgentPluginFromPath,
-	loadAgentPluginsFromPaths,
-	parseAgentConfigFromYaml,
-	parsePartialAgentConfigFromYaml,
-	parseRuleConfigFromMarkdown,
-	parseSkillConfigFromMarkdown,
-	parseWorkflowConfigFromMarkdown,
-	RULES_CONFIG_DIRECTORY_NAME,
-	resolveAgentPluginPaths,
-	resolveAgentTools,
-	resolveAndLoadAgentPlugins,
-	resolveDocumentsHooksDirectoryPath,
-	resolveDocumentsRulesDirectoryPath,
-	resolveDocumentsWorkflowsDirectoryPath,
-	resolveHooksConfigSearchPaths,
-	resolvePluginConfigSearchPaths,
-	resolveRulesConfigSearchPaths,
-	resolveSkillsConfigSearchPaths,
-	resolveWorkflowsConfigSearchPaths,
-	SKILLS_CONFIG_DIRECTORY_NAME,
-	toHookConfigFileName,
-	toPartialAgentConfig,
-	UnifiedConfigFileWatcher,
-	WORKFLOWS_CONFIG_DIRECTORY_NAME,
-} from "./agents";
 export {
 	createOAuthClientCallbacks,
 	type OAuthClientCallbacksOptions,
 } from "./auth/client";
 export {
+	completeClineDeviceAuth,
 	createClineOAuthProvider,
 	getValidClineCredentials,
 	loginClineOAuth,
 	refreshClineToken,
+	startClineDeviceAuth,
 } from "./auth/cline";
 export {
 	getValidOpenAICodexCredentials,
@@ -213,16 +162,87 @@ export {
 	ChatViewStateSchema,
 } from "./chat/chat-schema";
 export type {
-	FastFileIndexOptions,
-	MentionEnricherOptions,
-	MentionEnrichmentResult,
-} from "./input";
+	LoadAgentPluginFromPathOptions,
+	ResolveAgentPluginPathsOptions,
+} from "./extensions";
 export {
-	enrichPromptWithMentions,
-	getFileIndex,
-	prewarmFileIndex,
-} from "./input";
+	discoverPluginModulePaths,
+	loadAgentPluginFromPath,
+	loadAgentPluginsFromPaths,
+	resolveAgentPluginPaths,
+	resolveAndLoadAgentPlugins,
+	resolvePluginConfigSearchPaths,
+} from "./extensions";
+export type {
+	AgentConfigWatcher,
+	AgentConfigWatcherEvent,
+	AgentYamlConfig,
+	AvailableRuntimeCommand,
+	BuildAgentConfigOverridesOptions,
+	CreateAgentConfigWatcherOptions,
+	CreateInstructionWatcherOptions,
+	CreateRulesConfigDefinitionOptions,
+	CreateSkillsConfigDefinitionOptions,
+	CreateUserInstructionConfigWatcherOptions,
+	CreateWorkflowsConfigDefinitionOptions,
+	HookConfigFileEntry,
+	ParseMarkdownFrontmatterResult,
+	ParseYamlFrontmatterResult,
+	RuleConfig,
+	SkillConfig,
+	UnifiedConfigDefinition,
+	UnifiedConfigFileCandidate,
+	UnifiedConfigFileContext,
+	UnifiedConfigRecord,
+	UnifiedConfigWatcherEvent,
+	UnifiedConfigWatcherOptions,
+	UserInstructionConfig,
+	UserInstructionConfigType,
+	UserInstructionConfigWatcher,
+	UserInstructionConfigWatcherEvent,
+	WorkflowConfig,
+} from "./extensions/config";
+export {
+	createAgentConfigDefinition,
+	createAgentConfigWatcher,
+	createRulesConfigDefinition,
+	createSkillsConfigDefinition,
+	createUserInstructionConfigWatcher,
+	createWorkflowsConfigDefinition,
+	HOOK_CONFIG_FILE_EVENT_MAP,
+	HOOKS_CONFIG_DIRECTORY_NAME,
+	HookConfigFileName,
+	listAvailableRuntimeCommandsFromWatcher,
+	listHookConfigFiles,
+	parseAgentConfigFromYaml,
+	parsePartialAgentConfigFromYaml,
+	parseRuleConfigFromMarkdown,
+	parseSkillConfigFromMarkdown,
+	parseWorkflowConfigFromMarkdown,
+	RULES_CONFIG_DIRECTORY_NAME,
+	resolveAgentTools,
+	resolveDocumentsHooksDirectoryPath,
+	resolveDocumentsRulesDirectoryPath,
+	resolveDocumentsWorkflowsDirectoryPath,
+	resolveHooksConfigSearchPaths,
+	resolveRulesConfigSearchPaths,
+	resolveRuntimeSlashCommandFromWatcher,
+	resolveSkillsConfigSearchPaths,
+	resolveWorkflowsConfigSearchPaths,
+	SKILLS_CONFIG_DIRECTORY_NAME,
+	toHookConfigFileName,
+	toPartialAgentConfig,
+	UnifiedConfigFileWatcher,
+	WORKFLOWS_CONFIG_DIRECTORY_NAME,
+} from "./extensions/config";
 export {
+	type CreateDisabledMcpToolPoliciesOptions,
+	type CreateDisabledMcpToolPolicyOptions,
+	type CreateMcpToolsOptions,
+	createDefaultMcpServerClientFactory,
+	createDisabledMcpToolPolicies,
+	createDisabledMcpToolPolicy,
+	createMcpTools,
 	hasMcpSettingsFile,
 	InMemoryMcpManager,
 	type LoadMcpSettingsOptions,
@@ -239,11 +259,48 @@ export {
 	type McpSseTransportConfig,
 	type McpStdioTransportConfig,
 	type McpStreamableHttpTransportConfig,
+	type McpToolCallRequest,
+	type McpToolCallResult,
+	type McpToolDescriptor,
+	type McpToolNameTransform,
+	type McpToolProvider,
 	type RegisterMcpServersFromSettingsOptions,
 	registerMcpServersFromSettingsFile,
 	resolveDefaultMcpSettingsPath,
 	resolveMcpServerRegistrations,
-} from "./mcp";
+} from "./extensions/mcp";
+export {
+	createPersistentSubprocessHooks,
+	createSubprocessHooks,
+	type HookEventName,
+	HookEventNameSchema,
+	type HookEventPayload,
+	HookEventPayloadSchema,
+	PersistentHookClient,
+	type PersistentHookClientOptions,
+	type PersistentSubprocessHookControl,
+	type PersistentSubprocessHooksOptions,
+	parseHookEventPayload,
+	type RunHookOptions,
+	type RunHookResult,
+	type RunSubprocessEventOptions,
+	type RunSubprocessEventResult,
+	runHook,
+	runSubprocessEvent,
+	type SubprocessHookControl,
+	type SubprocessHooksOptions,
+} from "./hooks";
+export type {
+	FastFileIndexOptions,
+	MentionEnricherOptions,
+	MentionEnrichmentResult,
+} from "./input";
+export {
+	enrichPromptWithMentions,
+	getFileIndex,
+	prewarmFileIndex,
+} from "./input";
+export { getClineDefaultSystemPrompt } from "./prompt/default-system";
 export {
 	addLocalProvider,
 	type DeleteLocalProviderRequest,
@@ -259,11 +316,10 @@ export {
 	type UpdateLocalProviderRequest,
 	updateLocalProvider,
 } from "./providers/local-provider-service";
-export type { AvailableRuntimeCommand } from "./runtime/commands";
-export {
-	listAvailableRuntimeCommandsFromWatcher,
-	resolveRuntimeSlashCommandFromWatcher,
-} from "./runtime/commands";
+export type {
+	CheckpointEntry,
+	CheckpointMetadata,
+} from "./runtime/checkpoint-hooks";
 export {
 	formatRulesForSystemPrompt,
 	isRuleEnabled,
@@ -274,31 +330,24 @@ export {
 	createTeamName,
 	DefaultRuntimeBuilder,
 } from "./runtime/runtime-builder";
-export {
-	type SandboxCallOptions,
-	SubprocessSandbox,
-	type SubprocessSandboxOptions,
-} from "./runtime/sandbox/subprocess-sandbox";
 export type {
 	BuiltRuntime,
 	RuntimeBuilder,
 	RuntimeBuilderInput,
 	SessionRuntime,
+	TeamToolsFactory,
+	TeamToolsFactoryOptions,
+	TeamToolsFactoryResult,
 } from "./runtime/session-runtime";
-export type { AvailableSkill } from "./runtime/skills";
 export {
-	listAvailableSkillsFromWatcher,
-	resolveSkillsSlashCommandFromWatcher,
-} from "./runtime/skills";
+	type SandboxCallOptions,
+	SubprocessSandbox,
+	type SubprocessSandboxOptions,
+} from "./runtime/subprocess-sandbox";
 export {
 	type DesktopToolApprovalOptions,
 	requestDesktopToolApproval,
 } from "./runtime/tool-approval";
-export type { AvailableWorkflow } from "./runtime/workflows";
-export {
-	listAvailableWorkflowsFromWatcher,
-	resolveWorkflowSlashCommandFromWatcher,
-} from "./runtime/workflows";
 export { DefaultSessionManager } from "./session/default-session-manager";
 export {
 	clearRpcDiscoveryIfAddressMatches,
@@ -365,15 +414,10 @@ export type {
 	WorkspaceManagerEvent,
 } from "./session/workspace-manager";
 export { InMemoryWorkspaceManager } from "./session/workspace-manager";
-export type { WorkspaceManifest } from "./session/workspace-manifest";
 export {
 	buildWorkspaceMetadata,
-	emptyWorkspaceManifest,
 	generateWorkspaceInfo,
 	normalizeWorkspacePath,
-	upsertWorkspaceInfo,
-	WorkspaceInfoSchema,
-	WorkspaceManifestSchema,
 } from "./session/workspace-manifest";
 export {
 	type MigrateLegacyProviderSettingsOptions,
@@ -387,7 +431,33 @@ export {
 	type SqliteTeamStoreOptions,
 } from "./storage/team-store";
 export {
+	type AgentTask,
+	AgentTeam,
+	AgentTeamsRuntime,
+	type AgentTeamsRuntimeOptions,
+	type BootstrapAgentTeamsOptions,
+	type BootstrapAgentTeamsResult,
+	bootstrapAgentTeams,
+	buildDelegatedAgentConfig,
 	buildTeamProgressSummary,
+	type CreateAgentTeamsToolsOptions,
+	createAgentTeamsTools,
+	createDelegatedAgent,
+	createDelegatedAgentConfigProvider,
+	createSpawnAgentTool,
+	type DelegatedAgentConfigProvider,
+	type DelegatedAgentConnectionConfig,
+	type DelegatedAgentKind,
+	type DelegatedAgentRuntimeConfig,
+	reviveTeamStateDates,
+	type SpawnTeammateOptions,
+	type SubAgentEndContext,
+	type SubAgentStartContext,
+	sanitizeTeamName,
+	type TaskResult,
+	type TeamEvent,
+	type TeamMemberConfig,
+	type TeamTeammateRuntimeConfig,
 	toTeamProgressLifecycleEvent,
 } from "./team";
 export type {
@@ -421,13 +491,21 @@ export {
 } from "./telemetry/core-events";
 export type { ITelemetryAdapter } from "./telemetry/ITelemetryAdapter";
 export {
-	LoggerTelemetryAdapter,
-	type LoggerTelemetryAdapterOptions,
-} from "./telemetry/LoggerTelemetryAdapter";
+	type CreateOpenTelemetryTelemetryServiceOptions,
+	createConfiguredTelemetryService,
+	createOpenTelemetryTelemetryService,
+	OpenTelemetryProvider,
+	type OpenTelemetryProviderOptions,
+} from "./telemetry/OpenTelemetryProvider";
+export {
+	TelemetryLoggerSink,
+	type TelemetryLoggerSinkOptions,
+} from "./telemetry/TelemetryLoggerSink";
 export { CORE_BUILD_VERSION } from "./version";
 export async function loadOpenTelemetryAdapter() {
 	return import("./telemetry/index.js");
 }
+export { createContextCompactionPrepareTurn } from "./extensions/context/compaction";
 export {
 	TelemetryService,
 	type TelemetryServiceOptions,
@@ -452,11 +530,16 @@ export {
 	ToolPresets,
 } from "./tools";
 // Compatibility barrel (legacy imports).
-export type { RuntimeEnvironment, SessionEvent, StoredMessages } from "./types";
+export type { RuntimeEnvironment } from "./types";
 export type { SessionStatus } from "./types/common";
 export { SESSION_STATUSES, SessionSource } from "./types/common";
 export type {
 	CoreAgentMode,
+	CoreCompactionConfig,
+	CoreCompactionContext,
+	CoreCompactionResult,
+	CoreCompactionStrategy,
+	CoreCompactionSummarizerConfig,
 	CoreModelConfig,
 	CoreRuntimeFeatures,
 	CoreSessionConfig,
@@ -480,4 +563,3 @@ export {
 } from "./types/provider-settings";
 export type { SessionRecord, SessionRef } from "./types/sessions";
 export type { ArtifactStore, SessionStore, TeamStore } from "./types/storage";
-export type { WorkspaceInfo } from "./types/workspace";

package/src/prompt/default-system.ts

@@ -0,0 +1,21 @@
+import { basename, resolve } from "node:path";
+import { buildClineSystemPrompt } from "@clinebot/shared";
+
+export function getClineDefaultSystemPrompt(
+	ide: string,
+	cwd: string,
+	providerId: string,
+	metadata = "",
+	rules = "",
+	platform = (typeof process !== "undefined" && process?.platform) || "unknown",
+): string {
+	return buildClineSystemPrompt({
+		ide,
+		platform,
+		workspaceRoot: resolve(cwd),
+		workspaceName: basename(cwd),
+		metadata,
+		rules,
+		providerId,
+	});
+}

package/src/providers/local-provider-registry.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import * as LlmsModels from "@clinebot/llms/models";
+import * as LlmsModels from "@clinebot/llms";
 import type { RpcProviderCapability, RpcProviderModel } from "@clinebot/shared";
 import type { ProviderSettingsManager } from "../storage/provider-settings-manager";
 

package/src/providers/local-provider-service.test.ts

@@ -1,7 +1,7 @@
 import { mkdtempSync, rmSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import * as LlmsModels from "@clinebot/llms/models";
+import * as LlmsModels from "@clinebot/llms";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { ProviderSettingsManager } from "../storage/provider-settings-manager";
 import {
@@ -922,6 +922,27 @@ describe("listLocalProviders", () => {
 		).toBe(true);
 	});
 
+	it("uses the same built-in model list for cline as vercel-ai-gateway", async () => {
+		manager.saveProviderSettings(
+			{
+				provider: "cline",
+				apiKey: "test-key",
+				baseUrl: "https://api.cline.bot/api/v1",
+				model: "anthropic/claude-sonnet-4.6",
+			},
+			{ setLastUsed: false },
+		);
+
+		const { providers } = await listLocalProviders(manager);
+		const cline = providers.find((provider) => provider.id === "cline");
+		const gateway = providers.find(
+			(provider) => provider.id === "vercel-ai-gateway",
+		);
+
+		expect(cline?.modelList?.length).toBeGreaterThan(0);
+		expect(cline?.modelList).toEqual(gateway?.modelList);
+	});
+
 	it("does not eagerly fetch LiteLLM private models while listing providers", async () => {
 		manager.saveProviderSettings(
 			{
@@ -950,7 +971,7 @@ describe("listLocalProviders", () => {
 		const litellm = providers.find((provider) => provider.id === "litellm");
 
 		expect(fetchMock).not.toHaveBeenCalled();
-		expect(litellm?.modelList).toEqual([]);
+		expect(litellm?.modelList?.length).toBeGreaterThan(0);
 		expect(
 			litellm?.modelList?.some((model) => model.id === "team/private-model"),
 		).toBe(false);

package/src/providers/local-provider-service.ts

@@ -1,5 +1,5 @@
-import * as LlmsModels from "@clinebot/llms/models";
-import * as LlmsProviders from "@clinebot/llms/providers";
+import * as LlmsModels from "@clinebot/llms";
+import * as LlmsProviders from "@clinebot/llms";
 import type {
 	RpcAddProviderActionRequest,
 	RpcOAuthProviderId,

package/src/runtime/checkpoint-hooks.test.ts

@@ -0,0 +1,167 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { describe, expect, it } from "vitest";
+import {
+	type CheckpointEntry,
+	type CheckpointMetadata,
+	createCheckpointHooks,
+} from "./checkpoint-hooks";
+
+const execFile = promisify(execFileCallback);
+
+async function runGit(cwd: string, ...args: string[]): Promise<string> {
+	const result = await execFile("git", ["-C", cwd, ...args], {
+		windowsHide: true,
+	});
+	return result.stdout.trim();
+}
+
+async function createGitRepo(): Promise<string> {
+	const cwd = await mkdtemp(join(tmpdir(), "core-checkpoint-"));
+	await runGit(cwd, "init");
+	await runGit(cwd, "config", "user.name", "Codex Test");
+	await runGit(cwd, "config", "user.email", "codex@example.com");
+	await writeFile(join(cwd, "note.txt"), "base\n", "utf8");
+	await runGit(cwd, "add", "note.txt");
+	await runGit(cwd, "commit", "-m", "initial");
+	return cwd;
+}
+
+describe("createCheckpointHooks", () => {
+	it("creates one checkpoint at the start of each root run and appends metadata", async () => {
+		const cwd = await createGitRepo();
+		let metadata: Record<string, unknown> | undefined;
+		try {
+			const hooks = createCheckpointHooks({
+				cwd,
+				sessionId: "sess_1",
+				readSessionMetadata: async () => metadata,
+				writeSessionMetadata: async (next) => {
+					metadata = next;
+				},
+			});
+
+			await writeFile(join(cwd, "note.txt"), "run-one\n", "utf8");
+			await hooks.onRunStart?.({
+				agentId: "agent_1",
+				conversationId: "conv_1",
+				parentAgentId: null,
+				userMessage: "first",
+			});
+			await hooks.onBeforeAgentStart?.({
+				agentId: "agent_1",
+				conversationId: "conv_1",
+				parentAgentId: null,
+				iteration: 1,
+				systemPrompt: "system",
+				messages: [],
+			});
+
+			const first = metadata?.checkpoint as CheckpointMetadata;
+			expect(first.history).toHaveLength(1);
+			expect(first.latest.runCount).toBe(1);
+			expect(first.latest.ref).toMatch(/^[0-9a-f]{40}$/);
+
+			await writeFile(join(cwd, "note.txt"), "run-two\n", "utf8");
+			await hooks.onRunStart?.({
+				agentId: "agent_1",
+				conversationId: "conv_1",
+				parentAgentId: null,
+				userMessage: "second",
+			});
+			await hooks.onBeforeAgentStart?.({
+				agentId: "agent_1",
+				conversationId: "conv_1",
+				parentAgentId: null,
+				iteration: 1,
+				systemPrompt: "system",
+				messages: [],
+			});
+
+			const checkpoint = metadata?.checkpoint as CheckpointMetadata;
+			expect(checkpoint.latest.runCount).toBe(2);
+			expect(checkpoint.history).toHaveLength(2);
+			expect(
+				checkpoint.history.map((entry: CheckpointEntry) => entry.runCount),
+			).toEqual([1, 2]);
+			expect(checkpoint.latest.kind).toBe("stash");
+		} finally {
+			await rm(cwd, { recursive: true, force: true });
+		}
+	});
+
+	it("falls back to a commit checkpoint when the worktree is clean", async () => {
+		const cwd = await createGitRepo();
+		let metadata: Record<string, unknown> | undefined;
+		try {
+			const hooks = createCheckpointHooks({
+				cwd,
+				sessionId: "sess_clean",
+				readSessionMetadata: async () => metadata,
+				writeSessionMetadata: async (next) => {
+					metadata = next;
+				},
+			});
+
+			await hooks.onRunStart?.({
+				agentId: "agent_1",
+				conversationId: "conv_1",
+				parentAgentId: null,
+				userMessage: "clean",
+			});
+			await hooks.onBeforeAgentStart?.({
+				agentId: "agent_1",
+				conversationId: "conv_1",
+				parentAgentId: null,
+				iteration: 1,
+				systemPrompt: "system",
+				messages: [],
+			});
+
+			const checkpoint = metadata?.checkpoint as CheckpointMetadata;
+			expect(checkpoint.history).toHaveLength(1);
+			expect(checkpoint.latest.kind).toBe("commit");
+			expect(checkpoint.latest.ref).toMatch(/^[0-9a-f]{40}$/);
+		} finally {
+			await rm(cwd, { recursive: true, force: true });
+		}
+	});
+
+	it("skips checkpoint creation for subagents", async () => {
+		const cwd = await createGitRepo();
+		let writes = 0;
+		try {
+			const hooks = createCheckpointHooks({
+				cwd,
+				sessionId: "sess_1",
+				readSessionMetadata: async () => undefined,
+				writeSessionMetadata: async () => {
+					writes += 1;
+				},
+			});
+
+			await writeFile(join(cwd, "note.txt"), "subagent-dirty\n", "utf8");
+			await hooks.onRunStart?.({
+				agentId: "agent_child",
+				conversationId: "conv_child",
+				parentAgentId: "agent_root",
+				userMessage: "child",
+			});
+			await hooks.onBeforeAgentStart?.({
+				agentId: "agent_child",
+				conversationId: "conv_child",
+				parentAgentId: "agent_root",
+				iteration: 1,
+				systemPrompt: "system",
+				messages: [],
+			});
+
+			expect(writes).toBe(0);
+		} finally {
+			await rm(cwd, { recursive: true, force: true });
+		}
+	});
+});