@mariozechner/pi-coding-agent 0.27.1 → 0.27.3

package/docs/custom-tools.md

@@ -192,7 +192,7 @@ interface ToolSessionEvent {
 
 **Reasons:**
 - `start`: Initial session load on startup
-- `switch`: User switched to a different session (`/session`)
+- `switch`: User switched to a different session (`/resume`)
 - `branch`: User branched from a previous message (`/branch`)
 - `clear`: User cleared the session (`/clear`)
 
@@ -400,12 +400,12 @@ const factory: CustomToolFactory = (pi) => {
 
 ## Examples
 
-See [`examples/custom-tools/todo.ts`](../examples/custom-tools/todo.ts) for a complete example with:
+See [`examples/custom-tools/todo/index.ts`](../examples/custom-tools/todo/index.ts) for a complete example with:
 - `onSession` for state reconstruction
 - Custom `renderCall` and `renderResult`
 - Proper branching support via details storage
 
 Test with:
 ```bash
-pi --tool packages/coding-agent/examples/custom-tools/todo.ts
+pi --tool packages/coding-agent/examples/custom-tools/todo/index.ts
 ```

package/docs/hooks.md

@@ -120,7 +120,7 @@ user branches (/branch)
   ├─► session (reason: "before_branch", can cancel)
   └─► session (reason: "branch", AFTER branch)
 
-user switches session (/session)
+user switches session (/resume)
   │
   ├─► session (reason: "before_switch", can cancel)
   └─► session (reason: "switch", AFTER switch)
@@ -154,13 +154,18 @@ pi.on("session", async (event, ctx) => {
   if (event.reason === "before_clear") {
     return { cancel: true };
   }
-  // No return needed if not cancelling
+
+  // For before_branch only: create branch but skip conversation restore
+  // (useful for checkpoint hooks that restore files separately)
+  if (event.reason === "before_branch") {
+    return { skipConversationRestore: true };
+  }
 });
 ```
 
 **Reasons:**
 - `start`: Initial session load on startup
-- `before_switch` / `switch`: User switched sessions (`/session`)
+- `before_switch` / `switch`: User switched sessions (`/resume`)
 - `before_clear` / `clear`: User cleared the session (`/clear`)
 - `before_branch` / `branch`: User branched the session (`/branch`)
 - `shutdown`: Process is exiting (double Ctrl+C, Ctrl+D, or SIGTERM)

package/docs/sdk.md

@@ -258,10 +258,16 @@ If no model is provided:
 
 ### API Keys
 
+API key resolution priority:
+1. `settings.json` apiKeys (e.g., `{ "apiKeys": { "anthropic": "sk-..." } }`)
+2. Custom providers from `models.json`
+3. OAuth credentials from `oauth.json`
+4. Environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.)
+
 ```typescript
 import { defaultGetApiKey, configureOAuthStorage } from "@mariozechner/pi-coding-agent";
 
-// Default: checks models.json, OAuth, environment variables
+// Default: checks settings.json, models.json, OAuth, environment variables
 const { session } = await createAgentSession();
 
 // Custom resolver
@@ -271,7 +277,7 @@ const { session } = await createAgentSession({
     if (model.provider === "anthropic") {
       return process.env.MY_ANTHROPIC_KEY;
     }
-    // Fall back to default
+    // Fall back to default (pass settingsManager for settings.json lookup)
     return defaultGetApiKey()(model);
   },
 });

package/examples/custom-tools/subagent/index.ts

@@ -203,6 +203,7 @@ async function runSingleAgent(
 	agents: AgentConfig[],
 	agentName: string,
 	task: string,
+	cwd: string | undefined,
 	step: number | undefined,
 	signal: AbortSignal | undefined,
 	onUpdate: OnUpdateCallback | undefined,
@@ -263,7 +264,7 @@ async function runSingleAgent(
 		let wasAborted = false;
 
 		const exitCode = await new Promise<number>((resolve) => {
-			const proc = spawn("pi", args, { cwd: pi.cwd, shell: false, stdio: ["ignore", "pipe", "pipe"] });
+			const proc = spawn("pi", args, { cwd: cwd ?? pi.cwd, shell: false, stdio: ["ignore", "pipe", "pipe"] });
 			let buffer = "";
 
 			const processLine = (line: string) => {
@@ -338,11 +339,13 @@ async function runSingleAgent(
 const TaskItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
 	task: Type.String({ description: "Task to delegate to the agent" }),
+	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 });
 
 const ChainItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
 	task: Type.String({ description: "Task with optional {previous} placeholder for prior output" }),
+	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 });
 
 const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
@@ -357,6 +360,7 @@ const SubagentParams = Type.Object({
 	chain: Type.Optional(Type.Array(ChainItem, { description: "Array of {agent, task} for sequential execution" })),
 	agentScope: Type.Optional(AgentScopeSchema),
 	confirmProjectAgents: Type.Optional(Type.Boolean({ description: "Prompt before running project-local agents. Default: true.", default: true })),
+	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
 });
 
 const factory: CustomToolFactory = (pi) => {
@@ -441,7 +445,7 @@ const factory: CustomToolFactory = (pi) => {
 						}
 					} : undefined;
 					
-					const result = await runSingleAgent(pi, agents, step.agent, taskWithContext, i + 1, signal, chainUpdate, makeDetails("chain"));
+					const result = await runSingleAgent(pi, agents, step.agent, taskWithContext, step.cwd, i + 1, signal, chainUpdate, makeDetails("chain"));
 					results.push(result);
 					
 					const isError = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
@@ -486,7 +490,7 @@ const factory: CustomToolFactory = (pi) => {
 				
 				const results = await mapWithConcurrencyLimit(params.tasks, MAX_CONCURRENCY, async (t, index) => {
 					const result = await runSingleAgent(
-						pi, agents, t.agent, t.task, undefined, signal,
+						pi, agents, t.agent, t.task, t.cwd, undefined, signal,
 						// Per-task update callback
 						(partial) => {
 							if (partial.details?.results[0]) {
@@ -511,7 +515,7 @@ const factory: CustomToolFactory = (pi) => {
 			}
 
 			if (params.agent && params.task) {
-				const result = await runSingleAgent(pi, agents, params.agent, params.task, undefined, signal, onUpdate, makeDetails("single"));
+				const result = await runSingleAgent(pi, agents, params.agent, params.task, params.cwd, undefined, signal, onUpdate, makeDetails("single"));
 				const isError = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
 				if (isError) {
 					const errorMsg = result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mariozechner/pi-coding-agent",
-	"version": "0.27.1",
+	"version": "0.27.3",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"piConfig": {
@@ -39,9 +39,9 @@
 		"prepublishOnly": "npm run clean && npm run build"
 	},
 	"dependencies": {
-		"@mariozechner/pi-agent-core": "^0.27.1",
-		"@mariozechner/pi-ai": "^0.27.1",
-		"@mariozechner/pi-tui": "^0.27.1",
+		"@mariozechner/pi-agent-core": "^0.27.3",
+		"@mariozechner/pi-ai": "^0.27.3",
+		"@mariozechner/pi-tui": "^0.27.3",
 		"chalk": "^5.5.0",
 		"cli-highlight": "^2.1.11",
 		"diff": "^8.0.2",