@gotgenes/pi-subagents 7.4.0 → 7.5.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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)
 
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "7.4.0",
+  "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 =

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,