@jopqior/pi-subagents 1.0.0

package/docs/comparison-with-upstream.md

@@ -0,0 +1,77 @@
+# Comparison with upstream
+
+`@gotgenes/pi-subagents` began as a fork of [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents) by [@tintinweb](https://github.com/tintinweb).
+The original design — autonomous subagent dispatch, the live widget, the conversation viewer, custom agent types — is the foundation everything here builds on.
+
+It has since become an independently maintained hard fork.
+It follows its own architecture, does not track upstream as a merge target, and cherry-picks upstream fixes only when they fit its scope.
+This document compares the fork against the current upstream release so you can choose between them.
+
+Versions compared: `@gotgenes/pi-subagents` 16.2.1 and `@tintinweb/pi-subagents` 0.10.3 (current at the time of writing).
+
+## At a glance
+
+| Aspect          | @gotgenes/pi-subagents          | @tintinweb/pi-subagents                 |
+| --------------- | ------------------------------- | --------------------------------------- |
+| Philosophy      | Minimal, composable core        | Batteries-included, all-in-one          |
+| Pi peer scope   | `@earendil-works/pi-*` (>=0.75) | `@earendil-works/pi-*` (>=0.74)         |
+| Spawn tool name | `subagent`                      | `Agent`                                 |
+| Runtime deps    | `@sinclair/typebox`             | `@sinclair/typebox`, `croner`, `nanoid` |
+| License         | MIT                             | MIT                                     |
+
+Both ship TypeScript source directly (Pi runs `./src/index.ts`) and target the same `@earendil-works/pi-*` Pi.
+The peer-dep migration that prompted the original fork has since landed upstream, so the Pi scope is no longer a differentiator.
+
+## Common ground
+
+Both extensions provide the same core experience:
+
+- Foreground/background subagents with a live above-editor widget and a conversation viewer.
+- Custom agent types defined in `.pi/agents/<name>.md` with YAML frontmatter (system prompt, model, thinking, tools).
+- Fuzzy model selection, context inheritance, mid-run steering, session resume, and graceful turn limits.
+- A `pi.events` lifecycle bus (`subagents:created`, `started`, `completed`, `failed`, `steered`, `compacted`).
+
+## What upstream has that this fork does not
+
+Upstream is the batteries-included option.
+It keeps several subsystems built in that this fork deliberately removed or delegated:
+
+| Capability              | @tintinweb/pi-subagents                           | @gotgenes/pi-subagents                                                                                                                            |
+| ----------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tool restrictions       | `disallowed_tools` frontmatter (denylist)         | Delegated — `permission:` via [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system) |
+| Worktree isolation      | Built-in                                          | Delegated — [`@gotgenes/pi-subagents-worktrees`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-subagents-worktrees)               |
+| Persistent agent memory | `memory:` frontmatter (project / local / user)    | Removed                                                                                                                                           |
+| Skill preloading        | `skills:` frontmatter (preload named skills)      | Removed — children always inherit the parent's skills                                                                                             |
+| Scheduling              | Cron / interval / one-shot subagents (`schedule`) | Removed                                                                                                                                           |
+| Cross-extension control | `subagents:rpc:*` event RPC                       | Replaced by a typed service (below)                                                                                                               |
+| Model-scope enforcement | `enabledModels` allowlist validation              | Not included                                                                                                                                      |
+| Notifications           | Smart group-join consolidation                    | Individual per-agent notifications                                                                                                                |
+
+## What this fork adds
+
+This fork is a minimal core that other extensions build on, plus a small companion ecosystem:
+
+- **Typed service API** — `SubagentsService` exposed via `Symbol.for()` accessors, so another extension can spawn and manage subagents without importing this package or relying on ad-hoc event RPC.
+- **Child-session lifecycle events** — `subagents:child:spawning` / `session-created` / `bound` / `completed` / `disposed`, with `session-created` firing synchronously before `bindExtensions()` so consumers can register the child session deterministically, and `bound` firing after it resolves so they can observe what the child's extensions installed.
+- **`<active_agent>` system-prompt tag** — lets [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system) resolve per-agent `permission:` frontmatter (allow / ask / deny — richer than a binary denylist) inside the child session.
+- **Companion packages** — permission policy and worktree isolation live in dedicated packages rather than the core.
+- **Re-architected codebase** — decomposed into seven domains behind a typed public API boundary, backed by ~994 tests.
+
+## Which should I use?
+
+**Use `@tintinweb/pi-subagents`** if you want a single, batteries-included extension with nothing else to install: built-in tool denylist, scheduled / cron subagents, cross-extension RPC, and model-scope enforcement in one package.
+It is the canonical upstream and the original.
+
+**Use `@gotgenes/pi-subagents`** if you want a minimal, composable core: richer allow / ask / deny permissions and worktree isolation through companion packages, a typed service plus lifecycle events to build your own extensions on, and an actively refactored codebase — and you do not need built-in scheduling, RPC, or model-scope enforcement.
+
+The spawn tool is named `subagent` here versus `Agent` upstream, so prompts and docs that hard-code the tool name are not drop-in portable between the two.
+
+## Patches contributed upstream
+
+Three of the fork's early changes were opened as PRs against upstream and remain a record of the shared lineage:
+
+1. Peer-dep migration to `@earendil-works/pi-*` — [tintinweb/pi-subagents#71](https://github.com/tintinweb/pi-subagents/pull/71) (upstream has since migrated).
+2. Post-`bindExtensions` active-tool re-filter — [tintinweb/pi-subagents#72](https://github.com/tintinweb/pi-subagents/pull/72).
+3. `<active_agent>` system-prompt tag — [tintinweb/pi-subagents#73](https://github.com/tintinweb/pi-subagents/pull/73).
+
+The fork has since diverged well beyond these.

package/docs/configuration.md

@@ -0,0 +1,364 @@
+# Configuration
+
+`@jopqior/pi-subagents` has two configuration surfaces: **agent definition files** that describe an agent type, and a **`subagents.json`** settings file that tunes the runtime.
+Neither is required — every field has a default.
+
+For the tools, commands, events, and service API, see the [README](../README.md).
+
+## Default Agent Types
+
+| Type              | Tools                      | Model                         | Prompt Mode            | Description                                                                                      |
+| ----------------- | -------------------------- | ----------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------ |
+| `general-purpose` | all 7                      | inherit                       | `append` (parent twin) | Inherits the parent's prompt identity — same rules, CLAUDE.md, project conventions               |
+| `Explore`         | read, bash, grep, find, ls | haiku (falls back to inherit) | `replace`              | Fast codebase exploration (read-only); inherits the parent prompt as a base                      |
+| `Plan`            | read, bash, grep, find, ls | inherit                       | `replace`              | Software architect for implementation planning (read-only); inherits the parent prompt as a base |
+
+The `general-purpose` agent is a **parent twin** — it receives the parent's inherited identity and nothing of its own, so it follows the same rules the parent does.
+Explore and Plan use `replace` mode: the parent prompt is the cacheable base and their specialist read-only instructions are appended last, giving them the final say.
+
+Default agents can be **overridden** by creating a `.md` file with the same name (e.g. `.pi/agents/general-purpose.md`), or **disabled** per-project with `enabled: false` frontmatter.
+
+## What a child inherits from the parent's prompt
+
+Pi assembles a system prompt in layers.
+Its own preamble and tool guidelines come first, then your `AGENTS.md` or `CLAUDE.md` project context, then the catalogue of available skills, then a `Current working directory:` footer — and finally whatever extensions append each turn.
+
+A child inherits only the **stable identity** layers: everything up to, but not including, the skills catalogue.
+The layers after it are resolved against one session, so Pi and the child's own extensions rebuild them for the child rather than the child borrowing the parent's:
+
+| Layer                              | Where a child's copy comes from                            |
+| ---------------------------------- | ---------------------------------------------------------- |
+| Pi preamble, project context       | inherited from the parent, byte for byte                   |
+| `Available tools:` / `Guidelines:` | stated by the child's own `@gotgenes/pi-permission-system` |
+| Skills catalogue                   | rebuilt by Pi for the child's own directory and tool set   |
+| `Current working directory:`       | rebuilt by Pi for the child's own directory                |
+| Extension-appended blocks          | rebuilt by the child's own extensions                      |
+
+This matters most for a child that runs somewhere other than the parent — one given an isolated workspace by a `WorkspaceProvider`.
+Its skills resolve from its own workspace, and its working-directory claim names that workspace.
+Inheriting the parent's copies instead would give such a child a catalogue of skills it may not have and a directory claim that walks it back out of its workspace.
+
+Inheriting the identity rather than the whole prompt also gives the child a leading prefix it shares with the parent, which local inference engines reuse instead of reprocessing.
+How much that is worth depends on the host: a provider whose cache prefix covers the tool definitions ahead of the system prompt — Anthropic's does — reuses nothing for a child, because a child's tool set always differs from its parent's.
+
+The tool sections are listed above as the child's own rather than inherited because `@gotgenes/pi-permission-system` relocates them to the end of the prompt, so each session states the tools it actually holds without editing the bytes a child inherits.
+Without that extension installed, a child inherits the parent's `Available tools:` listing unchanged, which names the parent's tools rather than the child's ([#901]).
+
+If you write extensions that add to the system prompt, see [Extensions that append to the system prompt](../README.md#extensions-that-append-to-the-system-prompt).
+The reasoning behind the boundary is recorded in [ADR 0006](decisions/0006-inherited-prompt-is-identity-only.md), and what the inherited region guarantees in [ADR 0008](decisions/0008-inherited-region-is-shared-parts.md).
+
+### Portable inheritance (opt-in)
+
+The inherited identity includes Pi's own preamble.
+That is correct when the child talks to the same API as its parent, and wrong when the child's provider **re-homes** the prompt into another harness — `pi-claude-bridge`, for example, projects it onto Claude Code's preset as an append.
+There, Pi's preamble reaches an API that already has a base prompt of its own, and Anthropic's subscription gate scores the documentation-routing line inside it as a third-party app ([#883]).
+
+Opt such a provider into `portable`, which replaces the inherited identity with the parent's operator-authored parts only:
+
+```json
+{
+  "promptInheritance": { "claude-bridge": "portable" }
+}
+```
+
+| Strategy         | The child's identity                                           | Shares a prefix with the parent |
+| ---------------- | -------------------------------------------------------------- | ------------------------------- |
+| `full` (default) | the parent's identity layers, byte for byte                    | yes                             |
+| `portable`       | the parent's custom prompt, append prompt, and project context | no                              |
+
+The map keys on the **provider id of the child's resolved model**, so only children whose requests actually travel through that provider change strategy.
+That is also why the key is the provider rather than the agent: a `subagent` call may override an agent's model, which moves the child to a different transport, and the strategy follows it.
+
+Skills stay un-inherited either way — the child builds its own catalogue — and the parent's tool guidelines are never inherited under `portable`, because Pi derives them from the tools a session actually holds.
+Project context files ride along, and must: the child's loader is built with context files suppressed, so this is the only way a portable child sees your `AGENTS.md` at all.
+
+**Use `portable` only for a provider that re-homes the prompt into a harness supplying its own base.**
+It is not enforced, because Pi exposes no way to identify such a provider — but pointing it at an ordinary provider is worse than leaving the default.
+`@gotgenes/pi-anthropic-auth`, for instance, finds Pi's role line in order to shape the OAuth system prompt; a portable child has no such line, so shaping returns it unchanged and the child never receives the neutral role prompt that shaping would have substituted.
+
+If the parent has no context files, custom prompt, or append prompt, a portable child falls back to a short generic base rather than to the full parent prompt — opting in never silently re-embeds the preamble it exists to avoid.
+
+The reasoning is recorded in [ADR 0009](decisions/0009-portable-inheritance-is-provider-scoped.md).
+
+[#883]: https://github.com/gotgenes/pi-packages/issues/883
+[#901]: https://github.com/gotgenes/pi-packages/issues/901
+
+## Custom Agents
+
+Define custom agent types by creating `.md` files.
+The filename becomes the agent type name.
+Any name is allowed — using a default agent's name overrides it.
+
+Agents are discovered from two locations (higher priority wins):
+
+| Priority    | Location                                                                         | Scope                         |
+| ----------- | -------------------------------------------------------------------------------- | ----------------------------- |
+| 1 (highest) | `.pi/agents/<name>.md`                                                           | Project — per-repo agents     |
+| 2           | `$PI_CODING_AGENT_DIR/agents/<name>.md` (default `~/.pi/agent/agents/<name>.md`) | Global — available everywhere |
+
+Project-level agents override global ones with the same name, so you can customize a global agent for a specific project.
+The global location follows the upstream `PI_CODING_AGENT_DIR` env var — set it to relocate all pi-coding-agent state (agents, skills, settings) to a custom directory.
+
+### Example: `.pi/agents/auditor.md`
+
+```markdown
+---
+description: Security Code Reviewer
+tools: read, grep, find, bash
+model: anthropic/claude-opus-4-6
+thinking: high
+max_turns: 30
+---
+
+You are a security auditor.
+Review code for vulnerabilities including:
+
+- Injection flaws (SQL, command, XSS)
+- Authentication and authorization issues
+- Sensitive data exposure
+- Insecure configurations
+
+Report findings with file paths, line numbers, severity, and remediation advice.
+```
+
+Then spawn it like any built-in type:
+
+```text
+subagent({ subagent_type: "auditor", prompt: "Review the auth module", description: "Security audit" })
+```
+
+### Frontmatter Fields
+
+All fields are optional — sensible defaults for everything.
+
+| Field               | Default        | Description                                                                                                                                                                                                                                   |
+| ------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `description`       | filename       | Agent description shown in tool listings                                                                                                                                                                                                      |
+| `display_name`      | —              | Display name for UI (e.g. widget, agent list)                                                                                                                                                                                                 |
+| `tools`             | all 7          | The agent's complete tool allowlist — built-in or extension-registered names. `none` for no tools. See [Tool selection](#tool-selection)                                                                                                      |
+| `model`             | inherit parent | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`)                                                                                                                                                                              |
+| `thinking`          | inherit        | off, minimal, low, medium, high, xhigh, max. An unrecognized value is dropped, and the agent inherits the parent's level                                                                                                                      |
+| `max_turns`         | unlimited      | Max agentic turns before graceful shutdown. `0` or omit for unlimited                                                                                                                                                                         |
+| `prompt_mode`       | `append`       | `replace`: parent prompt is the cacheable base; body is appended last with full control and no `<agent_instructions>` wrapper. `append`: parent prompt is the base; body is wrapped in `<agent_instructions>` (agent acts as a "parent twin") |
+| `inherit_context`   | `false`        | Fork parent conversation into agent                                                                                                                                                                                                           |
+| `run_in_background` | `false`        | Run in background by default                                                                                                                                                                                                                  |
+| `enabled`           | `true`         | Set to `false` to disable an agent (useful for hiding a default agent per-project)                                                                                                                                                            |
+| `locked`            | —              | Fields a `subagent` tool caller may not override. `true` or a list of field names. See [Locking fields against callers](#locking-fields-against-callers)                                                                                      |
+
+The caller decides, and the agent file fills the gaps.
+A `subagent` tool parameter wins over the agent file's value for `model`, `thinking`, `max_turns`, `inherit_context`, and `run_in_background`; the agent file supplies whichever of those the caller left unset.
+
+### Locking fields against callers
+
+An agent whose model, thinking level, or turn limit is a correctness requirement rather than a default can withhold it from callers with `locked`.
+
+```yaml
+---
+model: anthropic/claude-haiku-4-5
+max_turns: 10
+locked: true
+---
+```
+
+`locked: true` withholds every field this file sets — here `model` and `max_turns`, while `thinking`, `inherit_context`, and `run_in_background` stay open because the file names no value for them.
+This is the behavior every agent file had before locking became opt-in, so it is the one-line way to keep an existing file working unchanged.
+
+A list withholds exactly the fields it names, in either YAML spelling:
+
+```yaml
+locked: model, thinking            # comma-separated
+locked: [model, max_turns]         # flow sequence
+```
+
+The list form also withholds a field this file leaves unset — `locked: [model]` with no `model:` denies the caller a model override and lets the child inherit the parent's.
+An entry naming anything other than `model`, `thinking`, `max_turns`, `inherit_context`, or `run_in_background` is ignored.
+
+A lock is never silent: when a caller passes a value for a locked field, the tool result says which agent locked which parameters.
+
+A lock binds the `subagent` tool only.
+[`SubagentsService.spawn`](../README.md#for-extension-authors) is a programmatic caller rather than a model guessing at harness settings, so its options win regardless.
+
+A registered spawn-selection provider is a later authority for `model` and `thinking` only.
+The operator still chooses both after ordinary resolution, and that pair overrides defaults, explicit arguments, and `locked:` values for those two fields.
+Other locked fields are unchanged.
+With no provider, locking and ordinary resolution are unchanged.
+
+### Tool selection
+
+`tools` is the agent's **complete allowlist** of capability tools, not a filter over the built-ins.
+No tool that touches the filesystem, the shell, or the network reaches a child unless the agent names it — whoever registered it.
+
+Entries may name built-in tools (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`) or tools registered by any extension:
+
+```yaml
+---
+description: Browser-driving researcher
+tools: read, grep, find, agent_browser
+---
+```
+
+Naming an extension's tool is the supported way to give a child access to it.
+This matters because a child loads the parent's extensions and runs their setup functions, so an extension **does** call `registerTool` inside the child — and Pi then drops that tool, because the allowlist is applied before the child's tool registry is built.
+The registration reports no error; the tool simply is not there.
+List the tool by name and it is admitted the moment its extension registers it.
+
+Three names are always removed from a child, even when an agent lists them: `subagent`, `get_subagent_result`, and `steer_subagent`.
+This is the recursion guard — without it, an agent could spawn agents of its own without bound.
+
+Two names are always **added**, whatever an agent lists: `ask_parent` and `notify_parent`.
+These are the child's channel back to the agent that delegated to it — protocol the core installs in every child, like the `<active_agent>` tag and the parent-context prefix.
+Neither reaches the filesystem, the shell, or the network, so a read-only agent stays read-only.
+`ask_parent` records a question and tells the child to end its turn, so the delegating agent can answer by resuming it; `notify_parent` sends a one-way update and returns at once.
+A question outlives the window in which it can be answered — the session is released after its retention window, and a workspace is torn down at run end unless the child completed — so once a resume would be refused, the result reports the question and the reason rather than the `resume` call.
+Both go to every agent, `notify_parent` only while [`midRunUpdates`](#persistent-settings) is on.
+Where an update lands depends on whether an announcement can still reach you in time to act on it.
+It arrives as its own message when you are idle and the agent is still running — the one case where steering it is still possible.
+Otherwise it rides that agent's outcome, under "Updates this agent sent while it worked": the foreground call, the resume, the `get_subagent_result` report, or the completion notice, whichever delivers that run.
+Either way you see it once.
+
+Accepted forms, all equivalent:
+
+```yaml
+tools: read, grep, find      # comma-separated
+tools: [read, grep, find]    # YAML flow sequence
+tools:                       # YAML block sequence
+  - read
+  - grep
+  - find
+tools: none                  # no tools at all
+```
+
+Omitting `tools` entirely gives the agent all seven built-ins and no extension tools.
+
+Two other settings interact with this list:
+
+- [`excludedExtensionPackages`](#excluding-package-extensions-from-children) stops an extension from loading in children at all, so naming one of its tools has no effect there.
+- When [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system) is installed, its `permission:` frontmatter narrows the set further, per turn.
+  Use it to deny a tool; use `tools` to decide what the agent has in the first place.
+
+## Persistent Settings
+
+Runtime tuning values set via `/subagents:settings` (max concurrency, default max turns, grace turns, the two session-retention windows, the abort-on-interrupt policy, and the mid-run update channel) persist across pi restarts.
+A completed subagent's record is kept for the whole parent session (so `get_subagent_result` never misses); only its heavy in-memory session is released — after `consumedSessionRetentionMinutes` once the result has been collected, or after the `unconsumedSessionRetentionMinutes` safety cap if it never was.
+An agent that asked a question and has not been answered holds the safety cap rather than the consumed window, because reading a question is not finishing with the agent — the answer is delivered by resuming the very session the short window would release.
+
+Set `midRunUpdates` to `false` to withhold `notify_parent` from every agent, leaving them no way to tell you anything before they finish.
+`ask_parent` is unaffected: a blocked agent can still end its turn with a question.
+Two files, merged on load:
+
+- **Global:** `~/.pi/agent/subagents.json` — your machine-wide defaults.
+  Edit by hand; the `/subagents:settings` command never writes here.
+- **Project:** `<cwd>/.pi/subagents.json` — per-project overrides.
+  Written by `/subagents:settings`.
+
+**Precedence:** project overrides global on any field present in both.
+Missing fields fall back to the hardcoded defaults (max concurrency `4`, default max turns unlimited, grace turns `5`, consumed-session retention `10` minutes, unconsumed-session retention `720` minutes, abort-all-on-interrupt `true`, mid-run updates `true`).
+
+**Example — global defaults for a beefy machine:**
+
+```bash
+mkdir -p ~/.pi/agent
+cat > ~/.pi/agent/subagents.json <<'EOF'
+{
+  "maxConcurrent": 16,
+  "graceTurns": 10,
+  "unconsumedSessionRetentionMinutes": 1440,
+  "abortAllOnInterrupt": false,
+  "midRunUpdates": true
+}
+EOF
+```
+
+Every project now starts with concurrency 16, grace 10, and ESC left to the parent, without ever touching the command.
+Individual projects can still override via `/subagents:settings`.
+
+**Failure behavior:** missing file is silent; malformed JSON logs a `[pi-subagents] Ignoring malformed settings at …` warning to stderr; invalid/out-of-range field values are dropped per-field; write failures downgrade the `/subagents:settings` toast to a warning with `(session only; failed to persist)`.
+
+### Excluding package extensions from children
+
+Some package extensions are parent-scoped or expensive to initialize per session.
+Because children run in the parent's process, such an extension initializing once per child multiplies its cost in a single heap — enough, in the case that motivated this feature, to exhaust the V8 heap with four concurrent children.
+
+List the offending packages under `excludedExtensionPackages` to keep their extensions out of child sessions:
+
+```json
+{
+  "excludedExtensionPackages": ["npm:@cortexkit/pi-magic-context"]
+}
+```
+
+Entries must match Pi's configured package source string exactly, as it appears in your Pi `settings.json` `packages` array — there is no glob or prefix matching.
+
+What this does and does not do:
+
+- Only the matched packages' **extensions** are disabled, and only in children.
+  Their skills, prompts, and themes stay available to children.
+- The parent session is unaffected, as is the child's own settings — only the child's resource loading is filtered.
+- The exclusion happens during package resolution, so the extension's module is never imported and its factory never runs in the child.
+- Excluding a package keeps the **tools** that extension registers out of child sessions too: its factory never runs there, so an agent that names one of those tools in [`tools`](#tool-selection) gets nothing.
+  If you need the tools but want the extension's resources released when the child is disposed, exclusion is the wrong lever — see [Child session lifecycle](../README.md#child-session-lifecycle).
+
+This key is hand-edited in the global or project `subagents.json`; `/subagents:settings` does not expose it, but it is preserved when you change other settings there.
+An absent or empty list reproduces the default behavior, in which children inherit every parent extension.
+
+The same is true of [`promptInheritance`](#portable-inheritance-opt-in): hand-edited only, preserved across other settings changes, and absent means every child inherits the full parent identity.
+
+#### Excluding a permission extension
+
+When [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system) is installed, it rides into children harmlessly by construction, so exclusion is an optimization and never a correctness requirement.
+Excluding an extension that only registers an authorizer chain link costs nothing but saves its load time: the node that adjudicates an ask still judges every descendant's request.
+
+One case used to weaken a child, and recent versions of that extension close it.
+An extension can declare the filesystem path *another* package's tool accesses, so that the permission system's `path` and `external_directory` gates can see it.
+Excluding such a declaring package left the tool present in the child with its path undeclared, and the child's own gates stopped seeing it — silently, because the parent's gating is unaffected and still looks correct.
+
+The condition needed both halves, so most exclusions could never hit it:
+
+- Package **A** registers a tool whose path lives under a non-standard input key.
+- Package **B** registers the path extractor for A's tool.
+- You exclude **B** but not **A**.
+
+If one package supplies both the tool and its extractor, excluding it removes both together and no gap opens.
+
+Since the version of `@gotgenes/pi-permission-system` that closed this, a child session that has no extractor of its own for a tool borrows one from the session that spawned it, so the split above no longer leaves a path ungated.
+Preview formatters resolve the same way, so an approval prompt for such a tool still shows its registered preview rather than raw JSON.
+The borrowed declaration is recorded: the child's review-log entry carries `extractorSource: "inherited"`.
+Nothing is borrowed across a process boundary — children here run in the parent's process, which is what makes it possible.
+
+One thing exclusion still does **not** weaken, by design: an authorizer chain link is never borrowed from another session, because a link decides rather than describes.
+
+Excluding `@gotgenes/pi-permission-system` itself is a different matter: a child then loads no permission node at all, so nothing gates its tool calls, no `permission:` frontmatter applies, and no `ask` is forwarded.
+See [Subagent Integration](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/subagent-integration.md#loading-asymmetry) for the full rule.
+
+This one does not pass silently.
+This extension announces each child once its extensions have bound, and a recent `@gotgenes/pi-permission-system` uses that announcement to notice a child with no node of its own: it records the child in its permission review log and warns once per session that the child's tool calls are ungated.
+The warning names this setting as the likeliest cause, because a failure to load that extension in the child leaves the same absence and the parent cannot tell the two apart.
+Remove the entry to restore gating in child sessions; keep it, knowing the children it spawns are unguarded.
+
+### Abort on interrupt
+
+By default, pressing ESC to interrupt the parent agent also aborts every subagent.
+Set `abortAllOnInterrupt` to `false` (or flip it from `/subagents:settings`) to keep background and queued subagents running when you interrupt the parent — useful when you spawn long background work and then want to steer the parent without losing it.
+
+A foreground agent aborts on ESC regardless of this setting.
+It holds the parent's own run signal for the duration of its blocking tool call, so the interrupt reaches it directly; the policy governs background and queued agents.
+
+The policy is read at the moment ESC fires, so flipping it mid-session applies to the very next interrupt.
+
+## Model providers in child sessions
+
+A subagent inherits every model provider the parent can reach, including providers an extension registered at runtime with `pi.registerProvider` rather than through `models.json` or `auth.json`.
+This is what lets a child run under a dynamically registered provider such as `pi-claude-bridge`.
+
+The child does not share the parent's provider pool — it gets its own, with the parent's registrations copied onto it.
+An extension loaded in a child can therefore register or unregister providers without disturbing the parent or any sibling agent.
+
+Inheritance is a **snapshot taken when the agent spawns**.
+A provider registered in the parent after a child has started does not appear in that running child; agents spawned afterwards pick it up.
+This matches the rest of the parent state a child captures at spawn — working directory, model, and system prompt are all frozen the same way.
+
+Provider inheritance needs no configuration.
+It does require Pi 0.81.0 or newer, which is the floor this package declares — that is the release where the model registry began exposing every runtime registration for replay.
+
+One thing the child does still share with the parent: when a provider's API key is a shell command (`"apiKey": "!my-command"`), Pi caches the command's resolved output process-wide, so parent and children reuse one result rather than re-running it per agent.
+That cache is Pi's, not this extension's, and it predates provider inheritance.

package/docs/decisions/0001-deferred-patches.md

@@ -0,0 +1,80 @@
+---
+status: superseded
+date: 2026-05-11
+---
+
+# 0001 — Deferred fork patches and upstream-PR strategy
+
+## Status
+
+Superseded by [`docs/architecture/architecture.md`](../architecture/architecture.md), which commits to a hard fork with material scope reduction (scheduling removal, `SubagentsAPI` boundary, `index.ts` decomposition).
+The original rationale below remains useful context.
+
+## Context
+
+This fork was created to land three pieces of work identified during RepOne issue [#442](https://github.com/Tiny-IG-Software/repone/issues/442):
+
+1. **Peer-dep rename** — `@mariozechner/pi-*` → `@earendil-works/pi-*`.
+2. **Patch 2 — Re-activate extension tools post-`bindExtensions`** (Spike 3 finding).
+3. **Patch 3 — Inject `<active_agent>` tag** (Spike 4 finding).
+
+A fourth piece of work was scoped during the same spike round but deferred:
+
+- **Patch 1 — Mirror parent's `additionalExtensionPaths` (and siblings) into the child's `DefaultResourceLoader`** (Spike 2 finding).
+
+This ADR records why Patch 1 was deferred and the strategy for upstream PRs back to [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents).
+
+## Decision
+
+### Patch 1 is deferred
+
+The original Spike 2 finding was that the parent's `additionalExtensionPaths` does not propagate to the child's `DefaultResourceLoader`.
+The fix was sketched as "plumb parent's `additionalExtensionPaths` (and siblings) into the child."
+
+During planning for this fork, two implementation constraints surfaced:
+
+1. The parent's `DefaultResourceLoader.additionalExtensionPaths` is **private** — no public getter on `ExtensionContext`.
+2. The parent's CLI flags (e.g., `pi -e <path>`) are parsed in `main.js` and not surfaced through any extension API.
+
+A working patch would have to either:
+
+- Accept new fields in `RunOptions` so callers supply the paths explicitly, **or**
+- Reach into `process.argv` to re-resolve `-e`/`--extensions` flags from the child's perspective.
+
+Neither matches the production need.
+For RepOne (and any consumer that installs extensions via `pi install`), extensions are settings-discoverable: children inherit them independently of the parent's `DefaultResourceLoader` configuration.
+The `pi -e <path>` ephemeral-extension case is the only beneficiary of Patch 1, and it does not appear in our workflow.
+
+We therefore defer Patch 1 rather than carry a speculative patch in the fork's diff against upstream.
+A follow-up issue on the RepOne board (linked from #443) captures the criterion for revisiting: **a workflow that needs `pi -e <path>` ephemeral extensions to reach children**.
+
+### Upstream PRs are open
+
+All three divergences now have upstream PRs, opened after production validation in RepOne:
+
+1. **Peer-dep migration** — [tintinweb/pi-subagents#71](https://github.com/tintinweb/pi-subagents/pull/71) (`fix(deps)!: migrate from deprecated @mariozechner/pi-* to @earendil-works/pi-*`)
+2. **Post-bind re-filter** — [tintinweb/pi-subagents#72](https://github.com/tintinweb/pi-subagents/pull/72) (`fix(agent-runner): re-filter active tools after bindExtensions so extension tools land in child`)
+3. **Active-agent tag** — [tintinweb/pi-subagents#73](https://github.com/tintinweb/pi-subagents/pull/73) (`feat(prompts): inject <active_agent name="..."/> tag for permission resolution`)
+
+If these land upstream, upstream gains the peer-dep fix and the two RepOne patches.
+However, the fork now diverges intentionally beyond those patches — see [`docs/architecture/architecture.md`](../architecture/architecture.md) for the full scope of planned changes.
+
+## Consequences
+
+### Positive
+
+- The fork's diff against upstream stays minimal — three patches plus tooling alignment.
+- We avoid landing a speculative Patch 1 that would need rework if upstream's `ExtensionContext` API changes.
+- Production evidence strengthened the upstream PRs.
+
+### Negative
+
+- The `pi -e <path>` ephemeral-extension case in subagents will not work until Patch 1 lands.
+  We accept this because no consumer in scope uses that pattern.
+
+### Operational
+
+- Upstream PRs are open and linked above.
+  If merged, upstream gains the three patches, but the fork continues independently with broader architectural changes per [`docs/architecture/architecture.md`](../architecture/architecture.md).
+- The architecture document governs the fork's direction going forward; this ADR's original "thin-patch" framing no longer describes the fork's trajectory.
+- When Patch 1 is eventually added, it should be a separate ADR in `docs/decisions/` with its own follow-up.