@tintinweb/pi-subagents 0.7.3 → 0.9.0

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-05-30
+
+> **Heads-up — orchestrator behavior may shift.** This release substantially rewrites the `Agent` tool description and the three default-agent descriptions (`general-purpose`, `Explore`, `Plan`) to mirror Claude Code's upstream wording. No API, schema, or tool-call shape changes — purely a prompt-engineering shift, but a load-bearing one:
+> - **Agent selection may drift.** The new agent descriptions carry richer positive ("Use it to …") and negative ("Do NOT use it for …") guidance plus search-breadth hints for `Explore` (`"quick"` / `"medium"` / `"very thorough"`). For ambiguous tasks where the orchestrator previously picked one default agent, it may now pick another — typically more correctly, but the choice may differ from prior releases.
+> - **Subagent briefings will skew longer and more contextual.** The restored upstream guardrails and the new `## Writing the prompt` section actively coach "smart colleague who just walked into the room"-style prompts. Expect more context, more constraint, more upfront framing in the `prompt:` field the orchestrator passes to subagents.
+> - **Parallel/background patterns more strongly enforced.** The merged bullet on parallel execution now explicitly says `run_in_background: true` is required on each tool call for actual concurrency, and that the orchestrator MUST send a single message with multiple tool uses when the user says "in parallel." Workflows relying on sequential-foreground default behavior are unaffected.
+> - If you have tests or workflows that depend on the prior agent-selection or briefing behavior, pin to a v0.7.x release.
+
+### Added
+- **`scopeModels` setting — opt-in subagent model-scope enforcement** (off by default). New setting toggleable via `/agents → Settings → Scope models`. When enabled, the *effective* model of each subagent spawn is validated against `enabledModels` from pi's settings (which pi manages via its own `/scoped-models` UI; pi-subagents only reads it). **Both pi settings files are honored**: global `<agentDir>/settings.json` plus project-local `<cwd>/.pi/settings.json`, with project overriding global — mirrors pi's `SettingsManager` deep-merge and our own `subagents.json` precedence. Out-of-scope handling depends on source: caller-supplied via `Agent({ model: "..." })` → hard error to the orchestrator with the allowed list; frontmatter-pinned or parent-inherited → warning toast + the agent runs anyway (preserves "frontmatter is authoritative" guarantee from v0.5.1; `scopeModels` is a guardrail against runtime LLM choices, not user-level config). Limitation: only exact `provider/modelId` entries in `enabledModels` are honored — globs (`*sonnet*`), bare model IDs, and `:thinking` suffixes that pi itself supports are silently dropped here. Matches pi's `/scoped-models` picker output, so the limitation is invisible to UI users.
+
+### Changed
+- **`Agent` tool prompt restructured to mirror Claude Code's upstream Agent tool description format.** Section headings now match upstream (`## When not to use`, `## Usage notes`, `## Writing the prompt`); the auto-generated agent list renders as a flat list (no `Default agents:` / `Custom agents:` sub-headers) with a per-agent `(Tools: …)` suffix derived from each agent's `builtinToolNames` (or `*` when the agent has the full built-in set). Restored upstream's load-bearing guardrails that were missing or compressed in the old prompt: "result is not visible to the user → summarize", "trust but verify", "fresh agent / self-contained prompt" on resume, "tell the agent whether to write code or do research", "use proactively when the description says so", "MUST send a single message for parallel", and the worktree auto-cleanup behavior detail. The three redundant "Use Explore / Plan / general-purpose for …" shorthand bullets were dropped — the agent descriptions themselves now carry the canonical (and richer) selection guidance. Upstream's two `<example>` blocks at the end of "Writing the prompt" are also intentionally omitted: the per-orchestrator-turn token cost is recurring, the abstract guidance + the now-rich agent descriptions cover the same pedagogical ground, and the examples embed Anthropic-specific `<thinking>` framing that doesn't generalize across pi-ai's provider surface (OpenAI, Bedrock, Gemini, Mistral, …). All pi-specific bullets (`resume`, `steer_subagent`, `model`, `thinking`, `inherit_context`, `isolation: "worktree"`, `${scheduleGuideline}`) preserved.
+- **Default agent descriptions (`general-purpose`, `Explore`, `Plan`) replaced with upstream Claude Code's verbatim wording.** Previously one-line labels (e.g. `"Fast codebase exploration agent (read-only)"`); now multi-sentence descriptions that include positive ("Use it to …") and negative ("Do NOT use it for …") guidance plus, for Explore, search-breadth hints (`"quick"` / `"medium"` / `"very thorough"`). The LLM-facing selection signal is now substantially stronger.
+- **`/agents → Eject` now emits YAML-safe `description:` frontmatter.** The new Explore description contains a `: ` colon-space pattern (the search-breadth hint) and embedded quote characters — emitting it raw would have produced malformed frontmatter that the `yaml` parser would mis-parse. `ejectAgent` now wraps the description with `JSON.stringify` (a valid YAML 1.2 double-quoted scalar), so any description string round-trips cleanly through eject → re-load. Latent bug: previously unreachable because old descriptions were YAML-plain-safe.
+- **`/agents → Settings` UI rewritten to inline-editable `SettingsList`.** Replaces the previous modal `ctx.ui.select` chain. All settings visible at once; `↑`/`↓` to navigate, `Space` to cycle preset values on numerics (`Max concurrency`, `Default max turns`, `Grace turns`), `Enter` to type a custom value, `Esc` to exit. Functionally equivalent — same fields, same valid ranges, same persistence behavior — but the interaction model is different. Users scripting against the old screen flow may notice.
+- **`.gitignore` additions.** Added `.pi/subagents.json` (project-local subagents settings — written by `/agents → Settings`, shouldn't be committed) plus pi-runtime working files (`progress.md`, `AGENTS.md`, `CLAUDE.md`). **Migration:** if you previously committed `.pi/subagents.json` to your repo, run `git rm --cached .pi/subagents.json` to untrack — gitignore only blocks new additions.
+
+## [0.8.0] - 2026-05-26
+
+> **⚠️ Breaking: peer dependencies moved from `@mariozechner/pi-*` to `@earendil-works/pi-*`.** The upstream Pi runtime relocated npm scopes on 2026-05-07; the `@mariozechner/pi-*` packages are deprecated. This release pins `@earendil-works/pi-{ai,coding-agent,tui}` at `>=0.74.0`. Hosts on the old scope must update their pi installation first (`pi update --self` handles the rename automatically) before installing this version.
+>
+> **Note on Node:** this release is tested against `@earendil-works/pi-coding-agent@latest` (currently `0.75.x`), which requires Node `>=22.19.0` because its bundled `undici` calls Node 22+ APIs. CI runs on Node 22. The peer range (`>=0.74.0`) technically also matches the upstream `legacy-node20` line (`0.74.x`, Node 20 compatible) and this extension contains no Node 22+ API calls of its own, but the legacy line is not exercised in CI — consumers pinning it do so at their own risk.
+
+### Changed
+- **Peer deps migrated from `@mariozechner/pi-*` to `@earendil-works/pi-*`** ([#76](https://github.com/tintinweb/pi-subagents/issues/76) — thanks [@SEHANTA](https://github.com/SEHANTA) for the report). On **2026-05-07** the upstream Pi runtime moved npm scopes — `@mariozechner/pi-coding-agent@0.73.1` was the final publish (now deprecated on npm), and `@earendil-works/pi-coding-agent@0.74.0` shipped 30 minutes later from the same monorepo (same author, same code). `peerDependencies` now target `@earendil-works/pi-{ai,coding-agent,tui}` at `>=0.74.0`, and all `src/**` and `test/**` imports are renamed to the new scope — pure rename, no API changes. Consumers pinning the new scope no longer hit the peer-dep conflict warnings reported in [#76](https://github.com/tintinweb/pi-subagents/issues/76).
+- **`ThinkingLevel` now imported from `@earendil-works/pi-ai` instead of `…/pi-agent-core`.** `src/types.ts` previously reached past the public API into `pi-agent-core` (an internal package), which only resolved because npm flat-hoisted it as a transitive of `pi-coding-agent` — under pnpm or strict-resolver setups the import failed (`TS2307: Cannot find module '@mariozechner/pi-agent-core'`). `pi-ai` re-exports `ThinkingLevel` from its public surface (`export * from "./types.ts"`), so the import goes through the documented entry point and no extra peer dep is needed.
+
+### Fixed
+- **`.pi/subagent-schedules/` is no longer created in every working directory.** `ScheduleStore`'s constructor previously ran `mkdirSync` unconditionally, so any session with scheduling enabled left an empty `.pi/subagent-schedules/` dir behind even when nothing was ever scheduled. Directory creation is now lazy — deferred to a new private `ensureDir()` invoked at the top of `withLock`, so the dir (and its `<sessionId>.json`) appear only when a job is actually persisted. Additionally, `update`/`remove` now short-circuit on an unknown id (in-memory `jobs.has(id)` check) before taking the lock, so no-op mutations never touch disk. Read-only use (`list`/`get`/`hasName`) and constructing the store never create the dir. Pre-existing leftover dirs are not cleaned up — remove them manually.
+
 ## [0.7.3] - 2026-05-14
 
 ### Added

package/README.md

@@ -31,6 +31,7 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 - **Event bus** — lifecycle events (`subagents:created`, `started`, `completed`, `failed`, `steered`, `compacted`) emitted via `pi.events`, enabling other extensions to react to sub-agent activity
 - **Cross-extension RPC** — other pi extensions can spawn and stop subagents via the `pi.events` event bus (`subagents:rpc:ping`, `subagents:rpc:spawn`, `subagents:rpc:stop`). Standardized reply envelopes with protocol versioning. Emits `subagents:ready` on load
 - **Schedule subagents** — pass `schedule` to the `Agent` tool to fire on cron / interval / one-shot. Session-scoped jobs with PID-locked persistence; results land via the same `subagent-notification` followUp path as manual background completions; manage via `/agents → Scheduled jobs`
+- **Model scope enforcement** — opt-in validation that subagent model choices stay within your pi `enabledModels` allowlist (sourced from `/scoped-models`, with both global and project-local pi settings honored). Caller-supplied out-of-scope → hard error to orchestrator; frontmatter-pinned out-of-scope → warning + runs anyway (frontmatter authoritative). Toggle via `/agents → Settings → Scope models`
 
 ## Install
 
@@ -310,9 +311,29 @@ When background agents complete, they notify the main agent. The **join mode** c
 **Configuration:**
 - Configure join mode in `/agents` → Settings → Join mode
 
+## Model Scope
+
+**Opt-in:** off by default. Enable via `/agents → Settings → Scope models`.
+
+When on, each subagent spawn's effective model is validated against pi's own `enabledModels` list (configured via pi's `/scoped-models` UI). pi-subagents reads that list; it doesn't manage it. Both of pi's settings files are honored: global `~/.pi/agent/settings.json` and project-local `<cwd>/.pi/settings.json`. **Project overrides global** — mirrors pi's `SettingsManager` deep-merge, so a tighter per-project scope (hand-edited into the project settings) is respected.
+
+**Out-of-scope handling depends on source:**
+
+| Model source | Out-of-scope behavior |
+|---|---|
+| Caller-supplied via `Agent({ model: "..." })` | Hard error returned to the orchestrator, listing allowed models |
+| Pinned in agent frontmatter | Warning toast + the pinned model runs (frontmatter is authoritative) |
+| Parent-inherited (neither set) | Warning toast + parent's model runs |
+
+**Design:** `scopeModels` is a guardrail against the orchestrator picking unexpected models at runtime, not a hard policy against user-level config. The "frontmatter is authoritative" guarantee from v0.5.1 still holds for `model:` — caller params can't override frontmatter, and frontmatter pins run even when out of scope (with a visible warning).
+
+**Pattern format:** only exact `provider/modelId` entries are honored (e.g. `anthropic/claude-haiku-4-5-20251001`). Glob patterns (`*sonnet*`), bare model IDs, and `:thinking` suffixes — which pi itself supports — are silently dropped here. pi's `/scoped-models` picker writes exact entries, so the limitation is invisible if you configure scope through the UI. Hand-edited globs produce an empty allowed set (scope check becomes a no-op).
+
+**No-op safety:** if `enabledModels` is missing or empty in pi's settings, scope check skips entirely — no false positives, no spurious errors.
+
 ## Persistent Settings
 
-Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns, default join mode) persist across pi restarts. Two files, merged on load:
+Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns, default join mode, scheduling on/off, scope models on/off) persist across pi restarts. Two files, merged on load:
 
 - **Global:** `~/.pi/agent/subagents.json` — your machine-wide defaults. Edit by hand; the `/agents` menu never writes here.
 - **Project:** `<cwd>/.pi/subagents.json` — per-project overrides. Written by `/agents` → Settings.

package/dist/agent-manager.d.ts

@@ -5,8 +5,8 @@
  * Excess agents are queued and auto-started as running agents complete.
  * Foreground agents bypass the queue (they block the parent anyway).
  */
-import type { Model } from "@mariozechner/pi-ai";
-import type { AgentSession, ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { Model } from "@earendil-works/pi-ai";
+import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type ToolActivity } from "./agent-runner.js";
 import type { AgentInvocation, AgentRecord, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
 export type OnAgentComplete = (record: AgentRecord) => void;

package/dist/agent-runner.d.ts

@@ -1,9 +1,9 @@
 /**
  * agent-runner.ts — Core execution engine: creates sessions, runs agents, collects results.
  */
-import type { Model } from "@mariozechner/pi-ai";
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
-import { type AgentSession, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { Model } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type AgentSession, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { SubagentType, ThinkingLevel } from "./types.js";
 /** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
 export declare function normalizeMaxTurns(n: number | undefined): number | undefined;

package/dist/agent-runner.js

@@ -1,7 +1,7 @@
 /**
  * agent-runner.ts — Core execution engine: creates sessions, runs agents, collects results.
  */
-import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@mariozechner/pi-coding-agent";
+import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { getAgentConfig, getConfig, getMemoryToolNames, getReadOnlyMemoryToolNames, getToolNamesForType } from "./agent-types.js";
 import { buildParentContext, extractText } from "./context.js";
 import { DEFAULT_AGENTS } from "./default-agents.js";

package/dist/context.d.ts

@@ -1,7 +1,7 @@
 /**
  * context.ts — Extract parent conversation context for subagent inheritance.
  */
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 /** Extract text from a message content block array. */
 export declare function extractText(content: unknown[]): string;
 /**

package/dist/custom-agents.js

@@ -3,7 +3,7 @@
  */
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
-import { getAgentDir, parseFrontmatter } from "@mariozechner/pi-coding-agent";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
 /**
  * Scan for custom agent .md files from multiple locations.

package/dist/default-agents.js

@@ -10,7 +10,7 @@ export const DEFAULT_AGENTS = new Map([
         {
             name: "general-purpose",
             displayName: "Agent",
-            description: "General-purpose agent for complex, multi-step tasks",
+            description: "General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you.",
             // builtinToolNames omitted — means "all available tools" (resolved at lookup time)
             // inheritContext / runInBackground / isolated omitted — strategy fields, callers decide per-call.
             // Setting them to false would lock callsite intent (see resolveAgentInvocationConfig in invocation-config.ts).
@@ -26,7 +26,7 @@ export const DEFAULT_AGENTS = new Map([
         {
             name: "Explore",
             displayName: "Explore",
-            description: "Fast codebase exploration agent (read-only)",
+            description: "Fast read-only search agent for locating code. Use it to find files by pattern (eg. \"src/components/**/*.tsx\"), grep for symbols or keywords (eg. \"API endpoints\"), or answer \"where is X defined / which files reference Y.\" Do NOT use it for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis — it reads excerpts rather than whole files and will miss content past its read window. When calling, specify search breadth: \"quick\" for a single targeted lookup, \"medium\" for moderate exploration, or \"very thorough\" to search across multiple locations and naming conventions.",
             builtinToolNames: READ_ONLY_TOOLS,
             extensions: true,
             skills: true,
@@ -68,7 +68,7 @@ Use Bash ONLY for read-only operations: ls, git status, git log, git diff, find,
         {
             name: "Plan",
             displayName: "Plan",
-            description: "Software architect for implementation planning (read-only)",
+            description: "Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.",
             builtinToolNames: READ_ONLY_TOOLS,
             extensions: true,
             skills: true,

package/dist/enabled-models.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Reads `enabledModels` from pi's settings (global `<agentDir>/settings.json`
+ * + project-local `<cwd>/.pi/settings.json`, project wins) and resolves
+ * entries to concrete `provider/modelId` keys for scope validation.
+ *
+ * **Project overrides global**, mirroring pi's own `SettingsManager`
+ * deep-merge behavior and matching the precedence we use for our own
+ * `subagents.json` settings (see `src/settings.ts:loadSettings`). If
+ * project file has `enabledModels` set, it wholly replaces global's
+ * (array fields are replaced, not concatenated).
+ *
+ * **Limited subset of upstream's resolveModelScope.** We support exact
+ * `provider/modelId` matching only. Upstream (pi-coding-agent's
+ * `core/model-resolver.ts`) additionally supports glob patterns
+ * (`*sonnet*`, `anthropic/*`), bare model IDs without provider, and
+ * thinking-level suffixes (`provider/*:high`). Those forms are silently
+ * ignored here.
+ *
+ * In practice, pi's `/scoped-models` picker writes exact `provider/modelId`
+ * entries, so the limitation is invisible for users who configure scope
+ * through pi's UI. Hand-edited settings using globs or bare IDs will
+ * produce an empty allowed set (scope check becomes a no-op).
+ *
+ * Example:
+ *   enabledModels = ["anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6"]
+ *   → resolves to { "anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6" }
+ */
+/** Minimal registry shape — only the methods resolveEnabledModels actually calls. */
+export interface ModelRegistryRef {
+    getAll(): unknown[];
+    getAvailable?(): unknown[];
+}
+/**
+ * Read enabledModels from pi's settings — project-local overrides global.
+ * Mirrors pi's SettingsManager deep-merge for the `enabledModels` field
+ * (and matches our own loadSettings precedence in src/settings.ts).
+ * Returns undefined when neither file has the field.
+ */
+export declare function readEnabledModels(cwd: string): string[] | undefined;
+export declare function resolveEnabledModels(patterns: string[] | undefined, registry: ModelRegistryRef, cwd?: string): Set<string> | undefined;
+/**
+ * True when `model` is in the allowed set. Centralizes the key format
+ * (`provider/id` lowercase) so callers don't have to reproduce it —
+ * both set-building (resolveExact) and lookup go through `modelKey`.
+ */
+export declare function isModelInScope(model: {
+    provider: string;
+    id: string;
+}, allowed: Set<string>): boolean;

package/dist/enabled-models.js

@@ -0,0 +1,145 @@
+/**
+ * Reads `enabledModels` from pi's settings (global `<agentDir>/settings.json`
+ * + project-local `<cwd>/.pi/settings.json`, project wins) and resolves
+ * entries to concrete `provider/modelId` keys for scope validation.
+ *
+ * **Project overrides global**, mirroring pi's own `SettingsManager`
+ * deep-merge behavior and matching the precedence we use for our own
+ * `subagents.json` settings (see `src/settings.ts:loadSettings`). If
+ * project file has `enabledModels` set, it wholly replaces global's
+ * (array fields are replaced, not concatenated).
+ *
+ * **Limited subset of upstream's resolveModelScope.** We support exact
+ * `provider/modelId` matching only. Upstream (pi-coding-agent's
+ * `core/model-resolver.ts`) additionally supports glob patterns
+ * (`*sonnet*`, `anthropic/*`), bare model IDs without provider, and
+ * thinking-level suffixes (`provider/*:high`). Those forms are silently
+ * ignored here.
+ *
+ * In practice, pi's `/scoped-models` picker writes exact `provider/modelId`
+ * entries, so the limitation is invisible for users who configure scope
+ * through pi's UI. Hand-edited settings using globs or bare IDs will
+ * produce an empty allowed set (scope check becomes a no-op).
+ *
+ * Example:
+ *   enabledModels = ["anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6"]
+ *   → resolves to { "anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6" }
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+/** Paths to pi's settings.json files: [project, global] (project takes precedence). */
+function settingsPaths(cwd) {
+    return [
+        join(cwd, ".pi", "settings.json"),
+        join(getAgentDir(), "settings.json"),
+    ];
+}
+/** Read `enabledModels` from a single settings.json file. Undefined when missing or absent. */
+function readField(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf-8"));
+        if (Array.isArray(raw?.enabledModels))
+            return raw.enabledModels;
+    }
+    catch {
+        /* corrupt file — silent */
+    }
+    return undefined;
+}
+/**
+ * Read enabledModels from pi's settings — project-local overrides global.
+ * Mirrors pi's SettingsManager deep-merge for the `enabledModels` field
+ * (and matches our own loadSettings precedence in src/settings.ts).
+ * Returns undefined when neither file has the field.
+ */
+export function readEnabledModels(cwd) {
+    const [project, global] = settingsPaths(cwd);
+    return readField(project) ?? readField(global);
+}
+/**
+ * Resolve enabledModels patterns → Set<"provider/modelId"> (lowercase keys).
+ *
+ * Only exact `provider/modelId` patterns are matched (case-insensitive).
+ * Patterns without a slash, with glob characters, or with a `:thinking`
+ * suffix are silently dropped. See module-level docstring for rationale.
+ *
+ * Cache: keyed on JSON.stringify(patterns) + mtime/size of *both*
+ * project and global settings.json files. Re-resolves when either file
+ * changes or the patterns argument differs.
+ *
+ * Returns undefined when no patterns are provided or no patterns match
+ * (scope check becomes a no-op at the call site).
+ */
+// Module-level cache — invalidated when either settings.json changes or patterns differ.
+let cachedAllowed;
+let cachedHash = "";
+let cachedPatternsKey = "";
+/** mtime+size hash of one file, or "missing" if absent. */
+function hashOf(path) {
+    try {
+        const s = statSync(path);
+        return `${s.mtimeMs}-${s.size}`;
+    }
+    catch {
+        return "missing";
+    }
+}
+export function resolveEnabledModels(patterns, registry, cwd = process.cwd()) {
+    // Fast path: check cache (stat both project and global settings.json files)
+    const patternsKey = JSON.stringify(patterns);
+    const [project, global] = settingsPaths(cwd);
+    const fileHash = `${hashOf(project)};${hashOf(global)}`;
+    if (fileHash === cachedHash && patternsKey === cachedPatternsKey) {
+        return cachedAllowed;
+    }
+    // Cache miss — resolve
+    if (!patterns || patterns.length === 0) {
+        cachedHash = fileHash;
+        cachedPatternsKey = patternsKey;
+        cachedAllowed = undefined;
+        return undefined;
+    }
+    const available = (registry.getAvailable?.() ?? registry.getAll());
+    const allowed = new Set();
+    for (const pattern of patterns) {
+        const trimmed = pattern.trim();
+        if (!trimmed)
+            continue; // skip empty/whitespace
+        resolveExact(trimmed, available, allowed);
+    }
+    const result = allowed.size > 0 ? allowed : undefined;
+    cachedHash = fileHash;
+    cachedPatternsKey = patternsKey;
+    cachedAllowed = result;
+    return result;
+}
+/**
+ * True when `model` is in the allowed set. Centralizes the key format
+ * (`provider/id` lowercase) so callers don't have to reproduce it —
+ * both set-building (resolveExact) and lookup go through `modelKey`.
+ */
+export function isModelInScope(model, allowed) {
+    return allowed.has(modelKey(model));
+}
+/** Canonical lowercase `provider/id` key for the allowed set. */
+function modelKey(model) {
+    return `${model.provider}/${model.id}`.toLowerCase();
+}
+/**
+ * Resolve exact model pattern. Example: "google/gemma-4-31b-it".
+ */
+function resolveExact(pattern, available, allowed) {
+    // "provider/modelId" — exact (colon is part of id, not split)
+    const slashIdx = pattern.indexOf("/");
+    if (slashIdx === -1)
+        return; // bare modelId not supported
+    const provider = pattern.slice(0, slashIdx).toLowerCase();
+    const modelId = pattern.slice(slashIdx + 1).toLowerCase();
+    const exact = available.find(m => m.provider.toLowerCase() === provider && m.id.toLowerCase() === modelId);
+    if (exact) {
+        allowed.add(modelKey(exact));
+    }
+}

package/dist/env.d.ts

@@ -1,6 +1,6 @@
 /**
  * env.ts — Detect environment info (git, platform) for subagent system prompts.
  */
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { EnvInfo } from "./types.js";
 export declare function detectEnv(pi: ExtensionAPI, cwd: string): Promise<EnvInfo>;

package/dist/index.d.ts

@@ -9,5 +9,5 @@
  * Commands:
  *   /agents                 — Interactive agent management menu
  */
-import { type ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 export default function (pi: ExtensionAPI): void;