@gotgenes/pi-subagents 7.3.2 → 7.5.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [7.5.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.4.0...pi-subagents-v7.5.0) (2026-05-26)
+
+
+### Features
+
+* add permission bridge for cross-extension registration ([#101](https://github.com/gotgenes/pi-packages/issues/101)) ([1827720](https://github.com/gotgenes/pi-packages/commit/18277203f7ee10e56f90a0d4db587a4aa95376ab))
+* register child sessions with permission system ([#101](https://github.com/gotgenes/pi-packages/issues/101)) ([0487828](https://github.com/gotgenes/pi-packages/commit/04878286d7da6660362360482fb916b1b3743ce3))
+
+
+### Bug Fixes
+
+* resolve pre-existing lint errors in pi-autoformat and pi-permission-system ([68fd516](https://github.com/gotgenes/pi-packages/commit/68fd516e33ddbb9a5e37ef19e949ee9ecdc37252))
+
+
+### Documentation
+
+* document permission-bridge in architecture ([#101](https://github.com/gotgenes/pi-packages/issues/101)) ([d0120ab](https://github.com/gotgenes/pi-packages/commit/d0120abdf049e2aeba14ba75071ed55b24e23dbe))
+* update subagent integration docs for native permission bridge ([#101](https://github.com/gotgenes/pi-packages/issues/101)) ([0bd456b](https://github.com/gotgenes/pi-packages/commit/0bd456befa8ea6918e74f4393d844868795edc77))
+
+## [7.4.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.3.2...pi-subagents-v7.4.0) (2026-05-25)
+
+
+### Features
+
+* add model attribution to formatAssistantMessage ([76f2ada](https://github.com/gotgenes/pi-packages/commit/76f2adaa6bad9d1a3b15a3ba208b3ab96e07ecd1))
+* add model attribution to getAgentConversation ([c186c37](https://github.com/gotgenes/pi-packages/commit/c186c370b975e5ef6596d9a3d7719c720a580640))
+
+
+### Documentation
+
+* **retro:** add retro notes for issue [#214](https://github.com/gotgenes/pi-packages/issues/214) ([7e39c96](https://github.com/gotgenes/pi-packages/commit/7e39c96563517661c1c8c7f250402115b232a097))
+
 ## [7.3.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.3.1...pi-subagents-v7.3.2) (2026-05-25)
 
 

package/README.md

@@ -421,27 +421,57 @@ disallowed_tools: write, edit
 
 This is useful for creating agents that inherit extension tools but should not have write access.
 
+## Permission System Integration
+
+When [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permission-system) is installed, this extension integrates automatically:
+
+- **Per-agent permission policies** — define `permission:` in agent YAML frontmatter to set allow/ask/deny rules per agent type.
+  The permission system resolves the agent name from the `<active_agent>` tag in the child system prompt.
+- **Tool filtering** — the permission system's `before_agent_start` handler removes denied tools from the child session before the agent starts.
+- **`ask`-state forwarding** — when a child session triggers an `ask` permission, the prompt forwards to the parent session's UI.
+  The parent approves or denies, and the child resumes.
+- **Deterministic child detection** — every child session registers with the permission system's `SubagentSessionRegistry` before `bindExtensions()` fires, so detection does not rely on env vars or filesystem heuristics.
+
+No configuration is required.
+When `@gotgenes/pi-permission-system` is not installed, the registration calls are silent no-ops.
+
 ## Architecture
 
+See `docs/architecture/architecture.md` for the full architecture document with domain decomposition, Mermaid diagrams, and improvement roadmap.
+
 ```text
 src/
-  index.ts            # Extension entry: tool/command registration, rendering
-  types.ts            # Type definitions (AgentConfig, AgentRecord, etc.)
-  default-agents.ts   # Embedded default agent configs (general-purpose, Explore, Plan)
-  agent-types.ts      # Unified agent registry (defaults + user), tool name resolution
-  agent-runner.ts     # Session creation, execution, graceful max_turns, steer/resume
-  agent-manager.ts    # Agent lifecycle, concurrency queue, completion notifications
-  custom-agents.ts    # Load user-defined agents from .pi/agents/*.md
-  memory.ts           # Persistent agent memory (resolve, read, build prompt blocks)
-  skill-loader.ts     # Preload skills (Pi-standard + Agent Skills spec layouts)
-  output-file.ts      # Streaming output file transcripts for agent sessions
-  worktree.ts         # Git worktree isolation (create, cleanup, prune)
-  prompts.ts          # Config-driven system prompt builder
-  context.ts          # Parent conversation context for inherit_context
-  env.ts              # Environment detection (git, platform)
-  ui/
-    agent-widget.ts       # Persistent widget: spinners, activity, status icons, theming
-    conversation-viewer.ts # Live conversation overlay for viewing agent sessions
+  index.ts                          # Extension entry: tool/command registration, rendering
+  runtime.ts                        # Session-scoped state bag with methods
+  types.ts                          # Shared type definitions
+  settings.ts                       # Persistent settings (concurrency, turn limits)
+  config/                           # Agent type registry and configuration
+    agent-types.ts                  # Unified agent registry (defaults + custom)
+    default-agents.ts               # Embedded default agent configs
+    custom-agents.ts                # Load user-defined agents from .pi/agents/*.md
+    invocation-config.ts            # Per-call merge of tool params + agent config
+  session/                          # Pure session assembly
+    session-config.ts               # Session configuration assembler
+    prompts.ts                      # Config-driven system prompt builder
+    context.ts                      # Parent conversation context for inherit_context
+    skill-loader.ts                 # Preload skills from Pi-standard + Agent Skills spec
+    env.ts                          # Environment detection (git, platform)
+    model-resolver.ts               # Fuzzy model matching
+  lifecycle/                        # Agent execution and state tracking
+    agent-manager.ts                # Spawn, queue, abort, resume, concurrency
+    agent-runner.ts                 # Session creation, turn loop, tool filtering
+    agent-record.ts                 # Status state machine
+    parent-snapshot.ts              # Immutable spawn-time parent state
+    permission-bridge.ts            # Optional bridge to pi-permission-system registry
+    worktree.ts                     # Git worktree isolation
+  observation/                      # Progress tracking and notification
+    record-observer.ts              # Session-event stats observer
+    notification.ts                 # Completion nudges
+  service/                          # Cross-extension API boundary
+    service.ts                      # SubagentsService interface + Symbol.for() accessors
+    service-adapter.ts              # SubagentsService wrapper around AgentManager
+  tools/                            # LLM-facing tools
+  ui/                               # Widget, conversation viewer, /agents menu
 ```
 
 ## Deviations from upstream
@@ -458,6 +488,9 @@ Each has a corresponding upstream PR:
 3. **`<active_agent>` system-prompt tag** (`src/prompts.ts`) — `buildAgentPrompt` prepends `<active_agent name="${config.name}"/>` to every assembled child system prompt (both `replace` and `append` modes).
    Downstream extensions like [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permission-system) parse this tag to resolve per-agent `permission:` frontmatter inside the child session.
    Upstream PR: [tintinweb/pi-subagents#73](https://github.com/tintinweb/pi-subagents/pull/73).
+4. **Permission-system registration** (`src/lifecycle/permission-bridge.ts`) — `runAgent` registers every child session with `@gotgenes/pi-permission-system`'s `SubagentSessionRegistry` before `bindExtensions()` and unregisters in the `finally` block.
+   This enables deterministic child detection and `ask`-state forwarding to the parent UI.
+   No upstream equivalent — this feature is specific to the `@gotgenes` fork.
 
 The upstream `vitest` suite plus tests added for each patch all pass on every commit.
 

package/docs/architecture/architecture.md

@@ -259,6 +259,7 @@ src/
 │   ├── agent-record.ts             status state machine
 │   ├── parent-snapshot.ts          immutable spawn-time parent state
 │   ├── execution-state.ts          session/output phase state
+│   ├── permission-bridge.ts        optional bridge to pi-permission-system registry
 │   ├── worktree.ts                 git worktree isolation
 │   ├── worktree-state.ts           worktree phase state
 │   └── usage.ts                    token usage tracking
@@ -333,7 +334,8 @@ They declare this package as an optional peer dependency and use dynamic import
 
 - The three tools: `Agent`, `get_subagent_result`, `steer_subagent`.
 - `AgentManager` — spawn, queue, abort, resume, concurrency control.
-- `agent-runner` — session creation, turn loop, tool filtering, extension binding (Patches 2 and 3).
+- `agent-runner` — session creation, turn loop, tool filtering, extension binding (Patches 2 and 3), permission-system registration.
+- `permission-bridge` — optional cross-extension bridge to `@gotgenes/pi-permission-system`; registers each child session with `SubagentSessionRegistry` before `bindExtensions()` so the permission system detects in-process children deterministically.
 - `session-config` — pure configuration assembler (extracted from `agent-runner`).
 - `SubagentRuntime` — session-scoped state bag with methods.
 - `ParentSnapshot` — immutable snapshot of parent session state, captured once at spawn time.

package/docs/retro/0214-convert-remaining-closure-factories-to-classes.md

@@ -38,3 +38,29 @@ Test count held at 913 (57 files) — no new tests needed, no tests removed.
 - Adding the `SpawnOptions` import to `service-adapter.ts` was required for the `spawn` method signature; the plan anticipated this correctly.
 - The `sed -i` command required the macOS `-i ''` form (no in-place backup extension) rather than the GNU `sed -i` form.
 - Dead-code gate (`pnpm fallow dead-code`) passed cleanly from the repo root — no suppression needed.
+
+## Stage: Final Retrospective (2026-05-25T22:00:00Z)
+
+### Session summary
+
+Shipped `pi-subagents-v7.3.2` with 3 refactor commits converting all remaining closure factories to classes.
+All 4 lifecycle stages (plan → TDD → ship → retro) completed in a single day with zero rework and zero deviations from the plan.
+
+### Observations
+
+#### What went well
+
+- Strong precedent from Phase 11 (#195, #196) made this issue zero-friction — the plan, implementation, and test updates all followed an established template.
+- The plan's prediction of a `makeWizard(deps)` helper for `agent-creation-wizard.test.ts` kept the step-2 diff readable by centralizing 14 inline constructor calls.
+- `SubagentsServiceAdapter implements SubagentsService` gave compile-time contract verification, catching any interface drift immediately via `pnpm run check`.
+- The plan correctly anticipated the `SpawnOptions` import need in `service-adapter.ts`.
+
+#### What caused friction (agent side)
+
+- None.
+  This was a textbook mechanical refactoring with no behavioral changes, no edge cases, and no test rework.
+
+#### What caused friction (user side)
+
+- None.
+  The issue was well-scoped with explicit target files and a clear precedent to follow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "7.3.2",
+  "version": "7.5.0",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/lifecycle/agent-runner.ts

@@ -11,6 +11,7 @@ import {
 import type { AgentConfigLookup } from "#src/config/agent-types";
 import type { ParentSessionInfo } from "#src/lifecycle/agent-manager";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import { registerChildSession, unregisterChildSession } from "#src/lifecycle/permission-bridge";
 import { extractAssistantContent } from "#src/session/content-items";
 import { extractText } from "#src/session/context";
 import type { EnvInfo } from "#src/session/env";
@@ -347,6 +348,15 @@ export async function runAgent(
     session.setActiveToolsByName(filtered);
   }
 
+  // Register with pi-permission-system's SubagentSessionRegistry before
+  // bindExtensions() so isSubagentExecutionContext() hits the registry on the
+  // first check during child extension initialization. Unregistered in the
+  // finally block below to guarantee cleanup on both success and error paths.
+  registerChildSession(sessionDir, {
+    agentName: type,
+    parentSessionId: options.context.parentSession?.parentSessionId,
+  });
+
   // Bind extensions so that session_start fires and extensions can initialize
   // (e.g. loading credentials, setting up state). Placed after tool filtering
   // so extension-provided skills/prompts from extendResourcesFromExtensions()
@@ -406,6 +416,7 @@ export async function runAgent(
     unsubTurns();
     collector.unsubscribe();
     cleanupAbort();
+    unregisterChildSession(sessionDir);
   }
 
   const responseText =
@@ -455,8 +466,9 @@ export function getAgentConversation(session: AgentSession): string {
       if (text.trim()) parts.push(`[User]: ${text.trim()}`);
     } else if (msg.role === "assistant") {
       const { textParts, toolNames } = extractAssistantContent(msg.content);
+      const attribution = formatAttribution(msg);
       if (textParts.length > 0)
-        parts.push(`[Assistant]: ${textParts.join("\n")}`);
+        parts.push(`[Assistant${attribution}]: ${textParts.join("\n")}`);
       if (toolNames.length > 0)
         parts.push(`[Tool Calls]:\n${toolNames.map((n) => `  Tool: ${n}`).join("\n")}`);
     } else if (msg.role === "toolResult") {
@@ -468,3 +480,11 @@ export function getAgentConversation(session: AgentSession): string {
 
   return parts.join("\n\n");
 }
+
+/** Build a `(provider/model)` attribution suffix for assistant messages. */
+function formatAttribution(msg: { provider?: string; model?: string }): string {
+  const { provider, model } = msg;
+  if (!provider && !model) return "";
+  if (provider && model) return ` (${provider}/${model})`;
+  return ` (${provider ?? model})`;
+}

package/src/lifecycle/permission-bridge.ts

@@ -0,0 +1,63 @@
+/**
+ * permission-bridge.ts — Cross-extension bridge to @gotgenes/pi-permission-system.
+ *
+ * pi-subagents does not import pi-permission-system directly. Instead it
+ * accesses the published PermissionsService via a process-global Symbol.for()
+ * key, the same mechanism pi-permission-system uses to publish itself.
+ *
+ * When pi-permission-system is not installed, getPermissionsService() returns
+ * undefined and all registration calls are silent no-ops.
+ */
+
+/**
+ * The two PermissionsService methods pi-subagents needs.
+ *
+ * Follows ISP — does not expose the full PermissionsService surface
+ * (checkPermission, getToolPermission, etc.) to avoid coupling.
+ */
+interface PermissionsServiceConsumer {
+	registerSubagentSession(
+		sessionKey: string,
+		info: { parentSessionId?: string; agentName: string },
+	): void;
+	unregisterSubagentSession(sessionKey: string): void;
+}
+
+const PERMISSION_SERVICE_KEY = Symbol.for(
+	"@gotgenes/pi-permission-system:service",
+);
+
+function getPermissionsService(): PermissionsServiceConsumer | undefined {
+	return (globalThis as Record<symbol, unknown>)[
+		PERMISSION_SERVICE_KEY
+	] as PermissionsServiceConsumer | undefined;
+}
+
+/**
+ * Register a child session with pi-permission-system's SubagentSessionRegistry.
+ *
+ * Must be called after deriving sessionDir but before session.bindExtensions()
+ * so isSubagentExecutionContext() hits the registry on the first check during
+ * child extension initialization.
+ *
+ * @param sessionKey - The session directory path (unique per session).
+ * @param info       - Agent name and optional parent session ID for forwarding.
+ */
+export function registerChildSession(
+	sessionKey: string,
+	info: { parentSessionId?: string; agentName: string },
+): void {
+	getPermissionsService()?.registerSubagentSession(sessionKey, info);
+}
+
+/**
+ * Unregister a child session from pi-permission-system's SubagentSessionRegistry.
+ *
+ * Must be called in a finally block so cleanup happens on both success and
+ * error paths.
+ *
+ * @param sessionKey - The session directory path used during registration.
+ */
+export function unregisterChildSession(sessionKey: string): void {
+	getPermissionsService()?.unregisterSubagentSession(sessionKey);
+}

package/src/ui/agent-menu.ts

@@ -72,9 +72,9 @@ export class AgentsMenuHandler {
     private readonly registry: AgentTypeRegistry,
     private readonly agentActivity: AgentActivityReader,
     private readonly settings: AgentMenuSettings,
-    private readonly fileOps: AgentFileOps,
-    private readonly personalAgentsDir: string,
-    private readonly projectAgentsDir: string,
+    fileOps: AgentFileOps,
+    personalAgentsDir: string,
+    projectAgentsDir: string,
   ) {
     this.editor = new AgentConfigEditor(
       fileOps,

package/src/ui/message-formatters.ts

@@ -116,20 +116,31 @@ export function formatToolResult(
   ];
 }
 
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+/** Model/provider attribution for assistant messages. */
+export interface MessageAttribution {
+  provider?: string;
+  model?: string;
+}
+
 // ── formatAssistantMessage ───────────────────────────────────────────────────
 
 /**
  * Format an assistant message into display lines.
  * Always returns at least the [Assistant] header line.
+ * When attribution is provided, renders as `[Assistant (provider/model)]`.
  */
 export function formatAssistantMessage(
   content: { type: string; [key: string]: unknown }[],
   width: number,
   ctx: FormatterContext,
+  attribution?: MessageAttribution,
 ): string[] {
   const { theme, wrapText } = ctx;
   const { textParts, toolNames } = extractAssistantContent(content);
-  const lines: string[] = [theme.bold("[Assistant]")];
+  const label = formatAttributionLabel(attribution);
+  const lines: string[] = [theme.bold(`[Assistant${label}]`)];
   if (textParts.length > 0) {
     lines.push(...wrapText(textParts.join("\n").trim(), width));
   }
@@ -154,10 +165,15 @@ export function formatMessage(
     return formatUserMessage(msg.content as string | unknown[], width, ctx);
   }
   if (msg.role === "assistant") {
+    const attribution: MessageAttribution = {
+      provider: msg.provider as string | undefined,
+      model: msg.model as string | undefined,
+    };
     return formatAssistantMessage(
       msg.content as { type: string; [key: string]: unknown }[],
       width,
       ctx,
+      attribution,
     );
   }
   if (msg.role === "toolResult") {
@@ -168,3 +184,12 @@ export function formatMessage(
   }
   return null;
 }
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Build a `(provider/model)` attribution suffix, or empty string when absent. */
+function formatAttributionLabel(attr?: MessageAttribution): string {
+  if (!attr?.provider && !attr?.model) return "";
+  if (attr.provider && attr.model) return ` (${attr.provider}/${attr.model})`;
+  return ` (${attr.provider ?? attr.model})`;
+}