@oh-my-pi/pi-coding-agent 13.9.5 → 13.9.11

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 ## [Unreleased]
 
+## [13.9.10] - 2026-03-08
+### Added
+
+- Added `env` parameter to bash tool to pass environment variables safely without shell re-parsing, preventing quote and special character bugs with multiline or untrusted values
+- Added support for rendering partial `env` assignments in command preview while tool arguments are still streaming
+- Added `env` support to the bash tool so commands can reference safe shell variables without inline quoting bugs for multiline or quote-heavy values
+
+### Changed
+
+- Changed bash tool to display environment variable assignments in command preview when `env` parameter is used
+
+## [13.9.8] - 2026-03-08
+### Added
+
+- Added docs.rs scraper for extracting Rust crate documentation from rustdoc JSON, including support for modules, functions, structs, traits, enums, and other Rust items with caching
+
+## [13.9.7] - 2026-03-08
+
+### Added
+
+- Added `skipPostPromptRecoveryWait` option to handoff operations to defer recovery work until after handoff completion
+- Added deferred auto-compaction scheduling to allow threshold-triggered handoffs to complete while the original prompt is still unwinding
+
+### Changed
+
+- Extracted handoff document template to dedicated prompt file for improved maintainability and template variable support
+- Changed handoff prompt generation to use template rendering with support for custom focus instructions
+- Refactored internal prompt-in-flight tracking from boolean flag to counter to properly handle nested prompt operations
+- Moved llms.txt endpoint discovery to fallback strategy when rendered page content is low quality, prioritizing page-specific content over site-wide files
+- Enhanced llms.txt endpoint detection to scope candidates to the requested URL path, searching section-specific files before site-wide ones
+
+## [13.9.6] - 2026-03-08
+
+### Added
+
+- Added `glob` parameter to `ast_grep` and `ast_edit` tools for additional glob filtering relative to the `path` parameter
+- Added `combineSearchGlobs` utility function to merge glob patterns from `path` and `glob` parameters
+
+### Changed
+
+- Renamed `patterns` parameter to `pat` in `ast_grep` tool for consistency
+- Renamed `selector` parameter to `sel` in `ast_grep` and `ast_edit` tools for brevity
+- Updated tool documentation with expanded guidance on AST pattern syntax, metavariable usage, and contextual matching strategies
+- Updated `grep` tool to combine glob patterns from `path` and `glob` parameters instead of throwing an error when both are provided
+
 ## [13.9.4] - 2026-03-07
 ### Added
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "13.9.5",
+	"version": "13.9.11",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -41,12 +41,12 @@
 	},
 	"dependencies": {
 		"@mozilla/readability": "^0.6",
-		"@oh-my-pi/omp-stats": "13.9.5",
-		"@oh-my-pi/pi-agent-core": "13.9.5",
-		"@oh-my-pi/pi-ai": "13.9.5",
-		"@oh-my-pi/pi-natives": "13.9.5",
-		"@oh-my-pi/pi-tui": "13.9.5",
-		"@oh-my-pi/pi-utils": "13.9.5",
+		"@oh-my-pi/omp-stats": "13.9.11",
+		"@oh-my-pi/pi-agent-core": "13.9.11",
+		"@oh-my-pi/pi-ai": "13.9.11",
+		"@oh-my-pi/pi-natives": "13.9.11",
+		"@oh-my-pi/pi-tui": "13.9.11",
+		"@oh-my-pi/pi-utils": "13.9.11",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/src/modes/components/tool-execution.ts

@@ -478,7 +478,7 @@ export class ToolExecutionComponent extends Container {
 						},
 						this.#renderState,
 						theme,
-						this.#args, // Pass args for tools that need them
+						this.#getCallArgsForRender(),
 					);
 					if (resultComponent) {
 						this.#contentBox.addChild(ensureInvalidate(resultComponent));
@@ -560,10 +560,14 @@ export class ToolExecutionComponent extends Container {
 			return Math.max(1, Math.min(maxSeconds, value));
 		};
 
-		if (this.#toolName === "bash" && this.#result) {
-			// Pass raw output and expanded state - renderer handles width-aware truncation
-			const output = this.#getTextOutput().trimEnd();
-			context.output = output;
+		if (this.#toolName === "bash") {
+			// Bash needs render context even before a result exists. The renderer uses the pending-call args
+			// plus this context to keep the inline command preview visible while tool-call JSON is still streaming.
+			if (this.#result) {
+				// Pass raw output and expanded state - renderer handles width-aware truncation
+				const output = this.#getTextOutput().trimEnd();
+				context.output = output;
+			}
 			context.expanded = this.#expanded;
 			context.previewLines = BASH_DEFAULT_PREVIEW_LINES;
 			context.timeout = normalizeTimeoutSeconds(this.#args?.timeout, 3600);

package/src/modes/controllers/event-controller.ts

@@ -184,13 +184,19 @@ export class EventController {
 							continue;
 						}
 
+						// Preserve the raw partial JSON for renderers that need to surface fields before the JSON object closes.
+						// Bash uses this to show inline env assignments during streaming instead of popping them in at completion.
+						const renderArgs =
+							"partialJson" in content
+								? { ...content.arguments, __partialJson: content.partialJson }
+								: content.arguments;
 						if (!this.ctx.pendingTools.has(content.id)) {
 							this.#resetReadGroup();
 							this.ctx.chatContainer.addChild(new Text("", 0, 0));
 							const tool = this.ctx.session.getToolByName(content.name);
 							const component = new ToolExecutionComponent(
 								content.name,
-								content.arguments,
+								renderArgs,
 								{
 									showImages: settings.get("terminal.showImages"),
 									editFuzzyThreshold: settings.get("edit.fuzzyThreshold"),
@@ -206,7 +212,7 @@ export class EventController {
 						} else {
 							const component = this.ctx.pendingTools.get(content.id);
 							if (component) {
-								component.updateArgs(content.arguments, content.id);
+								component.updateArgs(renderArgs, content.id);
 							}
 						}
 					}

package/src/modes/utils/ui-helpers.ts

@@ -272,9 +272,13 @@ export class UiHelpers {
 
 					readGroup = null;
 					const tool = this.ctx.session.getToolByName(content.name);
+					const renderArgs =
+						"partialJson" in content
+							? { ...content.arguments, __partialJson: content.partialJson }
+							: content.arguments;
 					const component = new ToolExecutionComponent(
 						content.name,
-						content.arguments,
+						renderArgs,
 						{
 							showImages: settings.get("terminal.showImages"),
 							editFuzzyThreshold: settings.get("edit.fuzzyThreshold"),

package/src/prompts/agents/explore.md

@@ -99,6 +99,7 @@ Given a task, you rapidly investigate the codebase and return structured finding
 <directives>
 - You **MUST** use tools for broad pattern matching / code search as much as possible.
 - You **SHOULD** invoke tools in parallel when possible—this is a short investigation, and you are supposed to finish in a few seconds.
+- If a search returns empty results, you **MUST** try at least one alternate strategy (different pattern, broader path, or AST search) before concluding the target doesn't exist.
 </directives>
 
 <thoroughness>

package/src/prompts/agents/librarian.md

@@ -111,6 +111,8 @@ Before acting, determine what kind of question this is:
 - If you discover undocumented behavior or gotchas, you **MUST** populate `caveats`.
 - When local `node_modules` has the package, you **SHOULD** prefer it over cloning — it reflects the version the project actually uses.
 - You **SHOULD** use `web_search` to find the canonical repo URL and to check for known issues, but the definitive answer **MUST** come from reading source code.
+- If a search or lookup returns empty or unexpectedly few results, you **MUST** try at least 2 fallback strategies (broader query, alternate path, different source) before concluding nothing exists.
+- If the package is absent from local `node_modules` and cloning fails, you **MUST** fall back to `web_search` for official API documentation before reporting failure.
 </directives>
 
 <critical>

package/src/prompts/system/handoff-document.md

@@ -0,0 +1,46 @@
+<critical>
+Write a comprehensive handoff document for another instance of yourself.
+The handoff **MUST** be sufficient for seamless continuation without access to this conversation.
+Output ONLY the handoff document. No preamble, no commentary, no wrapper text.
+</critical>
+
+<instruction>
+Capture exact technical state, not abstractions.
+Include concrete file paths, symbol names, commands run, test results, observed failures, decisions made, and any partial work that materially affects the next step.
+</instruction>
+
+<output>
+Use exactly this structure:
+
+## Goal
+[What the user is trying to accomplish]
+
+## Constraints & Preferences
+- [Any constraints, preferences, or requirements mentioned]
+
+## Progress
+### Done
+- [x] [Completed tasks with specifics]
+
+### In Progress
+- [ ] [Current work if any]
+
+### Pending
+- [ ] [Tasks mentioned but not started]
+
+## Key Decisions
+- **[Decision]**: [Rationale]
+
+## Critical Context
+- [Code snippets, file paths, function/type names, error messages, or data essential to continue]
+- [Repository state if relevant]
+
+## Next Steps
+1. [What should happen next]
+</output>
+
+{{#if additionalFocus}}
+<instruction>
+Additional focus: {{additionalFocus}}
+</instruction>
+{{/if}}

package/src/prompts/system/subagent-system-prompt.md

@@ -29,13 +29,7 @@ Your result **MUST** match this TypeScript interface:
 {{/if}}
 
 {{SECTION_SEPERATOR "Giving Up"}}
-If you cannot complete the assignment, you **MUST** call `submit_result` exactly once with `result.error` describing what you tried and the exact blocker.
+Giving up is a last resort. If truly blocked, you **MUST** call `submit_result` exactly once with `result.error` describing what you tried and the exact blocker.
+You **MUST NOT** give up due to uncertainty, missing information obtainable via tools or repo context, or needing a design decision you can derive yourself.
 
-Giving up is a last resort.
-You **MUST NOT** give up due to uncertainty or missing information obtainable via tools or repo context.
-You **MUST NOT** give up due to requiring a design, you can derive that yourself, more than capable of that.
-
-Proceed with the best approach using the most reasonable option.
-
-You **MUST** keep going until this ticket is closed.
-This matters.
+You **MUST** keep going until this ticket is closed. This matters.

package/src/prompts/system/system-prompt.md

@@ -313,8 +313,9 @@ Today is '{{date}}', and your work begins now. Get it right.
 - You **MUST** use the most specialized tool, **NEVER** `cat` if there's tool.bash, `rg/grep`:tool.grep, `find`:tool.find, `sed`:tool.edit…
 - Every turn **MUST** materially advance the deliverable.
 - You **MUST** default to action. You **MUST NOT** ask for confirmation to continue work. If you hit an error, you **MUST** fix it. If you know the next step, you **MUST** take it. The user will intervene if needed.
-- You **MUST NOT** make speculative edits before understanding the surrounding design.
 - You **MUST** default to informed action. You **MUST NOT** ask for confirmation to continue work. If you hit an error, you **MUST** fix it. If you know the next step, you **MUST** take it. The user will intervene if needed.
+- You **MUST NOT** make speculative edits before understanding the surrounding design.
+- You **MUST NOT** stop calling tools to save round-trips when the task is incomplete. Completeness beats efficiency.
 - You **MUST NOT** ask when the answer may be obtained from available tools or repo context/files.
 - You **MUST** verify the effect. When a task involves a behavioral change, you **MUST** confirm the change is observable before yielding: run the specific test, command, or scenario that covers your change.
 </critical>

package/src/prompts/tools/ast-edit.md

@@ -2,10 +2,16 @@ Performs structural AST-aware rewrites via native ast-grep.
 
 <instruction>
 - Use for codemods and structural rewrites where plain text replace is unsafe
-- Narrow scope with `path` before replacing (`path` accepts files, directories, or glob patterns)
-- Default to language-scoped rewrites in mixed repositories: set `lang` and keep `path` narrow
-- Treat parse issues as a scoping signal: tighten `path`/`lang` before retrying
+- Narrow scope with `path` before replacing (`path` accepts files, directories, or glob patterns; use `glob` for an additional filter relative to `path`)
+- Default to language-scoped rewrites in mixed repositories: set `lang` and keep `path`/`glob` narrow
+- Treat parse issues as a scoping or pattern-shape signal: tighten `path`/`lang`, or rewrite the pattern into valid syntax before retrying
 - Metavariables captured in each rewrite pattern (`$A`, `$$$ARGS`) are substituted into that entry's rewrite template
+- For variadic captures, use `$$$NAME` (not `$$NAME`)
+- Rewrite patterns must parse as valid AST for the target language; if a method or declaration does not parse standalone, wrap it in valid context or switch to a contextual `sel`
+- When using contextual `sel`, the match and replacement target the selected node, not the outer wrapper you used to make the pattern parse
+- For TypeScript declarations and methods, prefer patterns that tolerate annotations you do not care about, e.g. `async function $NAME($$$ARGS): $_ { $$$BODY }` or `class $_ { method($$$ARGS): $_ { $$$BODY } }`
+- Metavariables must be the sole content of an AST node; partial-text metavariables like `prefix$VAR` or `"hello $NAME"` do NOT work in patterns or rewrites
+- To delete matched code, use an empty `out` string: `{"pat":"console.log($$$)","out":""}`
 - Each matched rewrite is a 1:1 structural substitution; you cannot split one capture into multiple nodes or merge multiple captures into one node
 </instruction>
 
@@ -17,14 +23,23 @@ Performs structural AST-aware rewrites via native ast-grep.
 <examples>
 - Rename a call site across a directory:
   `{"ops":[{"pat":"oldApi($$$ARGS)","out":"newApi($$$ARGS)"}],"lang":"typescript","path":"src/"}`
-- Multi-op codemod:
-  `{"ops":[{"pat":"require($A)","out":"import $A"},{"pat":"module.exports = $E","out":"export default $E"}],"lang":"javascript","path":"src/"}`
+- Delete all matching calls (empty `out` removes the matched node):
+  `{"ops":[{"pat":"console.log($$$ARGS)","out":""}],"lang":"typescript","path":"src/"}`
+- Rewrite an import source path:
+  `{"ops":[{"pat":"import { $$$IMPORTS } from \"old-package\"","out":"import { $$$IMPORTS } from \"new-package\""}],"lang":"typescript","path":"src/"}`
+- Modernize to optional chaining (same metavariable enforces identity):
+  `{"ops":[{"pat":"$A && $A()","out":"$A?.()"}],"lang":"typescript","path":"src/"}`
 - Swap two arguments using captures:
   `{"ops":[{"pat":"assertEqual($A, $B)","out":"assertEqual($B, $A)"}],"lang":"typescript","path":"tests/"}`
+- Rename a TypeScript function declaration while tolerating any return type annotation:
+  `{"ops":[{"pat":"async function fetchData($$$ARGS): $_ { $$$BODY }","out":"async function loadData($$$ARGS): $_ { $$$BODY }"}],"sel":"function_declaration","lang":"typescript","path":"src/api.ts"}`
+- Convert Python print calls to logging:
+  `{"ops":[{"pat":"print($$$ARGS)","out":"logger.info($$$ARGS)"}],"lang":"python","path":"src/"}`
 </examples>
 
 <critical>
 - `ops` **MUST** contain at least one concrete `{ pat, out }` entry
 - If the path pattern spans multiple languages, set `lang` explicitly for deterministic rewrites
+- Parse issues mean the rewrite request is malformed or mis-scoped; do not assume a clean no-op until the pattern parses successfully
 - For one-off local text edits, prefer the Edit tool instead of AST edit
 </critical>

package/src/prompts/tools/ast-grep.md

@@ -2,14 +2,22 @@ Performs structural code search using AST matching via native ast-grep.
 
 <instruction>
 - Use this when syntax shape matters more than raw text (calls, declarations, specific language constructs)
-- Prefer a precise `path` scope to keep results targeted and deterministic (`path` accepts files, directories, or glob patterns)
-- Default to language-scoped search in mixed repositories: pair `path` glob + explicit `lang` to avoid parse-noise from non-source files
-- `patterns` is required and must include at least one non-empty AST pattern; `lang` is optional (`lang` is inferred per file extension when omitted)
+- Prefer a precise `path` scope to keep results targeted and deterministic (`path` accepts files, directories, or glob patterns; use `glob` for an additional filter relative to `path`)
+- Default to language-scoped search in mixed repositories: pair `path` + `glob` + explicit `lang` to avoid parse-noise from non-source files
+- `pat` is required and must include at least one non-empty AST pattern; `lang` is optional (`lang` is inferred per file extension when omitted)
 - Multiple patterns run in one native pass; results are merged and then `offset`/`limit` are applied to the combined match set
-- Use `selector` only for contextual pattern mode; otherwise provide direct patterns
+- Use `sel` only for contextual pattern mode; otherwise provide direct patterns
+- In contextual pattern mode, results are returned for the selected node (`sel`), not the outer wrapper used to make the pattern parse
 - For variadic arguments/fields, use `$$$NAME` (not `$$NAME`)
+- Patterns must parse as a single valid AST node for the target language; if a bare pattern fails, wrap it in valid context or use `sel`
 - Patterns match AST structure, not text — whitespace/formatting differences are ignored
 - When the same metavariable appears multiple times, all occurrences must match identical code
+- For TypeScript declarations and methods, prefer shapes that tolerate annotations you do not care about, e.g. `async function $NAME($$$ARGS): $_ { $$$BODY }` or `class $_ { method($$$ARGS): $_ { $$$BODY } }` instead of omitting the return type entirely
+- Metavariables must be the sole content of an AST node; partial-text metavariables like `prefix$VAR`, `"hello $NAME"`, or `a $OP b` do NOT work — match the whole node instead
+- `$$$` captures are lazy (non-greedy): they stop when the next element in the pattern can match; place the most specific node after `$$$` to control where capture ends
+- `$_` is a non-capturing wildcard (matches any single node without binding); use it when you need to tolerate a node but don't need its value
+- Search the right declaration form before concluding absence: top-level function, class method, and variable-assigned function are different AST shapes
+- If you only need to prove a symbol exists, prefer a looser contextual search such as `pat: ["executeBash"]` with `sel: "identifier"`
 </instruction>
 
 <output>
@@ -19,16 +27,25 @@ Performs structural code search using AST matching via native ast-grep.
 
 <examples>
 - Find all console logging calls in one pass (multi-pattern, scoped):
-  `{"patterns":["console.log($$$)","console.error($$$)"],"lang":"typescript","path":"src/"}`
-- Capture and inspect metavariable bindings from a pattern:
-  `{"patterns":["require($MOD)"],"lang":"javascript","path":"src/"}`
+  `{"pat":["console.log($$$)","console.error($$$)"],"lang":"typescript","path":"src/"}`
+- Find all named imports from a specific package:
+  `{"pat":["import { $$$IMPORTS } from \"react\""],"lang":"typescript","path":"src/"}`
+- Match arrow functions assigned to a const (different AST shape than function declarations):
+  `{"pat":["const $NAME = ($$$ARGS) => $BODY"],"lang":"typescript","path":"src/utils/"}`
+- Match any method call on an object using wildcard `$_` (ignores method name):
+  `{"pat":["logger.$_($$$ARGS)"],"lang":"typescript","path":"src/"}`
 - Contextual pattern with selector — match only the identifier `foo`, not the whole call:
-  `{"patterns":["foo()"],"selector":"identifier","lang":"typescript","path":"src/utils.ts"}`
+  `{"pat":["foo()"],"sel":"identifier","lang":"typescript","path":"src/utils.ts"}`
+- Match a TypeScript function declaration without caring about its exact return type:
+  `{"pat":["async function processItems($$$ARGS): $_ { $$$BODY }"],"sel":"function_declaration","lang":"typescript","path":"src/worker.ts"}`
+- Loosest existence check for a symbol in one file:
+  `{"pat":["processItems"],"sel":"identifier","lang":"typescript","path":"src/worker.ts"}`
 </examples>
 
 <critical>
-- `patterns` is required
+- `pat` is required
 - Set `lang` explicitly to constrain matching when path pattern spans mixed-language trees
 - Avoid repo-root AST scans when the target is language-specific; narrow `path` first
+- Treat parse issues as query failure, not evidence of absence: repair the pattern or tighten `path`/`glob`/`lang` before concluding "no matches"
 - If exploration is broad/open-ended across subsystems, use Task tool with explore subagent first
 </critical>

package/src/prompts/tools/bash.md

@@ -2,6 +2,8 @@ Executes bash command in shell session for terminal operations like git, bun, ca
 
 <instruction>
 - You **MUST** use `cwd` parameter to set working directory instead of `cd dir && …`
+- Prefer `env: { NAME: "…" }` for multiline, quote-heavy, or untrusted values instead of inlining them into shell syntax; reference them from the command as `$NAME`
+- Quote variable expansions like `"$NAME"` to preserve exact content and avoid shell parsing bugs
 - PTY mode is opt-in: set `pty: true` only when command expects a real terminal (for example `sudo`, `ssh` where you need input from the user); default is `false`
 - You **MUST** use `;` only when later commands should run regardless of earlier failures
 - `skill://` URIs are auto-resolved to filesystem paths before execution

package/src/session/agent-session.ts

@@ -89,6 +89,7 @@ import { getCurrentThemeName, theme } from "../modes/theme/theme";
 import { normalizeDiff, normalizeToLF, ParseError, previewPatch, stripBom } from "../patch";
 import type { PlanModeState } from "../plan-mode/state";
 import autoHandoffThresholdFocusPrompt from "../prompts/system/auto-handoff-threshold-focus.md" with { type: "text" };
+import handoffDocumentPrompt from "../prompts/system/handoff-document.md" with { type: "text" };
 import planModeActivePrompt from "../prompts/system/plan-mode-active.md" with { type: "text" };
 import planModeReferencePrompt from "../prompts/system/plan-mode-reference.md" with { type: "text" };
 import planModeToolDecisionReminderPrompt from "../prompts/system/plan-mode-tool-decision-reminder.md" with {
@@ -260,6 +261,7 @@ export interface HandoffResult {
 interface HandoffOptions {
 	autoTriggered?: boolean;
 	signal?: AbortSignal;
+	skipPostPromptRecoveryWait?: boolean;
 }
 
 /** Internal marker for hook messages queued through the agent loop */
@@ -397,7 +399,7 @@ export class AgentSession {
 	#streamingEditAbortTriggered = false;
 	#streamingEditCheckedLineCounts = new Map<string, number>();
 	#streamingEditFileCache = new Map<string, string>();
-	#promptInFlight = false;
+	#promptInFlightCount = 0;
 	#obfuscator: SecretObfuscator | undefined;
 	#pendingActionStore: PendingActionStore | undefined;
 	#checkpointState: CheckpointState | undefined = undefined;
@@ -1560,7 +1562,7 @@ export class AgentSession {
 
 	/** Whether agent is currently streaming a response */
 	get isStreaming(): boolean {
-		return this.agent.state.isStreaming || this.#promptInFlight;
+		return this.agent.state.isStreaming || this.#promptInFlightCount > 0;
 	}
 
 	/** Wait until streaming and deferred recovery work are fully settled. */
@@ -1999,7 +2001,7 @@ export class AgentSession {
 			skipPostPromptRecoveryWait?: boolean;
 		},
 	): Promise<void> {
-		this.#promptInFlight = true;
+		this.#promptInFlightCount++;
 		const generation = this.#promptGeneration;
 		try {
 			// Flush any pending bash messages before the new prompt
@@ -2109,7 +2111,7 @@ export class AgentSession {
 				await this.#waitForPostPromptRecovery();
 			}
 		} finally {
-			this.#promptInFlight = false;
+			this.#promptInFlightCount = Math.max(0, this.#promptInFlightCount - 1);
 		}
 	}
 
@@ -2508,11 +2510,10 @@ export class AgentSession {
 		this.#cancelPostPromptTasks();
 		this.agent.abort();
 		await this.agent.waitForIdle();
-		// Clear promptInFlight: waitForIdle resolves when the agent loop's finally
-		// block runs (#resolveRunningPrompt), but #promptWithMessage's finally
-		// (#promptInFlight = false) fires on a later microtask. Without this,
-		// isStreaming stays true and a subsequent prompt() throws.
-		this.#promptInFlight = false;
+		// Clear prompt-in-flight state: waitForIdle resolves when the agent loop's finally
+		// block runs, but nested prompt setup/finalizers may still be unwinding. Without this,
+		// a subsequent prompt() can incorrectly observe the session as busy after an abort.
+		this.#promptInFlightCount = 0;
 	}
 
 	/**
@@ -3194,41 +3195,9 @@ export class AgentSession {
 		}
 
 		// Build the handoff prompt
-		let handoffPrompt = `Write a comprehensive handoff document that will allow another instance of yourself to seamlessly continue this work. The document should capture everything needed to resume without access to this conversation.
-
-Use this format:
-
-## Goal
-[What the user is trying to accomplish]
-
-## Constraints & Preferences
-- [Any constraints, preferences, or requirements mentioned]
-
-## Progress
-### Done
-- [x] [Completed tasks with specifics]
-
-### In Progress
-- [ ] [Current work if any]
-
-### Pending
-- [ ] [Tasks mentioned but not started]
-
-## Key Decisions
-- **[Decision]**: [Rationale]
-
-## Critical Context
-- [Code snippets, file paths, error messages, or data essential to continue]
-- [Repository state if relevant]
-
-## Next Steps
-1. [What should happen next]
-
-Be thorough - include exact file paths, function names, error messages, and technical details. Output ONLY the handoff document, no other text.`;
-
-		if (customInstructions) {
-			handoffPrompt += `\n\nAdditional focus: ${customInstructions}`;
-		}
+		const handoffPrompt = renderPromptTemplate(handoffDocumentPrompt, {
+			additionalFocus: customInstructions,
+		});
 
 		// Create a promise that resolves when the agent completes
 		let handoffText: string | undefined;
@@ -3273,11 +3242,16 @@ Be thorough - include exact file paths, function names, error messages, and tech
 			if (handoffSignal.aborted) {
 				throw new Error("Handoff cancelled");
 			}
-			await this.prompt(handoffPrompt, {
-				expandPromptTemplates: false,
-				synthetic: true,
-				skipCompactionCheck: true,
-			});
+			await this.#promptWithMessage(
+				{
+					role: "developer",
+					content: [{ type: "text", text: handoffPrompt }],
+					attribution: "agent",
+					timestamp: Date.now(),
+				},
+				handoffPrompt,
+				{ skipCompactionCheck: true, skipPostPromptRecoveryWait: options?.skipPostPromptRecoveryWait },
+			);
 			await completionPromise;
 
 			if (handoffCancelled || handoffSignal.aborted) {
@@ -3730,11 +3704,22 @@ Be thorough - include exact file paths, function names, error messages, and tech
 	/**
 	 * Internal: Run auto-compaction with events.
 	 */
-	async #runAutoCompaction(reason: "overflow" | "threshold", willRetry: boolean): Promise<void> {
+	async #runAutoCompaction(reason: "overflow" | "threshold", willRetry: boolean, deferred = false): Promise<void> {
 		const compactionSettings = this.settings.getGroup("compaction");
-
 		if (!compactionSettings.enabled || compactionSettings.strategy === "off") return;
 		const generation = this.#promptGeneration;
+		if (!deferred && reason !== "overflow" && compactionSettings.strategy === "handoff") {
+			this.#schedulePostPromptTask(
+				async signal => {
+					await Promise.resolve();
+					if (signal.aborted) return;
+					await this.#runAutoCompaction(reason, willRetry, true);
+				},
+				{ generation },
+			);
+			return;
+		}
+
 		let action: "context-full" | "handoff" =
 			compactionSettings.strategy === "handoff" && reason !== "overflow" ? "handoff" : "context-full";
 		await this.#emitSessionEvent({ type: "auto_compaction_start", reason, action });
@@ -3750,6 +3735,7 @@ Be thorough - include exact file paths, function names, error messages, and tech
 				const handoffResult = await this.handoff(handoffFocus, {
 					autoTriggered: true,
 					signal: this.#autoCompactionAbortController.signal,
+					skipPostPromptRecoveryWait: true,
 				});
 				if (!handoffResult) {
 					const aborted = this.#autoCompactionAbortController.signal.aborted;
@@ -4028,15 +4014,25 @@ Be thorough - include exact file paths, function names, error messages, and tech
 			await this.#emitSessionEvent({ type: "auto_compaction_end", action, result, aborted: false, willRetry });
 
 			if (!willRetry && compactionSettings.autoContinue !== false) {
-				await this.#promptWithMessage(
-					{
-						role: "developer",
-						content: [{ type: "text", text: "Continue if you have next steps." }],
-						attribution: "agent",
-						timestamp: Date.now(),
+				const continuePrompt = async () => {
+					await this.#promptWithMessage(
+						{
+							role: "developer",
+							content: [{ type: "text", text: "Continue if you have next steps." }],
+							attribution: "agent",
+							timestamp: Date.now(),
+						},
+						"Continue if you have next steps.",
+						{ skipPostPromptRecoveryWait: true },
+					);
+				};
+				this.#schedulePostPromptTask(
+					async signal => {
+						await Promise.resolve();
+						if (signal.aborted) return;
+						await continuePrompt();
 					},
-					"Continue if you have next steps.",
-					{ skipPostPromptRecoveryWait: true },
+					{ generation },
 				);
 			}
 

package/src/tools/ast-edit.ts

@@ -14,7 +14,7 @@ import { Ellipsis, Hasher, type RenderCache, renderStatusLine, renderTreeList, t
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import type { ToolSession } from ".";
 import type { OutputMeta } from "./output-meta";
-import { hasGlobPathChars, parseSearchPath, resolveToCwd } from "./path-utils";
+import { combineSearchGlobs, hasGlobPathChars, parseSearchPath, resolveToCwd } from "./path-utils";
 import {
 	dedupeParseErrors,
 	formatCount,
@@ -38,7 +38,8 @@ const astEditSchema = Type.Object({
 	}),
 	lang: Type.Optional(Type.String({ description: "Language override" })),
 	path: Type.Optional(Type.String({ description: "File, directory, or glob pattern to rewrite (default: cwd)" })),
-	selector: Type.Optional(Type.String({ description: "Optional selector for contextual pattern mode" })),
+	glob: Type.Optional(Type.String({ description: "Optional glob filter relative to path" })),
+	sel: Type.Optional(Type.String({ description: "Optional selector for contextual pattern mode" })),
 	limit: Type.Optional(Type.Number({ description: "Max total replacements" })),
 });
 
@@ -98,7 +99,7 @@ export class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolD
 			const maxFiles = parseInt(process.env.PI_MAX_AST_FILES ?? "", 10) || 1000;
 
 			let searchPath: string | undefined;
-			let globFilter: string | undefined;
+			let globFilter = params.glob?.trim() || undefined;
 			const rawPath = params.path?.trim();
 			if (rawPath) {
 				const internalRouter = this.session.internalRouter;
@@ -114,7 +115,7 @@ export class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolD
 				} else {
 					const parsedPath = parseSearchPath(rawPath);
 					searchPath = resolveToCwd(parsedPath.basePath, this.session.cwd);
-					globFilter = parsedPath.glob;
+					globFilter = combineSearchGlobs(parsedPath.glob, globFilter);
 				}
 			}
 
@@ -133,7 +134,7 @@ export class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolD
 				lang: params.lang?.trim(),
 				path: resolvedSearchPath,
 				glob: globFilter,
-				selector: params.selector?.trim(),
+				selector: params.sel?.trim(),
 				dryRun: true,
 				maxReplacements,
 				maxFiles,
@@ -277,7 +278,7 @@ export class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolD
 							lang: params.lang?.trim(),
 							path: resolvedSearchPath,
 							glob: globFilter,
-							selector: params.selector?.trim(),
+							selector: params.sel?.trim(),
 							dryRun: false,
 							maxReplacements,
 							maxFiles,
@@ -320,7 +321,7 @@ interface AstEditRenderArgs {
 	ops?: Array<{ pat?: string; out?: string }>;
 	lang?: string;
 	path?: string;
-	selector?: string;
+	sel?: string;
 	limit?: number;
 }