pi-open-agents 0.1.30 → 0.1.31

package/README.md

@@ -167,6 +167,11 @@ active agent's rules *before it runs* — not just used to filter the toolset:
 > blocks matching *individual calls* (patterns included), not just statically
 > hiding whole tools. (#20)
 
+> **⚠️ Behavior change (v0.1.31):** subagent results are now file + summary
+> by default — full output goes to a temp archive, inline carries the child's
+> closing outcome block (#32). If you parsed full inline output
+> programmatically, read the archive path from the result instead.
+
 > **⚠️ Behavior change (v0.1.30):** primary-agent static filtering now covers
 > **all tool sources**, not just builtins (#18). If an agent declares
 > `permission` or `tools:`, extension tools (web, LSP, MCP, …) not matched
@@ -208,12 +213,24 @@ If an agent has the `subagent` tool, the plugin automatically appends a
 subagents and the correct call syntax:
 
 ```
-subagent({ agent: "<name>", task: "<task>", cwd?, session?, model? })
+subagent({ agent: "<name>", task: "<task>", cwd?, session?, model?, output? })
 ```
 
 You never need to explain delegation mechanics in agent prompts. The plugin
 handles it, the same way pi handles tool descriptions.
 
+### Subagent output: file + summary (not full-inline)
+
+Every run archives its verbatim output to a temp file and returns only a
+short outcome inline — open the file only if the summary is not enough to
+decide the next step. The child is instructed (via its system prompt) to end
+with a `## Outcome` block; without it, the executor falls back to today's
+truncated inline. Pass `output: "<path>"` when the deliverable itself is a
+file: the child writes it there and cites it as `` `<path>` — <what it
+contains> '' ›. On failure the error always comes back inline, never behind a
+file reference. Inspired by @EduardoOrtiz89's fork (`output`/`outputMode`),
+redesigned as the default instead of an opt-in (#32).
+
 ### Subagent execution engine
 
 When an agent delegates, the plugin spawns a child pi process with the target
@@ -397,6 +414,7 @@ six sessions, zero chaos: that's the exact workstation setup documented in
 - ~~**Agent hot-reload**~~ — ✅ works via pi's built-in `/reload`, shipped in [0.1.27](https://github.com/andrea-tomassi/pi-open-agents/releases/tag/v0.1.27) (#9)
 - ~~**Per-call model override** in `subagent()`~~ — ✅ shipped in [0.1.19](https://github.com/andrea-tomassi/pi-open-agents/releases/tag/v0.1.19) (#10)
 - ~~**Primary tool filters incl. extension tools**~~ — ✅ shipped in [0.1.30](https://github.com/andrea-tomassi/pi-open-agents/releases/tag/v0.1.30) (#18)
+- ~~**Subagent output: file + summary**~~ — ✅ shipped in [0.1.31](https://github.com/andrea-tomassi/pi-open-agents/releases/tag/v0.1.31) (#32)
 - **Parallel subagent limit** — #11
 
 ---
@@ -408,7 +426,7 @@ opening an issue or pull request.
 
 ```bash
 npm install
-npm test          # 207 tests
+npm test          # 216 tests
 npm run typecheck # tsc --noEmit
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-open-agents",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "description": "Unified agent and subagent management for pi coding agent, with OpenCode-compatible agent definitions.",
   "keywords": [
     "pi-package",

package/src/index.ts

@@ -261,9 +261,9 @@ export { matchPattern, isWildcardPattern } from "./permission/matcher.ts";
 export { evaluate, toolToPermission, getDisabledTools, filterDisabledTools } from "./permission/evaluator.ts";
 
 // Subagent re-exports
-export { runSubagent, resolveSubagentSession, resolvePiEntryPoint, isVirtualBunPath, resolveCompiledCommand } from "./subagent/executor.ts";
+export { runSubagent, resolveSubagentSession, resolvePiEntryPoint, isVirtualBunPath, resolveCompiledCommand, extractOutcomeBlock, OUTCOME_MARKER } from "./subagent/executor.ts";
 export type { AgentProgress, AgentResult, RunSubagentOptions, SubagentSessionInfo, SubagentSessionMode, HostProcessProbe } from "./subagent/executor.ts";
 export { resolveSkills } from "./subagent/skills.ts";
 export type { ResolvedSkill } from "./subagent/skills.ts";
-export { buildSubagentPrompt } from "./subagent/prompt.ts";
+export { buildSubagentPrompt, buildClosingContract } from "./subagent/prompt.ts";
 export { formatResultLines, formatUsage } from "./subagent/render.ts";

package/src/primary/executor.ts

@@ -201,7 +201,7 @@ export function buildSubagentGuidance(
     .map((a) => `- ${a.name}: ${a.description ?? "Subagent for delegated tasks."}`)
     .join("\n");
 
-  return `\n\n## Subagent Delegation\n\nYou have ${available.length} subagent(s) available. Delegate isolated tasks using the \`subagent\` tool:\n\nsubagent({ agent: "<name>", task: "<task description>" })\n\nAvailable subagents:\n${list}\n\nIMPORTANT: Subagent names are NOT bash commands. Always use the \`subagent\` tool to delegate — never write scripts that call agent names as CLI commands.`;
+  return `\n\n## Subagent Delegation\n\nYou have ${available.length} subagent(s) available. Delegate isolated tasks using the \`subagent\` tool:\n\nsubagent({ agent: "<name>", task: "<task description>" })\n\nAvailable subagents:\n${list}\n\nSubagent output: every run saves its full output to a temp file and returns only a short outcome summary — open the file only if the summary is not enough to decide your next step. Pass \`output: "<path>"\` when the deliverable itself is a file (report, patch, doc): the child writes it there and cites it in its summary. On failure the child always returns the error inline.\n\nIMPORTANT: Subagent names are NOT bash commands. Always use the \`subagent\` tool to delegate — never write scripts that call agent names as CLI commands.`;
 }
 
 /**

package/src/subagent/executor.ts

@@ -127,6 +127,13 @@ export interface RunSubagentOptions {
   parentCeiling?: string[];
   /** Parent's restrictive (deny/ask) permission rules, inherited into the child's gate via env. */
   parentRules?: Array<{ permission: string; pattern: string; action: "deny" | "ask" }>;
+  /**
+   * Commissioned deliverable path (issue #32). When set, the child is
+   * instructed to write its main deliverable there (resolved against cwd
+   * when relative) and cite it in the outcome block. Independent from the
+   * automatic temp archive of the full transcript output.
+   */
+  outputPath?: string;
   resolvePi?: () => Promise<PiResolution> | PiResolution;
   runner?: ProcessRunner;
   fs?: ExecutorFs;
@@ -216,6 +223,31 @@ export function composeChildTools(
   return result.length > 0 ? result : "none";
 }
 
+/**
+ * Marker separating the child's full transcript from its closing outcome
+ * block (issue #32). The child is instructed (see buildClosingContract) to
+ * end its final message with a `## Outcome` line followed by 2-3 lines.
+ */
+export const OUTCOME_MARKER = "## Outcome";
+
+/**
+ * Split the child's closing outcome block off the full output.
+ *
+ * Returns the text after the LAST marker line (case-insensitive, surrounding
+ * whitespace ignored), or undefined when the child omitted the block —
+ * older agents and error paths fall back to today's truncated inline.
+ */
+export function extractOutcomeBlock(output: string): string | undefined {
+  const lines = output.split("\n");
+  let idx = -1;
+  lines.forEach((line, i) => {
+    if (line.trim().toLowerCase() === OUTCOME_MARKER.toLowerCase()) idx = i;
+  });
+  if (idx === -1) return undefined;
+  const rest = lines.slice(idx + 1).join("\n").trim();
+  return rest ? rest : undefined;
+}
+
 export function subagentSessionDir(
   cwd: string,
   agentDir = path.join(os.homedir(), ".pi", "agent"),
@@ -620,12 +652,25 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
     options.onProgress?.(progress(status));
 
   try {
+    // ── Commissioned deliverable (issue #32) ──
+    // Resolved against the child cwd so the closing contract can name the
+    // exact path and the task can point at it.
+    const deliverablePath =
+      options.outputPath && options.outputPath.trim()
+        ? path.resolve(options.cwd, options.outputPath)
+        : undefined;
+    const task =
+      deliverablePath !== undefined
+        ? `${options.task}\n\nDeliverable: save your main deliverable to ${deliverablePath} and cite it in the outcome block.`
+        : options.task;
+
     // ── Build system prompt ──
     const promptFilePath = path.join(tempDir, "system-prompt.md");
     const promptResult = await buildSubagentPrompt({
       agent: options.agent,
       cwd: options.cwd,
       agentDir: options.agentDir,
+      outputPath: deliverablePath,
     });
 
     for (const source of promptResult.skills.skippedPackages) {
@@ -641,9 +686,9 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
 
     // ── Write task to file if too long ──
     let taskFilePath: string | undefined;
-    if (options.task.length > TASK_FILE_THRESHOLD) {
+    if (task.length > TASK_FILE_THRESHOLD) {
       taskFilePath = path.join(tempDir, "task.md");
-      await fileSystem.writeFile(taskFilePath, options.task);
+      await fileSystem.writeFile(taskFilePath, task);
     }
 
     // ── Resolve pi CLI entry point ──
@@ -701,7 +746,7 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
     }
 
     // Task
-    args.push(buildTaskArgument(options.task, taskFilePath));
+    args.push(buildTaskArgument(task, taskFilePath));
 
     // ── Build env vars ──
     const envVars: SubagentEnvVars = {
@@ -810,16 +855,38 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
       output = stderr || `Subagent exited with code ${exit.exitCode}`;
     }
 
-    // ── Truncate large output ──
-    const truncated = truncateHeadContent(output, OUTPUT_MAX_BYTES, OUTPUT_MAX_LINES);
-    if (truncated !== undefined) {
-      const originalOutput = output;
-      const fullOutputPath = path.join(
-        options.outputArchiveDir ?? os.tmpdir(),
-        `${safeFilePart(options.agent.name)}-${startedAt}-output.md`,
+    // ── Archive full output + derive the inline result (issue #32) ──
+    // Every run archives the verbatim output to a temp file; inline the
+    // child only sends its closing outcome block (file reference included).
+    // Without the block (older agents, error paths) fall back to today's
+    // truncated inline. A failed archive write must never break delegation:
+    // fall back to inline-only and warn.
+    const fullOutputPath = path.join(
+      options.outputArchiveDir ?? os.tmpdir(),
+      `${safeFilePart(options.agent.name)}-${startedAt}-output.md`,
+    );
+    let archived = false;
+    try {
+      await fileSystem.writeFile(fullOutputPath, output);
+      archived = true;
+    } catch (error) {
+      console.warn(
+        `[pi-open-agents] could not archive subagent output to ${fullOutputPath}: ${error instanceof Error ? error.message : String(error)}`,
       );
-      await fileSystem.writeFile(fullOutputPath, originalOutput);
-      output = `${truncated}\n\n[Output truncated: original ${originalOutput.split("\n").length} lines / ${byteLength(originalOutput)} bytes. Full output: ${fullOutputPath}]`;
+    }
+    const outcome = extractOutcomeBlock(output);
+    if (archived && outcome !== undefined) {
+      output = `${outcome}\n\nFull output: ${fullOutputPath}`;
+    } else if (archived) {
+      const truncated = truncateHeadContent(output, OUTPUT_MAX_BYTES, OUTPUT_MAX_LINES);
+      if (truncated !== undefined) {
+        output = `${truncated}\n\n[Output truncated: original ${output.split("\n").length} lines / ${byteLength(output)} bytes. Full output: ${fullOutputPath}]`;
+      }
+    } else {
+      const truncated = truncateHeadContent(output, OUTPUT_MAX_BYTES, OUTPUT_MAX_LINES);
+      if (truncated !== undefined) {
+        output = `${truncated}\n\n[Output truncated: original ${output.split("\n").length} lines / ${byteLength(output)} bytes. Archive write failed — full output unavailable.]`;
+      }
     }
 
     const result: AgentResult = {

package/src/subagent/prompt.ts

@@ -13,6 +13,12 @@ export interface BuildPromptOptions {
   agent: AgentDefinition;
   cwd: string;
   agentDir?: string;
+  /**
+   * Commissioned deliverable path (issue #32). When set, the child is told
+   * to write its main deliverable there and cite it in the outcome block.
+   * Already resolved against the child cwd by the caller.
+   */
+  outputPath?: string;
 }
 
 export interface BuildPromptResult {
@@ -48,10 +54,47 @@ function formatSkillsForPrompt(
   return lines.join("\n");
 }
 
+/**
+ * Child-side result contract (issue #32).
+ *
+ * Every run archives the full output to a temp file and returns only a
+ * short outcome inline — the child must therefore END its final message
+ * with a brief outcome block after a `## Outcome` marker line, cite
+ * commissioned files as `` `<path>` — <one-line description> '' ›, and keep
+ * errors inline (never behind a file reference).
+ */
+export function buildClosingContract(outputPath?: string): string {
+  const lines = [
+    "",
+    "",
+    "## Result Contract",
+    "",
+    "When your task is complete, end your final message with a short outcome block,",
+    "separated from the rest by a line containing exactly `## Outcome`:",
+    "",
+    "## Outcome",
+    "Outcome: <one line — done / failed + why>",
+    "Details: <what matters for the caller's next step, 2-3 lines>",
+    "",
+    "If you produced files the caller asked for, list each on its own line as",
+    "`<path>` — <one line describing the content>.",
+    "Keep the outcome block to 2-3 lines. Never paste the full output after the",
+    "marker when a file reference suffices; never hide an error behind a file reference.",
+  ];
+  if (outputPath) {
+    lines.push(
+      "",
+      `The caller expects its deliverable at \`${outputPath}\` — write it there with your file tools`,
+      "and cite it in the outcome block.",
+    );
+  }
+  return lines.join("\n");
+}
 /**
  * Build the system prompt for a subagent.
  *
- * Starts with the agent body, appends skill injection if the agent has skills.
+ * Starts with the agent body, appends skill injection if the agent has skills,
+ * then the result-closing contract (issue #32).
  */
 export async function buildSubagentPrompt(options: BuildPromptOptions): Promise<BuildPromptResult> {
   let prompt = options.agent.prompt;
@@ -75,5 +118,7 @@ export async function buildSubagentPrompt(options: BuildPromptOptions): Promise<
     }
   }
 
+  prompt = `${prompt}${buildClosingContract(options.outputPath)}`;
+
   return { prompt, skills: skillsResult };
 }

package/src/subagent/tool.ts

@@ -55,6 +55,12 @@ interface SubagentParams {
   cwd?: string;
   session?: SubagentSessionMode;
   model?: string;
+  /**
+   * Commissioned deliverable path (issue #32). The child writes its main
+   * deliverable there and cites it in the closing outcome; the full
+   * transcript is always archived to temp regardless.
+   */
+  output?: string;
 }
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
@@ -279,7 +285,7 @@ export function registerSubagentTool(
     name: "subagent",
     label: "Subagent",
     description: "Delegate a task to a named sub-agent running in an isolated pi process.",
-    promptSnippet: "Delegate isolated tasks with subagent({ agent, task, cwd?, session?, model? }).",
+    promptSnippet: "Delegate isolated tasks with subagent({ agent, task, cwd?, session?, model?, output? }).",
     promptGuidelines,
     parameters: Type.Object({
       agent: Type.String({ description: "Name of the agent to invoke" }),
@@ -295,6 +301,11 @@ export function registerSubagentTool(
           description: 'Per-call model override in "provider/model-id" format (e.g. "anthropic/claude-sonnet-4-5"). Model ids may contain slashes for aggregator providers ("openrouter/anthropic/claude-opus-5.5"). Takes precedence over the agent definition default.',
         }),
       ),
+      output: Type.Optional(
+        Type.String({
+          description: "Deliverable file path. The child writes its main deliverable there (relative paths resolve against the child cwd) and cites it in the closing outcome. The full transcript is always archived to temp regardless.",
+        }),
+      ),
     }),
 
     async execute(
@@ -356,6 +367,7 @@ export function registerSubagentTool(
         agentDir: options.agentDir,
         session,
         modelOverride: params.model,
+        outputPath: params.output && params.output.trim() ? params.output : undefined,
         parentCeiling,
         parentRules: parentRules.length > 0 ? parentRules : undefined,
         onProgress: (progress) => onUpdate?.(toProgressResult(progress)),