@gotgenes/pi-subagents 6.15.0 → 6.16.1

package/docs/retro/0144-consolidate-observation-model.md

@@ -0,0 +1,39 @@
+---
+issue: 144
+issue_title: "Consolidate observation model (Phase 9, Step L)"
+---
+
+# Retro: #144 — Consolidate observation model
+
+## Final Retrospective (2026-05-23)
+
+### Session summary
+
+Planned and implemented the Phase 9 Step L observation model consolidation.
+Removed dual `_toolUses`/`_lifetimeUsage` counting from `AgentActivityTracker`, added `session`/`outputFile` convenience getters to `AgentRecord`, migrated 14 callsites, and dissolved `NotificationDeps` into plain constructor parameters.
+Released as `pi-subagents-v6.16.0`.
+
+### Observations
+
+#### What went well
+
+- The plan correctly anticipated that TDD steps 4 (remove tracker stats) and 5 (migrate UI consumers) would be type-coupled and need merging.
+  This played out exactly as predicted — no surprise rework.
+- Step 2's grep sweep during `execution?.` migration found two callsites (`agent-tool.ts:315`, `agent-manager.ts:353`) that the plan's file list missed.
+  Systematic grep at migration time caught them before commit.
+
+#### What caused friction (agent side)
+
+- `instruction-violation` — Did not load the `colgrep` skill during the planning phase despite two explicit instructions: AGENTS.md ("Use `colgrep` for intent-based codebase exploration") and the `/plan-issue` prompt ("load the `code-design` skill and the `colgrep` skill for convention discovery").
+  Loaded 4 other skills but skipped colgrep.
+  User-caught ("I noticed you didn't load or use `colgrep`").
+  Impact: one extra round-trip with the user; no rework since the plan hadn't been committed yet.
+  The colgrep searches proved useful once run — highest-scoring hit for "dependency bag converted to plain constructor parameters" was `notification.ts`, directly confirming the target.
+- `wrong-abstraction` — When editing `src/ui/ui-observer.ts` to remove the `message_end` accumulation block, the replacement text closed the `session.subscribe(...)` callback but also added the function's closing brace, producing a duplicate `}`.
+  Autoformat caught the parse error immediately.
+  Impact: one follow-up edit, no downstream rework.
+
+#### What caused friction (user side)
+
+- None observed.
+  The user's intervention on colgrep was timely — caught before plan commit, not after.

package/docs/retro/0145-decompose-execute-push-ctx-to-boundary.md

@@ -0,0 +1,56 @@
+---
+issue: 145
+issue_title: "Decompose execute and push ExtensionContext to the boundary (Phase 9, Step M)"
+---
+
+# Retro: #145 — Decompose execute and push ExtensionContext to the boundary
+
+## Final Retrospective (2026-05-23)
+
+### Session summary
+
+Extracted config resolution into a pure `resolveSpawnConfig` function, injected three collaborators (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) into `createAgentTool` to eliminate `ctx` reads from `execute`, pushed `ParentSnapshot` to `AgentManager`'s public API, and dissolved three small dependency bags (`ForegroundDeps`, `BackgroundDeps`, `AdapterDeps`) into plain parameters.
+Released as `pi-subagents-v6.15.0`.
+
+### Observations
+
+#### What went well
+
+- User's two escalating questions ("Are there any other missing collaborators?"
+  → "Hiding dependencies in an object bag still counts as dependencies!") caught a `premature-convergence` before it landed as committed code.
+  The reverted partial step 3 attempt was ~4 files of changes that would have needed rework.
+  The resulting design (injected collaborators) is meaningfully better than the original plan's mechanical relocation.
+- Folding tightly-coupled TDD steps (ctx elimination + params shrinking + deps dissolution) into fewer commits avoided intermediate states with broken types.
+  The plan's 12-step sequence would have required lift-and-shift gymnastics; the actual 7-commit sequence was cleaner.
+
+#### What caused friction (agent side)
+
+- `premature-convergence` — the original plan relocated `buildParentSnapshot` calls to `execute` without questioning whether `execute` should read `ctx` at all.
+  The existing `code-design` skill has DIP and parameter-relay rules that should have flagged this.
+  The `service-adapter.ts` module already demonstrated the getter-injection pattern (`getCtx`, `getModelRegistry`), but I didn't search for it during plan writing.
+  Impact: one plan rewrite commit (76bb57b), one reverted partial implementation (~15 minutes of rework).
+  User-caught.
+
+- `missing-context` — didn't use `colgrep` during initial plan writing to discover the established getter-injection convention in `service-adapter.ts`.
+  Used `grep` exclusively for exact symbol matching.
+  When prompted by the user to use `colgrep`, the results were confirmatory rather than revelatory because I'd already read the relevant files by that point.
+  The miss was not using it *earlier* for intent-based exploration ("how do existing modules inject session-scoped state?").
+  Impact: added friction but no rework — the user's questions surfaced the pattern before code was committed.
+  User-caught.
+
+- `instruction-violation` — wrote an inline `import()` type assertion (`session.ctx as import("@earendil-works/pi-coding-agent").ExtensionContext`) in `service-adapter.ts`.
+  AGENTS.md says "Use standard top-level imports only."
+  Impact: one extra edit round, caught before committing.
+  User-caught.
+
+#### What caused friction (user side)
+
+- The user's redirecting questions were well-timed and effective.
+  The escalation from "Are there any other missing collaborators?"
+  to the more pointed "Hiding dependencies in an object bag still counts as dependencies!"
+  was the right amount of pressure.
+  No friction observed on the user side.
+
+### Changes made
+
+1. `.pi/prompts/plan-issue.md` — added `colgrep` skill loading to the "Load skills" section for code-change plans, so convention discovery happens during exploration rather than after committing to a design.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.15.0",
+  "version": "6.16.1",
   "exports": {
     ".": "./src/service.ts"
   },

package/src/agent-manager.ts

@@ -350,7 +350,7 @@ export class AgentManager {
     signal?: AbortSignal,
   ): Promise<AgentRecord | undefined> {
     const record = this.agents.get(id);
-    const session = record?.execution?.session;
+    const session = record?.session;
     if (!session) return undefined;
 
     record.resetForResume(Date.now());
@@ -402,7 +402,7 @@ export class AgentManager {
 
   /** Dispose a record's session and remove it from the map. */
   private removeRecord(id: string, record: AgentRecord): void {
-    record.execution?.session?.dispose?.();
+    record.session?.dispose?.();
     this.agents.delete(id);
     this.pendingSteers.delete(id);
   }
@@ -480,7 +480,7 @@ export class AgentManager {
     // Clear queue
     this.queue = [];
     for (const record of this.agents.values()) {
-      record.execution?.session?.dispose();
+      record.session?.dispose();
     }
     this.agents.clear();
     // Prune any orphaned git worktrees (crash recovery)

package/src/agent-record.ts

@@ -12,6 +12,7 @@
  * after construction as lifecycle information becomes available.
  */
 
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import type { ExecutionState } from "./execution-state.js";
 import type { NotificationState } from "./notification-state.js";
 import type { AgentInvocation, SubagentType } from "./types.js";
@@ -85,6 +86,16 @@ export class AgentRecord {
 	worktreeState?: WorktreeState;
 	notification?: NotificationState;
 
+	/** The active agent session, or undefined before the session is created. */
+	get session(): AgentSession | undefined {
+		return this.execution?.session;
+	}
+
+	/** Path to the agent's session JSONL file, or undefined if not yet available. */
+	get outputFile(): string | undefined {
+		return this.execution?.outputFile;
+	}
+
 	constructor(init: AgentRecordInit) {
 		this.id = init.id;
 		this.type = init.type;

package/src/index.ts

@@ -62,12 +62,12 @@ export default function (pi: ExtensionAPI) {
   // ---- Notification system ----
   // runtime.widget is assigned after AgentManager construction; arrow closures
   // capture `runtime` by reference so they always read the current value.
-  const notifications = new NotificationManager({
-    sendMessage: (msg, opts) => pi.sendMessage(msg, opts),
-    agentActivity: runtime.agentActivity,
-    markFinished: (id) => runtime.markFinished(id),
-    updateWidget: () => runtime.updateWidget(),
-  });
+  const notifications = new NotificationManager(
+    (msg, opts) => pi.sendMessage(msg, opts),
+    runtime.agentActivity,
+    (id) => runtime.markFinished(id),
+    () => runtime.updateWidget(),
+  );
 
   // Settings: owns all three in-memory values and handles load/save/emit.
   // onMaxConcurrentChanged is wired after manager is constructed (closure captures by reference).

package/src/notification.ts

@@ -46,7 +46,7 @@ export function formatTaskNotification(record: AgentRecord, resultMaxLen: number
   const status = getStatusLabel(record.status, record.error);
   const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
-  const contextPercent = getSessionContextPercent(record.execution?.session);
+  const contextPercent = getSessionContextPercent(record.session);
   const ctxXml = contextPercent !== null ? `<context_percent>${Math.round(contextPercent)}</context_percent>` : "";
   const compactXml = record.compactionCount ? `<compactions>${record.compactionCount}</compactions>` : "";
 
@@ -57,7 +57,7 @@ export function formatTaskNotification(record: AgentRecord, resultMaxLen: number
     : "No output.";
 
   const toolCallId = record.notification?.toolCallId;
-  const outputFile = record.execution?.outputFile;
+  const outputFile = record.outputFile;
   return [
     "<task-notification>",
     `<task-id>${record.id}</task-id>`,
@@ -90,7 +90,7 @@ export function buildNotificationDetails(
     maxTurns: activity?.maxTurns,
     totalTokens,
     durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
-    outputFile: record.execution?.outputFile,
+    outputFile: record.outputFile,
     error: record.error,
     resultPreview: record.result
       ? record.result.length > resultMaxLen
@@ -124,17 +124,6 @@ export function buildEventData(record: AgentRecord) {
 
 // ---- Notification system factory ----
 
-/** Narrow deps for the notification system — only the methods it actually calls. */
-export interface NotificationDeps {
-  sendMessage: (
-    msg: { customType: string; content: string; display: boolean; details?: unknown },
-    opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
-  ) => void;
-  agentActivity: Map<string, AgentActivityTracker>;
-  markFinished: (id: string) => void;
-  updateWidget: () => void;
-}
-
 export interface NotificationSystem {
   cancelNudge: (key: string) => void;
   sendCompletion: (record: AgentRecord) => void;
@@ -147,7 +136,15 @@ const NUDGE_HOLD_MS = 200;
 export class NotificationManager implements NotificationSystem {
   private pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
 
-  constructor(private deps: NotificationDeps) {}
+  constructor(
+    private sendMessage: (
+      msg: { customType: string; content: string; display: boolean; details?: unknown },
+      opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+    ) => void,
+    private agentActivity: Map<string, AgentActivityTracker>,
+    private markFinished: (id: string) => void,
+    private updateWidget: () => void,
+  ) {}
 
   cancelNudge(key: string): void {
     const timer = this.pendingNudges.get(key);
@@ -158,16 +155,16 @@ export class NotificationManager implements NotificationSystem {
   }
 
   sendCompletion(record: AgentRecord): void {
-    this.deps.agentActivity.delete(record.id);
-    this.deps.markFinished(record.id);
+    this.agentActivity.delete(record.id);
+    this.markFinished(record.id);
     this.scheduleNudge(record.id, () => this.emitIndividualNudge(record));
-    this.deps.updateWidget();
+    this.updateWidget();
   }
 
   cleanupCompleted(id: string): void {
-    this.deps.agentActivity.delete(id);
-    this.deps.markFinished(id);
-    this.deps.updateWidget();
+    this.agentActivity.delete(id);
+    this.markFinished(id);
+    this.updateWidget();
   }
 
   dispose(): void {
@@ -194,15 +191,15 @@ export class NotificationManager implements NotificationSystem {
     if (record.notification?.resultConsumed) return;
 
     const notification = formatTaskNotification(record, 500);
-    const outputFile = record.execution?.outputFile;
+    const outputFile = record.outputFile;
     const footer = outputFile ? `\nFull transcript available at: ${outputFile}` : "";
 
-    this.deps.sendMessage(
+    this.sendMessage(
       {
         customType: "subagent-notification",
         content: notification + footer,
         display: true,
-        details: buildNotificationDetails(record, 500, this.deps.agentActivity.get(record.id)),
+        details: buildNotificationDetails(record, 500, this.agentActivity.get(record.id)),
       },
       { deliverAs: "followUp", triggerTurn: true },
     );

package/src/service-adapter.ts

@@ -88,7 +88,7 @@ export function createSubagentsService(
       if (!record || record.status !== "running") {
         return false;
       }
-      const session = record.execution?.session;
+      const session = record.session;
       if (!session) {
         // Session not ready yet — queue via manager for delivery once initialized
         return manager.queueSteer(id, message);

package/src/tools/agent-tool.ts

@@ -312,7 +312,7 @@ Guidelines:
             `Agent not found: "${params.resume}". It may have been cleaned up.`,
           );
         }
-        if (!existing.execution?.session) {
+        if (!existing.session) {
           return textResult(
             `Agent "${params.resume}" has no active session to resume.`,
           );

package/src/tools/background-spawner.ts

@@ -79,7 +79,7 @@ export function spawnBackground(
       `Agent ID: ${id}\n` +
       `Type: ${config.displayName}\n` +
       `Description: ${config.description}\n` +
-      (record?.execution?.outputFile ? `Output file: ${record.execution.outputFile}\n` : "") +
+      (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
       (isQueued
         ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n`
         : "") +

package/src/tools/foreground-runner.ts

@@ -63,12 +63,14 @@ export async function runForeground(
 
   const fgState = new AgentActivityTracker(config.effectiveMaxTurns);
   let unsubUI: (() => void) | undefined;
+  let recordRef: AgentRecord | undefined;
 
   const streamUpdate = () => {
+    const toolUses = recordRef?.toolUses ?? 0;
     const details: AgentDetails = {
       ...config.detailBase,
-      toolUses: fgState.toolUses,
-      tokens: formatLifetimeTokens(fgState),
+      toolUses,
+      tokens: recordRef ? formatLifetimeTokens(recordRef) : "",
       turnCount: fgState.turnCount,
       maxTurns: fgState.maxTurns,
       durationMs: Date.now() - startedAt,
@@ -77,7 +79,7 @@ export async function runForeground(
       spinnerFrame: spinnerFrame % SPINNER.length,
     };
     onUpdate?.({
-      content: [{ type: "text", text: `${fgState.toolUses} tool uses...` }],
+      content: [{ type: "text", text: `${toolUses} tool uses...` }],
       details: details as any,
     });
   };
@@ -110,6 +112,7 @@ export async function runForeground(
         parentSessionId: params.parentSessionId,
         onSessionCreated: (session, record) => {
           fgState.setSession(session);
+          recordRef = record;
           unsubUI = subscribeUIObserver(session, fgState, streamUpdate);
           fgId = record.id;
           agentActivity.set(record.id, fgState);
@@ -132,7 +135,7 @@ export async function runForeground(
     widget.markFinished(fgId);
   }
 
-  const tokenText = formatLifetimeTokens(fgState);
+  const tokenText = formatLifetimeTokens(record);
   const details = buildDetails(config.detailBase, record, fgState, { tokens: tokenText });
 
   const fallbackNote = config.fellBack

package/src/tools/get-result-tool.ts

@@ -65,7 +65,7 @@ export function createGetResultTool(deps: GetResultDeps) {
       const displayName = getDisplayName(record.type, deps.registry);
       const duration = formatDuration(record.startedAt, record.completedAt);
       const tokens = formatLifetimeTokens(record);
-      const contextPercent = getSessionContextPercent(record.execution?.session);
+      const contextPercent = getSessionContextPercent(record.session);
       const statsParts = [`Tool uses: ${record.toolUses}`];
       if (tokens) statsParts.push(tokens);
       if (contextPercent !== null) statsParts.push(`Context: ${Math.round(contextPercent)}%`);
@@ -92,8 +92,8 @@ export function createGetResultTool(deps: GetResultDeps) {
       }
 
       // Verbose: include full conversation
-      if (params.verbose && record.execution?.session) {
-        const conversation = deps.getConversation(record.execution.session);
+      if (params.verbose && record.session) {
+        const conversation = deps.getConversation(record.session);
         if (conversation) {
           output += `\n\n--- Agent Conversation ---\n${conversation}`;
         }

package/src/tools/steer-tool.ts

@@ -49,7 +49,7 @@ export function createSteerTool(deps: SteerToolDeps) {
           `Agent "${params.agent_id}" is not running (status: ${record.status}). Cannot steer a non-running agent.`,
         );
       }
-      const session = record.execution?.session;
+      const session = record.session;
       if (!session) {
         // Session not ready yet — queue via manager for delivery once initialized
         deps.queueSteer(record.id, params.message);

package/src/ui/agent-activity-tracker.ts

@@ -5,24 +5,15 @@
  * in `ui-observer.ts`. Callers use named transition methods; readers use read-only accessors.
  */
 
-import { addUsage, type LifetimeUsage, type SessionLike } from "../usage.js";
-
-/** Usage delta accepted by onUsageUpdate — matches the LifetimeUsage accumulator shape. */
-export interface UsageDelta {
-	input: number;
-	output: number;
-	cacheWrite: number;
-}
+import type { SessionLike } from "../usage.js";
 
 /** Per-agent live activity state with explicit transition methods and read-only accessors. */
 export class AgentActivityTracker {
 	private _activeTools = new Map<string, string>();
 	private _toolKeySeq = 0;
-	private _toolUses = 0;
 	private _responseText = "";
 	private _session: SessionLike | undefined = undefined;
 	private _turnCount = 1;
-	private _lifetimeUsage: LifetimeUsage = { input: 0, output: 0, cacheWrite: 0 };
 
 	constructor(private readonly _maxTurns?: number) {}
 
@@ -33,12 +24,11 @@ export class AgentActivityTracker {
 		this._activeTools.set(toolName + "_" + (++this._toolKeySeq), toolName);
 	}
 
-	/** Record that a tool has finished executing; increments toolUses. No-op when no matching tool is active. */
-	onToolEnd(toolName: string): void {
+	/** Remove a tool from active tools (called when tool execution ends). No-op when no matching tool is active. */
+	onToolDone(toolName: string): void {
 		for (const [key, name] of this._activeTools) {
 			if (name === toolName) {
 				this._activeTools.delete(key);
-				this._toolUses++;
 				break;
 			}
 		}
@@ -59,11 +49,6 @@ export class AgentActivityTracker {
 		this._turnCount++;
 	}
 
-	/** Accumulate a usage delta into the lifetime usage totals. */
-	onUsageUpdate(delta: UsageDelta): void {
-		addUsage(this._lifetimeUsage, delta);
-	}
-
 	/** Bind the session reference (called once when the agent session is created). */
 	setSession(session: SessionLike): void {
 		this._session = session;
@@ -76,11 +61,6 @@ export class AgentActivityTracker {
 		return this._activeTools;
 	}
 
-	/** Total completed tool invocations. */
-	get toolUses(): number {
-		return this._toolUses;
-	}
-
 	/** The agent's latest partial response text (reset at each message start). */
 	get responseText(): string {
 		return this._responseText;
@@ -101,8 +81,4 @@ export class AgentActivityTracker {
 		return this._maxTurns;
 	}
 
-	/** Accumulated lifetime token usage (survives compaction). */
-	get lifetimeUsage(): Readonly<LifetimeUsage> {
-		return this._lifetimeUsage;
-	}
 }

package/src/ui/agent-menu.ts

@@ -207,7 +207,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
   }
 
   async function viewAgentConversation(ctx: ExtensionContext, record: AgentRecord) {
-    const session = record.execution?.session;
+    const session = record.session;
     if (!session) {
       ctx.ui.notify(
         `Agent is ${record.status === "queued" ? "queued" : "expired"} — no session available.`,