@clinebot/core 0.0.33 → 0.0.35

package/src/{team → extensions/tools/team}/team-tools.ts

@@ -4,12 +4,11 @@ import {
 	TEAM_AWAIT_TIMEOUT_MS,
 	TEAM_RUN_MESSAGE_PREVIEW_LIMIT,
 	TEAM_RUN_TEXT_PREVIEW_LIMIT,
+	TEAM_TASK_IGNORED_FIELDS_BY_ACTION,
 	type TeamAttachOutcomeFragmentInput,
 	TeamAttachOutcomeFragmentInputSchema,
-	type TeamAwaitAllRunsInput,
-	TeamAwaitAllRunsInputSchema,
-	type TeamAwaitRunInput,
-	TeamAwaitRunInputSchema,
+	type TeamAwaitRunsInput,
+	TeamAwaitRunsInputSchema,
 	type TeamBroadcastInput,
 	TeamBroadcastInputSchema,
 	type TeamCancelRunInput,
@@ -24,8 +23,8 @@ import {
 	TeamListOutcomesInputSchema,
 	type TeamListRunsInput,
 	TeamListRunsInputSchema,
-	type TeamLogUpdateInput,
-	TeamLogUpdateInputSchema,
+	type TeamMissionLogInput,
+	TeamMissionLogInputSchema,
 	type TeamReadMailboxInput,
 	TeamReadMailboxInputSchema,
 	type TeamReviewOutcomeFragmentInput,
@@ -113,6 +112,24 @@ function summarizeRun(run: TeamRunRecord): TeamRunToolSummary {
 	};
 }
 
+function assertAwaitedRunSucceeded(run: TeamRunRecord): void {
+	if (run.status === "failed") {
+		throw new Error(
+			`Run "${run.id}" failed${run.error ? `: ${run.error}` : ""}`,
+		);
+	}
+	if (run.status === "cancelled") {
+		throw new Error(
+			`Run "${run.id}" was cancelled${run.error ? `: ${run.error}` : ""}`,
+		);
+	}
+	if (run.status === "interrupted") {
+		throw new Error(
+			`Run "${run.id}" was interrupted${run.error ? `: ${run.error}` : ""}`,
+		);
+	}
+}
+
 export type TeamTeammateRuntimeConfig = DelegatedAgentRuntimeConfig;
 
 export interface CreateAgentTeamsToolsOptions {
@@ -244,7 +261,6 @@ export function createAgentTeamsTools(
 					const spec: TeamTeammateSpec = {
 						agentId: validatedInput.agentId,
 						rolePrompt: validatedInput.rolePrompt,
-						maxIterations: validatedInput.maxIterations,
 					};
 					spawnTeamTeammate({
 						runtime: options.runtime,
@@ -312,12 +328,26 @@ export function createAgentTeamsTools(
 		createTool<TeamTaskInput, TeamTaskToolResult>({
 			name: "team_task",
 			description:
-				"Manage shared team tasks. Use action=create|list|claim|complete|block.",
+				"Manage shared team tasks with action-specific payloads. " +
+				"create requires title and description, with optional dependsOn and assignee. " +
+				"list accepts optional status, assignee. " +
+				"claim requires taskId. complete requires taskId and summary. block requires taskId and reason. " +
+				"Do not include fields from other actions.",
 			inputSchema: zodToJsonSchema(TeamTaskInputSchema),
 			execute: async (input) => {
 				const validatedInput = validateWithZod(TeamTaskInputSchema, input);
 				switch (validatedInput.action) {
 					case "create": {
+						const ignoredFieldSet = new Set(
+							TEAM_TASK_IGNORED_FIELDS_BY_ACTION.create ?? [],
+						);
+						const ignoredFields = Object.entries(
+							input as Record<string, unknown>,
+						)
+							.filter(
+								([field, value]) => ignoredFieldSet.has(field) && value != null,
+							)
+							.map(([field]) => field);
 						const task = options.runtime.createTask({
 							title: validatedInput.title!,
 							description: validatedInput.description!,
@@ -329,6 +359,12 @@ export function createAgentTeamsTools(
 							action: "create",
 							taskId: task.id,
 							status: task.status,
+							...(ignoredFields.length > 0
+								? {
+										ignoredFields,
+										note: `Ignored fields for action=create: ${ignoredFields.join(", ")}`,
+									}
+								: {}),
 						};
 					}
 					case "list":
@@ -337,8 +373,6 @@ export function createAgentTeamsTools(
 							tasks: options.runtime.listTaskItems({
 								status: validatedInput.status,
 								assignee: validatedInput.assignee,
-								unassignedOnly: validatedInput.unassignedOnly,
-								readyOnly: validatedInput.readyOnly,
 							}),
 						};
 					case "claim": {
@@ -383,6 +417,11 @@ export function createAgentTeamsTools(
 		}) as Tool,
 	);
 
+	// Track in-flight sync runs per agent for dedup
+	// (Claude sometimes emits duplicate tool_use blocks in a single response;
+	//  we execute the first and return an informative "duplicate ignored" to the rest)
+	const pendingSyncRuns = new Set<string>();
+
 	tools.push(
 		createTool<
 			TeamRunTaskInput,
@@ -417,22 +456,36 @@ export function createAgentTeamsTools(
 						runId: run.id,
 					};
 				}
-				const result = await options.runtime.routeToTeammate(
-					validatedInput.agentId,
-					validatedInput.task,
-					{
-						taskId: validatedInput.taskId || undefined,
-						fromAgentId: options.requesterId,
-						continueConversation:
-							validatedInput.continueConversation || undefined,
-					},
-				);
-				return {
-					agentId: validatedInput.agentId,
-					mode: "sync",
-					text: result.text,
-					iterations: result.iterations,
-				};
+
+				/// Deduplication guard: reject a duplicate sync call for the same agent
+				// that was already dispatched in this same parallel tool-call batch.
+				if (pendingSyncRuns.has(validatedInput.agentId)) {
+					throw new Error(
+						`Duplicate team_run_task call detected for agent "${validatedInput.agentId}". ` +
+							`Only one call per agent is allowed per turn. Discard this duplicate result.`,
+					);
+				}
+				pendingSyncRuns.add(validatedInput.agentId);
+				try {
+					const result = await options.runtime.routeToTeammate(
+						validatedInput.agentId,
+						validatedInput.task,
+						{
+							taskId: validatedInput.taskId || undefined,
+							fromAgentId: options.requesterId,
+							continueConversation:
+								validatedInput.continueConversation || undefined,
+						},
+					);
+					return {
+						agentId: validatedInput.agentId,
+						mode: "sync",
+						text: result.text,
+						iterations: result.iterations,
+					};
+				} finally {
+					pendingSyncRuns.delete(validatedInput.agentId);
+				}
 			},
 		}) as Tool,
 	);
@@ -467,44 +520,19 @@ export function createAgentTeamsTools(
 	);
 
 	tools.push(
-		createTool<TeamAwaitRunInput, TeamRunToolSummary>({
-			name: "team_await_run",
+		createTool<TeamAwaitRunsInput, TeamRunToolSummary | TeamRunToolSummary[]>({
+			name: "team_await_runs",
 			description:
-				"Wait for one async run by runId. Uses a long timeout for legitimate teammate work.",
-			inputSchema: zodToJsonSchema(TeamAwaitRunInputSchema),
+				"Wait for async teammate runs. Provide runId to wait for one run, or omit it to wait for all active async runs. Uses a long timeout for legitimate teammate work.",
+			inputSchema: zodToJsonSchema(TeamAwaitRunsInputSchema),
 			timeoutMs: TEAM_AWAIT_TIMEOUT_MS,
 			execute: async (input) => {
-				const validatedInput = validateWithZod(TeamAwaitRunInputSchema, input);
-				const run = await options.runtime.awaitRun(validatedInput.runId);
-				if (run.status === "failed") {
-					throw new Error(
-						`Run "${run.id}" failed${run.error ? `: ${run.error}` : ""}`,
-					);
-				}
-				if (run.status === "cancelled") {
-					throw new Error(
-						`Run "${run.id}" was cancelled${run.error ? `: ${run.error}` : ""}`,
-					);
-				}
-				if (run.status === "interrupted") {
-					throw new Error(
-						`Run "${run.id}" was interrupted${run.error ? `: ${run.error}` : ""}`,
-					);
+				const validatedInput = validateWithZod(TeamAwaitRunsInputSchema, input);
+				if (validatedInput.runId) {
+					const run = await options.runtime.awaitRun(validatedInput.runId);
+					assertAwaitedRunSucceeded(run);
+					return summarizeRun(run);
 				}
-				return summarizeRun(run);
-			},
-		}) as Tool,
-	);
-
-	tools.push(
-		createTool<TeamAwaitAllRunsInput, TeamRunToolSummary[]>({
-			name: "team_await_all_runs",
-			description:
-				"Wait for all active async runs to complete. Uses a long timeout for legitimate teammate work.",
-			inputSchema: zodToJsonSchema(TeamAwaitAllRunsInputSchema),
-			timeoutMs: TEAM_AWAIT_TIMEOUT_MS,
-			execute: async (input) => {
-				validateWithZod(TeamAwaitAllRunsInputSchema, input);
 				const runs = await options.runtime.awaitAllRuns();
 				const failedRuns = runs.filter((run) =>
 					["failed", "cancelled", "interrupted"].includes(run.status),
@@ -528,7 +556,7 @@ export function createAgentTeamsTools(
 	tools.push(
 		createTool<TeamSendMessageInput, { id: string; toAgentId: string }>({
 			name: "team_send_message",
-			description: "Send a direct mailbox message to one teammate.",
+			description: "Send a mailbox message to a specific teammate.",
 			inputSchema: zodToJsonSchema(TeamSendMessageInputSchema),
 			execute: async (input) => {
 				const validatedInput = validateWithZod(
@@ -550,7 +578,7 @@ export function createAgentTeamsTools(
 	tools.push(
 		createTool<TeamBroadcastInput, { delivered: number }>({
 			name: "team_broadcast",
-			description: "Broadcast a mailbox message to all teammates.",
+			description: "Broadcast a message to all teammates.",
 			inputSchema: zodToJsonSchema(TeamBroadcastInputSchema),
 			execute: async (input) => {
 				const validatedInput = validateWithZod(TeamBroadcastInputSchema, input);
@@ -560,7 +588,6 @@ export function createAgentTeamsTools(
 					validatedInput.body,
 					{
 						taskId: validatedInput.taskId ?? undefined,
-						includeLead: validatedInput.includeLead ?? undefined,
 					},
 				);
 				return { delivered: messages.length };
@@ -583,7 +610,6 @@ export function createAgentTeamsTools(
 				);
 				return options.runtime.listMailbox(options.requesterId, {
 					unreadOnly: validatedInput.unreadOnly,
-					limit: validatedInput.limit,
 					markRead: true,
 				});
 			},
@@ -591,12 +617,15 @@ export function createAgentTeamsTools(
 	);
 
 	tools.push(
-		createTool<TeamLogUpdateInput, { id: string }>({
-			name: "team_log_update",
-			description: "Append a mission log update for this agent.",
-			inputSchema: zodToJsonSchema(TeamLogUpdateInputSchema),
+		createTool<TeamMissionLogInput, { id: string }>({
+			name: "team_mission_log",
+			description: "Append a mission log update for your team.",
+			inputSchema: zodToJsonSchema(TeamMissionLogInputSchema),
 			execute: async (input) => {
-				const validatedInput = validateWithZod(TeamLogUpdateInputSchema, input);
+				const validatedInput = validateWithZod(
+					TeamMissionLogInputSchema,
+					input,
+				);
 				const entry = options.runtime.appendMissionLog({
 					agentId: options.requesterId,
 					taskId: validatedInput.taskId || undefined,

package/src/{tools → extensions/tools}/types.ts

@@ -4,7 +4,7 @@
  * Type definitions for executors, configuration, and results.
  */
 
-import type { ToolContext } from "@clinebot/shared";
+import type { ImageContent, TextContent, ToolContext } from "@clinebot/shared";
 import type {
 	ApplyPatchInput,
 	EditFileInput,
@@ -23,7 +23,7 @@ export interface ToolOperationResult {
 	/** The query/input that was executed */
 	query: string;
 	/** The result content (if successful) */
-	result: string;
+	result: unknown;
 	/** Error message (if failed) */
 	error?: string;
 	/** Whether the operation succeeded */
@@ -32,6 +32,8 @@ export interface ToolOperationResult {
 	duration?: number;
 }
 
+export type FileReadResultContent = string | Array<TextContent | ImageContent>;
+
 // =============================================================================
 // Executor Interfaces
 // =============================================================================
@@ -46,7 +48,7 @@ export interface ToolOperationResult {
 export type FileReadExecutor = (
 	request: ReadFileRequest,
 	context: ToolContext,
-) => Promise<string>;
+) => Promise<FileReadResultContent>;
 
 /**
  * Executor for searching the codebase

package/src/{runtime → hooks}/checkpoint-hooks.ts

@@ -86,6 +86,33 @@ async function runGit(
 	};
 }
 
+/**
+ * Deletes all private git refs under refs/cline/checkpoints/{sessionId}/ that
+ * were created by the checkpoint system to keep stash objects reachable.
+ * Errors are swallowed — if the cwd is not a git repo or the refs don't exist,
+ * the delete is a no-op.
+ */
+export async function deleteCheckpointRefs(
+	cwd: string | null | undefined,
+	sessionId: string,
+): Promise<void> {
+	if (!cwd) return;
+	const prefix = `refs/cline/checkpoints/${sessionId}/`;
+	try {
+		const { stdout } = await runGit(cwd, [
+			"for-each-ref",
+			"--format=%(refname)",
+			prefix,
+		]);
+		const refs = stdout.trim().split("\n").filter(Boolean);
+		await Promise.allSettled(
+			refs.map((ref) => runGit(cwd, ["update-ref", "-d", ref])),
+		);
+	} catch {
+		// Not a git repo or git not available — ignore.
+	}
+}
+
 export function createCheckpointHooks(
 	options: CreateCheckpointHooksOptions,
 ): AgentHooks {

package/src/{runtime → hooks}/hook-file-hooks.test.ts

@@ -50,7 +50,12 @@ describe("createHookConfigFileHooks", () => {
 			});
 			expect(hooks).toBeUndefined();
 		} finally {
-			await rm(workspace, { recursive: true, force: true });
+			await rm(workspace, {
+				recursive: true,
+				force: true,
+				maxRetries: 3,
+				retryDelay: 250,
+			});
 		}
 	});
 
@@ -78,7 +83,12 @@ describe("createHookConfigFileHooks", () => {
 			});
 			expect(control).toMatchObject({ cancel: true, context: "legacy-ok" });
 		} finally {
-			await rm(workspace, { recursive: true, force: true });
+			await rm(workspace, {
+				recursive: true,
+				force: true,
+				maxRetries: 3,
+				retryDelay: 250,
+			});
 		}
 	});
 
@@ -106,7 +116,12 @@ describe("createHookConfigFileHooks", () => {
 			});
 			expect(control).toMatchObject({ cancel: false, context: "shebang-ok" });
 		} finally {
-			await rm(workspace, { recursive: true, force: true });
+			await rm(workspace, {
+				recursive: true,
+				force: true,
+				maxRetries: 3,
+				retryDelay: 250,
+			});
 		}
 	});
 
@@ -137,7 +152,12 @@ describe("createHookConfigFileHooks", () => {
 				context: "needs-review",
 			});
 		} finally {
-			await rm(workspace, { recursive: true, force: true });
+			await rm(workspace, {
+				recursive: true,
+				force: true,
+				maxRetries: 3,
+				retryDelay: 250,
+			});
 		}
 	});
 
@@ -168,7 +188,12 @@ describe("createHookConfigFileHooks", () => {
 				context: "python-ok",
 			});
 		} finally {
-			await rm(workspace, { recursive: true, force: true });
+			await rm(workspace, {
+				recursive: true,
+				force: true,
+				maxRetries: 3,
+				retryDelay: 250,
+			});
 		}
 	});
 
@@ -201,7 +226,12 @@ describe("createHookConfigFileHooks", () => {
 					context: "powershell-ok",
 				});
 			} finally {
-				await rm(workspace, { recursive: true, force: true });
+				await rm(workspace, {
+					recursive: true,
+					force: true,
+					maxRetries: 3,
+					retryDelay: 250,
+				});
 			}
 		},
 	);
@@ -231,7 +261,12 @@ describe("createHookConfigFileHooks", () => {
 			expect(payload.hookName).toBe("agent_error");
 			expect(payload.error?.message).toBe("401 unauthorized");
 		} finally {
-			await rm(workspace, { recursive: true, force: true });
+			await rm(workspace, {
+				recursive: true,
+				force: true,
+				maxRetries: 3,
+				retryDelay: 250,
+			});
 		}
 	});
 

package/src/{runtime → hooks}/hook-file-hooks.ts

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { appendFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import type { AgentHooks } from "@clinebot/agents";
 import {
 	augmentNodeCommandForDebug,
@@ -7,7 +8,7 @@ import {
 	type HookSessionContext,
 	withResolvedClineBuildEnv,
 } from "@clinebot/shared";
-import { ensureParentDir } from "@clinebot/shared/storage";
+import { ensureHookLogDir } from "@clinebot/shared/storage";
 import { listHookConfigFiles } from "../extensions/config/hooks-config-loader";
 import type { HookEventName, HookEventPayload } from "../hooks";
 
@@ -42,7 +43,6 @@ type AgentHookSessionShutdownContext = Parameters<
 type HookRuntimeOptions = {
 	cwd: string;
 	workspacePath: string;
-	hookLogPath?: string;
 	rootSessionId?: string;
 	logger?: BasicLogger;
 	toolCallTimeoutMs?: number;
@@ -147,10 +147,6 @@ function isAbortReason(reason?: string): boolean {
 	);
 }
 
-function ensureHookLogDir(filePath: string): void {
-	ensureParentDir(filePath);
-}
-
 function createPayloadBase(
 	ctx: HookContextBase,
 	options: HookRuntimeOptions,
@@ -159,7 +155,6 @@ function createPayloadBase(
 		process.env.CLINE_USER_ID?.trim() || process.env.USER?.trim() || "unknown";
 	const sessionContext: HookSessionContext = {
 		rootSessionId: options.rootSessionId || ctx.conversationId,
-		hookLogPath: options.hookLogPath,
 	};
 	return {
 		clineVersion: process.env.CLINE_VERSION?.trim() || "",
@@ -503,14 +498,12 @@ function runAsyncHookCommands(options: {
 }
 
 export function createHookAuditHooks(options: {
-	hookLogPath: string;
 	rootSessionId?: string;
 	workspacePath: string;
 }): AgentHooks {
 	const runtimeOptions: HookRuntimeOptions = {
 		cwd: options.workspacePath,
 		workspacePath: options.workspacePath,
-		hookLogPath: options.hookLogPath,
 		rootSessionId: options.rootSessionId,
 	};
 
@@ -519,8 +512,10 @@ export function createHookAuditHooks(options: {
 			ts: new Date().toISOString(),
 			...payload,
 		})}\n`;
-		ensureHookLogDir(options.hookLogPath);
-		appendFileSync(options.hookLogPath, line, "utf8");
+		const envPath = process.env.CLINE_HOOKS_LOG_PATH?.trim() || undefined;
+		const logPath = envPath ?? join(ensureHookLogDir(), "hooks.jsonl");
+		ensureHookLogDir(logPath);
+		appendFileSync(logPath, line, "utf8");
 	};
 
 	return {