@oh-my-pi/pi-coding-agent 13.0.2 → 13.1.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [13.1.0] - 2026-02-23
+### Breaking Changes
+
+- Renamed `file` parameter to `path` in replace, patch, and hashline edit operations
+
+### Added
+
+- Added clarification in hashline edit documentation that the `end` tag must include closing braces/brackets when replacing blocks to prevent syntax errors
+
+### Changed
+
+- Restructured task tool documentation for clarity, moving parameter definitions into a dedicated section and consolidating guidance on context, assignments, and parallelization
+- Reformatted system prompt template to use markdown headings instead of XML tags for skills, preloaded skills, and rules sections
+- Renamed `deviceScaleFactor` parameter to `device_scale_factor` in browser viewport configuration for consistency with snake_case naming convention
+- Moved intent field documentation from per-tool JSON schema descriptions into a single system prompt block, reducing token overhead proportional to tool count
+
 ## [13.0.1] - 2026-02-22
 ### Changed
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "13.0.2",
+	"version": "13.1.0",
 	"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.0.2",
-		"@oh-my-pi/pi-agent-core": "13.0.2",
-		"@oh-my-pi/pi-ai": "13.0.2",
-		"@oh-my-pi/pi-natives": "13.0.2",
-		"@oh-my-pi/pi-tui": "13.0.2",
-		"@oh-my-pi/pi-utils": "13.0.2",
+		"@oh-my-pi/omp-stats": "13.1.0",
+		"@oh-my-pi/pi-agent-core": "13.1.0",
+		"@oh-my-pi/pi-ai": "13.1.0",
+		"@oh-my-pi/pi-natives": "13.1.0",
+		"@oh-my-pi/pi-tui": "13.1.0",
+		"@oh-my-pi/pi-utils": "13.1.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/src/patch/index.ts

@@ -108,14 +108,14 @@ export { ApplyPatchError, EditMatchError, ParseError } from "./types";
 // ═══════════════════════════════════════════════════════════════════════════
 
 const replaceEditSchema = Type.Object({
-	file: Type.String({ description: "File path (relative or absolute)" }),
+	path: Type.String({ description: "File path (relative or absolute)" }),
 	old_text: Type.String({ description: "Text to find (fuzzy whitespace matching enabled)" }),
 	new_text: Type.String({ description: "Replacement text" }),
 	all: Type.Optional(Type.Boolean({ description: "Replace all occurrences (default: unique match required)" })),
 });
 
 const patchEditSchema = Type.Object({
-	file: Type.String({ description: "File path" }),
+	path: Type.String({ description: "File path" }),
 	op: Type.Optional(
 		StringEnum(["create", "delete", "update"], {
 			description: "Operation (default: update)",
@@ -192,10 +192,10 @@ const hashlineEditSchema = Type.Object(
 
 const hashlineEditParamsSchema = Type.Object(
 	{
-		file: Type.String({ description: "path" }),
-		edits: Type.Array(hashlineEditSchema, { description: "edits over $file" }),
-		delete: Type.Optional(Type.Boolean({ description: "If true, delete $file" })),
-		move: Type.Optional(Type.String({ description: "If set, move $file to $move" })),
+		path: Type.String({ description: "path" }),
+		edits: Type.Array(hashlineEditSchema, { description: "edits over $path" }),
+		delete: Type.Optional(Type.Boolean({ description: "If true, delete $path" })),
+		move: Type.Optional(Type.String({ description: "If set, move $path to $move" })),
 	},
 	{ additionalProperties: false },
 );
@@ -489,7 +489,7 @@ export class EditTool implements AgentTool<TInput> {
 		// Hashline mode execution
 		// ─────────────────────────────────────────────────────────────────
 		if (this.mode === "hashline") {
-			const { file: path, edits, delete: deleteFile, move } = params as HashlineParams;
+			const { path, edits, delete: deleteFile, move } = params as HashlineParams;
 
 			enforcePlanModeWrite(this.session, path, { op: deleteFile ? "delete" : "update", move });
 
@@ -659,7 +659,7 @@ export class EditTool implements AgentTool<TInput> {
 		// Patch mode execution
 		// ─────────────────────────────────────────────────────────────────
 		if (this.mode === "patch") {
-			const { file: path, op: rawOp, rename, diff } = params as PatchParams;
+			const { path, op: rawOp, rename, diff } = params as PatchParams;
 
 			// Normalize unrecognized operations to "update"
 			const op: Operation = rawOp === "create" || rawOp === "delete" ? rawOp : "update";
@@ -741,7 +741,7 @@ export class EditTool implements AgentTool<TInput> {
 		// ─────────────────────────────────────────────────────────────────
 		// Replace mode execution
 		// ─────────────────────────────────────────────────────────────────
-		const { file: path, old_text, new_text, all } = params as ReplaceParams;
+		const { path, old_text, new_text, all } = params as ReplaceParams;
 
 		enforcePlanModeWrite(this.session, path);
 

package/src/patch/shared.ts

@@ -71,7 +71,6 @@ export interface EditToolDetails {
 interface EditRenderArgs {
 	path?: string;
 	file_path?: string;
-	file?: string;
 	oldText?: string;
 	newText?: string;
 	patch?: string;
@@ -220,7 +219,7 @@ export const editToolRenderer = {
 	mergeCallAndResult: true,
 
 	renderCall(args: EditRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component {
-		const rawPath = args.file_path || args.path || args.file || "";
+		const rawPath = args.file_path || args.path || "";
 		const filePath = shortenPath(rawPath);
 		const editLanguage = getLanguageFromPath(rawPath) ?? "text";
 		const editIcon = uiTheme.fg("muted", uiTheme.getLangIcon(editLanguage));
@@ -275,7 +274,7 @@ export const editToolRenderer = {
 		uiTheme: Theme,
 		args?: EditRenderArgs,
 	): Component {
-		const rawPath = args?.file_path || args?.path || args?.file || "";
+		const rawPath = args?.file_path || args?.path || "";
 		const filePath = shortenPath(rawPath);
 		const editLanguage = getLanguageFromPath(rawPath) ?? "text";
 		const editIcon = uiTheme.fg("muted", uiTheme.getLangIcon(editLanguage));

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

@@ -100,6 +100,10 @@ You MUST NOT open a file hoping. Hope is not a strategy.
 {{#has tools "grep"}}- Known territory → `grep` to locate target{{/has}}
 {{#has tools "read"}}- Known location → `read` with offset/limit, not whole file{{/has}}
 {{/ifAny}}
+
+{{#if intentTracing}}
+Every tool has a required `{{intentField}}` parameter. Describe intent as one sentence in present participle form (e.g., Inserting comment before the function) with no trailing period.
+{{/if}}
 </tools>
 
 <procedure>
@@ -215,30 +219,26 @@ Match skill descriptions to the task domain. If a skill is relevant, you MUST re
 Relative paths in skill files resolve against the skill directory.
 
 {{#list skills join="\n"}}
-<skill name="{{name}}">
+### {{name}}
 {{description}}
-</skill>
 {{/list}}
 </skills>
 {{/if}}
 {{#if preloadedSkills.length}}
-<preloaded-skills>
+<skills>
 {{#list preloadedSkills join="\n"}}
 <skill name="{{name}}">
 {{content}}
 </skill>
 {{/list}}
-</preloaded-skills>
+</skills>
 {{/if}}
 {{#if rules.length}}
 <rules>
 Read `rule://<name>` when working in matching domain.
-
 {{#list rules join="\n"}}
-<rule name="{{name}}">
+### {{name}} (Glob: {{#list globs join=", "}}{{this}}{{/list}})
 {{description}}
-{{#list globs join="\n"}}<glob>{{this}}</glob>{{/list}}
-</rule>
 {{/list}}
 </rules>
 {{/if}}

package/src/prompts/tools/ask.md

@@ -12,33 +12,18 @@ Ask user when you need clarification or input during task execution.
 - Set `multi: true` on question to allow multiple selections
 </instruction>
 
-<output>
-Returns selected option(s) as text. For multi-part questions, returns map of question IDs to selected values.
-</output>
-
 <caution>
 - Provide 2-5 concise, distinct options
 </caution>
 
 <critical>
-**Default to action. You MUST NOT ask unless you are genuinely blocked and user preference is required to avoid a wrong outcome.**
-1. You MUST **resolve ambiguity yourself** using repo conventions, existing patterns, and reasonable defaults.
-2. You MUST **exhaust existing sources** (code, configs, docs, history) before asking anything.
-3. **If multiple choices are acceptable**, you MUST pick the most conservative/standard option and proceed; state the choice.
-4. You MUST **only ask when options have materially different tradeoffs and the user must decide.**
-**You MUST NOT include "Other" option in your options array.** UI automatically adds "Other (type your own)" to every question; adding your own creates duplicates.
+- **Default to action.** Resolve ambiguity yourself using repo conventions, existing patterns, and reasonable defaults. Exhaust existing sources (code, configs, docs, history) before asking. Only ask when options have materially different tradeoffs the user must decide.
+- **If multiple choices are acceptable**, pick the most conservative/standard option and proceed; state the choice.
+- **Do NOT include "Other" option** — UI automatically adds "Other (type your own)" to every question.
 </critical>
 
 <example name="single">
 question: "Which authentication method should this API use?"
 options: [{"label": "JWT"}, {"label": "OAuth2"}, {"label": "Session cookies"}]
 recommended: 0
-</example>
-
-<example name="multi-part">
-questions: [
-  {"id": "auth", "question": "Which auth method?", "options": [{"label": "JWT"}, {"label": "OAuth2"}], "recommended": 0},
-  {"id": "cache", "question": "Enable caching?", "options": [{"label": "Yes"}, {"label": "No"}]},
-  {"id": "features", "question": "Which features to include?", "options": [{"label": "Logging"}, {"label": "Metrics"}, {"label": "Tracing"}], "multi": true}
-]
 </example>

package/src/prompts/tools/{poll-jobs.md → await.md}

@@ -1,4 +1,4 @@
-# Poll Jobs
+# Await
 
 Block until one or more background jobs complete, fail, or are cancelled.
 

package/src/prompts/tools/bash.md

@@ -13,17 +13,18 @@ Executes bash command in shell session for terminal operations like git, bun, ca
 {{#if asyncEnabled}}
 - Use `async: true` for long-running commands when you don't need immediate output; the call returns a background job ID and the result is delivered automatically as a follow-up.
 - Use `read jobs://` to inspect all background jobs and `read jobs://<job-id>` for detailed status/output when needed.
-- When you need to wait for async results before continuing, you MUST call `poll_jobs` — it blocks until jobs complete. You MUST NOT poll `read jobs://` in a loop or yield and hope for delivery.
+- When you need to wait for async results before continuing, call `await` — it blocks until jobs complete. Do NOT poll `read jobs://` in a loop or yield and hope for delivery.
 {{/if}}
 </instruction>
 
 <output>
 Returns the output, and an exit code from command execution.
+- If output truncated, full output can be retrieved from `artifact://<id>`, linked in metadata
 - Exit codes shown on non-zero exit
 </output>
 
 <critical>
 - You MUST NOT use Bash for these operations like read, grep, find, edit, write, where specialized tools exist.
-- You MUST NOT use `2>&1` | `2>/dev/null` pattern, stdout and stderr are already merged.
+- You MUST NOT use `2>&1` pattern, stdout and stderr are already merged.
 - You MUST NOT use `| head -n 50` or `| tail -n 100` pattern, use `head` and `tail` parameters instead.
 </critical>

package/src/prompts/tools/browser.md

@@ -1,24 +1,17 @@
 # Browser
 
-Use this tool to navigate, click, type, scroll, drag, query DOM content, and capture screenshots.
+Navigate, click, type, scroll, drag, query DOM content, and capture screenshots.
 
 <instruction>
-- Use `action: "open"` to start a new headless browser session (or implicitly launch on first action)
-- Use `action: "goto"` with `url` to navigate
-- Use `action: "observe"` to capture a numbered accessibility snapshot with URL/title/viewport/scroll info
-	- You SHOULD prefer `click_id`, `type_id`, or `fill_id` actions using the returned `element_id` values
-	- Optional flags: `include_all` to include non-interactive nodes, `viewport_only` to limit to visible elements
-- Use `action: "click"`, `"type"`, `"fill"`, `"press"`, `"scroll"`, or `"drag"` for selector-based interactions
-	- You SHOULD prefer ARIA or text selectors (e.g. `p-aria/[name="Sign in"]`, `p-text/Continue`) over brittle CSS
-- Use `action: "click_id"`, `"type_id"`, or `"fill_id"` to interact with observed elements without selectors
-- Use `action: "wait_for_selector"` before interacting when the page is dynamic
-- Use `action: "evaluate"` with `script` to run a JavaScript expression in the page context
-- Use `action: "get_text"`, `"get_html"`, or `"get_attribute"` for DOM queries
-	- For batch queries, pass `args: [{ selector, attribute? }]` to get an array of results (attribute required for `get_attribute`)
-- Use `action: "extract_readable"` to return reader-mode content (title/byline/excerpt/text or markdown)
-	- Set `format` to `"markdown"` (default) or `"text"`
-- Use `action: "screenshot"` to capture images (optionally with `selector` to capture a single element)
-- Use `action: "close"` to release the browser when done
+- `"open"` starts a headless session (or implicitly on first action); `"goto"` navigates to `url`; `"close"` releases the browser
+- `"observe"` captures a numbered accessibility snapshot — prefer `click_id`/`type_id`/`fill_id` using returned `element_id` values; flags: `include_all`, `viewport_only`
+- `"click"`, `"type"`, `"fill"`, `"press"`, `"scroll"`, `"drag"` for selector-based interactions — prefer ARIA/text selectors (`p-aria/[name="Sign in"]`, `p-text/Continue`) over brittle CSS
+- `"click_id"`, `"type_id"`, `"fill_id"` to interact with observed elements without selectors
+- `"wait_for_selector"` before interacting when the page is dynamic
+- `"evaluate"` runs a JS expression in page context
+- `"get_text"`, `"get_html"`, `"get_attribute"` for DOM queries — batch via `args: [{ selector, attribute? }]`
+- `"extract_readable"` returns reader-mode content; `format`: `"markdown"` (default) or `"text"`
+- `"screenshot"` captures images (optionally with `selector`); can save to disk via `path`
 </instruction>
 
 <critical>
@@ -29,5 +22,5 @@ Use this tool to navigate, click, type, scroll, drag, query DOM content, and cap
 </critical>
 
 <output>
-Returns text output for navigation and DOM queries, and image output for screenshots. Screenshots can optionally be saved to disk via the `path` parameter.
+Text for navigation/DOM queries, images for screenshots.
 </output>

package/src/prompts/tools/fetch.md

@@ -3,14 +3,11 @@
 Retrieves content from a URL and returns it in a clean, readable format.
 
 <instruction>
-- Extract information from web pages (documentation, articles, API references)
-- Analyze GitHub issues, PRs, or repository content
-- Retrieve from Stack Overflow, Wikipedia, Reddit, NPM, arXiv, technical blogs
-- Access RSS/Atom feeds or JSON endpoints
+- Extract information from web pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, technical blogs, RSS/Atom feeds, JSON endpoints
 - Read PDF or DOCX files hosted at a URL
 - Use `raw: true` for untouched HTML or debugging
 </instruction>
 
 <output>
-Returns processed, readable content extracted from the URL. HTML is transformed to remove navigation, ads, and boilerplate. PDF and DOCX files are converted to text. JSON endpoints return formatted JSON. With `raw: true`, returns untransformed HTML.
+Returns processed, readable content. HTML transformed to remove boilerplate. PDF/DOCX converted to text. JSON returned formatted. With `raw: true`, returns untransformed HTML.
 </output>

package/src/prompts/tools/find.md

@@ -10,7 +10,7 @@ Fast file pattern matching that works with any codebase size.
 </instruction>
 
 <output>
-Matching file paths sorted by modification time (most recent first). Results truncated at 1000 entries or 50KB (configurable via `limit`).
+Matching file paths sorted by modification time (most recent first). Truncated at 1000 entries or 50KB (configurable via `limit`).
 </output>
 
 <example name="find files">

package/src/prompts/tools/grep.md

@@ -3,16 +3,13 @@
 Powerful search tool built on ripgrep.
 
 <instruction>
-- Supports full regex syntax (e.g., `log.*Error`, `function\\s+\\w+`)
+- Supports full regex syntax (e.g., `log.*Error`, `function\\s+\\w+`); literal braces need escaping (`interface\\{\\}` for `interface{}` in Go)
 - Filter files with `glob` (e.g., `*.js`, `**/*.tsx`) or `type` (e.g., `js`, `py`, `rust`)
-- Pattern syntax uses ripgrep—literal braces need escaping (`interface\\{\\}` to find `interface{}` in Go)
 - For cross-line patterns like `struct \\{[\\s\\S]*?field`, set `multiline: true` if needed
 - If the pattern contains a literal `\n`, multiline defaults to true
 </instruction>
 
 <output>
-- Results are always content mode.
-- Results grouped by directory (`# dir`) and file (`## └─ file`) headings
 {{#if IS_HASHLINE_MODE}}
 - Text output is CID prefixed: `LINE#ID:content`
 {{else}}

package/src/prompts/tools/hashline.md

@@ -22,20 +22,20 @@ Every edit has `op`, `pos`, and `lines`. Range replaces also have `end`. Both `p
 - `null` or `[]` — **delete** the line(s) entirely
 
 ### Line or range replace/delete
-- `{ file: "…", edits: [{ op: "replace", pos: "N#ID", lines: null }] }` — delete one line
-- `{ file: "…", edits: [{ op: "replace", pos: "N#ID", end: "M#ID", lines: null }] }` — delete a range
-- `{ file: "…", edits: [{ op: "replace", pos: "N#ID", lines: […] }] }` — replace one line
-- `{ file: "…", edits: [{ op: "replace", pos: "N#ID", end: "M#ID", lines: […] }] }` — replace a range
+- `{ path: "…", edits: [{ op: "replace", pos: "N#ID", lines: null }] }` — delete one line
+- `{ path: "…", edits: [{ op: "replace", pos: "N#ID", end: "M#ID", lines: null }] }` — delete a range
+- `{ path: "…", edits: [{ op: "replace", pos: "N#ID", lines: […] }] }` — replace one line
+- `{ path: "…", edits: [{ op: "replace", pos: "N#ID", end: "M#ID", lines: […] }] }` — replace a range
 
 ### Insert new lines
-- `{ file: "…", edits: [{ op: "prepend", pos: "N#ID", lines: […] }] }` — insert before tagged line
-- `{ file: "…", edits: [{ op: "prepend", lines: […] }] }` — insert at beginning of file (no tag)
-- `{ file: "…", edits: [{ op: "append", pos: "N#ID", lines: […] }] }` — insert after tagged line
-- `{ file: "…", edits: [{ op: "append", lines: […] }] }` — insert at end of file (no tag)
+- `{ path: "…", edits: [{ op: "prepend", pos: "N#ID", lines: […] }] }` — insert before tagged line
+- `{ path: "…", edits: [{ op: "prepend", lines: […] }] }` — insert at beginning of file (no tag)
+- `{ path: "…", edits: [{ op: "append", pos: "N#ID", lines: […] }] }` — insert after tagged line
+- `{ path: "…", edits: [{ op: "append", lines: […] }] }` — insert at end of file (no tag)
 
 ### File-level controls
-- `{ file: "…", delete: true, edits: [] }` — delete the file
-- `{ file: "…", move: "new/path.ts", edits: […] }` — move file to new path (edits applied first)
+- `{ path: "…", delete: true, edits: [] }` — delete the file
+- `{ path: "…", move: "new/path.ts", edits: […] }` — move file to new path (edits applied first)
 **Atomicity:** all ops in one call validate against the same pre-edit snapshot; tags reference the last `read`. Edits are applied bottom-up, so earlier tags stay valid even when later ops add or remove lines.
 </operations>
 
@@ -44,6 +44,7 @@ Every edit has `op`, `pos`, and `lines`. Range replaces also have `end`. Both `p
 2. **No no-ops:** replacement MUST differ from current.
 3. **Prefer insertion over neighbor rewrites:** You SHOULD anchor on structural boundaries (`}`, `]`, `},`), not interior lines.
 4. **For swaps/moves:** You SHOULD prefer one range op over multiple single-line ops.
+5. **Range end tag:** When replacing a block (e.g., an `if` body), the `end` tag MUST include the block's closing brace/bracket — not just the last interior line. Verify the `end` tag covers all lines being logically removed, including trailing `}`, `]`, or `)`. An off-by-one on `end` orphans a brace and breaks syntax.
 </rules>
 
 <recovery>
@@ -57,7 +58,7 @@ Every edit has `op`, `pos`, and `lines`. Range replaces also have `end`. Both `p
 ```
 ```
 {
-  file: "…",
+  path: "…",
   edits: [{
     op: "replace",
     pos: "{{hlineref 23 "  const timeout: number = 5000;"}}",
@@ -71,7 +72,7 @@ Every edit has `op`, `pos`, and `lines`. Range replaces also have `end`. Both `p
 Single line — `lines: null` deletes entirely:
 ```
 {
-  file: "…",
+  path: "…",
   edits: [{
     op: "replace",
     pos: "{{hlineref 7 "// @ts-ignore"}}",
@@ -82,7 +83,7 @@ Single line — `lines: null` deletes entirely:
 Range — add `end`:
 ```
 {
-  file: "…",
+  path: "…",
   edits: [{
     op: "replace",
     pos: "{{hlineref 80 "  // TODO: remove after migration"}}",
@@ -99,7 +100,7 @@ Range — add `end`:
 ```
 ```
 {
-  file: "…",
+  path: "…",
   edits: [{
     op: "replace",
     pos: "{{hlineref 14 "  placeholder: \"DO NOT SHIP\","}}",
@@ -118,7 +119,7 @@ Range — add `end`:
 ```
 ```
 {
-  file: "…",
+  path: "…",
   edits: [{
     op: "replace",
     pos: "{{hlineref 60 "    } catch (err) {"}}",
@@ -141,7 +142,7 @@ Range — add `end`:
 ```
 ```
 {
-  file: "…",
+  path: "…",
   edits: [{
     op: "prepend",
     pos: "{{hlineref 45 "  \"test\": \"bun test\""}}",
@@ -168,7 +169,7 @@ Bad — append after "}"
 Good — anchors to structural line:
 ```
 {
-  file: "…",
+  path: "…",
   edits: [{
     op: "prepend",
     pos: "{{hlineref 103 "export function serialize(data: unknown): string {"}}",
@@ -184,7 +185,7 @@ Good — anchors to structural line:
 </example>
 
 <critical>
-- Edit payload: `{ file, edits[] }`. Each entry: `op`, `lines`, optional `pos`/`end`. No extra keys.
+- Edit payload: `{ path, edits[] }`. Each entry: `op`, `lines`, optional `pos`/`end`. No extra keys.
 - Every tag MUST be copied exactly from fresh tool result as `N#ID`.
 - You MUST re-read after each edit call before issuing another on same file.
 </critical>

package/src/prompts/tools/lsp.md

@@ -3,25 +3,15 @@
 Interact with Language Server Protocol servers for code intelligence.
 
 <operations>
-- `definition`: Go to symbol definition
-- `references`: Find all references to symbol
-- `hover`: Get type info and documentation
-- `symbols`: List symbols in file, or search workspace (with query, no file)
-- `rename`: Rename symbol across codebase
-- `diagnostics`: Get errors/warnings for file, or check entire project (no file)
+- `definition`: Go to symbol definition → file path + position
+- `references`: Find all references → list of locations (file + position)
+- `hover`: Get type info and documentation → type signature + docs
+- `symbols`: List symbols in file, or search workspace (with query, no file) → names, kinds, locations
+- `rename`: Rename symbol across codebase → confirmation of changes
+- `diagnostics`: Get errors/warnings for file, or check entire project (no file) → list with severity + message
 - `reload`: Restart the language server
 </operations>
 
-<output>
-- `definition`: File path and position of definition
-- `references`: List of locations (file + position) where symbol used
-- `hover`: Type signature and documentation text
-- `symbols`: List of symbol names, kinds, locations
-- `rename`: Confirmation of changes made across files
-- `diagnostics`: List of errors/warnings with file, line, severity, message
-- `reload`: Confirmation of server restart
-</output>
-
 <caution>
 - Requires running LSP server for target language
 - Some operations require file to be saved to disk

package/src/prompts/tools/read.md

@@ -1,6 +1,6 @@
 # Read
 
-Reads files from local filesystem or harness URLs.
+Reads files from local filesystem or internal URLs.
 
 <instruction>
 - Reads up to {{DEFAULT_MAX_LINES}} lines default
@@ -14,13 +14,10 @@ Reads files from local filesystem or harness URLs.
 {{/if}}
 - Supports images (PNG, JPG) and PDFs
 - For directories, returns formatted listing with modification times
-- You SHOULD parallelize reads when exploring related files
+- Parallelize reads when exploring related files
 </instruction>
 
 <output>
-- Returns file content as text
-- Images: returns visual content for analysis
-- PDFs: returns extracted text
+- Returns file content as text; images return visual content; PDFs return extracted text
 - Missing files: returns closest filename matches for correction
-- Internal URLs: returns resolved content with pagination support
 </output>

package/src/prompts/tools/task.md

@@ -1,317 +1,135 @@
 # Task
 
-Launch subagents to execute parallel, well-scoped tasks.
+Launches subagents to parallelize workflows.
+
 {{#if asyncEnabled}}
-Use `read jobs://` to inspect background task state and `read jobs://<job-id>` for detailed status/output when needed.
-When you need to wait for async results before continuing, call `poll_jobs` — it blocks until jobs complete. You MUST NOT poll `read jobs://` in a loop or yield and hope for delivery.
+- Use `read jobs://` to inspect state; `read jobs://<job_id>` for detail.
+- Use the `await` tool to wait until completion. You MUST NOT poll `read jobs://` in a loop.
 {{/if}}
 
-## What subagents inherit automatically
-Subagents receive the **full system prompt**, including AGENTS.md, context files, and skills. You MUST NOT repeat project rules, coding conventions, or style guidelines in `context` — they already have them.
-
-## What subagents do NOT have
-Subagents have no access to your conversation history. They don't know:
-- Decisions you made but didn't write down
-- Which approach you chose among alternatives
-- What you learned from reading files during this session
-- Requirements the user stated only in conversation
-
-Subagents CAN grep the parent conversation file for supplementary details.
-
-For large intermediate outputs (long traces, JSON payloads, temporary analysis snapshots), you SHOULD write them to `local://<path>` and pass the path in task context instead of inlining bulky text.
-
-## Parameters
-
-### `agent` (required)
+Subagents lack your conversation history. Every decision, file content, and user requirement they need MUST be explicit in `context` or `assignment`.
 
-Agent type for all tasks in this batch.
-
-### `context` (optional — strongly recommended)
-
-Shared background prepended verbatim to every task `assignment`. Use only for session-specific information subagents lack.
+<parameters>
+- `agent`: Agent type for all tasks.
+  - `.id`: CamelCase, max 32 chars
+  - `.description`: UI display only — subagent never sees it
+  - `.assignment`: Complete self-contained instructions. One-liners PROHIBITED; missing acceptance criteria = too vague.
+  - `.skills`: Skill names to preload
+- `context`: Shared background prepended to every assignment. Session-specific info only.
+- `schema`: JTD schema for expected output. Format lives here — MUST NOT be duplicated in assignments.
+- `tasks`: Tasks to execute in parallel.
+- `isolated`: Run in isolated git worktree; returns patches. Use when tasks edit overlapping files.
+</parameters>
 
 <critical>
-You MUST NOT include project rules, coding conventions, or style guidelines — subagents already have AGENTS.md and context files in their system prompt. Repeating them wastes tokens and inflates context. Restating any rule from AGENTS.md in `context` is a bug — treat it like a lint error.
+- MUST NOT include AGENTS.md rules, coding conventions, or style guidelines — subagents already have them.
+- MUST NOT duplicate shared constraints across assignments — put them in `context` once.
+- MUST NOT tell tasks to run project-wide build/test/lint. Parallel agents share the working tree; each task edits, stops. Caller verifies after all complete.
+- For large payloads (traces, JSON blobs), write to `local://<path>` and pass the path in context.
+- If scope is unclear, run a **Discovery task** first to enumerate files and callsites, then fan out.
 </critical>
-**Before writing each line of context, ask:** "Would this sentence be true for ANY task in this repo, or only for THIS specific batch?" If it applies to any task → it's a project rule → the subagent already has it → you MUST delete the line.
 
-WRONG — restating project rules the subagent already has:
-```
-## Constraints
-- Use X import style, not Y (per AGENTS.md)
-- Use Z for private fields per AGENTS.md
-- Run the formatter after changes
-- Follow the logging convention
-```
-Every line above restates a project convention. The subagent reads AGENTS.md. You MUST delete them all.
+<scope>
+Each task: **at most 3–5 files**. Globs in file paths, "update all", or package-wide scope = too broad. Enumerate files explicitly and fan out to a cluster of agents.
+</scope>
 
-RIGHT — only session-specific decisions the subagent cannot infer from project files:
-```
-## Constraints
-- We decided to use approach A over B (session decision)
-- The migration target type is `Foo` from `bar` package (looked up this session)
-```
-
-Use template; omit non-applicable sections:
-
-````
-## Goal
-One sentence: batch accomplishes together.
-
-## Non-goals
-Explicitly exclude tempting scope — what tasks must not touch/attempt.
-
-## Constraints
-- Task-specific MUST / MUST NOT rules not already in AGENTS.md
-- Decisions made during this session that affect implementation
-
-## Reference Files
-- `path/to/file.ext` — pattern demo
-- `path/to/other.ext` — reuse or avoid
-
-## API Contract (if tasks produce/consume shared interface)
-```language
-// Exact type definitions, function signatures, interface shapes
-```
+<parallelization>
+**Test:** Can task B produce correct output without seeing A's result? Yes → parallel. No → sequential.
 
-## Acceptance (global)
-- Definition of "done" for batch
-- Note: build/test/lint verification happens AFTER all tasks complete — not inside tasks (see below)
-````
-**Belongs in `context`**: task-specific goal, non-goals, session decisions, reference paths, shared type definitions, API contracts, global acceptance commands — anything 2+ tasks need that isn't already in AGENTS.md.
-**Rule of thumb:** if repeat in 2+ tasks, belongs in `context`.
-**Does NOT belong in `context`**: project rules already in AGENTS.md/context files, per-task file lists, one-off requirements (go in `assignment`), structured output format (goes in `schema`).
-
-### `tasks` (required)
-
-Array tasks execute in parallel.
-
-|Field|Required|Purpose|
+|Sequential first|Then|Reason|
 |---|---|---|
-|`id`|✓|CamelCase identifier, max 32 chars|
-|`description`|✓|Short one-liner for UI display only — not seen by subagent|
-|`assignment`|✓|Complete per-task instructions. See [Writing an assignment](#writing-an-assignment).|
-|`skills`||Skill names preload. Use only when changes correctness — don’t spam every task.|
-
-{{#if isolationEnabled}}
-### `isolated` (optional)
-
-Run in isolated git worktree; returns patches. Use when tasks edit overlapping files or when you want clean per-task diffs.
-{{/if}}
-### `schema` (optional — recommended for structured output)
-
-JTD schema defining expected response structure. Use typed properties. If you care about parsing result, define here — you MUST NOT describe output format in `context` or `assignment`.
-
-<caution>
-**Schema vs agent mismatch causes null output.** Agents with `output="structured"` (e.g., `explore`) have a built-in schema. If you also pass `schema`, yours takes precedence — but if you describe output format in `context`/`assignment` instead, the agent's built-in schema wins. The agent gets confused trying to fit your requested format into its schema shape and submits `null`. Either: (1) use `schema` to override the built-in one, (2) use `task` agent which has no built-in schema, or (3) match your instructions to the agent's expected output shape.
-</caution>
----
-
-## Writing an assignment
-
-<critical>## Task scope
-
-`assignment` MUST contain enough info for agent to act **without asking a clarifying question**.
-**Minimum bar:** assignment under ~8 lines or missing acceptance criteria = too vague. One-liners guaranteed failure.
-
-Use structure every assignment:
-
+|Types/interfaces|Consumers|Need contract|
+|API exports|Callers|Need signatures|
+|Core module|Dependents|Import dependency|
+|Schema/migration|App logic|Schema dependency|
+**Safe to parallelize:** independent modules, isolated file-scoped refactors, tests for existing code.
+</parallelization>
+
+<templates>
+**context:**
 ```
-## Target
-- Files: exact path(s)
-- Symbols/entrypoints: specific functions, types, exports
-- Non-goals: what task must NOT touch (prevents scope creep)
-
-## Change
-- Step-by-step: add/remove/rename/restructure
-- Patterns/APIs to use; reference files if applicable
-
-## Edge Cases / Don't Break
-- Tricky case 1: …
-- Tricky case 2: …
-- Existing behavior must survive: …
-
-## Acceptance (task-local)
-- Expected behavior or observable result
-- DO NOT include project-wide build/test/lint commands (see below)
+## Goal         ← one sentence: what the batch accomplishes
+## Non-goals    ← what tasks must not touch
+## Constraints  ← MUST/MUST NOT rules beyond AGENTS.md; session decisions
+## API Contract ← exact types/signatures if tasks share an interface (omit if N/A)
+## Acceptance   ← definition of done; build/lint runs AFTER all tasks complete
 ```
-
-`context` carries shared background. `assignment` carries only delta: file-specific instructions, local edge cases, per-task acceptance checks. You MUST NOT duplicate shared constraints across assignments.
-
-### Anti-patterns (ban these)
-**Vague assignments** — agent guesses wrong or stalls:
-- "Refactor this to be cleaner."
-- "Migrate to N-API."
-- "Fix the bug in streaming."
-- "Update all constructors in `src/**/*.ts`."
-  **Vague context** — forces agent invent conventions:
-- "Use existing patterns."
-- "Follow conventions."
-- "No WASM."
-  **Redundant context** — wastes tokens repeating what subagents already have:
-- Restating AGENTS.md rules (coding style, import conventions, formatting commands, logger usage, etc.)
-- Repeating project constraints from context files
-- Listing tool/framework preferences already documented in the repo
-
-If a constraint appears in AGENTS.md, it MUST NOT appear in `context`. The subagent has the full system prompt.
-
-If tempted to write above, expand using templates.
-**Output format in prose instead of `schema`** — agent returns null:
-Structured agents (`explore`, `reviewer`) have built-in output schemas. Describing a different output format in `context`/`assignment` without overriding via `schema` creates a mismatch — the agent can't reconcile your prose instructions with its schema and submits null data. You MUST use `schema` for output structure, or pick an agent whose built-in schema matches your needs.
-**Test/lint commands in parallel tasks** — edit wars:
-Parallel agents share working tree. If two agents run `bun check` or `bun test` concurrently, they see each other's half-finished edits, "fix" phantom errors, loop. You MUST NOT tell parallel tasks to run project-wide build/test/lint commands. Each task edits, stops. Caller verifies after all tasks complete.
-**If you can't specify scope yet**, create **Discovery task** first: enumerate files, find callsites, list candidates. Then fan out with explicit paths.
-
-### Delegate intent, not keystrokes
-
-Your role as tech lead: set direction, define boundaries, call out pitfalls — then get out of way. Don’t read every file, decide every edit, dictate line-by-line. That makes you bottleneck; agent typist.
-**Be specific about:** constraints, naming conventions, API contracts, "don’t break" items, acceptance criteria.
-**Delegate:** code reading, approach selection, exact edit locations, implementation details. Agent has tools, can reason about code.
-
-Micromanaging (you think, agent types):
-```
-assignment: "In src/api/handler.ts, line 47, change `throw err` to `throw new ApiError(err.message, 500)`.
-On line 63, wrap fetch call try/catch return 502 on failure.
-On line 89, add null check before accessing resp.body…"
+**assignment:**
 ```
-
-Delegating (agent thinks within constraints):
+## Target       ← exact file paths; named symbols; explicit non-goals
+## Change       ← step-by-step what to add/remove/rename; patterns/APIs to use
+## Edge Cases   ← tricky inputs; existing behavior that must survive
+## Acceptance   ← observable result proving the task is done; no project-wide commands
 ```
-assignment: "## Target\n- Files: src/api/handler.ts\n\n## Change\nImprove error handling: replace raw throws
-with typed ApiError instances, add try/catch around external calls, guard against null responses.\n\n
-## Edge Cases / Don't Break\n- Existing error codes in tests must still match\n
-- Don't change public function signatures"
-```
-
-First style wastes your time, brittle if code shifts. Second gives agent room to do work.
-</critical>
+</templates>
 
-## Example
+<checklist>
+Before invoking:
+- `context` contains only session-specific info not in AGENTS.md
+- Every `assignment` follows the template; no one-liners; edge cases covered
+- Tasks are truly parallel — you can articulate why none depends on another's output
+- File paths are explicit; no globs
+- `schema` is set if you expect structured output
+</checklist>
 
-<example type="bad" label="Duplicated context inflates tokens">
-<tasks>
-  <task name="Grep">
-    <description>Port grep module from WASM to N-API…</description>
-    <assignment>Port grep module from WASM to N-API… (same blob repeated)</assignment>
-  </task>
-</tasks>
-</example>
+<example label="Rename exported symbol + update all call sites">
+Two tasks with non-overlapping file sets. Neither depends on the other's edits.
 
-<example type="good" label="Shared rules in context, only deltas in assignment">
 <context>
 ## Goal
-Port WASM modules to N-API, matching existing pi-natives conventions.
-
+Rename `parseConfig` → `loadConfig` in `src/config/parser.ts` and all callers.
 ## Non-goals
-Do not touch TS bindings or downstream consumers — separate phase.
-
-## Constraints
-- MUST use `#[napi]` attribute macro on all exports
-- MUST return `napi::Result<T>` for fallible ops; never panic
-- MUST use `spawn_blocking` for filesystem I/O or >1ms work
-  …
-
+Do not change function behavior, signature, or tests — rename only.
 ## Acceptance (global)
-- Caller verifies after all tasks: `cargo test -p pi-natives` and `cargo build -p pi-natives` with no warnings
-- Individual tasks must NOT run these commands themselves
+Caller runs `bun check:ts` after both tasks complete. Tasks must NOT run it.
 </context>
-
 <tasks>
-  <task name="PortGrep">
-    <description>Port grep module to N-API</description>
+  <task name="RenameExport">
+    <description>Rename the export in parser.ts</description>
     <assignment>
 ## Target
-- Files: `src/grep.rs`, `src/lib.rs` (registration only)
-- Symbols: search, search_multi, compile_pattern
+- File: `src/config/parser.ts`
+- Symbol: exported function `parseConfig`
+- Non-goals: do not touch callers or tests
 
 ## Change
-- Implement three N-API exports in grep.rs:
-  - `search(pattern: JsString, path: JsString, env: Env) → napi::Result<Vec<Match>>`
-…
+- Rename `parseConfig` → `loadConfig` (declaration + any JSDoc referencing it)
+- If `src/config/index.ts` re-exports `parseConfig`, update that re-export too
+
+## Edge Cases
+- If the function is overloaded, rename all overload signatures
+- Internal helpers named `_parseConfigValue` or similar: leave untouched — different symbols
+- Do not add a backwards-compat alias
 
-## Acceptance (task-local)
-- Three functions exported with correct signatures (caller verifies build after all tasks)
+## Acceptance
+- `src/config/parser.ts` exports `loadConfig`; `parseConfig` no longer appears as a top-level export in that file
     </assignment>
   </task>
-
-  <task name="PortHighlight">
-    <description>Port highlight module to N-API</description>
+  <task name="UpdateCallers">
+    <description>Update import and call sites in consuming modules</description>
     <assignment>
 ## Target
-- Files: `src/highlight.rs`, `src/lib.rs` (registration only)
-  …
+- Files: `src/cli/init.ts`, `src/server/bootstrap.ts`, `src/worker/index.ts`
+- Non-goals: do not touch `src/config/parser.ts` or `src/config/index.ts` — handled by sibling task
+
+## Change
+- In each file: replace `import { parseConfig }` → `import { loadConfig }` from its config path
+- Replace every call site `parseConfig(` → `loadConfig(`
+
+## Edge Cases
+- If a file spreads the import (`import * as cfg from "…"`) and calls `cfg.parseConfig(…)`, update the property access too
+- String literals containing "parseConfig" (log messages, comments) are documentation — leave them
+- If any file re-exports `parseConfig` to an external package boundary, keep the old name via `export { loadConfig as parseConfig }` and add a `// TODO: remove after next major` comment
+
+## Acceptance
+- No bare reference to `parseConfig` (as identifier, not string) remains in the three target files
     </assignment>
   </task>
 </tasks>
 </example>
----
-
-## Task scope
-
-Each task MUST have small, well-defined scope — **at most 3–5 files**.
-**Signs task too broad:**
-- File paths use globs (`src/**/*.ts`) instead of explicit names
-- Assignment says "update all" / "migrate everything" / "refactor across"
-- Scope covers entire package or directory tree
-  **Fix:** You MUST enumerate files first (grep/glob discovery), then fan out one task per file or small cluster.
----
-
-## Parallelization
-**Test:** Can task B produce correct output without seeing task A's result?
-- **Yes** → parallelize
-- **No** → run sequentially (A completes, then launch B with A output in context)
-
-### Must be sequential
-
-|First|Then|Reason|
-|---|---|---|
-|Define types/interfaces|Implement consumers|Consumers need contract|
-|Create API exports|Write bindings/callers|Callers need export names/signatures|
-|Scaffold structure|Implement bodies|Bodies need shape|
-|Core module|Dependent modules|Dependents import from core|
-|Schema/DB migration|Application logic|Logic depends on new schema shape|
-
-### Safe to parallelize
-- Independent modules, no cross-imports
-- Tests for already-implemented code
-- Isolated file-scoped refactors
-- Documentation for stable APIs
-
-### Phased execution
-
-<caution>
-**Parallel agents share the working tree.** They see each other's half-finished edits in real time. This is why:
-- Parallel tasks MUST NOT run project-wide build/test/lint — they will collide on phantom errors
-- Tasks editing overlapping files MUST use `isolated: true` (worktree isolation) or be made sequential
-- The caller MUST run verification after all tasks complete, not inside any individual task
-</caution>
-
-Layered work with dependencies:
-**Phase 1 — Foundation** (caller MUST do this, MUST NOT delegate): define interfaces, create scaffolds, establish API shape. You MUST NOT fan out until contract is known.
-**Phase 2 — Parallel implementation**: fan out tasks consuming same known interface. Include Phase 1 API contract in `context`.
-**Phase 3 — Integration** (caller MUST do this, MUST NOT delegate): wire modules, fix mismatches, verify builds.
-**Phase 4 — Dependent layer**: fan out tasks consuming Phase 2 outputs.
----
-
-## Pre-flight checklist
-
-<critical>
-Before calling tool, verify each item:
-- [ ] `context` MUST include only session-specific info not already in AGENTS.md/context files
-- [ ] Each `assignment` MUST follow the assignment template — one-liners are PROHIBITED
-- [ ] Each `assignment` MUST include edge cases / "don't break" items
-- [ ] Tasks MUST be truly parallel — you MUST be able to articulate why no task depends on another's output
-- [ ] Scope MUST be small; file paths MUST be explicit (no globs)
-- [ ] Tasks MUST NOT run project-wide build/test/lint — caller MUST verify after all tasks complete
-- [ ] `schema` MUST be used if you expect structured output
-</critical>
----
-
-## Agents
 
 {{#list agents join="\n"}}
-<agent name="{{name}}"{{#if output}} output="structured"{{/if}}>
-<description>{{description}}</description>
-<tools>{{default (join tools ", ") "All tools"}}</tools>
-</agent>
+### Agent: {{name}}
+**Tools:** {{default (join tools ", ") "All"}}
+{{description}}
 {{/list}}

package/src/prompts/tools/web-search.md

@@ -7,13 +7,6 @@ Search the web for up-to-date information beyond Claude's knowledge cutoff.
 - You MUST include links for cited sources in the final response
 </instruction>
 
-<output>
-Returns search results formatted as blocks with:
-- Result summaries and relevant excerpts
-- Links as markdown hyperlinks for citation
-- Provider-dependent structure based on selected backend
-</output>
-
 <caution>
 Searches are performed automatically within a single API call—no pagination or follow-up requests needed.
 </caution>

package/src/prompts/tools/write.md

@@ -5,13 +5,8 @@ Creates or overwrites file at specified path.
 <conditions>
 - Creating new files explicitly required by task
 - Replacing entire file contents when editing would be more complex
-- Prefer `local://<path>` for large temporary artifacts, subagent handoff payloads, and reusable planning artifacts that should survive within the session
 </conditions>
 
-<output>
-Confirmation of file creation/write with path. When LSP available, content may be auto-formatted before writing and diagnostics returned. Returns error if write fails (permissions, invalid path, disk full).
-</output>
-
 <critical>
 - You SHOULD use Edit tool for modifying existing files (more precise, preserves formatting)
 - You MUST NOT create documentation files (*.md, README) unless explicitly requested

package/src/sdk.ts

@@ -1,4 +1,11 @@
-import { Agent, type AgentEvent, type AgentMessage, type AgentTool, type ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import {
+	Agent,
+	type AgentEvent,
+	type AgentMessage,
+	type AgentTool,
+	INTENT_FIELD,
+	type ThinkingLevel,
+} from "@oh-my-pi/pi-agent-core";
 import { type Message, type Model, supportsXhigh } from "@oh-my-pi/pi-ai";
 import { prewarmOpenAICodexResponses } from "@oh-my-pi/pi-ai/providers/openai-codex-responses";
 import type { Component } from "@oh-my-pi/pi-tui";
@@ -1114,6 +1121,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	});
 
 	const repeatToolDescriptions = settings.get("repeatToolDescriptions");
+	const intentField = settings.get("tools.intentTracing") || $env.PI_INTENT_TRACING === "1" ? INTENT_FIELD : undefined;
 	const rebuildSystemPrompt = async (toolNames: string[], tools: Map<string, AgentTool>): Promise<string> => {
 		toolContextStore.setToolNames(toolNames);
 		const memoryInstructions = await buildMemoryToolDeveloperInstructions(agentDir, settings);
@@ -1128,6 +1136,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			skillsSettings: settings.getGroup("skills") as SkillsSettings,
 			appendSystemPrompt: memoryInstructions,
 			repeatToolDescriptions,
+			intentField,
 		});
 
 		if (options.systemPrompt === undefined) {
@@ -1146,6 +1155,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				customPrompt: options.systemPrompt,
 				appendSystemPrompt: memoryInstructions,
 				repeatToolDescriptions,
+				intentField,
 			});
 		}
 		return options.systemPrompt(defaultPrompt);
@@ -1283,7 +1293,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		},
 		cursorExecHandlers,
 		transformToolCallArguments: obfuscator?.hasSecrets() ? args => obfuscator!.deobfuscateObject(args) : undefined,
-		intentTracing: settings.get("tools.intentTracing") || $env.PI_INTENT_TRACING === "1",
+		intentTracing: !!intentField,
 	});
 	cursorEventEmitter = event => agent.emitExternalEvent(event);
 

package/src/system-prompt.ts

@@ -419,6 +419,8 @@ export interface BuildSystemPromptOptions {
 	preloadedSkills?: Skill[];
 	/** Pre-loaded rulebook rules (rules with descriptions, excluding TTSR and always-apply). */
 	rules?: Array<{ name: string; description?: string; path: string; globs?: string[] }>;
+	/** Intent field name injected into every tool schema. If set, explains the field in the prompt. */
+	intentField?: string;
 }
 
 /** Build the system prompt with tools, guidelines, and context */
@@ -439,6 +441,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		skills: providedSkills,
 		preloadedSkills: providedPreloadedSkills,
 		rules,
+		intentField,
 	} = options;
 	const resolvedCwd = cwd ?? getProjectDir();
 	const preloadedSkills = providedPreloadedSkills;
@@ -609,5 +612,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		dateTime,
 		cwd: resolvedCwd,
 		appendSystemPrompt: resolvedAppendPrompt ?? "",
+		intentTracing: !!intentField,
+		intentField: intentField ?? "",
 	});
 }

package/src/tools/{poll-jobs.ts → await-tool.ts}

@@ -1,10 +1,10 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import { type Static, Type } from "@sinclair/typebox";
 import { renderPromptTemplate } from "../config/prompt-templates";
-import pollJobsDescription from "../prompts/tools/poll-jobs.md" with { type: "text" };
+import awaitDescription from "../prompts/tools/await.md" with { type: "text" };
 import type { ToolSession } from "./index";
 
-const pollJobsSchema = Type.Object({
+const awaitSchema = Type.Object({
 	job_ids: Type.Optional(
 		Type.Array(Type.String(), {
 			description: "Specific job IDs to wait for. If omitted, waits for any running job.",
@@ -17,9 +17,9 @@ const pollJobsSchema = Type.Object({
 	),
 });
 
-type PollJobsParams = Static<typeof pollJobsSchema>;
+type AwaitParams = Static<typeof awaitSchema>;
 
-interface PollJobResult {
+interface AwaitResult {
 	id: string;
 	type: "bash" | "task";
 	status: "running" | "completed" | "failed" | "cancelled";
@@ -29,34 +29,34 @@ interface PollJobResult {
 	errorText?: string;
 }
 
-export interface PollJobsToolDetails {
-	jobs: PollJobResult[];
+export interface AwaitToolDetails {
+	jobs: AwaitResult[];
 	timedOut: boolean;
 }
 
-export class PollJobsTool implements AgentTool<typeof pollJobsSchema, PollJobsToolDetails> {
-	readonly name = "poll_jobs";
-	readonly label = "PollJobs";
+export class AwaitTool implements AgentTool<typeof awaitSchema, AwaitToolDetails> {
+	readonly name = "await";
+	readonly label = "Await";
 	readonly description: string;
-	readonly parameters = pollJobsSchema;
+	readonly parameters = awaitSchema;
 	readonly strict = true;
 
 	constructor(private readonly session: ToolSession) {
-		this.description = renderPromptTemplate(pollJobsDescription);
+		this.description = renderPromptTemplate(awaitDescription);
 	}
 
-	static createIf(session: ToolSession): PollJobsTool | null {
+	static createIf(session: ToolSession): AwaitTool | null {
 		if (!session.settings.get("async.enabled")) return null;
-		return new PollJobsTool(session);
+		return new AwaitTool(session);
 	}
 
 	async execute(
 		_toolCallId: string,
-		params: PollJobsParams,
+		params: AwaitParams,
 		signal?: AbortSignal,
-		_onUpdate?: AgentToolUpdateCallback<PollJobsToolDetails>,
+		_onUpdate?: AgentToolUpdateCallback<AwaitToolDetails>,
 		_context?: AgentToolContext,
-	): Promise<AgentToolResult<PollJobsToolDetails>> {
+	): Promise<AgentToolResult<AwaitToolDetails>> {
 		const manager = this.session.asyncJobManager;
 		if (!manager) {
 			return {
@@ -129,12 +129,12 @@ export class PollJobsTool implements AgentTool<typeof pollJobsSchema, PollJobsTo
 			errorText?: string;
 		}[],
 		timedOut: boolean,
-	): AgentToolResult<PollJobsToolDetails> {
+	): AgentToolResult<AwaitToolDetails> {
 		const now = Date.now();
-		const jobResults: PollJobResult[] = jobs.map(j => ({
+		const jobResults: AwaitResult[] = jobs.map(j => ({
 			id: j.id,
 			type: j.type,
-			status: j.status as PollJobResult["status"],
+			status: j.status as AwaitResult["status"],
 			label: j.label,
 			durationMs: Math.max(0, now - j.startTime),
 			...(j.resultText ? { resultText: j.resultText } : {}),

package/src/tools/browser.ts

@@ -380,7 +380,7 @@ const browserSchema = Type.Object({
 		Type.Object({
 			width: Type.Number({ description: "Viewport width in pixels" }),
 			height: Type.Number({ description: "Viewport height in pixels" }),
-			deviceScaleFactor: Type.Optional(Type.Number({ description: "Device scale factor" })),
+			device_scale_factor: Type.Optional(Type.Number({ description: "Device scale factor" })),
 		}),
 	),
 	delta_x: Type.Optional(Type.Number({ description: "Scroll delta X (scroll)" })),
@@ -515,7 +515,14 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 	async #resetBrowser(params?: BrowserParams): Promise<Page> {
 		await this.#closeBrowser();
 		this.#currentHeadless = this.session.settings.get("browser.headless");
-		const initialViewport = params?.viewport ?? DEFAULT_VIEWPORT;
+		const vp = params?.viewport;
+		const initialViewport = vp
+			? {
+					width: vp.width,
+					height: vp.height,
+					deviceScaleFactor: vp.device_scale_factor ?? DEFAULT_VIEWPORT.deviceScaleFactor,
+				}
+			: DEFAULT_VIEWPORT;
 		const puppeteer = await loadPuppeteer();
 		this.#browser = await puppeteer.launch({
 			headless: this.#currentHeadless,
@@ -556,8 +563,15 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 	}
 
 	async #applyViewport(page: Page, viewport?: BrowserParams["viewport"]): Promise<void> {
-		const target = viewport ?? DEFAULT_VIEWPORT;
-		await page.setViewport(target);
+		if (!viewport) {
+			await page.setViewport(DEFAULT_VIEWPORT);
+			return;
+		}
+		await page.setViewport({
+			width: viewport.width,
+			height: viewport.height,
+			deviceScaleFactor: viewport.device_scale_factor ?? DEFAULT_VIEWPORT.deviceScaleFactor,
+		});
 	}
 
 	async #clearElementCache(): Promise<void> {

package/src/tools/index.ts

@@ -15,6 +15,7 @@ import type { AgentOutputManager } from "../task/output-manager";
 import type { EventBus } from "../utils/event-bus";
 import { SearchTool } from "../web/search";
 import { AskTool } from "./ask";
+import { AwaitTool } from "./await-tool";
 import { BashTool } from "./bash";
 import { BrowserTool } from "./browser";
 import { CalculatorTool } from "./calculator";
@@ -25,7 +26,6 @@ import { FindTool } from "./find";
 import { GrepTool } from "./grep";
 import { NotebookTool } from "./notebook";
 import { wrapToolWithMetaNotice } from "./output-meta";
-import { PollJobsTool } from "./poll-jobs";
 import { PythonTool } from "./python";
 import { ReadTool } from "./read";
 import { reportFindingTool } from "./review";
@@ -54,6 +54,7 @@ export * from "../session/streaming-output";
 export { BUNDLED_AGENTS, TaskTool } from "../task";
 export * from "../web/search";
 export { AskTool, type AskToolDetails } from "./ask";
+export { AwaitTool, type AwaitToolDetails } from "./await-tool";
 export { BashTool, type BashToolDetails, type BashToolInput, type BashToolOptions } from "./bash";
 export { BrowserTool, type BrowserToolDetails } from "./browser";
 export { CalculatorTool, type CalculatorToolDetails } from "./calculator";
@@ -64,7 +65,6 @@ export { type FindOperations, FindTool, type FindToolDetails, type FindToolInput
 export { setPreferredImageProvider } from "./gemini-image";
 export { GrepTool, type GrepToolDetails, type GrepToolInput } from "./grep";
 export { NotebookTool, type NotebookToolDetails } from "./notebook";
-export { PollJobsTool, type PollJobsToolDetails } from "./poll-jobs";
 export { PythonTool, type PythonToolDetails, type PythonToolOptions } from "./python";
 export { ReadTool, type ReadToolDetails, type ReadToolInput } from "./read";
 export { reportFindingTool, type SubmitReviewDetails } from "./review";
@@ -169,7 +169,7 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	browser: s => new BrowserTool(s),
 	task: TaskTool.create,
 	cancel_job: CancelJobTool.createIf,
-	poll_jobs: PollJobsTool.createIf,
+	await: AwaitTool.createIf,
 	todo_write: s => new TodoWriteTool(s),
 	fetch: s => new FetchTool(s),
 	web_search: s => new SearchTool(s),

package/src/tools/notebook.ts

@@ -63,7 +63,7 @@ export class NotebookTool implements AgentTool<typeof notebookSchema, NotebookTo
 	readonly name = "notebook";
 	readonly label = "Notebook";
 	readonly description =
-		"Completely replaces the contents of a specific cell in a Jupyter notebook (.ipynb file) with new source. Jupyter notebooks are interactive documents that combine code, text, and visualizations, commonly used for data analysis and scientific computing. The notebook_path parameter must be an absolute path, not a relative path. The cell_number is 0-indexed. Use edit_mode=insert to add a new cell at the index specified by cell_number. Use edit_mode=delete to delete the cell at the index specified by cell_number.";
+		"Edit, insert, or delete cells in Jupyter notebooks (.ipynb). cell_index is 0-based. Paths must be absolute.";
 	readonly parameters = notebookSchema;
 	readonly strict = true;
 	readonly concurrency = "exclusive";