@komarspn/pi-permission-system 16.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MasuRii and Christopher D. Lasher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+<p align="center">
+  <img src="docs/assets/logo.png" alt="pi-permission-system logo">
+</p>
+
+# @gotgenes/pi-permission-system
+
+[![npm version](https://img.shields.io/npm/v/@gotgenes/pi-permission-system?style=flat&logo=npm&logoColor=white)](https://www.npmjs.com/package/@gotgenes/pi-permission-system) [![CI](https://img.shields.io/github/actions/workflow/status/gotgenes/pi-packages/ci.yml?style=flat&logo=github&label=CI)](https://github.com/gotgenes/pi-packages/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-6.x-3178C6?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![pnpm](https://img.shields.io/badge/pnpm-%3E%3D11-F69220?style=flat&logo=pnpm&logoColor=white)](https://pnpm.io/) [![Pi Package](https://img.shields.io/badge/Pi-Package-6366F1?style=flat)](https://pi.mariozechner.at/)
+
+Permission enforcement extension for the [Pi](https://pi.mariozechner.at/) coding agent that provides centralized, deterministic permission gates over tool, bash, MCP, skill, and special operations.
+
+> **Fork notice:** This package is a full fork of [MasuRii/pi-permission-system](https://github.com/MasuRii/pi-permission-system), published to npm as `@gotgenes/pi-permission-system`.
+> It has diverged substantially from upstream in config format, internal architecture, and permission model.
+
+## What It Does
+
+- **Hides disallowed tools** before the agent starts — no wasted turns probing for blocked tools
+- **Enforces allow / ask / deny** at tool-call time with UI confirmation dialogs
+- **Controls bash commands** with wildcard pattern matching (`git *: ask`, `rm -rf *: deny`)
+- **Gates MCP and skill access** at server, tool, and skill-name granularity
+- **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once
+- **Guards external paths** — prompts before file tools or bash commands reach outside `cwd`
+- **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry), and an unparseable bash command prompts (`ask`) rather than passing silently
+- **Forwards prompts from subagents** — `ask` policies work even in non-UI execution contexts
+- **Broadcasts UI prompt events** — `permissions:ui_prompt` fires only when the permission system is about to invoke the active user-facing permission UI
+- **Native [`@gotgenes/pi-subagents`](https://github.com/gotgenes/pi-subagents) integration** — in-process child sessions register with the permission system automatically, enabling per-agent policy enforcement and `ask`-state forwarding to the parent UI without configuration
+
+## Install
+
+```bash
+pi install npm:@gotgenes/pi-permission-system
+```
+
+## Quick Start
+
+1. Create the global config file at `~/.pi/agent/extensions/pi-permission-system/config.json`:
+
+    ```jsonc
+    {
+      "permission": {
+        "*": "allow",
+        "path": {
+          "*": "allow",
+          "*.env": "deny",
+          "*.env.*": "deny",
+          "*.env.example": "allow"
+        },
+        "bash": {
+          "*": "ask",
+          "rm -rf *": "deny",
+          "sudo *": "ask"
+        },
+        "external_directory": "ask"
+      }
+    }
+    ```
+
+2. Start Pi — the extension automatically loads and enforces your policy.
+
+All permissions use one of three states:
+
+| State   | Behavior                                 |
+| ------- | ---------------------------------------- |
+| `allow` | Permits the action silently              |
+| `deny`  | Blocks the action with an error message  |
+| `ask`   | Prompts the user for confirmation via UI |
+
+When the dialog prompts, you can approve once or approve a pattern for the rest of the session.
+See [docs/session-approvals.md](docs/session-approvals.md) for details on session-scoped rules and pattern suggestions.
+
+The `path` surface is a cross-cutting gate that applies to **all** file access — Pi tools, bash commands, MCP calls, and extension tools alike.
+Extension and MCP tools that operate on paths (via `input.path`, MCP's `input.arguments.path`, or a registered access extractor) are gated by default, so a `path` deny cannot be overridden by a per-tool allow — making it the right place to protect sensitive files like `.env` or `~/.ssh/*` from every tool at once.
+
+For per-tool path patterns (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns are matched against the file path from `input.path`.
+This lets you express rules like "allow reads but deny `.env` files" at the individual tool level.
+When Pi's current working directory is known, relative path inputs also match their cwd-normalized absolute form, so `src/App.jsx` can match both `src/*` and `/workspace/project/*`.
+
+The `external_directory` surface is the CWD-boundary gate: it decides whether reaching **outside** the working tree is allowed, and accepts a pattern map so you can allow specific outside-CWD directories without opening up all external access.
+This is the right surface for silencing repeated prompts on a local cache like `~/.cargo/registry` — allow it here, not on `path`:
+
+```jsonc
+{
+  "permission": {
+    "external_directory": {
+      "*": "ask",
+      "~/.cargo/registry/*": "allow"
+    }
+  }
+}
+```
+
+The trailing `*` is greedy and crosses subdirectory boundaries, so it allows every file beneath the directory; a bare `~/.cargo/registry` matches only the directory entry itself.
+
+Four layers compose with most-restrictive-wins: `path` (cross-cutting) → `external_directory` (CWD boundary) → per-tool patterns → `bash` command patterns.
+Because `ask` is more restrictive than `allow`, a `path` allow cannot loosen an `external_directory: ask` boundary — allow outside-CWD directories on `external_directory`.
+See [docs/configuration.md](docs/configuration.md) for the full recipe.
+
+## Configuration
+
+Config lives in one JSON file per scope:
+
+| Scope   | Path                                                      |
+| ------- | --------------------------------------------------------- |
+| Global  | `~/.pi/agent/extensions/pi-permission-system/config.json` |
+| Project | `<cwd>/.pi/extensions/pi-permission-system/config.json`   |
+
+Project overrides global; per-agent YAML frontmatter overrides both.
+
+Within a surface map like `bash` or `mcp`, **last matching rule wins** — put broad catch-alls first and specific overrides after.
+
+For the full reference — all surfaces, runtime knobs, per-agent overrides, merge semantics, and common recipes — see [docs/configuration.md](docs/configuration.md).
+
+## Upgrading
+
+### 16.0.0 — the bash gate now fails closed
+
+The permission gate fails closed: an internal gate error blocks the tool (with a `gate_error` review-log entry) instead of running it ungated, and a non-empty bash command that cannot be parsed resolves to `ask` (sentinel `<unparseable-bash-command>`) rather than falling through to a permissive top-level `*`.
+Commands that previously slipped through silently on the error or empty-parse path now block or prompt.
+
+If you relied on the old permissive behavior for bash, set an explicit permissive bash policy — `"bash": { "*": "allow" }` — which also suppresses the new startup warning emitted when a top-level `"*": "allow"` leaves bash ungated.
+
+## Documentation
+
+| Document                                                                                                                       | Contents                                                                                |
+| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| [docs/configuration.md](docs/configuration.md)                                                                                 | Full policy reference, runtime knobs, per-agent overrides, recipes                      |
+| [docs/session-approvals.md](docs/session-approvals.md)                                                                         | Session-scoped rules, pattern suggestions, bash arity table                             |
+| [docs/cross-extension-api.md](docs/cross-extension-api.md)                                                                     | Cross-extension service accessor, event bus integration, prompt and decision broadcasts |
+| [docs/subagent-integration.md](docs/subagent-integration.md)                                                                   | Permission forwarding, coexistence with subagent extensions                             |
+| [docs/guides/permission-frontmatter-for-subagent-extensions.md](docs/guides/permission-frontmatter-for-subagent-extensions.md) | Convention guide for subagent extension authors                                         |
+| [docs/opencode-compatibility.md](docs/opencode-compatibility.md)                                                               | OpenCode compatibility — shared concepts, divergences, porting guide                    |
+| [docs/troubleshooting.md](docs/troubleshooting.md)                                                                             | Common issues, diagnostic logging, threat model                                         |
+| [docs/migration/legacy-to-flat.md](docs/migration/legacy-to-flat.md)                                                           | Migration from pre-v2 config layout                                                     |
+
+## Development
+
+```bash
+pnpm run check       # Type-check TypeScript (no emit)
+pnpm run lint        # Biome + ESLint + lint:md
+pnpm run lint:md     # rumdl on README and docs
+pnpm run test        # Run tests from ./test
+pnpm run test:watch  # Run tests in watch mode
+```
+
+### Pre-commit hooks
+
+This project uses [prek](https://prek.j178.dev/) to run Biome, ESLint, and rumdl on staged files before each commit.
+Run `pnpm install` to set up hooks automatically.
+
+## Acknowledgments
+
+This project began as a fork of [MasuRii/pi-permission-system](https://github.com/MasuRii/pi-permission-system).
+Thank you to [MasuRii](https://github.com/MasuRii) for the original work that made this possible.
+
+Thank you to the [OpenCode](https://opencode.ai) team for the permission model design that inspired the flat config format and evaluation semantics used in this extension.
+
+## License
+
+[MIT](LICENSE)

package/config/config.example.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-permission-system/main/schemas/permissions.schema.json",
+
+  "debugLog": false,
+  "permissionReviewLog": true,
+  "yoloMode": false,
+
+  "toolInputPreviewMaxLength": 400,
+  "toolTextSummaryMaxLength": 120,
+
+  "piInfrastructureReadPaths": [],
+
+  "permission": {
+    "*": "ask",
+    "path": {
+      "*": "allow",
+      "*.env": "deny",
+      "*.env.*": "deny",
+      "*.env.example": "allow"
+    },
+    "read": "allow",
+    "write": "deny",
+    "edit": "deny",
+    "bash": {
+      "*": "ask",
+      "git *": "ask",
+      "git status": "allow",
+      "git diff": "allow",
+      "npm *": { "action": "deny", "reason": "Use pnpm instead" }
+    },
+    "mcp": { "*": "ask", "mcp_status": "allow", "mcp_list": "allow" },
+    "skill": { "*": "ask" },
+    "external_directory": {
+      "*": "ask",
+      "~/development/*": "allow",
+      "~/.cargo/registry/*": "allow"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@komarspn/pi-permission-system",
+  "version": "16.0.2",
+  "description": "Permission enforcement extension for the Pi coding agent.",
+  "type": "module",
+  "exports": {
+    ".": "./src/service.ts"
+  },
+  "imports": {
+    "#src/*": "./src/*",
+    "#test/*": "./test/*"
+  },
+  "files": [
+    "src",
+    "test",
+    "config/config.example.json",
+    "schemas/permissions.schema.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "coding-agent",
+    "permissions",
+    "policy",
+    "access-control",
+    "authorization",
+    "security"
+  ],
+  "author": {
+    "name": "Chris Lasher"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/komarspn/pi-packages.git",
+    "directory": "packages/pi-permission-system"
+  },
+  "homepage": "https://github.com/komarspn/pi-packages/tree/main/packages/pi-permission-system#readme",
+  "bugs": {
+    "url": "https://github.com/komarspn/pi-packages/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.79.0",
+    "@earendil-works/pi-tui": ">=0.79.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.16",
+    "@earendil-works/pi-coding-agent": "0.79.1",
+    "@earendil-works/pi-tui": "0.79.1",
+    "@types/node": "^22.15.3",
+    "rumdl": "^0.2.10",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "dependencies": {
+    "tree-sitter-bash": "^0.25.1",
+    "web-tree-sitter": "^0.26.9"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint:md": "rumdl check *.md docs/**/*.md",
+    "lint": "biome check . && eslint . && pnpm run lint:md"
+  }
+}

package/schemas/permissions.schema.json

@@ -0,0 +1,158 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/gotgenes/pi-permission-system/main/schemas/permissions.schema.json",
+  "title": "PI Permission System Configuration",
+  "description": "Unified config file combining runtime knobs and flat permission policy for pi-permission-system.",
+  "markdownDescription": "Unified config file combining runtime knobs and flat permission policy for [pi-permission-system](https://github.com/gotgenes/pi-permission-system).\n\nPlace at `~/.pi/agent/extensions/pi-permission-system/config.json` (global) or `<project>/.pi/extensions/pi-permission-system/config.json` (project).",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "description": "JSON Schema URI for editor autocomplete and validation.",
+      "type": "string"
+    },
+    "debugLog": {
+      "description": "Write verbose permission-system diagnostics to the extension logs directory.",
+      "markdownDescription": "Write verbose permission-system diagnostics to `logs/pi-permission-system-debug.jsonl` under the extension config directory.",
+      "type": "boolean",
+      "default": false
+    },
+    "permissionReviewLog": {
+      "description": "Write permission request and decision audit events to the extension logs directory.",
+      "markdownDescription": "Write permission request and decision audit events to `logs/pi-permission-system-permission-review.jsonl` under the extension config directory.",
+      "type": "boolean",
+      "default": true
+    },
+    "yoloMode": {
+      "description": "Auto-approve ask-state permission checks, including subagent approval forwarding.",
+      "markdownDescription": "Auto-approve `ask`-state permission checks, including subagent approval forwarding.\n\n⚠️ **Use with caution** — this disables all interactive confirmation prompts.",
+      "type": "boolean",
+      "default": false
+    },
+    "toolInputPreviewMaxLength": {
+      "description": "Maximum character length of the inline-JSON tool-input preview shown in permission prompts. Omit to use the default (200). Set to a large value to disable truncation.",
+      "markdownDescription": "Maximum character length of the inline-JSON tool-input preview shown in permission prompts.\n\nOmit to use the default (200). Set to a large value (e.g. `10000`) to effectively disable truncation and see the full input.",
+      "type": "integer",
+      "minimum": 1
+    },
+    "toolTextSummaryMaxLength": {
+      "description": "Maximum character length of inline pattern/path summaries (e.g. grep patterns, find globs, ls paths) in permission prompts. Omit to use the default (80).",
+      "markdownDescription": "Maximum character length of inline pattern/path summaries (e.g. grep patterns, find globs, ls paths) shown in permission prompts.\n\nOmit to use the default (80). Increase this when working with long regexes or deep paths that are being cut off.",
+      "type": "integer",
+      "minimum": 1
+    },
+    "piInfrastructureReadPaths": {
+      "description": "Additional directories to auto-allow for reads as Pi infrastructure, bypassing the external_directory gate. Supports ~ expansion and wildcard patterns (* and ?).",
+      "markdownDescription": "Additional directories to auto-allow for reads as Pi infrastructure, bypassing the `external_directory` gate.\n\nThe extension auto-discovers the global node_modules root (walks up from the extension's install path; falls back to `npm root -g` from a dev checkout), Pi's own install directory (via the coding-agent `getPackageDir()` API), `agentDir`, `agentDir/git`, and project-local `.pi/npm/` and `.pi/git/`. Add entries here for edge cases where auto-discovery is insufficient (e.g. custom `npmCommand` pointing to pnpm).\n\nSupports `~`/`$HOME` expansion. Entries may be plain directory prefixes or wildcard patterns using `*` (matches any characters, including `/`) and `?` (matches exactly one character). `**` and `*` are equivalent — both cross directory boundaries.\n\nOn Windows, matching is case-insensitive and tolerant of either path separator.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "default": []
+    },
+    "permission": {
+      "description": "Flat permission policy. Each key is a surface name; values are a PermissionState string (catch-all) or a pattern→action map.",
+      "markdownDescription": "Flat permission policy.\n\nEach top-level key is a surface name:\n- `\"*\"` — universal fallback (replaces `defaultPolicy.tools` from the legacy format)\n- Tool names (`read`, `write`, `bash`, `mcp`, `skill`, `external_directory`, `path`, etc.)\n\nA **string** value is shorthand for `{ \"*\": action }` (surface-level catch-all).\nAn **object** value maps wildcard patterns to actions — last matching pattern wins.\n\nFor built-in file tools (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns are matched against the file path from `input.path`. For example, `\"read\": { \"*\": \"allow\", \"*.env\": \"deny\" }` allows reads but denies `.env` files.\n\nWhen Pi's current working directory is known, relative path inputs also match their cwd-normalized absolute form, so `src/App.jsx` can match both `src/*` and `/workspace/project/*`. Bash path tokens use the effective directory after literal `cd` commands for this matching; non-literal `cd \"$DIR\"` style commands remain conservative.\n\nThe `path` surface is a cross-cutting gate that applies to **all** file access: Pi tools, bash commands, MCP calls (via `input.arguments.path`), and extension tools (via `input.path` or a registered access extractor). A `path` deny cannot be overridden by a per-tool allow. Use it to protect sensitive files (`.env`, `~/.ssh/*`) from all path-aware tools at once.\n\nThe `external_directory` surface gates access **outside** the working directory. Give it a pattern map to allow specific outside-CWD directories without opening all external access — e.g. `\"external_directory\": { \"*\": \"ask\", \"~/.cargo/registry/*\": \"allow\" }` to silence repeated prompts on a local cache. The trailing `*` is greedy and crosses subdirectory boundaries; a bare `~/.cargo/registry` matches only the directory entry itself. Because layers compose with most-restrictive-wins, a `path` allow cannot loosen an `external_directory: ask` boundary — allow outside-CWD directories here, not on `path`.\n\n**Merge order (lowest → highest precedence):** global → project → per-agent frontmatter.",
+      "type": "object",
+      "propertyNames": {
+        "description": "A surface name or the universal fallback key '*'.",
+        "type": "string",
+        "minLength": 1
+      },
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "$ref": "#/$defs/permissionState",
+            "description": "Catch-all shorthand: equivalent to { \"*\": action }."
+          },
+          {
+            "$ref": "#/$defs/permissionMap",
+            "description": "Pattern→action map for this surface."
+          }
+        ]
+      },
+      "examples": [
+        {
+          "*": "ask",
+          "path": {
+            "*": "allow",
+            "*.env": "deny",
+            "*.env.*": "deny",
+            "*.env.example": "allow"
+          },
+          "read": "allow",
+          "write": "deny",
+          "edit": "deny",
+          "bash": {
+            "*": "ask",
+            "git *": "ask",
+            "git status": "allow",
+            "git diff": "allow"
+          },
+          "mcp": { "*": "ask", "mcp_status": "allow", "exa:*": "allow" },
+          "skill": { "*": "ask", "librarian": "allow" },
+          "external_directory": { "*": "ask", "~/.cargo/registry/*": "allow" }
+        }
+      ]
+    }
+  },
+  "$defs": {
+    "permissionState": {
+      "description": "A permission decision: allow (permit silently), deny (block with error), or ask (prompt the user for confirmation).",
+      "oneOf": [
+        {
+          "const": "allow",
+          "description": "Permit the action silently with no user interaction."
+        },
+        {
+          "const": "deny",
+          "description": "Block the action with an error message. The agent is told not to retry."
+        },
+        {
+          "const": "ask",
+          "description": "Prompt the user for confirmation via the interactive UI before proceeding."
+        }
+      ]
+    },
+    "permissionMap": {
+      "description": "A map of wildcard patterns to permission states. Last matching pattern wins.",
+      "markdownDescription": "A map of wildcard patterns to permission states.\n\nUse `*` for wildcard matching. When multiple patterns match, the **last matching rule wins** — put broad catch-alls first and specific overrides after them.\n\nPattern keys support home directory expansion:\n- `~/path` or `$HOME/path` — expanded to the OS home directory at match time.\n- `~` or `$HOME` alone — expands to the home directory itself.\n\nThe stored pattern is always shown in logs and approval dialogs as written (e.g. `~/dev/*`).",
+      "type": "object",
+      "propertyNames": {
+        "description": "A non-empty pattern string. Use * for wildcard matching. Prefix with ~/ or $HOME/ for home-relative paths.",
+        "type": "string",
+        "minLength": 1
+      },
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "$ref": "#/$defs/permissionState",
+            "description": "A permission decision for this pattern."
+          },
+          {
+            "$ref": "#/$defs/denyWithReason",
+            "description": "Deny this pattern with an optional custom reason."
+          }
+        ]
+      }
+    },
+    "denyWithReason": {
+      "type": "object",
+      "description": "Deny with an optional custom reason shown to the agent when the action is blocked.",
+      "properties": {
+        "action": {
+          "const": "deny",
+          "description": "The permission decision \u2014 must be \"deny\"."
+        },
+        "reason": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Optional reason shown to the agent when this action is denied."
+        }
+      },
+      "required": ["action"],
+      "additionalProperties": false
+    }
+  }
+}

package/src/active-agent.ts

@@ -0,0 +1,72 @@
+/**
+ * Minimal session-entry view: the only fields {@link getActiveAgentName}
+ * reads off each entry. Narrowing to this structural slice (rather than the
+ * SDK `SessionEntry` discriminated union) keeps callers and test fixtures free
+ * of the union's nine unrelated variants.
+ */
+export interface SessionEntryView {
+  type: string;
+  customType?: string;
+  data?: unknown;
+}
+
+/**
+ * Narrow context for {@link getActiveAgentName} — it reads only the session
+ * entries. A full `ExtensionContext` satisfies this structurally.
+ */
+export interface ActiveAgentContext {
+  sessionManager: { getEntries(): readonly SessionEntryView[] };
+}
+
+/**
+ * Matches the `<active_agent name="...">` tag injected by pi-agent-router
+ * into the system prompt to identify which agent definition is active.
+ */
+export const ACTIVE_AGENT_TAG_REGEX =
+  /<active_agent\s+name=["']([^"']+)["'][^>]*>/i;
+
+export function normalizeAgentName(value: unknown): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+export function getActiveAgentName(ctx: ActiveAgentContext): string | null {
+  const entries = ctx.sessionManager.getEntries();
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry.type !== "custom" || entry.customType !== "active_agent") {
+      continue;
+    }
+
+    const data = entry.data as { name?: unknown } | undefined;
+    const normalizedName = normalizeAgentName(data?.name);
+    if (normalizedName) {
+      return normalizedName;
+    }
+
+    if (data?.name === null) {
+      return null;
+    }
+  }
+
+  return null;
+}
+
+export function getActiveAgentNameFromSystemPrompt(
+  systemPrompt: string | undefined,
+): string | null {
+  if (!systemPrompt) {
+    return null;
+  }
+
+  const match = ACTIVE_AGENT_TAG_REGEX.exec(systemPrompt);
+  if (!match?.[1]) {
+    return null;
+  }
+
+  return normalizeAgentName(match[1]);
+}

package/src/async-cache.ts

@@ -0,0 +1,21 @@
+/**
+ * Memoize an async factory, but drop a rejected result so the next call
+ * retries.
+ *
+ * On success the resolved promise is cached and shared across all callers (the
+ * factory runs once). On failure the cache is cleared before the rejection is
+ * re-thrown, so a transient init failure does not poison the memo for the
+ * process lifetime — the next call re-invokes the factory.
+ */
+export function memoizeAsyncWithRetry<T>(
+  factory: () => Promise<T>,
+): () => Promise<T> {
+  let cached: Promise<T> | null = null;
+  return () => {
+    cached ??= factory().catch((error: unknown) => {
+      cached = null; // poisoned result cleared → next call re-attempts
+      throw error;
+    });
+    return cached;
+  };
+}