`ref` is a JTD-reserved keyword (RFC 8927) used by the schema-reference
form, so the JTD-to-JSON-Schema converter on releases prior to 15.3.2
silently dropped it from the generated JSON Schema and required it at
the same time. Every explore-agent invocation then failed validation
with `schema_violation: files.0.ref: must not be present`.
The converter side was hardened in #1345 (shipped in 15.3.2). This
rename is defense-in-depth at the prompt level: the explore agent's
output contract no longer relies on the converter recognising a
user-named property that collides with a JTD keyword, and the field
name now matches what it actually carries.
Fixes#1379
Adds optional autoloadSkills field to agent frontmatter that automatically loads listed skills when a sub-agent is spawned. Uses the same buildSkillPromptMessage + sendCustomMessage mechanism as interactive skill loading, queued via sendCustomMessage({ triggerTurn: false }) before the first session.prompt(task). No extra agent turns, no new injection path. Skills stay in listing for sub-resource access. Compaction behavior matches manual loading. Unknown skill names silently skipped.
Lore-id: f85fdbdc
Constraint: autoload must use buildSkillPromptMessage + sendCustomMessage, never modify systemPrompt or use contextFiles
Constraint: triggerTurn must be false to avoid extra agent turns
Rejected: append to systemPrompt | agent cannot distinguish skill content from own instructions
Rejected: contextFiles injection | agent sees opaque file blob, cannot discover sub-resources
Rejected: promptCustomMessage per skill | N extra agent turns with model inference
Directive: autoload skill names are resolved against parent session skill list at spawn time in task/index.ts
Tested: TypeScript compiles clean with tsc --noEmit
Tested: parseAgentFields parses array and CSV string frontmatter
Tested: parseAgentFields returns undefined for absent and empty fields
Not-tested: bun test cannot run locally due to missing pi_natives native addon (requires Rust toolchain)
Confidence: high
Scope-risk: moderate
Reversibility: clean
- Updated the oracle agent description to present it as a senior engineer who can either consult or execute when delegated.
- Removed the read-only mandate and added requirements to implement changes, run checks, and report completed work in delegation mode.
- Adjusted the procedure and decision guidance to distinguish consult versus implement paths while keeping the scope limited to requested tasks.
- Added a new `oracle.md` prompt defining a read-only diagnostic, architecture, and debugging advisor.
- Imported `oracle.md` into the agent prompt loader in `packages/coding-agent/src/task/agents.ts`.
- Included `oracle.md` in `EMBEDDED_AGENT_DEFS` so the new agent is available at runtime.
- Standardized prompt templates across agents, tools, system, memory, and compaction to NEVER/AVOID wording.
- Reinforced policy language to ban edits/builds, state changes, and unsolicited JSON/code or filler output.
- Renamed stripRfc2119Bold to normalizeRfc2119, mapped NEVER/AVOID aliases, and skipped inline-code replacements.
- Updated the unreleased changelog to document the prompt-terminology migration.
When a patch introduces a new type that crosses a function/module
boundary (event, message, RPC frame, enum variant, etc.), the reviewer
must locate the dispatch point on the consuming side and confirm the
new type is handled. This class of bug is invisible from the diff alone
because the silent drop lives in untouched routing code.
Motivated by a missed P2 in PR #987: a new open_url extension_ui_request
was emitted by login() but RpcClient#handleLine had no case for it and
silently dropped every frame, leaving callers with no auth URL and the
command hanging until timeout.
- Removed persona preambles ("You are an expert...") in favor of direct imperatives.
- Stripped redundant MUST/SHOULD modals where plain prose suffices.
- Condensed multi-sentence instructions into tighter single-line equivalents.
- Renamed the built-in `grep` content-search tool to `search` across settings, schemas, and SDK exports.
- Switched execution wiring so `Task`, `Plan`, cursor, and shell mapping now invoke `search` instead of `grep`.
- Updated prompts, plan-mode docs, and example tool lists to replace `grep`/`ls` references with `search` guidance.
- Aligned `Grep*`/`grep` event, renderer, and hook types to `Search*`/`search` across runtime and tests.
- Documented and fixed `search` result rendering budget behavior and added internal-URL/path-list transcript notes.
- Updated reviewer prompt field descriptions to refer to file paths generally instead of absolute paths.
- Reworded notebook and write tool metadata to remove absolute-path constraints.
- Added system guidance to prefer cwd-relative paths for path-style tool arguments.
- Renamed subagent completion flow from `submit_result` to `yield` across SDK tools, prompts, and docs.
- Updated executor/task handling to require and parse `yield` calls, replacing legacy submit-result extraction and state flags.
- Added `subagent-yield-reminder` and updated system prompts to require `yield` with `result.data` or `result.error`.
- Renamed hidden-tool and registration plumbing to `yield`, including discovery helpers and renderer/test surface.
- Added designer model role for UI/UX design tasks with Gemini 3.1 Pro as default model.
- Implemented model role fallback list support enabling automatic fallback to next available model when primary is unavailable.
- Refactored model role resolution to support multiple fallback patterns per role with thinking level mapping.
- Updated designer agent to use pi/designer role alias instead of explicit model list, removing spawns configuration.
- Added test coverage for model resolver fallback patterns and designer role override preferences.
- Added test coverage for geminiImageTool X-Title header routing through OpenRouter.
- Migrated all package tsconfig files to extend tsconfig.workspace.json for unified TypeScript configuration across monorepo.
- Consolidated build and check scripts across 10+ packages to use biome for linting/formatting with separate type checking via tsgo.
- Renamed build scripts from build:native and build:binary to build for simplified command naming across packages/natives and packages/coding-agent.
- Refactored CI workflow to invoke bun tasks instead of inline shell scripts, reducing workflow complexity by 40+ lines.
- Removed sync-exports.ts and repro-stuck.ts scripts; deleted path aliases from tsconfig.base.json in favor of workspace-based configuration.
- Updated turbo.json with new task definitions (check:types, lint, fmt, fix) and removed build:native/embed:native tasks.
- Consolidated fetch tool into read tool with URL reading capability and caching support.
- Removed standalone fetch tool from all agent prompts and CLI documentation.
- Extended read tool schema with timeout and raw parameters for URL fetch control.
- Added URL caching mechanism to prevent redundant network requests during read operations.
- Refactored fetch module from class-based tool to standalone executeReadUrl function.
- Updated read tool documentation to describe multi-purpose capabilities including web pages, GitHub, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, blogs, and feeds.
- Added gh-renderer.ts module with GitHub Actions workflow visualization for terminal output.
- Enhanced gh_pr_view tool to fetch and display inline review comments alongside pull request reviews.
- Improved gh_run_watch tool output with structured job state tracking and failed log formatting.
- Fixed gh_run_watch to resolve explicit branch watches against GitHub API branch head instead of local HEAD.
- Fixed gh_* tool outputs to spill full large results to artifacts instead of pre-truncating.
- Standardized trailing newlines across 100+ prompt template files for POSIX compliance.
- Updated explore agent thinking level from off to med for improved reasoning.
- Simplified explore agent output schema: consolidated file references into single `ref` field with optional line ranges instead of separate `path`, `line_start`, `line_end` fields.
- Removed `code` section from explore agent output (critical code excerpts no longer extracted).
- Removed `dependencies`, `risks`, and `start_here` sections from explore agent output.
- Added fallback search strategies in librarian and explore agent prompts for handling empty results.
- Clarified task completion priority in system prompt by prohibiting premature tool call cessation.
- Consolidated and simplified 'Giving Up' guidance in subagent prompt with clearer uncertainty handling.
- Removed duplicate instructions and redundant phrasing to improve prompt clarity and conciseness.
- Added librarian and oracle agents for library research and technical diagnostics.
- Expanded tool support across explore, plan, and reviewer agents with lsp, fetch, web_search, and ast_grep.
- Added dependencies and risks output fields to explore agent for enhanced analysis.
- Renamed explore agent output field from query to summary with expanded description.
- Restructured submit_result tool parameter schema to wrap data and error fields in a nested result object.
- Updated all prompt documentation to reference the new result.data and result.error parameter paths.
- Added validation logic to ensure result is an object containing exactly one of data or error.
- Updated test cases to reflect the new nested result object parameter structure.
- Standardized prompt format, removing XML-like tags.
- Emphasized RFC 2119 keywords using bolding across all prompts.
- Rewrote the core system prompt with enhanced structure and directives.
- Standardized XML tag naming from snake_case to kebab-case across 50+ prompt files for consistency.
- Replaced imperative language with RFC 2119 keywords (MUST/SHOULD/MAY/MUST NOT) throughout system and tool prompts for clarity.
- Removed artifactsDir parameter from Python executor and simplified environment variable handling to use PI_SESSION_FILE only.
- Renamed read_path.md to read-path.md and updated memory guidance with hierarchy rules and conflict resolution workflow.
- Added noEscape option to bash URL expansion and extracted cwd parameter from leading cd commands for improved path handling.
- Exported NO_PAGER_ENV constant from bash-interactive module for centralized environment variable management.
- Added AgentBusyError exception class for concurrent operation handling across agent packages.
- Added automatic retry logic with 30-second timeout for agent prompts when agent is busy.
- Changed concurrent operation errors from generic Error to AgentBusyError for better error handling.
- Fixed model discovery to use default refresh mode instead of explicit 'online' parameter.
- Extracted model priority configuration from TypeScript constants to external priority.json file.
- Updated agent prompts (reviewer, explore, plan) to reference new model tier aliases (pi/slow, pi/smol, pi/plan).
- Removed hardcoded SMOL_MODEL_PRIORITY and SLOW_MODEL_PRIORITY constants from model-resolver.ts.
- Improved prompt formatting with consistent newlines and whitespace in agent configuration files.
- Refactored task API to use 'assignment' field instead of 'args' for per-task instructions, enabling clearer separation between shared context and task-specific work.
- Introduced structured context/assignment separation pattern with '<swarm_context>' wrapper for template rendering, replacing placeholder-based substitution.
- Changed agent frontmatter field from 'thinkingLevel' to 'thinking-level' (kebab-case) for consistency with YAML conventions.
- Removed 'context' parameter from ExecutorOptions as context is now prepended at template level rather than executor level.
- Removed 'args' field from AgentProgress and SingleResult interfaces, simplifying task result tracking.
- Updated task rendering to display full task text instead of formatted args, improving clarity in progress output.
- Added jsonStringify Handlebars helper to enable safe JSON serialization of template variables in frontmatter generation.
- Improved frontmatter parsing error messages to include source context, making debugging easier when YAML frontmatter parsing fails.
- Standardized markdown table formatting with consistent column alignment and spacing across SKILL.md documentation.
- Added blank lines after section headers and before code blocks to improve documentation readability.
- Updated nested markdown code block fence from triple to quadruple backticks for proper syntax highlighting.
- Fixed XML element indentation and closing tags for </procedure> and </system_directive> elements.
- Removed 'ls' tool from agent definitions (explore, plan, reviewer) to streamline available tool sets.
- Expanded model list in explore agent to include additional model variants (haiku-4.5, gemini-flash-latest, glm variants, gpt-5.1-codex-mini).
- Condensed prompt documentation throughout by removing articles, auxiliary verbs, and redundant explanations for improved clarity and conciseness.
- Simplified system prompts by replacing multi-line explanations with terse, semicolon-separated fragments and removing verbose motivational language.
- Reformatted tool documentation to use abbreviated language, removing 'the', 'a', and 'is' throughout for more direct technical writing.
- Removed blank lines and consolidated spacing in prompt files to reduce vertical whitespace and improve document density.
- Added model preference matching system with ModelMatchPreferences and ModelPreferenceContext interfaces to enable intelligent model selection based on usage history and provider preferences.
- Implemented buildPreferenceContext and pickPreferredModel functions to rank and select models based on usage order, provider history, and deprioritization settings.
- Enhanced parseModelPattern function to accept optional ModelMatchPreferences parameter, enabling model resolution to consider user preferences and usage history.
- Updated model matching logic to prioritize models based on historical usage patterns and provider preferences when multiple candidates match a pattern.
- Renamed 'complete' tool to 'submit_result' throughout codebase for clarity and consistency.
- Updated all tool references, function names, and variable names from 'complete' to 'submit_result' in executor, render, and tools modules.
- Renamed CompleteTool class to SubmitResultTool and CompleteDetails interface to SubmitResultDetails.
- Updated agent prompts and documentation to reference the new 'submit_result' tool name.
- Reorganized task.md prompt to move critical guidance to the top and restructure instructions for better clarity.
- Added ToolChoice type and toolChoice parameter support across all AI providers (OpenAI, Azure OpenAI, Anthropic, Google) enabling fine-grained control over tool/function selection during LLM calls.
- Added toolChoice override capability to Agent.prompt() method and session prompt options allowing callers to control tool selection behavior per request.
- Added provider-specific tool choice mapping functions (mapAnthropicToolChoice, mapGoogleToolChoice, mapOpenAiToolChoice) to normalize tool choice formats across different LLM APIs.
- Removed kernel heartbeat/ping mechanism from PythonKernel, simplifying health monitoring by relying on direct isAlive() checks instead of periodic HTTP requests.
- Added 'plan' model role option to support architectural planning with dedicated model selection via CLI argument (--plan), environment variable (OMP_PLAN_MODEL), and UI menu action.
- Updated model selector to display 'PLAN' badge for plan models and prioritize them in the model sorting order.
- Relaxed task management constraints to allow multiple tasks to be in_progress simultaneously, enabling parallel task execution instead of enforcing single-task-at-a-time workflow.
- Improved todo validation to check for blocking pending tasks before allowing a todo to be marked in_progress, with more specific error messages indicating which earlier tasks are blocking progress.
- Refined descriptions to be more concise and focused.
- Restructured content for improved clarity and consistency across all plan mode prompts.
- Tightened critical sections with more direct language.
- Improved plan mode prompt clarity and organization.
- Plan mode provides structured workflow where agents propose plans for user approval before execution.
- Added plan:// internal URL protocol for accessing plan files and injecting plan-mode context into subagent prompts.
- Added plan mode toggle shortcut and paused status indicator in status line.
- Fixed plan reference injection to properly pass workflow state to plan-mode system prompts.
- Improved autocomplete fuzzy matching to support subsequence matching for skill suggestions.
- Added format-prompts script for standardizing prompt file formatting across the codebase.
- Updated system prompt tags from `<required>`/`<antipatterns>` to `<important>`/`<avoid>` for clarity.
- Enhanced prompt formatting by removing blank lines after colons and around blocks for consistency.
- Standardized whitespace handling across all prompt files to improve readability.
- Removed centralized tool descriptions from prompt generation logic.
- Eliminated consolidated tool list rendering in system prompts.
- Added explicit tool name headings to individual tool documentation files.
- Simplifies prompt construction by decentralizing tool information.
- Added Python shared gateway setting for resource-efficient kernel reuse across sessions.
- Enhanced Python tool with session-scoped kernel isolation and workdir-aware session IDs.
- Added Python tool cancellation support with timeout handling and proper cleanup.
- Expanded Python prelude with enhanced file operations, git utilities, and improved output handling.
- Fixed AI provider message transformation for proper tool call handling and error recovery.
- Added IPython-backed Python tool with streaming output and image/JSON rendering.
- Implemented Jupyter kernel gateway integration with WebSocket communication.
- Added Python prelude with 30+ shell-like utility functions for file operations.
- Migrated environment variables from PI_ to OMP_ prefix with automatic migration.
- Added streaming output system with automatic spill-to-disk for large outputs.
- Reorganized settings interface into behavior, tools, display, voice, status, lsp, and exa tabs.
- Added thinkingLevel field to agent frontmatter allowing subagents to override thinking level with clamping to model capabilities.
- Added structured output schema to reviewer agent ensuring consistent review output format with findings, correctness verdict, and confidence.
- Expanded system prompt with defensive reasoning guidance including assumption checks, edge case awareness, and completion reflex inhibition.
- Consolidated expandPath, parseFrontmatter, and parseAgentFields utilities into discovery/helpers module eliminating code duplication across loaders.
- Replaced silent error handling with logger.warn calls across config parsing, migrations, extension loading, and OAuth refresh failures.
can1357