shariq-pi-extensions 0.2.6 → 0.2.7

package/docs/EXTENSIONS.md

@@ -38,7 +38,7 @@ The goal extension adds persistent, branch-safe objectives, progress evidence, b
 
 The subagent extension runs flat Pi child agents with profiles, capability policies, continuation, result delivery, optional worktrees, and a dashboard. Configuration lives in `<agent-dir>/subagents.json`; trusted projects may override it through their Pi config directory. The configured concurrency ceiling is 50.
 
-The extension supplies tools including `spawn_agent`, `task`, `check_agent`, `list_agents`, `wait_agent`, `send_message`, `close_agent`, `reply_question`, and `apply_agent_changes`. Child settlement is handed to Pi immediately as a turn-triggering follow-up, so Pi queues it while the parent is active or starts a new parent turn when idle; status tools are for explicit inspection, not waiting.
+The extension supplies tools including `spawn_agent`, `task`, `check_agent`, `list_agents`, `wait_agent`, `send_message`, `close_agent`, `reply_question`, and `apply_agent_changes`. Child settlement is handed to Pi immediately as an extension-originated user follow-up, so Pi queues it while the parent is active or starts a new parent turn when idle with the summary guaranteed in model context; status tools are for explicit inspection, not waiting.
 
 ### [Orchestration](../extensions/orchestration/README.md)
 
@@ -50,7 +50,7 @@ The model-facing `create_orchestration` tool starts planning only after an expli
 
 Managed PTYs support servers, watchers, long builds, downloads, and interactive processes. The extension tracks up to eight concurrent terminals, retains bounded output, stores full logs in restrictive temporary directories, and stops process groups during shutdown or reload.
 
-Its tools are `start_terminal`, `read_terminal`, `write_terminal`, `list_terminals`, and `stop_terminal`. A model-started terminal immediately hands its completion or failure to Pi as a turn-triggering follow-up, which Pi queues while the parent is active or uses to start a new parent turn when idle. Reading a terminal does not suppress that delivery; agents should inspect only for explicit progress requests or immediate interaction.
+Its tools are `start_terminal`, `read_terminal`, `write_terminal`, `list_terminals`, and `stop_terminal`. A model-started terminal immediately hands its completion or failure to Pi as an extension-originated user follow-up, which Pi queues while the parent is active or uses to start a new parent turn when idle with the bounded output guaranteed in model context. Reading a terminal does not suppress that delivery; agents should inspect only for explicit progress requests or immediate interaction.
 
 ## Web access
 

package/extensions/background-terminals/README.md

@@ -10,7 +10,7 @@ Session-scoped background pseudo-terminals for Pi. The extension combines Codex-
 - `list_terminals` — list running and settled terminals.
 - `stop_terminal` — stop complete process groups with TERM-to-KILL escalation.
 
-Each output response carries a byte cursor. Pass it to the next read/write operation to avoid repeating output. Long or uncertain commands should use `start_terminal` instead of a large blocking `bash` timeout. Settlement is handed to Pi immediately: it queues a follow-up while the parent is active or starts a new parent turn when idle, so the parent can continue other work or end its turn rather than poll.
+Each output response carries a byte cursor. Pass it to the next read/write operation to avoid repeating output. Long or uncertain commands should use `start_terminal` instead of a large blocking `bash` timeout. Settlement is handed to Pi immediately as an extension-originated user follow-up: it queues while the parent is active or starts a new parent turn when idle with bounded output guaranteed in model context, so the parent can continue other work or end its turn rather than poll.
 
 ## User interface
 
@@ -34,7 +34,7 @@ Each output response carries a byte cursor. Pass it to the next read/write opera
 - Output is sanitized before TUI or model rendering.
 - Processes run in their own PTY process group and are stopped on session shutdown, replacement, or reload.
 - Shutdown and stop operations are bounded and escalate from SIGTERM to SIGKILL.
-- Model-started terminals immediately hand one completion/failure follow-up to Pi; Pi queues it while the parent is active or starts the next parent turn when idle.
+- Model-started terminals immediately hand one model-visible completion/failure follow-up to Pi; Pi queues it while the parent is active or starts the next parent turn when idle.
 - Reading settled output does not consume or suppress the automatic completion delivery.
 - Completion delivery is keyed by terminal id to prevent duplicate follow-ups.
 

package/extensions/shared/README.md

@@ -8,7 +8,7 @@ Internal runtime utilities used by more than one extension. This directory is no
 - `child-session.ts` owns trust-aware child resources and bounded session shutdown.
 - `context-utilization.ts` formats model-context usage and capacity.
 - `dashboard-state.ts` keeps list selection stable as live rows change.
-- `settlement-delivery.ts` immediately hands asynchronous results to Pi as turn-triggering follow-ups.
+- `settlement-delivery.ts` immediately hands asynchronous results to Pi as extension-originated user follow-ups, guaranteeing model-visible settlement context.
 - `tool-call-timeout.ts` applies cancellation-aware execution limits to registered tools.
 - `tui-dashboard.ts` provides bounded, sanitized terminal-dashboard rendering helpers.
 

package/extensions/shared/settlement-delivery.ts

@@ -3,9 +3,17 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 type SettlementMessage = Parameters<ExtensionAPI["sendMessage"]>[0];
 
 /**
- * Hand settlement to Pi immediately. Pi starts a turn when idle and queues the
- * same message as a follow-up when the parent is still running.
+ * Hand settlement to Pi as an extension-originated user follow-up. A custom
+ * message can wake the parent yet fail to appear in the invoked model turn;
+ * sendUserMessage guarantees that the bounded result is model-visible. Pi
+ * starts a turn when idle and queues the same input while the parent is active.
  */
 export function deliverSettlement(pi: ExtensionAPI, message: SettlementMessage): void {
-  pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true });
+  const content = typeof message.content === "string"
+    ? message.content
+    : message.content
+      .filter((part) => part.type === "text")
+      .map((part) => part.text)
+      .join("\n");
+  pi.sendUserMessage(content, { deliverAs: "followUp" });
 }

package/extensions/subagents/README.md

@@ -19,7 +19,7 @@ The system is deliberately flat. Only the main Pi thread can spawn subagents. Ch
 - `reply_question` — answer a child’s blocking `ask_parent` request
 - `task` — atomically reserve capacity for up to the configured limit (maximum 50), start the fan-out in the background, and return child ids immediately
 
-Child sessions receive `message_parent`, `ask_parent`, `list_peers`, and `message_peer`. Peer messages are routed through the main-thread manager and can steer a running child or continue a settled one; they cannot create agents. Child settlement is handed to Pi immediately: it queues a follow-up while the parent is active or starts a new parent turn when idle, so the main turn can continue independent work or end and remain available to the user.
+Child sessions receive `message_parent`, `ask_parent`, `list_peers`, and `message_peer`. Peer messages are routed through the main-thread manager and can steer a running child or continue a settled one; they cannot create agents. Child settlement is handed to Pi immediately as an extension-originated user follow-up: it queues while the parent is active or starts a new parent turn when idle with the summary guaranteed in model context, so the main turn can continue independent work or end and remain available to the user.
 
 ## Profiles and capabilities
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shariq-pi-extensions",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Cross-platform extension suite for the Pi coding agent.",
   "license": "MIT",
   "author": "Shariq Riaz",

package/skills/background-terminals/SKILL.md

@@ -24,9 +24,9 @@ Provide:
 - the working directory when it differs from the current directory;
 - an initial wait only when startup output is needed for the next decision.
 
-After startup, continue only genuinely useful independent work. If none remains, end the turn immediately. Ending the turn is the waiting mechanism: terminal settlement is handed to Pi immediately, queued as a follow-up if the parent is still active, and otherwise starts the next parent turn with the final status and bounded output. Do not keep the current turn alive to wait, invent monitoring work, or call terminal tools merely to see whether the process finished.
+After startup, continue only genuinely useful independent work. If none remains, end the turn immediately. Ending the turn is the waiting mechanism: terminal settlement is handed to Pi immediately as an extension-originated user follow-up, queued if the parent is still active, and otherwise starts the next parent turn with the final status and bounded output visible in model context. Do not keep the current turn alive to wait, invent monitoring work, or call terminal tools merely to see whether the process finished.
 
-When that completion follow-up invokes the next turn, treat its attached output as the terminal result and continue the original task immediately. Do not wait for another user message, announce that you are still waiting, or call `read_terminal` to retrieve the same result again. If `start_terminal` itself returns a settled result, the output is already synchronous and no second completion notice is needed.
+When that completion follow-up invokes the next turn, treat its model-visible output as the terminal result and continue the original task immediately. Do not wait for another user message, announce that you are still waiting, or call `read_terminal` to retrieve the same result again. If `start_terminal` itself returns a settled result, the output is already synchronous and no second completion notice is needed.
 
 ## Inspect and interact only when necessary
 

package/skills/subagents/SKILL.md

@@ -24,14 +24,14 @@ This skill governs temporary Pi child agents. The `codex-thread-orchestrator` sk
 
 ## Wait by notification; inspect progress only when justified
 
-A successful `spawn_agent` or `task` call starts asynchronous work and returns control to the parent. When a child finishes, its settlement is handed to Pi immediately, queued as a follow-up if the parent is still active, and otherwise starts the next main-agent turn. The parent does not need to remain active or check once before ending its turn.
+A successful `spawn_agent` or `task` call starts asynchronous work and returns control to the parent. When a child finishes, its settlement is handed to Pi immediately as an extension-originated user follow-up, queued if the parent is still active, and otherwise starts the next main-agent turn with the summary visible in model context. The parent does not need to remain active or check once before ending its turn.
 
 After dispatch:
 
 1. Continue only parent work that is independently useful to the requested result.
 2. If no such work remains, end the turn immediately. A short progress note is enough when the user needs one.
 3. Do not call `wait_agent`, `list_agents`, or `check_agent` in the same turn merely because the child was just launched. Ending the turn is the waiting mechanism.
-4. When a child completion notice invokes the main agent, treat the attached summary as the child result and continue the original task immediately. Reconcile completed results, launch any intentionally queued work if capacity requires waves, and otherwise keep waiting through notifications. Do not wait for the user to prompt you again or call a status tool to retrieve the same result.
+4. When a child completion notice invokes the main agent, treat its model-visible summary as the child result and continue the original task immediately. Reconcile completed results, launch any intentionally queued work if capacity requires waves, and otherwise keep waiting through notifications. Do not wait for the user to prompt you again or call a status tool to retrieve the same result.
 
 A progress check is reasonable when the user asks for status, a child has run materially longer than expected for its task and model, an interruption left its state unclear, or current status will change an immediate coordination decision. Prefer `check_agent` for one known child and `list_agents` for a batch overview. Use `wait_agent` to collect results already expected to be available, not as a running-status probe.