@raoxxxwq/pi-codebuddy-sdk 0.5.0 → 0.6.0

package/README.md

@@ -9,6 +9,7 @@ Pi extension that registers **CodeBuddy** as a model provider. You keep using Pi
 
 - Exposes CodeBuddy models in Pi (`codebuddy/...` in `/model`)
 - Bridges Pi tools to the SDK (Pi still executes tools; CodeBuddy only plans and calls them)
+- Enforces one bridged tool call per assistant turn on the main Provider Path for stability
 - Forwards Pi's system prompt, skills, and project `AGENTS.md` so the model acts as Pi—not as standalone CodeBuddy Code
 - Supports session resume, compaction, streaming, thinking levels, and images
 - Learns runtime-served context windows over time and keeps Pi's registered model metadata conservatively aligned with observed reality
@@ -79,34 +80,61 @@ Pick any entry prefixed with `codebuddy/` (for example `codebuddy/hy3-preview-ag
 
 Tools, skills, extensions, `/compact`, and steer behave the same as with other Pi providers.
 
+### AskCodebuddy
+
+When the AskCodebuddy tool is enabled (default), any provider can delegate a focused sub-task to a separate CodeBuddy call. This is the **Delegation Path** — unlike the main Provider Path, CodeBuddy runs its own native tools directly (not Pi-bridged MCP tools).
+
+- `"read"` mode (default): codebase questions — review, analysis, explain.
+- `"full"` mode: allows writing and bash execution (runs without feedback to Pi — use with care).
+- `"none"` mode: general knowledge only (no file access).
+
+AskCodebuddy is blocked automatically when the active provider is already `codebuddy/...` (prevents circular delegation).
+
 ## Configuration
 
 **Optional.** Defaults work for most users.
 
-File: `~/.pi/agent/codebuddy-sdk.json` or `.pi/codebuddy-sdk.json` in a project.
+File: `~/.pi/agent/codebuddy-sdk.json` (global) or `.pi/codebuddy-sdk.json` (project). Project config overrides global.
 
 ```json
 {
   "askCodebuddy": {
     "enabled": true,
-    "allowFullMode": true
+    "allowFullMode": true,
+    "defaultMode": "read"
   },
   "provider": {
     "appendSystemPrompt": true,
-    "strictMcpConfig": true,
     "pathToCodebuddyCode": "/path/to/codebuddy"
   }
 }
 ```
 
+### AskCodebuddy options
+
 | Option | Default | Meaning |
 |--------|---------|---------|
 | `askCodebuddy.enabled` | `true` | Register the AskCodebuddy delegation tool |
-| `askCodebuddy.allowFullMode` | `true` | Allow write-capable delegation mode |
-| `provider.appendSystemPrompt` | `true` | Use Pi's system prompt and Pi Tool Bridge guidance instead of CodeBuddy's default identity; disable only for debugging/compatibility |
-| `provider.strictMcpConfig` | `true` | Use only Pi-bridged MCP tools so Pi remains the tool execution boundary; disable only for debugging/compatibility |
+| `askCodebuddy.allowFullMode` | `true` | Allow write-capable (`"full"`) delegation mode |
+| `askCodebuddy.defaultMode` | `"read"` | Default delegation mode: `"read"` (file access), `"full"` (write + bash), or `"none"` (general knowledge) |
+| `askCodebuddy.defaultIsolated` | `false` | Default whether the delegation runs in a clean session (no conversation history) |
+| `askCodebuddy.appendSkills` | `true` | Include Pi skills block in the delegation system prompt |
+| `askCodebuddy.name` | `"AskCodebuddy"` | Tool name |
+| `askCodebuddy.label` | `"Ask CodeBuddy"` | Tool label shown in the Pi TUI |
+| `askCodebuddy.description` | auto | Tool description shown in Pi |
+
+### Provider options
+
+These control the main Provider Path (when you pick `codebuddy/...` in `/model`). Options marked **escape hatch** are not for everyday tuning — disable only for debugging or compatibility.
+
+| Option | Default | Meaning |
+|--------|---------|---------|
+| `provider.appendSystemPrompt` | `true` | Use Pi's system prompt and Pi Tool Bridge guidance instead of CodeBuddy's default identity (**escape hatch** — disabling re-enables CodeBuddy filesystem settings) |
+| `provider.settingSources` | `["user","project"]` | CodeBuddy filesystem settings to load; only used when `appendSystemPrompt=false` (**escape hatch**) |
 | `provider.pathToCodebuddyCode` | auto | Path to `codebuddy` when it is **not** on `PATH` |
 
+The main Provider Path always runs with strict MCP enabled, so only the Pi-bridged MCP server is visible to CodeBuddy in provider mode.
+
 ## Privacy
 
 - The extension does **not** send conversation data to this repository or any third-party telemetry endpoint.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raoxxxwq/pi-codebuddy-sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Pi extension that uses CodeBuddy (via Agent SDK) as a model provider and adds an AskCodebuddy tool.",
   "author": "raoxxxwq",
   "license": "MIT",

package/src/config.ts

@@ -25,8 +25,6 @@ export interface Config {
 	provider?: {
 		appendSystemPrompt?: boolean;
 		settingSources?: SettingSource[];
-		strictMcpConfig?: boolean;
-		serialToolCalls?: boolean;
 		pathToCodebuddyCode?: string;
 	};
 }

package/src/index.ts

@@ -666,6 +666,9 @@ export const __test = {
 	syncSharedSession,
 	isEmptyArgs,
 	hasRequiredParams,
+	claimSerialToolUse,
+	interruptLiveQuery,
+	processStreamEvent,
 };
 
 function createDelegationSessionFromContext(
@@ -699,16 +702,10 @@ function stripToolHistoryForDelegation(messages: Context["messages"]): Context["
 
 function buildProviderBoundaryOptions(settings: NonNullable<Config["provider"]>) {
 	const appendSystemPrompt = settings.appendSystemPrompt !== false;
-	const strictMcpConfigEnabled = settings.strictMcpConfig !== false;
-	const serialToolCalls = settings.serialToolCalls !== false;
-	const extraArgs: Record<string, string | null> = {};
-	if (strictMcpConfigEnabled) extraArgs["strict-mcp-config"] = null;
 	return {
 		appendSystemPrompt,
-		strictMcpConfigEnabled,
-		serialToolCalls,
 		tools: [] as string[],
-		extraArgs,
+		extraArgs: { "strict-mcp-config": null } as Record<string, string | null>,
 		settingSources: appendSystemPrompt
 			? undefined
 			: settings.settingSources ?? ["user", "project"] as SettingSource[],
@@ -783,6 +780,18 @@ function hasRequiredParams(toolName: string, tools: Tool[]): boolean {
 	return Array.isArray(required) && required.length > 0;
 }
 
+function claimSerialToolUse(queryCtx: QueryContext, toolUseId: string): boolean {
+	if (!queryCtx.claimedToolUseId) {
+		queryCtx.claimedToolUseId = toolUseId;
+		return true;
+	}
+	return queryCtx.claimedToolUseId === toolUseId;
+}
+
+function interruptLiveQuery(ref: { current?: { interrupt?: () => Promise<void> | void } }): void {
+	void ref.current?.interrupt?.();
+}
+
 // Renames for CodeBuddy SDK param names that differ from pi's native names.
 // Keys not listed here pass through unchanged, so new pi params work automatically.
 const SDK_KEY_RENAMES: Record<string, Record<string, string>> = {
@@ -1137,7 +1146,6 @@ function processStreamEvent(
 			c.turnBlocks.push({ type: "thinking", thinking: "", thinkingSignature: "", index: event.index });
 			c.currentPiStream!.push({ type: "thinking_start", contentIndex: c.turnBlocks.length - 1, partial: c.turnOutput });
 		} else if (event.content_block?.type === "tool_use") {
-			c.turnToolCallIds.push(event.content_block.id);
 			c.turnToolCallIds.push(event.content_block.id);
 			c.turnBlocks.push({
 				type: "toolCall", id: event.content_block.id,
@@ -1583,7 +1591,7 @@ function streamCodebuddySdk(model: Model<any>, context: Context, options?: Simpl
 	const boundaryOptions = buildProviderBoundaryOptions(providerSettings);
 	const appendSystemPrompt = boundaryOptions.appendSystemPrompt;
 	const systemPrompt = appendSystemPrompt
-		? buildCodebuddySystemPrompt(context.systemPrompt, { availableToolNames: mcpTools.map((tool) => tool.name), serialToolCalls: boundaryOptions.serialToolCalls })
+		? buildCodebuddySystemPrompt(context.systemPrompt, { availableToolNames: mcpTools.map((tool) => tool.name) })
 		: undefined;
 
 	// Provider Path keeps CodeBuddy inside Pi's tool boundary: no built-in SDK
@@ -1639,22 +1647,31 @@ function streamCodebuddySdk(model: Model<any>, context: Context, options?: Simpl
 				toolUseID: opts.toolUseID,
 			};
 		}
+		if (!claimSerialToolUse(queryCtx, opts.toolUseID)) {
+			debug(`canUseTool: rejecting ${toolName}→${piName} — serial mode already claimed by ${queryCtx.claimedToolUseId} (toolUseId=${opts.toolUseID})`);
+			return {
+				behavior: "deny" as const,
+				message: `Only one tool call is allowed per assistant turn. Wait for the current tool result before calling another tool in a later turn.`,
+				toolUseID: opts.toolUseID,
+			};
+		}
 		return { behavior: "allow" as const, toolUseID: opts.toolUseID };
 	};
 
 	debug("provider: fresh query",
 		`model=${cliModel} msgs=${context.messages.length} tools=${mcpTools.length}`,
 		`resume=${resumeSessionId?.slice(0, 8) ?? "none"} effort=${effort ?? "default"}`,
-		`appendSys=${appendSystemPrompt} strictMcp=${boundaryOptions.strictMcpConfigEnabled}`,
+		`appendSys=${appendSystemPrompt} strictMcp=true`,
 		`promptLen=${promptText.length}${promptBlocks ? " [+images]" : ""}`);
 
 	// 3. Start SDK query (wait for model discovery + serialize SDK subprocess access)
 	let wasAborted = false;
 	let sdkQuery: ReturnType<typeof query> | undefined;
+	const liveQueryRef: { current?: ReturnType<typeof query> } = {};
 	const abortCtx = queryCtx;
 
 	const requestAbort = () => {
-		void sdkQuery?.interrupt().catch(() => {});
+		interruptLiveQuery(liveQueryRef);
 	};
 	const onAbort = () => {
 		wasAborted = true;
@@ -1669,11 +1686,12 @@ function streamCodebuddySdk(model: Model<any>, context: Context, options?: Simpl
 		else options.signal.addEventListener("abort", onAbort, { once: true });
 	}
 
-	void (async () => {
-		await ensureModelsDiscovered();
-		sdkQuery = query({ prompt, options: queryOptions });
-		queryCtx.activeQuery = sdkQuery;
-		activeQueryContexts.add(queryCtx);
+		void (async () => {
+			await ensureModelsDiscovered();
+			sdkQuery = query({ prompt, options: queryOptions });
+			liveQueryRef.current = sdkQuery;
+			queryCtx.activeQuery = sdkQuery;
+			activeQueryContexts.add(queryCtx);
 
 		try {
 			const { capturedSessionId } = await consumeQuery(sdkQuery, customToolNameToPi, model, () => wasAborted, queryCtx);
@@ -1719,10 +1737,11 @@ function streamCodebuddySdk(model: Model<any>, context: Context, options?: Simpl
 					break;
 				}
 
-				const contOptions = { ...queryOptions, resume: resumeId, ...makeCliDebugOptions("continuation") };
-				const contQuery = query({ prompt: steerPrompt, options: contOptions });
-				queryCtx.activeQuery = contQuery;
-				debug(`provider: continuation query, model=${cliModel}, resume=${resumeId.slice(0, 8)}, promptLen=${steerPrompt.length}`);
+					const contOptions = { ...queryOptions, resume: resumeId, ...makeCliDebugOptions("continuation") };
+					const contQuery = query({ prompt: steerPrompt, options: contOptions });
+					liveQueryRef.current = contQuery;
+					queryCtx.activeQuery = contQuery;
+					debug(`provider: continuation query, model=${cliModel}, resume=${resumeId.slice(0, 8)}, promptLen=${steerPrompt.length}`);
 
 				try {
 					const { capturedSessionId: contSid } = await consumeQuery(contQuery, customToolNameToPi, model, () => wasAborted, queryCtx);
@@ -1768,6 +1787,7 @@ function streamCodebuddySdk(model: Model<any>, context: Context, options?: Simpl
 			queryCtx.currentPiStream = null;
 		} finally {
 			if (options?.signal) options.signal.removeEventListener("abort", onAbort);
+			liveQueryRef.current = undefined;
 			if (queryCtx.activeQuery === sdkQuery) {
 				for (const pending of queryCtx.pendingToolCalls.values()) { pending.resolve({ content: [{ type: "text", text: "Query ended" }] }); }
 				queryCtx.pendingToolCalls.clear();

package/src/query-state.ts

@@ -41,6 +41,10 @@ export class QueryContext {
 	// Prevents double-deferral and lets the assistant-message path know it
 	// must emit the done event after backfilling.
 	doneDeferredForArgs = false;
+	// First toolUseID observed by canUseTool in this assistant turn.
+	// Any different toolUseID in the same turn is denied so provider-path
+	// tools always execute serially.
+	claimedToolUseId: string | null = null;
 
 	// Per-turn (reset together)
 	turnOutput: AssistantMessage | null = null;
@@ -66,6 +70,7 @@ export class QueryContext {
 		this.turnSawToolCall = false;
 		this.argsPendingBlocks = [];
 		this.doneDeferredForArgs = false;
+		this.claimedToolUseId = null;
 		this.matchedToolCallIds = new Set();
 		// turnToolCallIds and nextHandlerIdx are NOT reset — they persist across
 		// tool-result delivery callbacks within the same assistant message.

package/src/skills.ts

@@ -20,7 +20,6 @@ const BUILTIN_TOOL_GUIDANCE: Record<string, string> = {
 
 export interface ToolBridgeInstructionOptions {
 	availableToolNames?: Iterable<string>;
-	serialToolCalls?: boolean;
 }
 
 function normalizeToolNames(names: Iterable<string> | undefined): Set<string> {
@@ -72,18 +71,14 @@ export function buildPiToolBridgeInstruction(options: ToolBridgeInstructionOptio
 	if (has("bash")) {
 		lines.push(`- Use \`${mcpName("bash")}\` only when file tools are insufficient, for search/test/build/git information, or when command execution is requested.`);
 	}
-	if (options.serialToolCalls !== false) {
-		// Force serial tool calls. CodeBuddy's MCP client drops arguments for
-		// 2nd+ parallel tool_call blocks in a single response: the
-		// content_block_stop for those blocks never arrives, so pi finalizes a
-		// dangling toolcall_start with empty {} args and the call fails
-		// validation. Instructing one-tool-per-turn avoids the failure at the
-		// source. The stream-side backfill defense cannot catch this because it
-		// keys off content_block_stop, which never fires for the dropped call.
-		lines.push("Call AT MOST ONE tool per turn. Never emit multiple tool_call blocks in a single response. Issue one tool call, wait for its result, then decide the next call in the following turn. Parallel tool calls are unsupported and will fail.");
-	} else if (toolNames.size > 1) {
-		lines.push("When calling multiple tools in a single response, ensure each tool_call has complete arguments — do not leave required fields empty or rely on defaults. Incomplete parallel tool calls will be rejected.");
-	}
+	// Force serial tool calls. CodeBuddy's MCP client drops arguments for
+	// 2nd+ parallel tool_call blocks in a single response: the
+	// content_block_stop for those blocks never arrives, so pi finalizes a
+	// dangling toolcall_start with empty {} args and the call fails
+	// validation. Instructing one-tool-per-turn avoids the failure at the
+	// source. The stream-side backfill defense cannot catch this because it
+	// keys off content_block_stop, which never fires for the dropped call.
+	lines.push("Call AT MOST ONE tool per turn. Never emit multiple tool_call blocks in a single response. A second tool call in the same turn will be denied. Issue one tool call, wait for its result, then decide the next call in the following turn. Parallel tool calls are unsupported and will fail.");
 	lines.push("Tool arguments must match the Pi tool schema exactly. After a tool result, base the next step on that result; if it is an error, correct the call instead of assuming success.");
 
 	return lines.join("\n");
@@ -140,13 +135,13 @@ function applySkillsRewrite(systemPrompt: string): string {
 /** Pi system prompt as CodeBuddy override (replaces default "CodeBuddy Code" identity). */
 export function buildCodebuddySystemPrompt(
 	piSystemPrompt: string | undefined,
-	options?: { includeAgents?: boolean; includeSkills?: boolean; includeToolBridge?: boolean; availableToolNames?: Iterable<string>; serialToolCalls?: boolean },
+	options?: { includeAgents?: boolean; includeSkills?: boolean; includeToolBridge?: boolean; availableToolNames?: Iterable<string> },
 ): string | undefined {
 	const parts: string[] = [];
 	const includeToolBridge = options?.includeToolBridge !== false;
 
 	if (includeToolBridge) {
-		parts.push(buildPiToolBridgeInstruction({ availableToolNames: options?.availableToolNames, serialToolCalls: options?.serialToolCalls }));
+		parts.push(buildPiToolBridgeInstruction({ availableToolNames: options?.availableToolNames }));
 	}
 
 	if (piSystemPrompt) {