pi-orchestrator-config 4.2.0 → 4.2.1

package/extensions/orchestrator/subagent-tool.ts

@@ -6,7 +6,7 @@ import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { createRequire } from "node:module";
 
@@ -48,10 +48,20 @@ import {
   supportsAsyncLlm,
 } from "./async-capability.js";
 import { autoMarkInProgress, autoCompleteTask } from "./async-agents.js";
+import { getSetting } from "./project-settings.js";
+import { substituteSettingsPlaceholders } from "./rule-placeholders.js";
 import { resolveAgentModelProvider } from "./resolve-agent-model.js";
+import { parseModelOverride, mergeModelOverride } from "./parse-model-override.js";
 import { clockHHMM, getPiInvocation, getProjectTmpDir, djb2Hash } from "./utils.js";
 
-export { resolveAgentModelProvider };
+const SETTINGS_KEYS_FOR_SUBAGENT = JSON.parse(
+  fs.readFileSync(
+    path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "settings-keys.json"),
+    "utf-8",
+  ),
+);
+
+export { resolveAgentModelProvider, parseModelOverride };
 
 // ── Constants ────────────────────────────────────────────────────────────
 
@@ -82,6 +92,7 @@ const TaskItem = Type.Object({
   name: Type.Optional(Type.String({ description: "Display name for async status" })),
   estimatedSeconds: Type.Optional(Type.Number({ description: "Estimated task duration in seconds. Required for sync parallel tasks." })),
   taskId: Type.Optional(Type.String({ description: "Task ID to auto-complete when this async agent finishes" })),
+  model: Type.Optional(Type.String({ description: "Override the agent's model. Format: 'provider/model-id' or 'model-id'." })),
 });
 const ChainItem = Type.Object({
   agent: Type.String({ description: "Agent name" }),
@@ -141,6 +152,9 @@ const SubagentParams = Type.Object({
   persistSession: Type.Optional(
     Type.Boolean({ description: "Persist agent session to disk for reuse across calls. Default: false (ephemeral). When true, the same agent in the same project reuses its session — keeps context, saves tokens." }),
   ),
+  model: Type.Optional(
+    Type.String({ description: "Override the agent's model. Format: 'provider/model-id' (e.g., 'litellm/claude-opus-4-6-1m') or just 'model-id' (inherits provider). Overrides all other model resolution." }),
+  ),
 });
 
 // ── Interfaces ───────────────────────────────────────────────────────────
@@ -370,6 +384,7 @@ export async function runSingleAgent(
   parentModelId?: string,
   parentProvider?: string,
   persistSession?: boolean,
+  explicit?: { model?: string; provider?: string },
 ): Promise<SingleResult> {
   const agent = agents.find((a) => a.name === agentName);
   if (!agent) {
@@ -401,7 +416,7 @@ export async function runSingleAgent(
     // Deterministic session ID based on agent + cwd for session reuse
     args.push("--session-id", `sync-${agentName}-${djb2Hash(agentName + ':' + cwd).toString(36)}`);
   }
-  const { model: effectiveModel, provider: effectiveProvider } = resolveAgentModelProvider(agentName, agent, parentModelId, parentProvider, cwd);
+  const { model: effectiveModel, provider: effectiveProvider } = resolveAgentModelProvider(agentName, agent, parentModelId, parentProvider, cwd, explicit);
   if (effectiveModel) args.push("--model", effectiveModel);
   if (effectiveProvider) args.push("--provider", effectiveProvider);
   if (agent.tools && agent.tools.length > 0)
@@ -446,7 +461,12 @@ export async function runSingleAgent(
 
   try {
     if (agent.systemPrompt.trim()) {
-      const tmp = await writePromptFile(agent.name, agent.systemPrompt, cwd);
+      const resolvedPrompt = substituteSettingsPlaceholders(
+        agent.systemPrompt,
+        (key) => getSetting(cwd, key as any),
+        Object.keys(SETTINGS_KEYS_FOR_SUBAGENT),
+      );
+      const tmp = await writePromptFile(agent.name, resolvedPrompt, cwd);
       tmpDir = tmp.dir;
       tmpFile = tmp.filePath;
       args.push("--append-system-prompt", tmpFile);
@@ -528,6 +548,7 @@ export async function runSingleAgent(
 
     cur.exitCode = exitCode;
     cur.durationMs = Date.now() - startTime;
+
     if (aborted) throw new Error("Subagent was aborted");
     return cur;
   } finally {
@@ -575,7 +596,7 @@ function validateTaskId(taskId: string, cwd: string, sessionId?: string): string
 
 export function registerSubagentTool(
   pi: ExtensionAPI,
-  spawnAsyncAgent: (agentName: string, task: string, cwd: string, agents: AgentConfig[], options?: { fireAndForget?: boolean; name?: string; parentModelId?: string; parentProvider?: string; groupId?: string; taskId?: string }) => { id: string; error?: string; model?: string },
+  spawnAsyncAgent: (agentName: string, task: string, cwd: string, agents: AgentConfig[], options?: { fireAndForget?: boolean; name?: string; parentModelId?: string; parentProvider?: string; groupId?: string; taskId?: string; persistSession?: boolean; explicit?: { model?: string; provider?: string } }) => { id: string; error?: string; model?: string },
   killAsyncAgent: (target: string) => { killed: string[]; errors: string[] },
 ): void {
   // Only the orchestrator (top-level pi) can spawn subagents.
@@ -606,6 +627,7 @@ export function registerSubagentTool(
     parentModelId: string | undefined,
     parentProvider: string | undefined,
     ctx: any,
+    explicit?: { model?: string; provider?: string },
   ) {
     if (params.chain) {
       return {
@@ -664,6 +686,7 @@ export function registerSubagentTool(
         ? `group-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
         : undefined;
       for (const t of params.tasks) {
+        const taskExplicit = mergeModelOverride(t.model, explicit);
         const r = spawnAsyncAgent(t.agent, t.task, t.cwd, agents, {
           fireAndForget: params.fireAndForget,
           name: (t as any).name,
@@ -672,6 +695,7 @@ export function registerSubagentTool(
           groupId,
           taskId: (t as any).taskId,
           persistSession: params.persistSession,
+          explicit: taskExplicit,
         });
         if (r.error) {
           errors.push(`${t.agent}: ${r.error}`);
@@ -742,7 +766,15 @@ export function registerSubagentTool(
         };
       }
     }
-    const result = spawnAsyncAgent(params.agent, params.task, params.cwd, agents, { fireAndForget: params.fireAndForget, name: params.name, parentModelId, parentProvider, taskId: params.taskId, persistSession: params.persistSession });
+    const result = spawnAsyncAgent(params.agent, params.task, params.cwd, agents, {
+      fireAndForget: params.fireAndForget,
+      name: params.name,
+      parentModelId,
+      parentProvider,
+      taskId: params.taskId,
+      persistSession: params.persistSession,
+      explicit: explicit,
+    });
     if (result.error) {
       return {
         content: [{ type: "text" as const, text: result.error }],
@@ -770,6 +802,7 @@ export function registerSubagentTool(
     parentProvider: string | undefined,
     asyncOk: boolean,
     sessionId?: string,
+    explicit?: { model?: string; provider?: string },
   ) {
     const results: SingleResult[] = [];
     let prev = "";
@@ -848,6 +881,7 @@ export function registerSubagentTool(
         parentModelId,
         parentProvider,
         params.persistSession,
+        explicit,
       );
       activeAgents.delete(s.agent);
       updateWorking();
@@ -899,6 +933,7 @@ export function registerSubagentTool(
     parentProvider: string | undefined,
     asyncOk: boolean,
     sessionId?: string,
+    explicit?: { model?: string; provider?: string },
   ) {
     if (params.tasks.length > MAX_PARALLEL_TASKS)
       return {
@@ -997,6 +1032,7 @@ export function registerSubagentTool(
         const label = t.name || t.agent;
         activeAgents.add(label);
         updateWorking();
+        const taskExplicit = mergeModelOverride(t.model, explicit);
         const r = await runSingleAgent(
           agents,
           t.agent,
@@ -1014,6 +1050,7 @@ export function registerSubagentTool(
           parentModelId,
           parentProvider,
           params.persistSession,
+          taskExplicit,
         );
         all[i] = r;
         activeAgents.delete(t.name || t.agent);
@@ -1062,6 +1099,7 @@ export function registerSubagentTool(
     parentProvider: string | undefined,
     asyncOk: boolean,
     sessionId?: string,
+    explicit?: { model?: string; provider?: string },
   ) {
     if (!params.cwd) {
       return {
@@ -1116,6 +1154,7 @@ export function registerSubagentTool(
       parentModelId,
       parentProvider,
       params.persistSession,
+      explicit,
     );
     activeAgents.delete(label);
     updateWorking();
@@ -1451,6 +1490,8 @@ export function registerSubagentTool(
       const confirm = params.confirmProjectAgents ?? true;
       let parentModelId = ctx.model?.id as string | undefined;
       let parentProvider = ctx.model?.provider as string | undefined;
+      // Parse explicit model override from params (applies to all execution modes)
+      const explicitOverride = parseModelOverride(params.model);
       const asyncOk = supportsAsyncLlm(parentProvider, ctx.cwd);
       let capabilityNote = "";
 
@@ -1577,9 +1618,11 @@ export function registerSubagentTool(
         }
       }
 
+      const explicit = explicitOverride;
+
       // Async mode — spawn in background and return immediately
       if (params.async === true) {
-        const result = executeAsync(params, agents, mkd, parentModelId, parentProvider, ctx);
+        const result = executeAsync(params, agents, mkd, parentModelId, parentProvider, ctx, explicit);
         if (capabilityNote && result.content?.[0]?.type === "text") {
           result.content[0].text = `${capabilityNote}\n\n${result.content[0].text}`;
         }
@@ -1600,21 +1643,21 @@ export function registerSubagentTool(
       // Chain mode
       if (params.chain && params.chain.length > 0) {
         return withCapabilityNote(
-          await executeChain(params, agents, mkd, signal, onUpdate, activeAgents, updateWorking, parentModelId, parentProvider, asyncOk, sessionId),
+          await executeChain(params, agents, mkd, signal, onUpdate, activeAgents, updateWorking, parentModelId, parentProvider, asyncOk, sessionId, explicit),
         );
       }
 
       // Parallel mode
       if (params.tasks && params.tasks.length > 0) {
         return withCapabilityNote(
-          await executeParallel(params, agents, mkd, signal, onUpdate, activeAgents, updateWorking, parentModelId, parentProvider, asyncOk, sessionId),
+          await executeParallel(params, agents, mkd, signal, onUpdate, activeAgents, updateWorking, parentModelId, parentProvider, asyncOk, sessionId, explicit),
         );
       }
 
       // Single mode
       if (params.agent && params.task) {
         return withCapabilityNote(
-          await executeSingle(params, agents, mkd, signal, onUpdate, activeAgents, updateWorking, parentModelId, parentProvider, asyncOk, sessionId),
+          await executeSingle(params, agents, mkd, signal, onUpdate, activeAgents, updateWorking, parentModelId, parentProvider, asyncOk, sessionId, explicit),
         );
       }
 

package/extensions/pidiff/pidiff.ts

@@ -9,6 +9,7 @@
 
 import { execFileSync } from "node:child_process";
 import * as fs from "node:fs";
+import * as net from "node:net";
 import * as path from "node:path";
 import { createRequire } from "node:module";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -48,6 +49,32 @@ function getBranch(cwd: string): string {
   } catch { return ""; }
 }
 
+/** Return true if port can be bound on 127.0.0.1. */
+function isPortFree(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.once("error", () => { try { srv.close(); } catch {} resolve(false); });
+    srv.listen(port, "127.0.0.1", () => { srv.close(() => resolve(true)); });
+  });
+}
+
+/** Reuse preferred port if free; otherwise allocate a new one. */
+async function resolveSpawnPort(preferred: number | null | undefined): Promise<number> {
+  if (!preferred) {
+    const port = await findFreePort();
+    log(`allocated new port: ${port}`);
+    return port;
+  }
+  if (await isPortFree(preferred)) {
+    log(`reusing lockfile port: ${preferred}`);
+    return preferred;
+  }
+  log(`lockfile port ${preferred} in use, allocating new port`);
+  const port = await findFreePort();
+  log(`allocated new port: ${port}`);
+  return port;
+}
+
 export function registerPidiff(pi: ExtensionAPI): void {
   if (process.env.PI_SUBAGENT_CHILD === "1") return;
 
@@ -157,8 +184,8 @@ export function registerPidiff(pi: ExtensionAPI): void {
       spawning = true;
       try {
         log("spawning daemon...");
-        port = await findFreePort();
-        log(`allocated free port: ${port}`);
+        // Reuse lockfile port if available — keeps URL stable across reload/restart
+        port = await resolveSpawnPort(port);
         doSpawn(port, ctx.cwd);
         writeLockfile(lockDir, port, null, log);
         const ready = await waitForDaemon(port, 60, log);
@@ -288,7 +315,8 @@ export function registerPidiff(pi: ExtensionAPI): void {
           if (!connected) connect(ctx);
           return;
         }
-        const port = await findFreePort();
+        // Reuse lockfile port to keep URL stable — fall back if taken
+        const port = await resolveSpawnPort(lock?.port);
         doSpawn(port, ctx.cwd);
         writeLockfile(lockDir, port, null, log);
         if (ctx.hasUI) ctx.ui.notify("Starting pidiff server...", "info");
@@ -306,10 +334,14 @@ export function registerPidiff(pi: ExtensionAPI): void {
         if (ws) { try { ws.close(); } catch {} ws = null; }
         connected = false;
         const pidFile = path.join(lockDir, "pidiff.pid");
+        // Reuse existing port to keep URL stable (read before removeLockfile)
+        const lock = readLockfile(lockDir);
+        const preferredPort = activePort || lock?.port || 0;
         killDaemonByPid(pidFile, log);
         removeLockfile(lockDir, log);
         await new Promise(r => setTimeout(r, 1000));
-        const port = await findFreePort();
+        // Verify preferred port is free after kill — fall back if taken by another process
+        const port = await resolveSpawnPort(preferredPort || null);
         doSpawn(port, ctx.cwd);
         writeLockfile(lockDir, port, null, log);
         if (ctx.hasUI) ctx.ui.notify("Restarting pidiff server...", "info");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-orchestrator-config",
-  "version": "4.2.0",
+  "version": "4.2.1",
   "description": "Orchestrator pattern for pi: specialist subagents, enforcement, code review loop, workflow commands",
   "keywords": [
     "pi-package"
@@ -21,7 +21,8 @@
     "rules/",
     "prompts/",
     "templates/",
-    "skills/"
+    "skills/",
+    "settings-keys.json"
   ],
   "dependencies": {
     "@huggingface/transformers": "^4.2.0",

package/rules/10-agent-routing.md

@@ -56,3 +56,14 @@ Some agents are dispatched internally by rules or prompt templates, not by the r
 ## Fallback
 
 **Fallback:** No specialist? → `worker` agent
+
+## Model Override
+
+When the user asks to run an agent with a specific model:
+
+1. Use `list_models` tool to discover available providers and models.
+2. Pass the model to `subagent(model="provider/model-id")`.
+3. Format: `provider/model-id` (e.g., `litellm/claude-opus-4-6-1m`) or just `model-id` (overrides model only; provider follows normal resolution chain).
+4. For parallel tasks, set `model` per-task in the tasks array. Top-level `model` is used as fallback for tasks without their own.
+5. Chain steps share the top-level `model` — no per-step override.
+6. Explicit `model` param overrides agent_overrides, frontmatter, and settings.

package/rules/20-code-review-loop.md

@@ -17,7 +17,7 @@ call `addReviewerPending`/`recordReviewerResult` from bash, write to the JSON fi
 or use any method to fake a clean state. The enforcement system detects and blocks this.
 The ONLY way to reach `clean` status is to run the actual review agents.
 
-Resolution: project `.pi/pi-config-settings.json` → global `~/.pi/pi-config-settings.json` → `PI_REVIEW_LOOP_ENFORCEMENT` env var → `false`.
+Resolution is handled automatically via project settings injection.
 
 - MUST loop until clean or the max cycle cap is reached — see "Cycle Definition & Max Cycles" below.
 
@@ -46,8 +46,8 @@ Disable the review loop via `review_loop_enforcement: false` — not via max_cyc
 Cap check is after 5a; it only blocks `go to 2` (re-dispatch of step 2 / all 6 agents,
 including test-automator), not completing the current cycle's fix/explain.
 
-**After 5a completes on the max cycle, two outcomes — neither unblocks `git commit`**
-(still controlled solely by `review_loop_enforcement`; status must be `clean` + `tests_passed: true`):
+**After 5a completes on the max cycle, two outcomes** (report them; commit may still be
+allowed via the max-cycle path — see step 6):
 
 - **Not fixed** (explained why not) → outstanding — report them.
 - **Fixed** (verification blocked by the cap) → cannot re-dispatch to confirm clean — report that
@@ -64,6 +64,8 @@ cycle3: dispatch → findings → 5a (fix|explain) → cycle >= max → stop (no
 ```text
 1. Specialist writes/fixes code
 2. Send ALL 6 agents IN PARALLEL (async): 5 reviewers + test-automator
+   **On cycle 2+: MANDATORY — include prior cycle findings + responses in each reviewer's prompt (see Step 5a format).**
+   Reviewers without this context will blindly repeat the same findings. This is not optional.
 3. Wait for all 6 to complete
 4. Merge & deduplicate review findings
 5. Has findings OR tests failed?
@@ -73,14 +75,17 @@ cycle3: dispatch → findings → 5a (fix|explain) → cycle >= max → stop (no
         · cycle < {{REVIEW_LOOP_MAX_CYCLES}}? → go to 2 (re-run all 6 with prior findings + responses)
         · cycle >= {{REVIEW_LOOP_MAX_CYCLES}}? → **STOP** (terminal): report the two-outcome result
           (see "Cycle Definition & Max Cycles" above). Do NOT proceed to step 6.
-6. NOW you can commit — the pre-commit hook will pass (only when status is `clean` AND `tests_passed: true`)
-✅ DONE — commit/push allowed (enforcement checks status: clean AND tests_passed: true)
+6. NOW you can commit — the pre-commit hook will pass when:
+   - status is `clean` AND `tests_passed: true`, OR
+   - max cycles exhausted (`has_findings` or `clean`, no pending reviewers, `cycle >= review_loop_max_cycles` — no `tests_passed` check)
+✅ DONE — commit/push allowed
 ```
 
-🚨 **Step 6 applies only when clean.** Do NOT attempt `git commit` before reaching `clean` + `tests_passed: true`.
+🚨 **Step 6 applies when clean OR max cycles exhausted.** Do NOT attempt `git commit` before that.
 The enforcement rule blocks commits until this is satisfied — if it blocks you, run the reviewers.
 **After a cap stop:** report the two-outcome result (**Not fixed** → outstanding, **Fixed** → verification
-blocked); raise `review_loop_max_cycles` or disable `review_loop_enforcement` if needed — do **not**
+blocked); commit is allowed when status is `has_findings` or `clean`, no reviewers pending, and
+`cycle >= review_loop_max_cycles` (no `tests_passed` requirement); do **not**
 return to step 2 (re-dispatch of all 6 agents, including test-automator).
 
 ## Review Agents
@@ -100,7 +105,7 @@ Six agents run in parallel for comprehensive coverage:
 Do NOT block waiting for results — continue working while they run.**
 
 Send reviewers "Review the code changes" — never mention `git diff HEAD` in the task prompt.
-Reviewers get `$PI_REVIEW_BASE_BRANCH` env var and use `git diff origin/$PI_REVIEW_BASE_BRANCH...HEAD` themselves.
+Reviewers get `$PI_REVIEW_BASE_BRANCH` env var and use `git diff origin/$PI_REVIEW_BASE_BRANCH` themselves (includes uncommitted changes).
 
 Reviewers return structured JSON: `{"findings": [{"severity": "...", "file": "...", "line": N, "description": "...", "suggestion": "..."}]}`.
 The async runner validates the output is valid JSON and retries if not (up to 3 times).
@@ -137,7 +142,7 @@ The following findings were raised in review cycle {N}. Each has been either fix
 explained. Do NOT re-raise findings that were adequately addressed. Only re-raise if:
 - The code fix is incorrect or incomplete
 - The explanation is invalid or factually wrong
-- You disagree with the reasoning (explain why)
+- You disagree with the reasoning (state why in the finding description field)
 
 Findings with valid explanations that you accept → do not re-raise.
 Findings that were fixed in code → verify the fix, do not re-raise if correct.

package/settings-keys.json

@@ -0,0 +1,102 @@
+{
+  "dco": {
+    "type": "bool",
+    "env": "PI_DCO",
+    "default": false
+  },
+  "commit_trailer": {
+    "type": "bool_or_string",
+    "env": "PI_COMMIT_TRAILER",
+    "default": false
+  },
+  "use_worktrees": {
+    "type": "bool",
+    "env": "PI_USE_WORKTREES",
+    "default": false
+  },
+  "allow_push_to_protected_branches": {
+    "type": "bool",
+    "env": "PI_ALLOW_PUSH_TO_PROTECTED_BRANCHES",
+    "default": false
+  },
+  "comment_signature": {
+    "type": "bool",
+    "default": false
+  },
+  "review_loop_enforcement": {
+    "type": "bool",
+    "env": "PI_REVIEW_LOOP_ENFORCEMENT",
+    "default": false
+  },
+  "review_loop_max_cycles": {
+    "type": "int",
+    "env": "PI_REVIEW_LOOP_MAX_CYCLES",
+    "default": 3,
+    "min": 1,
+    "max": 10,
+    "strict_digits": true
+  },
+  "dream_interval_hours": {
+    "type": "number",
+    "env": "PI_DREAM_INTERVAL_HOURS",
+    "default": 3
+  },
+  "orchestrator_edit_write_block": {
+    "type": "bool",
+    "default": false
+  },
+  "pidash_enable": {
+    "type": "bool_enable",
+    "env": "PI_PIDASH_ENABLE",
+    "default": true
+  },
+  "pidiff_enable": {
+    "type": "bool_enable",
+    "env": "PI_PIDIFF_ENABLE",
+    "default": true
+  },
+  "pidash_port": {
+    "type": "port",
+    "env": "PI_PIDASH_PORT",
+    "default": 19190
+  },
+  "image_model": {
+    "type": "string",
+    "env": "PI_IMAGE_MODEL",
+    "default": ""
+  },
+  "internal_operations_provider": {
+    "type": "string",
+    "env": "PI_INTERNAL_OPERATIONS_PROVIDER",
+    "default": ""
+  },
+  "internal_operations_model": {
+    "type": "string",
+    "env": "PI_INTERNAL_OPERATIONS_MODEL",
+    "default": ""
+  },
+  "acpx_agents": {
+    "type": "agent_list",
+    "env": "ACPX_AGENTS",
+    "default": [],
+    "per_key_resolution": true
+  },
+  "cli_agents": {
+    "type": "agent_list",
+    "env": "CLI_AGENTS",
+    "default": [],
+    "per_key_resolution": true
+  },
+  "agent_provider": {
+    "type": "string",
+    "default": ""
+  },
+  "agent_model": {
+    "type": "string",
+    "default": ""
+  },
+  "agent_overrides": {
+    "type": "agent_overrides",
+    "default": {}
+  }
+}