@oh-my-pi/pi-coding-agent 5.4.0 → 5.5.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [5.5.0] - 2026-01-18
+### Changed
+
+- Updated task execution guidelines to improve prompt framing and parallelization instructions
+
+## [5.4.2] - 2026-01-16
+### Changed
+
+- Updated model resolution to accept pre-serialized settings for better performance
+- Improved system prompt guidance for position-addressed vs content-addressed file edits
+- Enhanced edit tool documentation with clear use cases for bash alternatives
+
 ## [5.4.0] - 2026-01-15
 
 ## [5.3.1] - 2026-01-15

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "5.4.0",
+	"version": "5.5.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"ompConfig": {
@@ -39,10 +39,10 @@
 		"prepublishOnly": "bun run generate-template && bun run clean && bun run build"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-agent-core": "5.4.0",
-		"@oh-my-pi/pi-ai": "5.4.0",
-		"@oh-my-pi/pi-git-tool": "5.4.0",
-		"@oh-my-pi/pi-tui": "5.4.0",
+		"@oh-my-pi/pi-agent-core": "5.5.0",
+		"@oh-my-pi/pi-ai": "5.5.0",
+		"@oh-my-pi/pi-git-tool": "5.5.0",
+		"@oh-my-pi/pi-tui": "5.5.0",
 		"@openai/agents": "^0.3.7",
 		"@silvia-odwyer/photon-node": "^0.3.4",
 		"@sinclair/typebox": "^0.34.46",

package/src/core/tools/task/executor.ts

@@ -269,8 +269,11 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 		}
 	}
 
+	const serializedSettings = options.settingsManager?.serialize();
+	const availableModels = options.modelRegistry?.getAvailable().map((model) => `${model.provider}/${model.id}`);
+
 	// Resolve and add model
-	const resolvedModel = await resolveModelPattern(modelOverride || agent.model);
+	const resolvedModel = await resolveModelPattern(modelOverride || agent.model, availableModels, serializedSettings);
 	const sessionFile = subtaskSessionFile ?? options.sessionFile ?? null;
 	const spawnsEnv = agent.spawns === undefined ? "" : agent.spawns === "*" ? "*" : agent.spawns.join(",");
 
@@ -601,7 +604,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 			enableLsp,
 			serializedAuth: options.authStorage?.serialize(),
 			serializedModels: options.modelRegistry?.serialize(),
-			serializedSettings: options.settingsManager?.serialize(),
+			serializedSettings,
 			mcpTools: options.mcpManager ? extractMCPToolMetadata(options.mcpManager) : undefined,
 		},
 	};

package/src/core/tools/task/model-resolver.ts

@@ -11,8 +11,9 @@
  *   - "omp/slow" or "pi/slow" → configured slow model from settings
  */
 
-import { type Settings, settingsCapability } from "../../../capability/settings";
+import { type Settings as SettingsFile, settingsCapability } from "../../../capability/settings";
 import { loadCapability } from "../../../discovery";
+import type { Settings as SettingsData } from "../../settings-manager";
 import { resolveOmpCommand } from "./omp-command";
 
 /** Cache for available models (provider/modelId format) */
@@ -80,7 +81,7 @@ export function clearModelCache(): void {
  * Load model roles from settings files using capability API.
  */
 async function loadModelRoles(): Promise<Record<string, string>> {
-	const result = await loadCapability<Settings>(settingsCapability.id, { cwd: process.cwd() });
+	const result = await loadCapability<SettingsFile>(settingsCapability.id, { cwd: process.cwd() });
 
 	// Merge all settings, prioritizing first (highest priority)
 	let modelRoles: Record<string, string> = {};
@@ -99,8 +100,12 @@ async function loadModelRoles(): Promise<Record<string, string>> {
  * Looks up the role in settings.modelRoles and returns the configured model.
  * Returns undefined if the role isn't configured.
  */
-async function resolveOmpAlias(role: string, availableModels: string[]): Promise<string | undefined> {
-	const roles = await loadModelRoles();
+async function resolveOmpAlias(
+	role: string,
+	availableModels: string[],
+	settings?: SettingsData,
+): Promise<string | undefined> {
+	const roles = settings?.modelRoles ?? (await loadModelRoles());
 
 	// Look up role in settings (case-insensitive)
 	const configured = roles[role] || roles[role.toLowerCase()];
@@ -135,10 +140,12 @@ function getProvider(fullModel: string): string | undefined {
  *
  * @param pattern - Model pattern to resolve
  * @param availableModels - Optional pre-fetched list of available models (in provider/modelId format)
+ * @param settings - Optional settings for role alias resolution (pi/..., omp/...)
  */
 export async function resolveModelPattern(
 	pattern: string | undefined,
 	availableModels?: string[],
+	settings?: SettingsData,
 ): Promise<string | undefined> {
 	if (!pattern || pattern === "default") {
 		return undefined;
@@ -161,7 +168,7 @@ export async function resolveModelPattern(
 		const lower = p.toLowerCase();
 		if (lower.startsWith("omp/") || lower.startsWith("pi/")) {
 			const role = lower.startsWith("omp/") ? p.slice(4) : p.slice(3);
-			const resolved = await resolveOmpAlias(role, models);
+			const resolved = await resolveOmpAlias(role, models, settings);
 			if (resolved) return resolved;
 			continue; // Role not configured, try next pattern
 		}

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

@@ -71,12 +71,20 @@ Every tool is a choice. The wrong choice is friction. The right choice is invisi
 File and system operations:
 - `mv`, `cp`, `rm`, `ln -s` — moving, copying, deleting, symlinking
 - `mkdir -p`, `chmod` — directory creation, permissions
-- `sd` — bulk find/replace across multiple files (faster than repeated edits)
 - `tar`, `zip`, `unzip` — archives
 - `curl` — downloading files
 - Build commands: `cargo`, `npm`, `make`, `docker`
 - Process management: running servers, background tasks
 
+Position-addressed and pattern-addressed edits:
+- `cat >> file <<'EOF'` — append to file
+- `sed -i 'N,Md' file` — delete lines N-M
+- `sed -i 'Na\text' file` — insert after line N
+- `sd 'pattern' 'replacement' file` — regex replace
+- `sd 'pattern' 'replacement' **/*.ts` — bulk regex across files
+- `sed -n 'N,Mp' src >> dest` — copy lines N-M to another file
+- `sed -n 'N,Mp' src >> dest && sed -i 'N,Md' src` — move lines N-M to another file
+
 ### What bash is NOT for
 Specialized tools exist. Use them.
 
@@ -84,7 +92,7 @@ Specialized tools exist. Use them.
 {{#has tools "grep"}}- Searching content: `grep` finds. Shell pipelines guess.{{/has}}
 {{#has tools "find"}}- Finding files: `find` knows structure. `ls | grep` hopes.{{/has}}
 {{#has tools "ls"}}- Listing directories: `ls` tool, not bash ls.{{/has}}
-{{#has tools "edit"}}- Editing files: `edit` is precise. `sed` is brittle.{{/has}}
+{{#has tools "edit"}}- Content-addressed edits: `edit` finds text. Use bash for position/pattern (append, line N, regex).{{/has}}
 {{#has tools "git"}}- Git operations: `git` tool has guards. Bash git has none.{{/has}}
 
 ### Hierarchy of trust

package/src/prompts/tools/edit.md

@@ -1,9 +1,30 @@
 Performs string replacements in files with fuzzy whitespace matching.
 
 Usage:
+- Use the smallest edit that uniquely identifies the change. To toggle a checkbox: `- [ ] Task` → `- [x] Task`, not the entire line.
 - You must use your read tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
 - Fuzzy matching handles minor whitespace/indentation differences automatically - you don't need to match indentation exactly.
 - ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
 - Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
 - The edit will FAIL if old_string is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use replace_all to change every instance of old_string.
 - Use replace_all for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.
+
+## When to use bash instead
+
+Edit is for content-addressed changes—you identify *what* to change by its text.
+
+For position-addressed or pattern-addressed changes, bash is more efficient:
+
+| Operation | Command |
+|-----------|---------|
+| Append to file | `cat >> file <<'EOF'`...`EOF` |
+| Prepend to file | `{ cat - file; } <<'EOF' > tmp && mv tmp file` |
+| Delete lines N-M | `sed -i 'N,Md' file` |
+| Insert after line N | `sed -i 'Na\text' file` |
+| Regex replace | `sd 'pattern' 'replacement' file` |
+| Bulk replace across files | `sd 'pattern' 'replacement' **/*.ts` |
+| Copy lines N-M to another file | `sed -n 'N,Mp' src >> dest` |
+| Move lines N-M to another file | `sed -n 'N,Mp' src >> dest && sed -i 'N,Md' src` |
+
+Use Edit when the *content itself* identifies the location.
+Use bash when *position* or *pattern* identifies what to change.

package/src/prompts/tools/task.md

@@ -32,9 +32,13 @@ Agents with "Output: structured" have a fixed schema enforced via frontmatter; y
 
 - Always include a short description of the task in the task parameter
 - **Plan-then-execute**: Put shared constraints in `context`, keep each task focused, specify acceptance criteria; use `output` when you need structured output
+- **Ask open-ended questions**: For exploration tasks, frame prompts to elicit factual discovery, not confirmation. Avoid yes/no questions that are easy to hallucinate.
+  - Bad: "Is there rate limiting?" or "Does the API validate tokens?" → Binary answers invite hallucination
+  - Good: "Find and describe how rate limiting is implemented" or "How does the API handle token validation?" → Forces investigation and factual reporting
+  - The subagent should report *what exists*, then YOU verify if it meets requirements
 - **Minimize tool chatter**: Avoid repeating large context; use Output tool with output ids for full logs
 - **Structured completion**: If `output` is provided, subagents must call `complete` to finish
-- **Parallelize**: Launch multiple agents concurrently whenever possible
+- **Parallelize**: Launch multiple agents whenever possible. You MUST use a single Task call with multiple entries in the `tasks` array to do this.
 - **Isolate file scopes**: Assign each task distinct files or directories so agents don't conflict
 - **Results are intermediate data**: Agent findings provide context for YOU to perform actual work. Do not treat agent reports as "task complete" signals.
 - **Stateless invocations**: Subagents have zero memory of your conversation. Pass ALL relevant context: requirements discussed, decisions made, schemas agreed upon, file paths mentioned. If you reference something from earlier discussion without including it, the subagent will fail.