@cydm/pie 1.0.49 → 1.0.51

package/dist/builtin/skills/skill-creator/SKILL.md

@@ -11,7 +11,7 @@ At a high level, the process of creating a skill goes like this:
 
 - Decide what you want the skill to do and roughly how it should do it
 - Write a draft of the skill
-- Create a few test prompts and run claude-with-access-to-the-skill on them
+- Create a few test prompts and run the agent with the skill loaded on them
 - Help the user evaluate the results both qualitatively and quantitatively
   - While the runs happen in the background, draft some quantitative evals if there aren't any (if there are some, you can either use as is or modify if you feel something needs to change about them). Then explain them to the user (or if they already existed, explain the ones that already exist)
   - Use the `eval-viewer/generate_review.mjs` script to show the user the results for them to look at, and also let them look at the quantitative metrics
@@ -31,7 +31,7 @@ Cool? Cool.
 
 ## Communicating with the user
 
-The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. If you haven't heard (and how could you, it's only very recently that it started), there's a trend now where the power of Claude is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm". On the other hand, the bulk of users are probably fairly computer-literate.
+The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. If you haven't heard (and how could you, it's only very recently that it started), there's a trend now where the power of AI coding agents is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm". On the other hand, the bulk of users are probably fairly computer-literate.
 
 So please pay attention to context cues to understand how to phrase your communication! In the default case, just to give you some idea:
 
@@ -48,7 +48,7 @@ It's OK to briefly explain terms if you're in doubt, and feel free to clarify te
 
 Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first — the tools used, the sequence of steps, corrections the user made, input/output formats observed. The user may need to fill the gaps, and should confirm before proceeding to the next step.
 
-1. What should this skill enable Claude to do?
+1. What should this skill enable the agent to do?
 2. When should this skill trigger? (what user phrases/contexts)
 3. What's the expected output format?
 4. Should we set up test cases to verify the skill works? Skills with objectively verifiable outputs (file transforms, data extraction, code generation, fixed workflow steps) benefit from test cases. Skills with subjective outputs (writing style, art) often don't need them. Suggest the appropriate default based on the skill type, but let the user decide.
@@ -64,7 +64,7 @@ Check available MCPs - if useful for research (searching docs, finding similar s
 Based on the user interview, fill in these components:
 
 - **name**: Skill identifier
-- **description**: When to trigger, what it does. This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Note: currently Claude has a tendency to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit "pushy". So for instance, instead of "How to build a simple fast dashboard to display internal Anthropic data.", you might write "How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'"
+- **description**: When to trigger, what it does. This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Note: models currently tend to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit "pushy". So for instance, instead of "How to build a simple fast dashboard to display internal company data.", you might write "How to build a simple fast dashboard to display internal company data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'"
 - **compatibility**: Required tools, dependencies (optional, rarely needed)
 - **the rest of the skill :)**
 
@@ -106,7 +106,7 @@ cloud-deploy/
     ├── gcp.md
     └── azure.md
 ```
-Claude reads only the relevant reference file.
+The agent reads only the relevant reference file.
 
 #### Principle of Lack of Surprise
 
@@ -244,7 +244,7 @@ Put each with_skill version before its baseline counterpart.
    ```
    For iteration 2+, also pass `--previous-workspace <workspace>/iteration-<N-1>`.
 
-   **Cowork / headless environments:** If `webbrowser.open()` is not available or the environment has no display, use `--static <output_path>` to write a standalone HTML file instead of starting a server. Feedback will be downloaded as a `feedback.json` file when the user clicks "Submit All Reviews". After download, copy `feedback.json` into the workspace directory for the next iteration to pick up.
+   **Headless environments:** If `webbrowser.open()` is not available or the environment has no display, use `--static <output_path>` to write a standalone HTML file instead of starting a server. Feedback will be downloaded as a `feedback.json` file when the user clicks "Submit All Reviews". After download, copy `feedback.json` into the workspace directory for the next iteration to pick up.
 
 Note: please use `generate_review.mjs` to create the viewer; there's no need to write custom HTML.
 
@@ -345,7 +345,7 @@ Create 20 eval queries — a mix of should-trigger and should-not-trigger. Save
 ]
 ```
 
-The queries must be realistic and something a Claude Code or Claude.ai user would actually type. Not abstract requests, but requests that are concrete and specific and have a good amount of detail. For instance, file paths, personal context about the user's job or situation, column names and values, company names, URLs. A little bit of backstory. Some might be in lowercase or contain abbreviations or typos or casual speech. Use a mix of different lengths, and focus on edge cases rather than making them clear-cut (the user will get a chance to sign off on them).
+The queries must be realistic and something a real user of a coding agent would actually type. Not abstract requests, but requests that are concrete and specific and have a good amount of detail. For instance, file paths, personal context about the user's job or situation, column names and values, company names, URLs. A little bit of backstory. Some might be in lowercase or contain abbreviations or typos or casual speech. Use a mix of different lengths, and focus on edge cases rather than making them clear-cut (the user will get a chance to sign off on them).
 
 Bad: `"Format this data"`, `"Extract text from PDF"`, `"Create a chart"`
 
@@ -397,7 +397,7 @@ This handles the full optimization loop automatically. It splits the eval set in
 
 Understanding the triggering mechanism helps design better eval queries. Skills appear in Pie's `available_skills` list with their name + description, and Pie decides whether to consult a skill based on that description. The important thing to know is that Pie only consults skills for tasks it can't easily handle on its own — simple, one-step queries like "read this PDF" may not trigger a skill even if the description matches perfectly, because Pie can handle them directly with basic tools. Complex, multi-step, or specialized queries reliably trigger skills when the description matches.
 
-This means your eval queries should be substantive enough that Claude would actually benefit from consulting a skill. Simple queries like "read file X" are poor test cases — they won't trigger skills regardless of description quality.
+This means your eval queries should be substantive enough that the model would actually benefit from consulting a skill. Simple queries like "read file X" are poor test cases — they won't trigger skills regardless of description quality.
 
 ### Step 4: Apply the result
 
@@ -405,9 +405,9 @@ Take `best_description` from the JSON output and update the skill's SKILL.md fro
 
 ---
 
-### Package and Present (only if `present_files` tool is available)
+### Package the skill
 
-Check whether you have access to the `present_files` tool. If you don't, skip this step. If you do, package the skill and present the .skill file to the user:
+Package the skill and point the user to the resulting file:
 
 ```bash
 node <skill-creator-path>/scripts/package_skill.mjs <path/to/skill-folder>
@@ -417,42 +417,14 @@ After packaging, direct the user to the resulting `.skill` file path so they can
 
 ---
 
-## Claude.ai-specific instructions
+## Updating an existing skill
 
-In Claude.ai, the core workflow is the same (draft → test → review → improve → repeat), but because Claude.ai doesn't have subagents, some mechanics change. Here's what to adapt:
-
-**Running test cases**: No subagents means no parallel execution. For each test case, read the skill's SKILL.md, then follow its instructions to accomplish the test prompt yourself. Do them one at a time. This is less rigorous than independent subagents (you wrote the skill and you're also running it, so you have full context), but it's a useful sanity check — and the human review step compensates. Skip the baseline runs — just use the skill to complete the task as requested.
-
-**Reviewing results**: If you can't open a browser (e.g., Claude.ai's VM has no display, or you're on a remote server), skip the browser reviewer entirely. Instead, present results directly in the conversation. For each test case, show the prompt and the output. If the output is a file the user needs to see (like a .docx or .xlsx), save it to the filesystem and tell them where it is so they can download and inspect it. Ask for feedback inline: "How does this look? Anything you'd change?"
-
-**Benchmarking**: Skip the quantitative benchmarking — it relies on baseline comparisons which aren't meaningful without subagents. Focus on qualitative feedback from the user.
-
-**The iteration loop**: Same as before — improve the skill, rerun the test cases, ask for feedback — just without the browser reviewer in the middle. You can still organize results into iteration directories on the filesystem if you have one.
-
-**Description optimization**: This section now defaults to Pie's own non-interactive runner. It does not require `claude -p`.
-
-**Blind comparison**: Requires subagents. Skip it.
-
-**Packaging**: The `package_skill.mjs` script works anywhere with Node.js and a filesystem. On Claude.ai or Codex CLI, you can run it and the user can download the resulting `.skill` file.
-
-**Updating an existing skill**: The user might be asking you to update an existing skill, not create a new one. In this case:
+The user might be asking you to update an existing skill, not create a new one. In this case:
 - **Preserve the original name.** Note the skill's directory name and `name` frontmatter field -- use them unchanged. E.g., if the installed skill is `research-helper`, output `research-helper.skill` (not `research-helper-v2`).
 - **Copy to a writeable location before editing.** The installed skill path may be read-only. Copy to `/tmp/skill-name/`, edit there, and package from the copy.
 - **If packaging manually, stage in `/tmp/` first**, then copy to the output directory -- direct writes may fail due to permissions.
 
----
-
-## Cowork-Specific Instructions
-
-If you're in Cowork, the main things to know are:
-
-- You have subagents, so the main workflow (spawn test cases in parallel, run baselines, grade, etc.) all works. (However, if you run into severe problems with timeouts, it's OK to run the test prompts in series rather than parallel.)
-- You don't have a browser or display, so when generating the eval viewer, use `--static <output_path>` to write a standalone HTML file instead of starting a server. Then proffer a link that the user can click to open the HTML in their browser.
-- For whatever reason, the Cowork setup seems to disincline Claude from generating the eval viewer after running the tests, so just to reiterate: whether you're in Cowork or in Claude Code, after running tests, you should always generate the eval viewer for the human to look at examples before revising the skill yourself and trying to make corrections, using `generate_review.mjs` (not writing your own boutique html code). Sorry in advance but I'm gonna go all caps here: GENERATE THE EVAL VIEWER *BEFORE* evaluating inputs yourself. You want to get them in front of the human ASAP!
-- Feedback works differently: since there's no running server, the viewer's "Submit All Reviews" button will download `feedback.json` as a file. You can then read it from there (you may have to request access first).
-- Packaging works — `package_skill.mjs` just needs Node.js and a filesystem.
-- Description optimization (`run_loop.mjs` / `run_eval.mjs`) should work in Cowork just fine since it uses Pie's non-interactive runner, not a browser, but please save it until you've fully finished making the skill and the user agrees it's in good shape.
-- **Updating an existing skill**: The user might be asking you to update an existing skill, not create a new one. Follow the update guidance in the claude.ai section above.
+Note: description optimization (`run_loop.mjs` / `run_eval.mjs`) uses Pie's own non-interactive runner and works headless, but save it until you've fully finished making the skill and the user agrees it's in good shape.
 
 ---
 
@@ -473,13 +445,13 @@ Repeating one more time the core loop here for emphasis:
 
 - Figure out what the skill is about
 - Draft or edit the skill
-- Run claude-with-access-to-the-skill on test prompts
+- Run test prompts with the skill loaded
 - With the user, evaluate the outputs:
   - Create benchmark.json and run `eval-viewer/generate_review.mjs` to help the user review them
   - Run quantitative evals
 - Repeat until you and the user are satisfied
 - Package the final skill and return it to the user.
 
-Please add steps to your TodoList, if you have such a thing, to make sure you don't forget. If you're in Cowork, please specifically put "Create evals JSON and run `eval-viewer/generate_review.mjs` so human can review test cases" in your TodoList to make sure it happens.
+Please add steps to your TodoList, if you have such a thing, to make sure you don't forget. Specifically put "Create evals JSON and run `eval-viewer/generate_review.mjs` so human can review test cases" in your TodoList to make sure it happens.
 
 Good luck!

package/dist/builtin/skills/skill-creator/eval-viewer/generate_review.mjs

@@ -6,7 +6,7 @@ import { readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { openInBrowser } from "../scripts/claude_cli.mjs";
+import { openInBrowser } from "../scripts/pie_runner.mjs";
 
 const execFileAsync = promisify(execFile);
 const METADATA_FILES = new Set(["transcript.md", "user_notes.md", "metrics.json"]);

package/dist/builtin/skills/skill-creator/eval-viewer/viewer.html

@@ -545,7 +545,7 @@
     <div class="header">
       <div>
         <h1>Eval Review: <span id="skill-name"></span></h1>
-        <div class="instructions">Review each output and leave feedback below. Navigate with arrow keys or buttons. When done, copy feedback and paste into Claude Code.</div>
+        <div class="instructions">Review each output and leave feedback below. Navigate with arrow keys or buttons. When done, copy feedback and paste it back into your Pie session.</div>
       </div>
       <div class="progress" id="progress"></div>
     </div>
@@ -634,7 +634,7 @@
   <div class="done-overlay" id="done-overlay">
     <div class="done-card">
       <h2>Review Complete</h2>
-      <p>Your feedback has been saved. Go back to your Claude Code session and tell Claude you're done reviewing.</p>
+      <p>Your feedback has been saved. Go back to your Pie session and say you're done reviewing.</p>
       <div class="btn-row">
         <button onclick="closeDoneDialog()">OK</button>
       </div>

package/dist/builtin/skills/skill-creator/references/schemas.md

@@ -225,7 +225,7 @@ Output from Benchmark mode. Located at `benchmarks/<timestamp>/benchmark.json`.
   "metadata": {
     "skill_name": "pdf",
     "skill_path": "/path/to/pdf",
-    "executor_model": "claude-sonnet-4-20250514",
+    "executor_model": "pie-agent",
     "analyzer_model": "most-capable-model",
     "timestamp": "2026-01-15T10:30:00Z",
     "evals_run": [1, 2, 3],

package/dist/builtin/skills/skill-creator/scripts/generate_report.mjs

@@ -75,7 +75,7 @@ ${refreshTag}    <title>${titlePrefix}Skill Description Optimization</title>
 <body>
     <h1>${titlePrefix}Skill Description Optimization</h1>
     <div class="explainer">
-        <strong>Optimizing your skill's description.</strong> This page updates automatically as Claude tests different versions of your skill's description. Each row is an iteration — a new description attempt. The columns show test queries: green checkmarks mean the skill triggered correctly (or correctly didn't trigger), red crosses mean it got it wrong.
+        <strong>Optimizing your skill's description.</strong> This page updates automatically as the model tests different versions of your skill's description. Each row is an iteration — a new description attempt. The columns show test queries: green checkmarks mean the skill triggered correctly (or correctly didn't trigger), red crosses mean it got it wrong.
     </div>
     <div class="summary">
         <p><strong>Original:</strong> ${escapeHtml(data?.original_description ?? "N/A")}</p>

package/dist/builtin/skills/skill-creator/scripts/improve_description.mjs

@@ -25,9 +25,9 @@ export async function improveDescription({
     ? `Train: ${trainScore}, Test: ${testResults.summary.passed}/${testResults.summary.total}`
     : `Train: ${trainScore}`;
 
-  let prompt = `You are optimizing a skill description for a Claude Code skill called "${skillName}". A "skill" is sort of like a prompt, but with progressive disclosure -- there's a title and description that Claude sees when deciding whether to use the skill, and then if it does use the skill, it reads the .md file which has lots more details and potentially links to other resources in the skill folder like helper files and scripts and additional documentation or examples.
+  let prompt = `You are optimizing a skill description for a Pie skill called "${skillName}". A "skill" is sort of like a prompt, but with progressive disclosure -- there's a title and description that the agent sees when deciding whether to use the skill, and then if it does use the skill, it reads the .md file which has lots more details and potentially links to other resources in the skill folder like helper files and scripts and additional documentation or examples.
 
-The description appears in Claude's "available_skills" list. When a user sends a query, Claude decides whether to invoke the skill based solely on the title and on this description. Your goal is to write a description that triggers for relevant queries, and doesn't trigger for irrelevant ones.
+The description appears in the agent's "available_skills" list. When a user sends a query, the agent decides whether to invoke the skill based solely on the title and on this description. Your goal is to write a description that triggers for relevant queries, and doesn't trigger for irrelevant ones.
 
 Here's the current description:
 <current_description>
@@ -93,7 +93,7 @@ Concretely, your description should not be more than about 100-200 words, even i
 Here are some tips that we've found to work well in writing these descriptions:
 - The skill should be phrased in the imperative -- "Use this skill for" rather than "this skill does"
 - The skill description should focus on the user's intent, what they are trying to achieve, vs. the implementation details of how the skill works.
-- The description competes with other skills for Claude's attention — make it distinctive and immediately recognizable.
+- The description competes with other skills for the model's attention — make it distinctive and immediately recognizable.
 - If you're getting lots of failures after repeated attempts, change things up. Try different sentence structures or wordings.
 
 I'd encourage you to be creative and mix up the style in different iterations since you'll have multiple opportunities to try different approaches and we'll just grab the highest-scoring one at the end.

package/dist/builtin/skills/skill-creator/scripts/pie_runner.mjs

@@ -2,11 +2,11 @@
 
 import crypto from "node:crypto";
 import { spawn } from "node:child_process";
+import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
-const REPO_ROOT = path.resolve(SCRIPT_DIR, "../../../../../../");
 
 export function findProjectRoot(start = process.cwd()) {
   return path.resolve(start);
@@ -29,13 +29,41 @@ export function openInBrowser(target) {
   spawn("xdg-open", [target], { detached: true, stdio: "ignore" }).unref();
 }
 
-function getPieCliPath(cwd = process.cwd()) {
-  return path.join(REPO_ROOT, "products/cli/dist/cli.js");
+let cachedCliPath;
+
+/**
+ * Locate the Pie CLI entry point across layouts:
+ * - installed package: <pkg>/dist/builtin/skills/skill-creator/scripts -> <pkg>/dist/cli.js
+ * - dev repository:   <repo>/products/cli/builtin/skills/skill-creator/scripts -> <repo>/products/cli/dist/cli.js
+ * - explicit override via PIE_CLI_PATH
+ *
+ * Candidate order is layout-aware: an installed build always prefers the
+ * package root and a dev checkout always prefers products/cli, so an
+ * unrelated sibling artifact cannot win over the correct entry.
+ */
+export function getPieCliPath() {
+  if (cachedCliPath) return cachedCliPath;
+  const installed = path.resolve(SCRIPT_DIR, "../../../../../dist/cli.js"); // installed package root
+  const dev = path.resolve(SCRIPT_DIR, "../../../../dist/cli.js"); // dev repo: products/cli
+  const inInstalledLayout = SCRIPT_DIR.includes(`${path.sep}dist${path.sep}builtin${path.sep}`);
+  const candidates = [
+    process.env.PIE_CLI_PATH,
+    ...(inInstalledLayout ? [installed, dev] : [dev, installed]),
+  ].filter((candidate) => typeof candidate === "string" && candidate.length > 0);
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      cachedCliPath = candidate;
+      return cachedCliPath;
+    }
+  }
+  throw new Error(
+    `Pie CLI entry not found. Tried: ${candidates.join(", ")}. Set PIE_CLI_PATH to the cli.js entry point.`,
+  );
 }
 
 export async function runPieJsonPrompt(prompt, { cwd = process.cwd(), timeout = 300_000, sessionId = null } = {}) {
   return new Promise((resolve, reject) => {
-    const args = [getPieCliPath(cwd), prompt, "--json-output"];
+    const args = [getPieCliPath(), prompt, "--json-output"];
     if (sessionId) {
       args.push("--session-id", sessionId);
     }

package/dist/builtin/skills/skill-creator/scripts/run_loop.mjs

@@ -6,7 +6,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { generateHtml } from "./generate_report.mjs";
 import { improveDescription } from "./improve_description.mjs";
-import { findProjectRoot, openInBrowser } from "./claude_cli.mjs";
+import { findProjectRoot, openInBrowser } from "./pie_runner.mjs";
 import { runEval } from "./run_eval.mjs";
 import { parseSkillFile, resolveSkillPath } from "./skill_metadata.mjs";
 

package/dist/chunks/{chunk-7RYOIXA2.js → chunk-A644H2XX.js}

@@ -1,7 +1,7 @@
 import { createRequire as __createRequire } from "node:module"; const require = __createRequire(import.meta.url);
 import {
   Agent
-} from "./chunk-FKAO25XH.js";
+} from "./chunk-B3SMW2XW.js";
 import {
   FileSystemGateway,
   Type,
@@ -11,7 +11,7 @@ import {
   getPlatformConfig,
   hashText,
   streamSimple
-} from "./chunk-K6ZOCJ4V.js";
+} from "./chunk-S2J3SZZX.js";
 import {
   __commonJS,
   __toESM
@@ -848,6 +848,10 @@ var BUILTIN_TOOL_CAPABILITY_METADATA = {
   spawn_subagents_parallel: { riskClass: "read_only", concurrencySafe: false, permissionScope: "host", readsHostResource: true, availableInPlanMode: true, maxOutputChars: 1e5 },
   ask_user_multi: { riskClass: "user_interaction", concurrencySafe: false, permissionScope: "user", asksUser: true, availableInPlanMode: true, allowedForSubagentByDefault: true },
   manage_todo_list: { riskClass: "session_mutation", concurrencySafe: false, permissionScope: "session", mutatesSession: true, availableInPlanMode: true },
+  // plan_scratch ships as the plan-mode extension's session-local draft tool;
+  // registration feeds /permissions display and the legacy plan-mode name list,
+  // while runtime decisions still honor the tool's inline risk metadata first.
+  plan_scratch: { riskClass: "session_mutation", concurrencySafe: false, permissionScope: "session", mutatesSession: true, availableInPlanMode: true },
   unity_project_inspect: { riskClass: "read_only", concurrencySafe: true, permissionScope: "unity", readsHostResource: true, availableInPlanMode: true, allowedForSubagentByDefault: true },
   unity_scene_query: { riskClass: "read_only", concurrencySafe: true, permissionScope: "unity", readsHostResource: true, availableInPlanMode: true, allowedForSubagentByDefault: true },
   unity_scene_object_inspect: { riskClass: "read_only", concurrencySafe: true, permissionScope: "unity", readsHostResource: true, availableInPlanMode: true, allowedForSubagentByDefault: true },
@@ -1409,8 +1413,9 @@ function buildSubagentPlan(deps, task, name, priority, timeoutSeconds) {
   const complexity = inferComplexity(task, priority);
   const modelClass = selectModelClass(complexity, priority);
   const modelResolution = deps.resolveModelClass?.(modelClass);
-  const model = modelResolution?.model ?? deps.model;
-  const apiKey = modelResolution?.apiKey ?? deps.apiKey;
+  const resolvedPair = modelResolution?.model && modelResolution?.apiKey ? { model: modelResolution.model, apiKey: modelResolution.apiKey } : void 0;
+  const model = resolvedPair?.model ?? deps.model;
+  const apiKey = resolvedPair?.apiKey ?? deps.apiKey;
   const partialPlan = {
     task,
     name,
@@ -1508,6 +1513,9 @@ async function runSubagentWithProgress(deps, task, reportProgress, signal) {
     if (!apiKey) {
       throw new Error("No API key available for subagent execution.");
     }
+    if (!model) {
+      throw new Error("No model configured for subagent execution.");
+    }
     if (signal?.aborted) {
       throw new Error("Subagent aborted by parent");
     }
@@ -1682,22 +1690,30 @@ function buildParallelResult(tasks, totalDuration) {
 `;
   return resultText;
 }
+var TASK_FIELD_ALIASES = ["task", "description", "prompt", "objective"];
 function normalizeTaskDefs(args) {
   const taskDefs = args?.tasks;
   if (!Array.isArray(taskDefs) || taskDefs.length === 0) {
     return { error: "Invalid spawn_subagents_parallel arguments: tasks must be a non-empty array." };
   }
   const normalized = [];
+  const allowedFields = [...TASK_FIELD_ALIASES, "name", "priority", "timeout"];
   for (const [index, def] of taskDefs.entries()) {
     if (!def || typeof def !== "object") {
-      return { error: `Invalid task #${index + 1}: expected an object with task.` };
+      return { error: `Invalid task #${index + 1}: expected an object with the objective in "task" (aliases "description"/"prompt"/"objective" accepted).` };
     }
-    if ("prompt" in def || "kind" in def || "max_turns" in def) {
-      return { error: "Invalid spawn_subagents_parallel arguments: use tasks[].task plus optional name/priority; prompt, kind, and max_turns are no longer supported." };
+    const unknownFields = Object.keys(def).filter((key) => !allowedFields.includes(key));
+    if (unknownFields.length > 0) {
+      return { error: `Invalid task #${index + 1}: unknown field(s) ${unknownFields.map((key) => `"${key}"`).join(", ")}; allowed fields: ${allowedFields.map((key) => `"${key}"`).join(", ")}.` };
     }
-    const task = typeof def.task === "string" ? def.task.trim() : "";
+    const taskValues = [
+      ...new Set(
+        TASK_FIELD_ALIASES.map((key) => typeof def[key] === "string" ? def[key].trim() : "").filter((value) => value.length > 0)
+      )
+    ];
+    const task = taskValues.join("\n\n");
     if (!task) {
-      return { error: `Invalid task #${index + 1}: task cannot be empty.` };
+      return { error: `Invalid task #${index + 1}: provide the objective in "task" (aliases "description"/"prompt"/"objective" are accepted).` };
     }
     const timeoutSeconds = "timeout" in def ? Number(def.timeout) : DEFAULT_SUBAGENT_TIMEOUT_SECONDS;
     if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) {
@@ -1713,25 +1729,61 @@ function normalizeTaskDefs(args) {
   }
   return normalized;
 }
+var DEFAULT_MAX_CONCURRENT_SUBAGENTS = 4;
+var MAX_TRANSIENT_RETRIES = 2;
+var TRANSIENT_RETRY_BACKOFF_MS = 2e3;
+var TRANSIENT_ERROR_PATTERN = /econnreset|econnaborted|etimedout|timeout|enotfound|eai_again|econnrefused|socket hang up|sse stream aborted|fetch failed|status 5\d\d|bad gateway|service unavailable|overloaded/i;
+function isTransientNetworkError(message) {
+  return TRANSIENT_ERROR_PATTERN.test(message);
+}
+function sleep(ms, signal) {
+  return new Promise((resolve3) => {
+    const timer = setTimeout(resolve3, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve3();
+      },
+      { once: true }
+    );
+  });
+}
+async function runWithConcurrencyLimit(jobs, limit) {
+  let next = 0;
+  const workers = Array.from({ length: Math.max(1, Math.min(limit, jobs.length)) }, async () => {
+    while (next < jobs.length) {
+      const current = jobs[next++];
+      await current();
+    }
+  });
+  await Promise.all(workers);
+}
 function createSubagentCapability(deps) {
   const spawnParallelTool = {
     name: "spawn_subagents_parallel",
     label: "Spawn Subagents",
     description: `Spawn child agents to run bounded sub-tasks in parallel.
 
-Use this for independent investigation, search, review, or triage work. Provide each task as a plain objective. Pie chooses the model class automatically. Use timeout only for unusually long tasks.`,
+Use this for independent investigation, search, review, or triage work. Provide each task as a plain objective. Pie chooses the model class automatically. Use timeout only for unusually long tasks.
+
+Arguments shape (each tasks[] item puts the objective in "task" \u2014 "description"/"prompt"/"objective" are accepted as aliases):
+{ "tasks": [{ "task": "<objective text>", "name": "<optional short label>", "priority": "fast" | "thorough", "timeout": 600 }] }`,
     parameters: Type.Object({
       tasks: Type.Array(
         Type.Object(
           {
-            task: Type.String({ description: "The bounded sub-task objective. Be specific and include expected output." }),
+            task: Type.Optional(Type.String({ description: "The bounded sub-task objective. Be specific and include expected output. Preferred field name." })),
+            description: Type.Optional(Type.String({ description: "Alias for task." })),
+            prompt: Type.Optional(Type.String({ description: "Alias for task." })),
+            objective: Type.Optional(Type.String({ description: "Alias for task." })),
             name: Type.Optional(Type.String({ description: "Short name for this subagent, shown in progress updates." })),
             priority: Type.Optional(Type.Union([Type.Literal("fast"), Type.Literal("thorough")], { description: "fast uses lower-cost defaults; thorough raises model class when needed." })),
-            timeout: Type.Optional(Type.Number({ description: "Timeout in seconds. Default: 1200s (20 minutes). For longer tasks, explicitly set a higher value, e.g. { timeout: 3600 }." }))
+            timeout: Type.Optional(Type.Number({ description: "Timeout in seconds. Default: 1200s (20 minutes). For longer tasks, explicitly set a higher value, e.g. 3600." }))
           },
-          { additionalProperties: false }
+          { additionalProperties: false, description: "Objective goes in 'task' (or an accepted alias); plus optional name/priority/timeout." }
         ),
-        { description: "Array of tasks to run in parallel", minItems: 1, maxItems: 10 }
+        { description: "Array of tasks to run in parallel; at least one of task/description/prompt/objective must be a non-empty string per item.", minItems: 1, maxItems: 10 }
       )
     }, { additionalProperties: false }),
     async execute(first, second, third, fourth) {
@@ -1774,7 +1826,30 @@ Use this for independent investigation, search, review, or triage work. Provide
       toolContext.log?.(`Spawning ${tasks.length} parallel subagents: ${tasks.map((task) => task.name).join(", ")}`);
       toolContext.reportProgress?.({ message: `Launching ${tasks.length} parallel subagents...`, increment: 5 });
       const startTime = Date.now();
-      await Promise.all(tasks.map((task) => runSubagentWithProgress(deps, task, toolContext.reportProgress, signal)));
+      const runTask = async (task) => {
+        for (let attempt = 0; ; attempt++) {
+          await runSubagentWithProgress(deps, task, toolContext.reportProgress, signal);
+          const canRetry = task.status === "failed" && isTransientNetworkError(task.error ?? "") && attempt < MAX_TRANSIENT_RETRIES && !signal?.aborted;
+          if (!canRetry) return;
+          const failureReason = task.error ?? "unknown";
+          task.evidence.length = 0;
+          task.runtimeEvidence.length = 0;
+          task.reportedEvidence.length = 0;
+          task.confidenceSignals.length = 0;
+          task.status = "pending";
+          task.error = void 0;
+          task.completedAt = void 0;
+          const backoffMs = (deps.transientRetryBackoffMs ?? TRANSIENT_RETRY_BACKOFF_MS) * (attempt + 1);
+          toolContext.reportProgress?.({ message: `[${task.name}] Transient error, retrying in ${Math.round(backoffMs / 1e3)}s (attempt ${attempt + 2}/${MAX_TRANSIENT_RETRIES + 1})...` });
+          deps.log(`[subagent] ${task.name} failed with a transient error (${failureReason}); retrying`);
+          await sleep(backoffMs, signal);
+          if (signal?.aborted) return;
+        }
+      };
+      await runWithConcurrencyLimit(
+        tasks.map((task) => () => runTask(task)),
+        Math.max(1, deps.maxConcurrentSubagents ?? DEFAULT_MAX_CONCURRENT_SUBAGENTS)
+      );
       const totalDuration = Date.now() - startTime;
       const completed = tasks.filter((task) => task.status === "completed").length;
       const failed = tasks.filter((task) => task.status === "failed" || task.status === "timeout").length;
@@ -1845,6 +1920,12 @@ var ManageTodoListParamsSchema = Type.Object(
   },
   { additionalProperties: false }
 );
+var MANAGE_TODO_LIST_TOOL_DESCRIPTION = `Manage a session-local todo list. Use when the user explicitly asks to use the todo tool, create/manage todos, track tasks, follow a todo list, show tasks, or mark a task done.
+NEVER use for: internal planning, tracking your own progress, remembering subtasks, or creating checklists for yourself.
+Use action=create with items to create a list; provide todo titles and optional descriptions only. The tool assigns ids and starts item 1 automatically.
+Use action=complete_current after finishing the current item; the tool advances to the next item or clears the list after the final item. Do not call complete_current after a required install, build, test, or verification command just failed; fix/retry first or clear with a reason.
+When a todo list exists, keep executing from the current in-progress item until it is cleared. If the work cannot continue, explain the failure and use action=clear with a reason.
+Actions: create, read, complete_current, clear.`;
 function cloneTodos(todos) {
   return todos.map((todo) => ({ ...todo }));
 }
@@ -2568,14 +2649,14 @@ function isTransientFileError(error) {
   const message = error instanceof Error ? error.message : String(error);
   return /^(EPERM|EACCES|EBUSY|ENOTEMPTY)$/.test(code) || /\b(EPERM|EACCES|EBUSY|locked|busy)\b/i.test(message);
 }
-function sleep(ms) {
+function sleep2(ms) {
   return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 async function retryFileOperation(operation, retryDelaysMs) {
   let lastError;
   for (const [index, delayMs] of retryDelaysMs.entries()) {
     if (delayMs > 0) {
-      await sleep(delayMs);
+      await sleep2(delayMs);
     }
     try {
       operation();
@@ -3964,7 +4045,8 @@ var SessionManager = class {
         name: newName ?? `${this.activeSession.metadata.name} (Branch)`,
         createdAt: now,
         updatedAt: now,
-        tags: this.activeSession.metadata.tags
+        tags: this.activeSession.metadata.tags,
+        cwd: this.activeSession.metadata.cwd
       }
     );
     return newSessionId;
@@ -4001,7 +4083,8 @@ var SessionManager = class {
         createdAt: now,
         updatedAt: now,
         activeEntryId: newActiveEntryId,
-        tags: this.activeSession.metadata.tags
+        tags: this.activeSession.metadata.tags,
+        cwd: this.activeSession.metadata.cwd
       }
     );
     return newSessionId;
@@ -12532,7 +12615,7 @@ function sanitizeTitle(title) {
 }
 function isTextCompletionStepTitle(title) {
   const normalized = sanitizeTitle(title).toLowerCase();
-  return /反馈|总结|结论|汇报|说明|解释|收尾|验证|确认|位置|结果/u.test(title) || /\b(summarize|summary|report|explain|explanation|wrap[\s-]?up|verify|verification|confirm|result|results|location|findings)\b/i.test(normalized);
+  return /反馈|总结|结论|汇报|说明|解释|收尾|验证|确认|位置|结果/u.test(normalized) || /\b(summarize|summary|report|explain|explanation|wrap[\s-]?up|verify|verification|confirm|result|results|location|findings)\b/i.test(normalized);
 }
 function maybeAdvanceTodoExecutionState(state, signal) {
   if (state.mode !== "todo" || state.source === "user_todo" || state.lifecycle !== "active" || !state.currentStepId) {
@@ -15166,6 +15249,7 @@ export {
   interpretShellExit,
   createSubagentCapability,
   ManageTodoListParamsSchema,
+  MANAGE_TODO_LIST_TOOL_DESCRIPTION,
   executeManageTodoList,
   maybeAdvanceTodoExecutionState,
   createAskUserCapability,

package/dist/chunks/{chunk-FKAO25XH.js → chunk-B3SMW2XW.js}

@@ -3,7 +3,7 @@ import {
   EventStream,
   streamSimple,
   validateToolArguments
-} from "./chunk-K6ZOCJ4V.js";
+} from "./chunk-S2J3SZZX.js";
 
 // ../../packages/agent-core/src/agent-loop.ts
 function createLoopErrorMessage(error, config, signal) {

package/dist/chunks/{chunk-J6PEH6ST.js → chunk-KDPAGHYY.js}

@@ -8,10 +8,10 @@ import {
   createSharedWebSearchTool,
   interpretShellExit,
   requestInteraction
-} from "./chunk-7RYOIXA2.js";
+} from "./chunk-A644H2XX.js";
 import {
   Type
-} from "./chunk-K6ZOCJ4V.js";
+} from "./chunk-S2J3SZZX.js";
 
 // src/config.ts
 import { existsSync, mkdirSync, readFileSync, renameSync } from "fs";

package/dist/chunks/{chunk-K6ZOCJ4V.js → chunk-S2J3SZZX.js}

@@ -9911,7 +9911,50 @@ function validateToolArguments(tool, toolCall) {
     throw new Error(`Invalid arguments for tool "${tool.name}"`);
   }
   const path = firstError.path || "/";
-  throw new Error(`Invalid arguments for tool "${tool.name}" at ${path}: ${firstError.message}`);
+  const hint = buildArgumentHint(tool.parameters, firstError.path || "", args);
+  throw new Error(
+    `Invalid arguments for tool "${tool.name}" at ${path}: ${firstError.message}${hint ? `; ${hint}` : ""}`
+  );
+}
+function buildArgumentHint(schema, errorPath, args) {
+  const parentPath = errorPath.includes("/") ? errorPath.slice(0, errorPath.lastIndexOf("/")) : "";
+  const node = resolveSchemaNode(schema, parentPath);
+  if (!node || typeof node !== "object" || !node.properties) return "";
+  const parts = [];
+  const allowed = Object.keys(node.properties);
+  if (allowed.length > 0) parts.push(`allowed keys: [${allowed.join(", ")}]`);
+  if (Array.isArray(node.required) && node.required.length > 0) {
+    parts.push(`required: [${node.required.map(String).join(", ")}]`);
+  }
+  const received = receivedKeysAt(args, parentPath);
+  if (received) parts.push(`received keys: [${received.join(", ")}]`);
+  return parts.join("; ");
+}
+function resolveSchemaNode(schema, path) {
+  let node = schema;
+  for (const segment of path.split("/").filter(Boolean)) {
+    if (!node || typeof node !== "object") return void 0;
+    if (/^\d+$/.test(segment)) {
+      node = node.items;
+    } else if (node.properties && segment in node.properties) {
+      node = node.properties[segment];
+    } else if (node.additionalProperties && typeof node.additionalProperties === "object") {
+      node = node.additionalProperties;
+    } else {
+      return void 0;
+    }
+  }
+  return node;
+}
+function receivedKeysAt(args, path) {
+  let target = args;
+  for (const segment of path.split("/").filter(Boolean)) {
+    target = target?.[segment];
+  }
+  if (target && typeof target === "object" && !Array.isArray(target)) {
+    return Object.keys(target);
+  }
+  return void 0;
 }
 
 // ../../packages/ai/src/index.ts

package/dist/chunks/{src-HYZFAW4V.js → src-UKCIAX6F.js}

@@ -3,8 +3,8 @@ import {
   Agent,
   agentLoop,
   agentLoopContinue
-} from "./chunk-FKAO25XH.js";
-import "./chunk-K6ZOCJ4V.js";
+} from "./chunk-B3SMW2XW.js";
+import "./chunk-S2J3SZZX.js";
 import "./chunk-LZQXQOPJ.js";
 export {
   Agent,