@signalridge/pi-subagents 1.13.0 → 1.15.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 1.15.0
+### Minor Changes
+
+- a4dc1de: Enforce missing per-invocation safety budgets on resumed agents, including foreground/background calls, nested resumes, mentions, and reused managed threads. Share fresh/resumed turn, token, and tool-call enforcement and terminal outcome mapping; preserve configured grace and tool timeouts. Resume inherits the original invocation's turn budget when not overridden, respects authoritative frontmatter/default policy, validates explicit limits like spawn, and does not let zero erase a configured cap. Nested resumes resolve only their branch-local frontmatter through an in-process budget-policy capability; internal callers without it retain the admitted invocation budget rather than consulting the root registry. Authoritative frontmatter zero remains unlimited after a finite earlier invocation. A retained session's finite or unlimited policy survives later default changes; one manager-resolved cap drives enforcement and queued/running UI counters. Activity updates are invocation-owned and lifetime usage is counted only once.
+  
+  Dispose grouped notifications and pending batch/nudge timers synchronously at confirmed shutdown, retire invocation-owned foreground progress/spinner callbacks before any teardown await, fence captured delivery callbacks, and preserve managed lifecycle/usage receipts while cooperative child teardown completes. Refused/failed resume admissions retire their own UI callbacks, while admitted lifetimes own final cleanup; mention notifications are fenced after asynchronous admission. Vetoable navigation remains unchanged.
+  
+  Selective upstream parity references: tintinweb/pi-subagents `d7c9ec0b027b91c7ab9da0fa5f4ae203474a5bdf`, `ca93a5247e72e7053fcd10bea7125d6c4205f949` (unreleased after the 0.22 tag), and `83be963a969eb359af29cbbb4d4af2d01748bfb5` (released in 0.22). The integrated engine is not imported; managed protocol v4 and payloads are unchanged. Event-based budgets cannot forcibly terminate a provider or tool that ignores abort.
+
+### Patch Changes
+
+- a4dc1de: Distinguish expandable Workflow groups from individual agents with a dedicated `▸` type mark across all run outcomes. Remove the duplicate trailing blank row before the footer while preserving Fleet navigation, exact-owner conversation opening, and the existing Workflow detail UI.
+
+## 1.14.0
+### Minor Changes
+
+- 0ec64d1: Gate admitted child edit, write, and bash operations through a synchronously captured root human approval service. Preserve tool admission and legacy ask-tools policy, reject canonical shadowing and duplicate child approval resources, retain ownership across resume, and exclude human review time without resetting execution budgets. Managed protocol and journal formats remain v4.
+
+### Patch Changes
+
+- 74b65a5: Bound edit call rendering without IO or diff work; retain captured service liveness and exact-name admission through post-approval IO; reject live child canonical conflicts even when SDK metadata still wins. Replace delegated bash dispatch with an owned POSIX backend guarded after CWD preparation, preserving the SDK output layer while owning process-group/IPC cleanup. Preserve native editor paste/cursor/Undo state with an admitted non-capturing UI bridge, and hide unfocused reviews so foreign native questions remain visible and answerable.
+  
+  Refuse Bun/compiled application and unknown interpreter capabilities before approval or subprocess startup instead of executing the host application as a supervisor. Use lossless hard wrapping, whole-grapheme and native-normalized Thai/Lao escaping, and explicit compact-preview whitespace/backslashes so spacing marks and distinct commands remain inspectable through actual terminal output.
+- 0925139: Bound synchronous file-review diff work before generation, capture bash execution options and environments, require exact per-name canonical review bindings, and close owned review overlays by identity. Recheck cooperative adapter admission after child tool-call normalizers and carry the same captured approval-service and branch-owner guard through background startup to command dispatch. Preserve existing v1 approval and v4 managed contracts; document review limits and trusted-extension boundaries.
+- Updated dependencies [74b65a5]
+- Updated dependencies [0ec64d1]
+- Updated dependencies [0925139]
+  - @signalridge/pi-approval-core@1.3.0
+
 ## 1.13.0
 ### Minor Changes
 

package/README.md

@@ -55,6 +55,8 @@ Derived from [tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents)
 
 The container-first FleetView and bounded drill-down patterns are independently adapted from tintinweb/pi-subagents at [`221df02323c6b6350ea8474579e0ee0f6cc84cea`](https://github.com/tintinweb/pi-subagents/tree/221df02323c6b6350ea8474579e0ee0f6cc84cea/src/ui) and [`fd8d81618d80ae83a3faf40cb87dae99cca33264`](https://github.com/tintinweb/pi-subagents/tree/fd8d81618d80ae83a3faf40cb87dae99cca33264/src/ui). Collision-only child-label discriminators are inspired by [nicobailon/pi-subagents `69673c7fbf3351e54a5b0786a7e9d9fff625a749`](https://github.com/nicobailon/pi-subagents/blob/69673c7fbf3351e54a5b0786a7e9d9fff625a749/src/tui/render-helpers.ts). The workflow engine and phase inspector remain owned by `pi-workflows`, not copied into this package. A separate optional, validated UI protocol supplies authoritative run names, statuses and observed phases and opens that owner's inspector. Without that peer, groups retain the observation-only child list. No workflow source imports, inferred DAG state or second queue/model policy are introduced. The managed protocol remains v4.
 
+Resume-budget and shutdown parity fixes selectively adapt upstream work at [`d7c9ec0`](https://github.com/tintinweb/pi-subagents/commit/d7c9ec0b027b91c7ab9da0fa5f4ae203474a5bdf), [`ca93a52`](https://github.com/tintinweb/pi-subagents/commit/ca93a5247e72e7053fcd10bea7125d6c4205f949) (unreleased after the 0.22 tag), and [`83be963`](https://github.com/tintinweb/pi-subagents/commit/83be963a969eb359af29cbbb4d4af2d01748bfb5) (released in 0.22). They retain this fork's manager-owned sessions, resource budgets, activity accounting, and protocol v4; the integrated upstream engine is not imported.
+
 The opt-in parent clarification broker is locally implemented. It uses the existing main session, not an upstream LLM arbitrator, cloned parent history, private UI automation, or an additional Agent per question. Permission gates remain human-owned.
 
 ## Lint policy
@@ -114,6 +116,14 @@ Foreground parent-mode calls are rejected **before spawn**: a main model blocked
 
 Install the changed package and reload/restart Pi to use this feature; an already running older installed package does not acquire new tools or parameters from checkout edits.
 
+### Root-owned operation approvals
+
+When a root approval service is present at child creation, admitted canonical `edit`, `write`, and `bash` tools use `@signalridge/pi-approval-core` reviewed SDK definitions. Each operation awaits the root human service with its exact final inputs, file diff or command, working directory, and a distinct `child:<agent-id>` source. Ordinary parent clarification answers never authorize operations. No service means existing behavior is unchanged; malformed or duplicate services refuse before child allocation. A captured service cannot reconnect after retirement or replacement.
+
+Tool admission, denylist, `ask_tools`, project trust, and isolation still apply first: approval adds no tools, including to internal zero-tool generation. The gate survives in-memory resume, steering, and nested `ctx.executeTool` calls. Noncanonical command/mutation-shaped tools require exactly one live cooperative adapter matching the effective schema identity. Known command or path-plus-edit/content schema properties are classified before invocation even when optional. Admission is also rechecked after each downstream public `tool_call` handler against the native mutable arguments and the originally captured execution name/schema; a normalizer cannot add a command or rename the event to bypass it. These post-handler checks never repeat `ask_tools` human prompts and retain the same shared execution deadline. Conflicting canonical extension tools are refused rather than silently replacing the reviewed binding. While root review is pending, only human waiting time is excluded from the child's default tool timeout; execution retains its remaining budget and native bash timeouts still apply after approval. Cancellation and divergent root/child branch ownership deny execution.
+
+Inherited `pi-approvals` resources are excluded before factory loading when the root service is captured, including package aliases. Explicit selection is rejected with guidance to integrate approvals in the root session. Children do not load another approval extension or forward their UI to impersonate a human; no UI/model mode is enabled automatically. Known-shape admission does not interpret arbitrary extension semantics or unknown schemas; a timed-out hook can still perform its own side effects outside the executor. This is an in-process trusted extension integration, not an OS sandbox for arbitrary extension code. Managed protocol and journal formats remain v4.
+
 ### Scheduling
 
 Add a `schedule` field to register the agent to fire later instead of running now:
@@ -461,6 +471,10 @@ Instead of hard-aborting at the turn limit, agents get a graceful shutdown:
 2. Up to 5 grace turns to finish cleanly
 3. Hard abort only after the grace period
 
+Each resumed prompt gets its own counters, not an unlimited continuation or a deduction from prior turns. This applies to foreground/background resumes, nested children, mentions, and reused managed threads. Agent frontmatter remains authoritative; without a per-resume override, the original invocation's turn limit is inherited, falling back to configured defaults. Resume overrides use the same non-negative safe-integer validation as spawning; caller zero cannot disable an inherited/configured cap. An authoritative frontmatter zero remains unlimited, even after an earlier finite invocation. Nested resumes reload the same branch-local definitions as nested spawns, never the root registry; an internal resume without scoped policy retains its admitted invocation budget. A retained session's admitted turn policy, including unlimited, survives later project-default changes; the manager supplies that same effective cap to queued and running progress trackers. The existing token/tool-call caps and tool timeout also apply to resumed prompts. Budgets are event-based: an already-running provider/tool can overshoot within one event or ignore abort; these are not process-isolation guarantees.
+
+Confirmed shutdown retires grouped completion, batch-finalization, held-nudge timers, and invocation-owned foreground spinners before awaiting child teardown. Captured delivery callbacks cannot wake the main model or publish foreground progress afterward, even while a provider ignores abort. Refused or failed resume admissions retire their own UI callbacks; an admitted run owns cleanup until settlement. Mention continuations cannot publish notifications after their root/runtime retires. Managed lifecycle/usage receipts remain available during cooperative shutdown; vetoable navigation attempts do not dispose these resources.
+
 | Status | Meaning | UI treatment |
 |--------|---------|-------------|
 | `completed` | Finished naturally | `completed` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-subagents",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "description": "Signalridge's managed subagent runtime with workflow-owned orchestration RPC.",
   "author": "tintinweb and signalridge contributors",
   "license": "MIT",
@@ -31,6 +31,7 @@
     "@sinclair/typebox": "*"
   },
   "dependencies": {
+    "@signalridge/pi-approval-core": "^1.3.0",
     "croner": "^10.0.1",
     "@signalridge/pi-subagents-protocol": "^1.6.0",
     "@signalridge/pi-ui": "^1.4.0",

package/src/agent-manager.ts

@@ -35,15 +35,19 @@ import {
 import {
   INTERNAL_AGENT_CONFIG_OVERRIDE,
   INTERNAL_PARENT_POLICY_SNAPSHOT,
+  INTERNAL_RESUME_BUDGET_POLICY,
   type InternalAgentConfigOverride,
   type ParentPolicySnapshot,
+  type ResumeBudgetPolicy,
 } from "./internal-run.js";
+import { resolveMaxTurns } from "./invocation-config.js";
 import { assignHandle, handleBase } from "./mention.js";
 import {
   assertParentModelRuntimeAvailable,
   parentModelSessionOptions,
 } from "./model-runtime-bridge.js";
 import type { ParentQuestionHandler } from "./parent-questions.js";
+import { selectResumeTurnPolicy } from "./run-budget-policy.js";
 import { shutdownAndDisposeSession } from "./session-lifecycle.js";
 import type { TierThinking } from "./settings.js";
 import type {
@@ -315,6 +319,21 @@ function snapshotCleanupFailure(
   });
 }
 
+/** Hard budgets take precedence over provider failure, then soft wrap-up. */
+function applyRunOutcome(
+  record: AgentRecord,
+  outcome: { aborted?: boolean; steered?: boolean; failure?: string },
+): void {
+  if (outcome.aborted) {
+    record.status = "aborted";
+  } else if (outcome.failure) {
+    record.status = "error";
+    record.error = outcome.failure;
+  } else {
+    record.status = outcome.steered ? "steered" : "completed";
+  }
+}
+
 interface SpawnArgs {
   pi: ExtensionAPI;
   ctx: ExtensionContext;
@@ -1021,10 +1040,27 @@ export type ManagedSpawnCallbacks = Pick<
   | "onCompaction"
   | "onSpawned"
 > & {
+  /** Reused thread's effective display budget, before queue admission. */
+  onResumeBudgetResolved?: (maxTurns: number | undefined) => void;
   /** Reused thread's actual run boundary, before native steering or prompt. */
   onResumeStarting?: (record: AgentRecord, startMessageIndex: number) => void;
 };
 
+export interface ResumeOptions {
+  readonly [INTERNAL_RESUME_BUDGET_POLICY]?: ResumeBudgetPolicy;
+  isBackground?: boolean;
+  maxTurns?: number;
+  onToolActivity?: (activity: ToolActivity) => void;
+  onTurnEnd?: (count: number) => void;
+  onTextDelta?: (delta: string, fullText: string) => void;
+  onAssistantUsage?: SpawnOptions["onAssistantUsage"];
+  onCompaction?: (info: CompactionInfo) => void;
+  /** Effective display cap, published synchronously before queue admission. */
+  onBudgetResolved?: (maxTurns: number | undefined) => void;
+  /** Called at actual admission, including a queued background resume. */
+  onStarted?: () => void;
+}
+
 interface ResumeTerminalSnapshot {
   status: AgentRecord["status"];
   startedAt: number;
@@ -1863,9 +1899,13 @@ export class AgentManager {
       // only filter excludes only explicit `false`, so undefined agents — which
       // have no inline surface — stay visible instead of vanishing.
       isBackground: options.isBackground,
-      invocation: options.invocation
-        ? cloneFrozenData(options.invocation)
-        : undefined,
+      invocation:
+        options.invocation || options.maxTurns !== undefined
+          ? cloneFrozenData({
+              ...options.invocation,
+              maxTurns: options.maxTurns ?? options.invocation?.maxTurns,
+            })
+          : undefined,
       depth: options.depth ?? 1,
       parentAgentId: options.parentAgentId,
       ...(ancestorAgentIds ? { ancestorAgentIds } : {}),
@@ -2176,9 +2216,13 @@ export class AgentManager {
         }
         void this.resume(threadedId, normalized.prompt, undefined, {
           isBackground: true,
+          maxTurns: policy.maxTurns,
+          onBudgetResolved: callbacks?.onResumeBudgetResolved,
           onStarted: () => {
             void Promise.resolve(callbacks?.onResumeStarting?.(record, record.session!.messages.length)).catch(() => {});
           },
+          onTurnEnd: callbacks?.onTurnEnd,
+          onTextDelta: callbacks?.onTextDelta,
           onToolActivity: callbacks?.onToolActivity,
           onAssistantUsage: callbacks?.onAssistantUsage,
           onCompaction: callbacks?.onCompaction
@@ -2560,14 +2604,7 @@ export class AgentManager {
           // Precedence: a hard abort keeps "aborted"; then a failed final turn
           // (provider error that pi resolved instead of rejecting, #144) is an
           // honest "error" — not a completion with an empty or stale result.
-          if (aborted) {
-            record.status = "aborted";
-          } else if (failure) {
-            record.status = "error";
-            record.error = failure;
-          } else {
-            record.status = steered ? "steered" : "completed";
-          }
+          applyRunOutcome(record, { aborted, steered, failure });
         }
         record.completedAt ??= Date.now();
         detach();
@@ -3094,21 +3131,7 @@ export class AgentManager {
     id: string,
     prompt: string,
     signal?: AbortSignal,
-    options?: {
-      isBackground?: boolean;
-      onToolActivity?: (activity: {
-        type: "start" | "end";
-        toolName: string;
-      }) => void;
-      onAssistantUsage?: (usage: {
-        input: number;
-        output: number;
-        cacheWrite: number;
-      }) => void;
-      onCompaction?: (info: unknown) => void;
-      /** Called once a queued background resume has acquired its run slot. */
-      onStarted?: () => void;
-    },
+    options?: ResumeOptions,
   ): Promise<AgentRecord | undefined> {
     if (this.disposed) return undefined;
     const record = this.agents.get(id);
@@ -3124,6 +3147,28 @@ export class AgentManager {
       record.invocation?.inheritContext === true,
     );
 
+    if (
+      options?.maxTurns !== undefined &&
+      (!Number.isSafeInteger(options.maxTurns) || options.maxTurns < 0)
+    ) {
+      throw new Error("maxTurns must be a non-negative safe integer");
+    }
+    // Nested definitions belong to their branch, never the global root registry.
+    // Without the scoped tool's capability, retain the admitted invocation policy.
+    const policy = record.parentAgentId === undefined
+      ? getAgentConfig(record.type)
+      : options?.[INTERNAL_RESUME_BUDGET_POLICY] ?? record.invocation;
+    const maxTurns = selectResumeTurnPolicy(record.session, resolveMaxTurns(
+      policy,
+      // A caller's zero cannot erase the original/configured safety policy.
+      options?.maxTurns || record.invocation?.maxTurns,
+    ));
+    try {
+      options?.onBudgetResolved?.(maxTurns === 0 ? undefined : maxTurns);
+    } catch {
+      // UI observers cannot alter the authoritative policy or admission.
+    }
+    options = { ...options, maxTurns };
     const snapshot = this.resumeSnapshot(record);
     if (options?.isBackground) {
       // A background resume is one lifecycle, including time spent queued. Keep
@@ -3177,18 +3222,31 @@ export class AgentManager {
     record.result = undefined;
     record.error = undefined;
     try {
-      const { text, failure } = await resumeAgent(record.session, prompt, {
+      options.onStarted?.();
+      const { text, failure, aborted, steered } = await resumeAgent(record.session, prompt, {
+        maxTurns,
+        onTurnEnd: (count) => {
+          if (!record.detached) options.onTurnEnd?.(count);
+        },
+        onTextDelta: (delta, text) => {
+          if (!record.detached) options.onTextDelta?.(delta, text);
+        },
         onToolActivity: (activity) => {
-          if (!record.detached && activity.type === "end") record.toolUses++;
+          if (record.detached) return;
+          if (activity.type === "end") record.toolUses++;
+          options.onToolActivity?.(activity);
         },
         onAssistantUsage: (usage) => {
-          if (!record.detached) addUsage(record.lifetimeUsage, usage);
+          if (record.detached) return;
+          addUsage(record.lifetimeUsage, usage);
+          options.onAssistantUsage?.(usage);
         },
         onCompaction: (info) => {
           if (record.detached) return;
           record.compactionCount++;
           this.syncManagedRecord(record);
           this.onCompact?.(record, info);
+          options.onCompaction?.(info);
         },
         signal: control.controller.signal,
       });
@@ -3197,8 +3255,7 @@ export class AgentManager {
         !control.controller.signal.aborted &&
         (record.status as AgentRecord["status"]) !== "stopped"
       ) {
-        record.status = failure ? "error" : "completed";
-        if (failure) record.error = failure;
+        applyRunOutcome(record, { aborted, steered, failure });
         record.result = text;
         record.completedAt = Date.now();
       }
@@ -3242,21 +3299,7 @@ export class AgentManager {
     record: AgentRecord,
     prompt: string,
     control: ResumeControl,
-    options?: {
-      isBackground?: boolean;
-      onToolActivity?: (activity: {
-        type: "start" | "end";
-        toolName: string;
-      }) => void;
-      onAssistantUsage?: (usage: {
-        input: number;
-        output: number;
-        cacheWrite: number;
-      }) => void;
-      onCompaction?: (info: unknown) => void;
-      /** Called once a queued background resume has acquired its run slot. */
-      onStarted?: () => void;
-    },
+    options?: ResumeOptions,
   ): Promise<string> {
     const snapshot = control.snapshot;
     let slotHeld = false;
@@ -3305,13 +3348,22 @@ export class AgentManager {
       }
 
       try {
-        const { text, failure } = await resumeAgent(record.session!, prompt, {
+        const { text, failure, aborted, steered } = await resumeAgent(record.session!, prompt, {
+          maxTurns: options?.maxTurns,
+          onTurnEnd: (count) => {
+            if (!record.detached) options?.onTurnEnd?.(count);
+          },
+          onTextDelta: (delta, text) => {
+            if (!record.detached) options?.onTextDelta?.(delta, text);
+          },
           onToolActivity: (activity) => {
-            if (!record.detached && activity.type === "end") record.toolUses++;
+            if (record.detached) return;
+            if (activity.type === "end") record.toolUses++;
             options?.onToolActivity?.(activity);
           },
           onAssistantUsage: (usage) => {
-            if (!record.detached) addUsage(record.lifetimeUsage, usage);
+            if (record.detached) return;
+            addUsage(record.lifetimeUsage, usage);
             options?.onAssistantUsage?.(usage);
           },
           onCompaction: (info) => {
@@ -3328,8 +3380,7 @@ export class AgentManager {
           !control.controller.signal.aborted &&
           (record.status as AgentRecord["status"]) !== "stopped"
         ) {
-          record.status = failure ? "error" : "completed";
-          if (failure) record.error = failure;
+          applyRunOutcome(record, { aborted, steered, failure });
           record.result = text;
           record.completedAt = Date.now();
         }