@opengsd/gsd-pi 1.10.0 → 1.11.0

package/src/resources/extensions/gsd/db-canonical-foundation-schema.ts

@@ -0,0 +1,129 @@
+// Project/App: gsd-pi
+// File Purpose: Additive v31 authority, operation provenance, domain event, and outbox schema.
+
+import type { DbAdapter } from "./db-adapter.js";
+
+/**
+ * v31 mapping:
+ * - schema_version remains DDL compatibility, not the domain revision.
+ * - audit_events remains optional operational telemetry, not domain history.
+ * - milestone_commit_attributions remains Git-specific, not operation provenance.
+ * - command_queue and runtime_kv remain coordination/cache surfaces, not an outbox.
+ */
+export function createCanonicalFoundationSchemaV31(db: DbAdapter): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS project_authority (
+      singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+      project_id TEXT NOT NULL UNIQUE,
+      project_root_realpath TEXT NOT NULL DEFAULT '',
+      revision INTEGER NOT NULL DEFAULT 0 CHECK (revision >= 0),
+      authority_epoch INTEGER NOT NULL DEFAULT 0 CHECK (authority_epoch >= 0),
+      created_at TEXT NOT NULL DEFAULT '',
+      updated_at TEXT NOT NULL DEFAULT ''
+    )
+  `);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS workflow_operations (
+      operation_id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      operation_type TEXT NOT NULL,
+      idempotency_key TEXT NOT NULL,
+      expected_revision INTEGER NOT NULL CHECK (expected_revision >= 0),
+      resulting_revision INTEGER NOT NULL CHECK (resulting_revision = expected_revision + 1),
+      expected_authority_epoch INTEGER NOT NULL CHECK (expected_authority_epoch >= 0),
+      resulting_authority_epoch INTEGER NOT NULL CHECK (
+        resulting_authority_epoch = expected_authority_epoch OR
+        resulting_authority_epoch = expected_authority_epoch + 1
+      ),
+      actor_type TEXT NOT NULL,
+      actor_id TEXT DEFAULT NULL,
+      source_transport TEXT NOT NULL,
+      trace_id TEXT DEFAULT NULL,
+      turn_id TEXT DEFAULT NULL,
+      request_hash TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      UNIQUE (project_id, idempotency_key),
+      UNIQUE (project_id, resulting_revision),
+      UNIQUE (operation_id, project_id, resulting_revision, resulting_authority_epoch),
+      FOREIGN KEY (project_id) REFERENCES project_authority(project_id)
+    )
+  `);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS workflow_domain_events (
+      event_id TEXT PRIMARY KEY,
+      operation_id TEXT NOT NULL,
+      event_index INTEGER NOT NULL DEFAULT 0 CHECK (event_index >= 0),
+      project_id TEXT NOT NULL,
+      project_revision INTEGER NOT NULL CHECK (project_revision > 0),
+      authority_epoch INTEGER NOT NULL CHECK (authority_epoch >= 0),
+      event_type TEXT NOT NULL,
+      entity_type TEXT NOT NULL,
+      entity_id TEXT NOT NULL,
+      caused_by_event_id TEXT DEFAULT NULL,
+      payload_json TEXT NOT NULL DEFAULT '{}',
+      created_at TEXT NOT NULL,
+      UNIQUE (operation_id, event_index),
+      FOREIGN KEY (operation_id, project_id, project_revision, authority_epoch)
+        REFERENCES workflow_operations(
+          operation_id, project_id, resulting_revision, resulting_authority_epoch
+        ),
+      FOREIGN KEY (caused_by_event_id) REFERENCES workflow_domain_events(event_id)
+    )
+  `);
+
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS trg_workflow_domain_events_immutable_update
+    BEFORE UPDATE ON workflow_domain_events
+    BEGIN
+      SELECT RAISE(ABORT, 'workflow domain events are immutable');
+    END
+  `);
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS trg_workflow_domain_events_immutable_delete
+    BEFORE DELETE ON workflow_domain_events
+    BEGIN
+      SELECT RAISE(ABORT, 'workflow domain events are immutable');
+    END
+  `);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS workflow_outbox (
+      outbox_id INTEGER PRIMARY KEY AUTOINCREMENT,
+      event_id TEXT NOT NULL,
+      destination TEXT NOT NULL,
+      available_at TEXT NOT NULL DEFAULT '',
+      attempt_count INTEGER NOT NULL DEFAULT 0 CHECK (attempt_count >= 0),
+      claimed_by TEXT DEFAULT NULL,
+      claim_expires_at TEXT DEFAULT NULL,
+      delivered_at TEXT DEFAULT NULL,
+      last_error TEXT DEFAULT NULL,
+      UNIQUE (event_id, destination),
+      FOREIGN KEY (event_id) REFERENCES workflow_domain_events(event_id)
+    )
+  `);
+
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_workflow_operations_created
+    ON workflow_operations(project_id, created_at, operation_id)
+  `);
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_workflow_domain_events_entity
+    ON workflow_domain_events(project_id, entity_type, entity_id, project_revision, event_index)
+  `);
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_workflow_outbox_pending
+    ON workflow_outbox(delivered_at, available_at, outbox_id)
+  `);
+
+  db.exec(`
+    INSERT OR IGNORE INTO project_authority (
+      singleton, project_id, project_root_realpath,
+      revision, authority_epoch, created_at, updated_at
+    ) VALUES (
+      1, lower(hex(randomblob(16))), '',
+      0, 0, '', ''
+    )
+  `);
+}

package/src/resources/extensions/gsd/db-migration-steps.ts

@@ -2,6 +2,7 @@
 // File Purpose: Schema migration DDL steps for the GSD database facade.
 
 import type { DbAdapter } from "./db-adapter.js";
+import { createCanonicalFoundationSchemaV31 } from "./db-canonical-foundation-schema.js";
 import { ensureColumn } from "./db-schema-metadata.js";
 
 export function applyMigrationV2Artifacts(db: DbAdapter): void {
@@ -494,3 +495,7 @@ export function applyMigrationV30ReworkBriefs(db: DbAdapter): void {
   db.exec("CREATE INDEX IF NOT EXISTS idx_rework_briefs_task ON rework_briefs(milestone_id, slice_id, task_id)");
   db.exec("CREATE INDEX IF NOT EXISTS idx_rework_findings_status ON rework_brief_findings(brief_id, severity, status)");
 }
+
+export function applyMigrationV31CanonicalFoundation(db: DbAdapter): void {
+  createCanonicalFoundationSchemaV31(db);
+}

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -124,11 +124,11 @@ Diagnostics record the file path, scope (global/project), severity (error/warnin
   - `validation` — used for gate evaluation, roadmap reassessment, milestone validation, and doc rewrites. Falls back to `planning` if unset.
   - `uat` — used for UAT runs. Falls back to `completion` if unset.
 
-- `thinking`: per-phase reasoning effort (ADR-026), separate from `models`. Same phase keys as `models`. Values: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. Thinking travels with the model — model choice and reasoning effort are independent controls, so you can run one model across phases at different reasoning levels.
+- `thinking`: per-phase reasoning effort (ADR-026), separate from `models`. Same phase keys as `models`. Values: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Thinking travels with the model — model choice and reasoning effort are independent controls, so you can run one model across phases at different reasoning levels.
   - Two equivalent ways to set it: inline as `models.<phase>.thinking`, or as a separate `thinking:` block keyed by phase. For the same phase, the inline value wins over the block; project preferences win over global; a phase that's unset inherits via the same sibling chain as `models` (e.g. `discuss → planning`).
   - If no thinking is configured for a phase, the session level (set via `/model`) is used, exactly as before — this is fully backward-compatible.
   - `execute-task` (code-writing) has a measured reasoning floor of `medium`: at lower levels models stop planning edits and thrash on file re-reads. The floor applies to the session/default path. An **explicit** `execution` thinking level bypasses the floor and is honored verbatim (with a one-time advisory) — set `execution: low` deliberately if you want it.
-  - Levels a model can't support are clamped to the nearest supported level at dispatch and never sent to the provider, so a model/level mismatch never fails a unit mid-run. `xhigh` support is model-dependent; current examples include OpenAI Codex Max models and Claude Sonnet 5 on Amazon Bedrock.
+  - Levels a model can't support are clamped to the nearest supported level at dispatch and never sent to the provider, so a model/level mismatch never fails a unit mid-run. `xhigh` and `max` support are model-dependent; current examples include `gpt-5.6-sol`, `gpt-5.6-terra`, and `gpt-5.6-luna`, which advertise both.
 
 - `skill_staleness_days`: number — skills unused for this many days get deprioritized during discovery. Set to `0` to disable staleness tracking. Default: `60`.
 
@@ -357,24 +357,33 @@ In `"parent"` mode, slice/task `targetRepositories` default to the declared chil
   - `"replace"` requires `prompt`.
   - `"skip"` is valid with no additional fields.
 
+- `planning_subagent_registry`: object — optional classification for custom planning agents. Each key is an agent id and must set:
+  - `read_only_specialist`: boolean — set to `true` to classify the custom agent as safe for planning dispatch.
+
 - `planning_subagents`: object — project-local widening for read-only planning subagent dispatch. Supported unit keys are `plan-milestone` and `plan-slice`; each has:
   - `allowed`: string[] — additional planning-safe agents for that unit.
 
-  Agents must already be classified by GSD as read-only planning specialists: `mnemo`, `scout`, `planner`, `reviewer`, `security`, or `tester`. The write gate still blocks source writes outside `.gsd/**`, unrestricted bash, stale subagent calls without agent identities, agents outside the global read-only registry, and agents not listed for the active unit.
+  Agents must be built-in read-only planning specialists (`mnemo`, `scout`, `planner`, `reviewer`, `security`, or `tester`) or registered in `planning_subagent_registry` with `read_only_specialist: true`. The write gate still blocks source writes outside `.gsd/**`, unrestricted bash, stale subagent calls without agent identities, agents outside the read-only registry, and agents not listed for the active unit.
 
   Example:
 
   ```yaml
+  planning_subagent_registry:
+    my-custom-planner:
+      read_only_specialist: true
+
   planning_subagents:
     plan-milestone:
       allowed:
         - scout
         - planner
+        - my-custom-planner
         - security
     plan-slice:
       allowed:
         - scout
         - planner
+        - my-custom-planner
         - reviewer
         - security
   ```

package/src/resources/extensions/gsd/doctor-engine-checks.ts

@@ -32,6 +32,7 @@ import { parseRoadmapSlices } from "./roadmap-slices.js";
 import { parsePlan } from "./parsers-legacy.js";
 import { parseSummary } from "./files.js";
 import { LAYOUT_SEGMENTS } from "./layout-policy.js";
+import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 
 const USER_AUTHORED_ARTIFACT_TYPES = new Set(["CONTEXT", "RESEARCH"]);
 
@@ -116,7 +117,8 @@ function checkboxDbStatusMilestoneIds(basePath: string, milestoneIds: string[]):
 
 function checkProjectionCheckboxDbStatus(basePath: string, milestoneIds: string[], issues: DoctorIssue[]): void {
   for (const milestoneId of milestoneIds) {
-    const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+    const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, milestoneId);
+    const roadmapPath = resolveMilestoneFile(artifactBasePath, milestoneId, "ROADMAP");
     const slices = getMilestoneSlices(milestoneId);
 
     if (roadmapPath && existsSync(roadmapPath)) {
@@ -142,7 +144,7 @@ function checkProjectionCheckboxDbStatus(basePath: string, milestoneIds: string[
     }
 
     for (const slice of slices) {
-      const planPath = resolveSliceFile(basePath, milestoneId, slice.id, "PLAN");
+      const planPath = resolveSliceFile(artifactBasePath, milestoneId, slice.id, "PLAN");
       if (!planPath || !existsSync(planPath)) continue;
       try {
         const plan = readFileSync(planPath, "utf-8");
@@ -192,7 +194,7 @@ function artifactExistsOnDisk(basePath: string, artifactPath: string, row?: Arti
   return resolveArtifactDiskPath(basePath, artifactPath, row) !== null;
 }
 
-function resolveLiteralArtifactDiskPath(basePath: string, artifactPath: string): string | null {
+function resolveLiteralArtifactDiskPath(basePath: string, artifactPath: string, row?: ArtifactRow): string | null {
   const relativeArtifactPath = artifactPathRelativeToGsd(artifactPath);
   if (isAbsolute(relativeArtifactPath)) {
     return existsSync(relativeArtifactPath) ? relativeArtifactPath : null;
@@ -201,6 +203,15 @@ function resolveLiteralArtifactDiskPath(basePath: string, artifactPath: string):
     const candidate = join(root, relativeArtifactPath);
     if (isPathInside(root, candidate) && existsSync(candidate)) return candidate;
   }
+  if (row?.milestone_id) {
+    const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, row.milestone_id);
+    if (artifactBasePath !== basePath) {
+      for (const root of [gsdProjectionRoot(artifactBasePath), gsdRoot(artifactBasePath)]) {
+        const candidate = join(root, relativeArtifactPath);
+        if (isPathInside(root, candidate) && existsSync(candidate)) return candidate;
+      }
+    }
+  }
   return null;
 }
 
@@ -243,7 +254,7 @@ function resolveArtifactDiskPath(basePath: string, artifactPath: string, row?: A
     const flatPath = resolveFlatPhaseArtifactDiskPath(basePath, row);
     if (flatPath) return flatPath;
   }
-  return resolveLiteralArtifactDiskPath(basePath, artifactPath);
+  return resolveLiteralArtifactDiskPath(basePath, artifactPath, row);
 }
 
 function taskExistsInPlan(basePath: string, milestoneId: string, sliceId: string, taskId: string): boolean {

package/src/resources/extensions/gsd/model-cost-table.ts

@@ -12,6 +12,12 @@ export interface ModelCostEntry {
   inputPer1k: number;
   /** Approximate cost per 1K output tokens in USD */
   outputPer1k: number;
+  /** Input-token-based long-context pricing tiers, when published */
+  tiers?: Array<{
+    inputTokensAbove: number;
+    inputPer1k: number;
+    outputPer1k: number;
+  }>;
   /** Last updated date */
   updatedAt: string;
 }
@@ -62,8 +68,9 @@ export const BUNDLED_COST_TABLE: ModelCostEntry[] = [
   // GPT-5.5 API list price, also used for live Codex OAuth routing.
   // Source: https://openai.com/api/pricing/
   { id: "gpt-5.5", inputPer1k: 0.005, outputPer1k: 0.03, updatedAt: "2026-04-23" },
-  // Mirrors gpt-5.5 list pricing until OpenAI publishes official gpt-5.6 pricing.
-  { id: "gpt-5.6", inputPer1k: 0.005, outputPer1k: 0.03, updatedAt: "2026-07-08" },
+  { id: "gpt-5.6-sol", inputPer1k: 0.005, outputPer1k: 0.03, tiers: [{ inputTokensAbove: 272000, inputPer1k: 0.01, outputPer1k: 0.045 }], updatedAt: "2026-07-11" },
+  { id: "gpt-5.6-terra", inputPer1k: 0.0025, outputPer1k: 0.015, tiers: [{ inputTokensAbove: 272000, inputPer1k: 0.005, outputPer1k: 0.0225 }], updatedAt: "2026-07-11" },
+  { id: "gpt-5.6-luna", inputPer1k: 0.001, outputPer1k: 0.006, tiers: [{ inputTokensAbove: 272000, inputPer1k: 0.002, outputPer1k: 0.009 }], updatedAt: "2026-07-11" },
 
   // Google
   { id: "gemini-2.0-flash", inputPer1k: 0.0001, outputPer1k: 0.0004, updatedAt: "2025-03-15" },
@@ -80,7 +87,11 @@ export const BUNDLED_COST_TABLE: ModelCostEntry[] = [
 export function lookupModelCost(modelId: string): ModelCostEntry | undefined {
   const bareId = modelId.includes("/") ? modelId.split("/").pop()! : modelId;
   return BUNDLED_COST_TABLE.find(e => e.id === bareId)
-    ?? BUNDLED_COST_TABLE.find(e => bareId.includes(e.id) || e.id.includes(bareId));
+    ?? BUNDLED_COST_TABLE.find(e =>
+      bareId.startsWith(`${e.id}-`) ||
+      bareId.startsWith(`${e.id}:`) ||
+      bareId.startsWith(`${e.id}@`)
+    );
 }
 
 /**

package/src/resources/extensions/gsd/model-router.ts

@@ -111,7 +111,9 @@ export const MODEL_CAPABILITY_TIER: Record<string, ComplexityTier> = {
   "gpt-5.3-codex": "heavy",
   "gpt-5.4": "heavy",
   "gpt-5.5": "heavy",
-  "gpt-5.6": "heavy",
+  "gpt-5.6-sol": "heavy",
+  "gpt-5.6-terra": "heavy",
+  "gpt-5.6-luna": "heavy",
   "o1": "heavy",
   "o3": "heavy",
   "o4-mini": "heavy",
@@ -151,7 +153,9 @@ const MODEL_COST_PER_1K_INPUT: Record<string, number> = {
   "gpt-5.3-codex-spark": 0.0003,
   "gpt-5.4": 0.005,
   "gpt-5.5": 0.005,
-  "gpt-5.6": 0.005,
+  "gpt-5.6-sol": 0.005,
+  "gpt-5.6-terra": 0.0025,
+  "gpt-5.6-luna": 0.001,
   "o4-mini": 0.005,
   "o4-mini-deep-research": 0.005,
   "gemini-2.0-flash": 0.0001,
@@ -202,9 +206,10 @@ export const MODEL_CAPABILITY_PROFILES: Record<string, ModelCapabilities> = {
   // OpenAI's 2026-04-23 published eval deltas across coding, tool use, and long context.
   // Source: https://openai.com/index/introducing-gpt-5-5/
   "gpt-5.5":                      { coding: 96, debugging: 93, research: 89, reasoning: 95, speed: 42, longContext: 90, instruction: 93 },
-  // GPT-5.6 profile is provisional: a small uniform step over gpt-5.5, to be
-  // recalibrated once OpenAI publishes official eval results.
-  "gpt-5.6":                      { coding: 97, debugging: 94, research: 90, reasoning: 96, speed: 42, longContext: 91, instruction: 94 },
+  // GPT-5.6 profiles are provisional until official eval results are available.
+  "gpt-5.6-sol":                  { coding: 97, debugging: 94, research: 90, reasoning: 96, speed: 42, longContext: 91, instruction: 94 },
+  "gpt-5.6-terra":                { coding: 96, debugging: 93, research: 89, reasoning: 95, speed: 48, longContext: 91, instruction: 93 },
+  "gpt-5.6-luna":                 { coding: 92, debugging: 88, research: 84, reasoning: 91, speed: 72, longContext: 91, instruction: 90 },
 
   // ── OpenAI o-series (reasoning-first) ──────────────────────────────────────
   "o1":                           { coding: 78, debugging: 82, research: 78, reasoning: 90, speed: 20, longContext: 65, instruction: 82 },

package/src/resources/extensions/gsd/planning-subagent-registry.ts

@@ -6,6 +6,8 @@
  * preference validation before any configured planning allowlist takes effect.
  */
 
+import type { PlanningSubagentRegistryConfig } from "./preferences-types.js";
+
 const PLANNING_DISPATCH_AGENT_REGISTRY = {
   mnemo: { readOnlySpecialist: true },
   scout: { readOnlySpecialist: true },
@@ -21,11 +23,23 @@ export const ALLOWED_PLANNING_DISPATCH_AGENTS = new Set<string>(
     .map(([agentId]) => agentId),
 );
 
-export function isReadOnlyPlanningDispatchAgent(agentId: string): boolean {
+function configuredPlanningDispatchAgents(registry?: PlanningSubagentRegistryConfig): string[] {
+  return Object.entries(registry ?? {})
+    .filter(([, metadata]) => metadata.read_only_specialist === true)
+    .map(([agentId]) => agentId);
+}
+
+export function isReadOnlyPlanningDispatchAgent(
+  agentId: string,
+  registry?: PlanningSubagentRegistryConfig,
+): boolean {
   const metadata = PLANNING_DISPATCH_AGENT_REGISTRY[agentId as keyof typeof PLANNING_DISPATCH_AGENT_REGISTRY];
-  return metadata?.readOnlySpecialist === true;
+  return metadata?.readOnlySpecialist === true || registry?.[agentId]?.read_only_specialist === true;
 }
 
-export function allowedPlanningDispatchAgentsList(): string {
-  return [...ALLOWED_PLANNING_DISPATCH_AGENTS].join(", ");
+export function allowedPlanningDispatchAgentsList(registry?: PlanningSubagentRegistryConfig): string {
+  return Array.from(new Set([
+    ...ALLOWED_PLANNING_DISPATCH_AGENTS,
+    ...configuredPlanningDispatchAgents(registry),
+  ])).join(", ");
 }

package/src/resources/extensions/gsd/preferences-models.ts

@@ -9,6 +9,7 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { getProviders } from "@gsd/pi-ai";
 import { gsdHome } from "./gsd-home.js";
 import type { DynamicRoutingConfig } from "./model-router.js";
 import { canonicalModelForTier, defaultRoutingConfig, resolveModelForTier } from "./model-router.js";
@@ -31,6 +32,33 @@ import { getUnitPhaseChain } from "./unit-registry.js";
 // Re-export types so existing consumers of ./preferences-models.js keep working
 export type { GSDPhaseModelConfig, GSDModelConfig, GSDModelConfigV2, ResolvedModelConfig } from "./preferences-types.js";
 
+type ProviderModelRegistry = {
+  getAll?: () => ReadonlyArray<{ provider: string }>;
+  getAvailable?: () => ReadonlyArray<{ provider: string }>;
+  getAllWithDiscovered?: () => ReadonlyArray<{ provider: string }>;
+};
+
+/**
+ * First-party providers shipped as bundled extensions that delegate to a
+ * vendor CLI (`authMode: "externalCli"`). They are registered into the live
+ * model registry at runtime, so they are absent from the generated `@gsd/pi-ai`
+ * catalog (`getProviders()`), but they are NOT custom: `PREFERENCES.md` can
+ * route to them, so they must defer to `PREFERENCES.md` like any other built-in
+ * provider. Without this exclusion the registry check below would classify the
+ * default `claude-code` provider (and the other CLI providers) as custom and
+ * silently skip `PREFERENCES.md` in auto-mode (#801, extends #4122).
+ *
+ * Kept in sync with the `registerProvider(...)` calls in the bundled CLI
+ * extensions (claude-code-cli, cursor-cli, google-cli). Names are lowercase for
+ * direct comparison against normalized provider ids.
+ */
+const BUILTIN_EXTENSION_PROVIDERS: ReadonlySet<string> = new Set([
+  "claude-code",
+  "cursor-agent",
+  "google-gemini-cli",
+  "google-antigravity",
+]);
+
 /**
  * Resolve which model ID to use for a given auto-mode unit type.
  * Returns undefined if no model preference is set for this unit type.
@@ -321,9 +349,8 @@ export function resolveDefaultSessionModel(
 }
 
 /**
- * Returns true if `provider` is defined as a custom provider in the user's
- * `~/.gsd/agent/models.json` (Ollama, vLLM, LM Studio, OpenAI-compatible
- * proxies, etc.).
+ * Returns true if `provider` is a custom provider. Custom providers may be
+ * declared in `models.json` or registered dynamically by a Pi extension.
  *
  * Used by auto-mode bootstrap to decide whether the session model
  * (set via `/gsd model`) should override `PREFERENCES.md`.  Custom providers
@@ -332,13 +359,16 @@ export function resolveDefaultSessionModel(
  * priority — otherwise auto-mode tries to start the built-in provider from
  * PREFERENCES.md and fails with "Not logged in · Please run /login" (#4122).
  *
- * Reads models.json directly with a lightweight JSON parse to avoid
- * pulling in the full model-registry at this call site.  Falls back to
- * `~/.pi/agent/models.json` for parity with `resolveModelsJsonPath()`.
- * Any read or parse error yields `false` (treat as not-custom) so a
- * malformed models.json never breaks the session bootstrap.
+ * Reads models.json directly with a lightweight JSON parse, then checks the
+ * live model registry for extension-registered providers that are not in the
+ * generated built-in provider catalog (`getProviders()`) and not one of the
+ * bundled external-CLI providers (`BUILTIN_EXTENSION_PROVIDERS`, e.g.
+ * `claude-code`), which register at runtime but are still built-in.  Falls back
+ * to `~/.pi/agent/models.json` for parity with `resolveModelsJsonPath()`. Any
+ * read, parse, or registry error yields `false` (treat as not-custom) so
+ * bootstrap stays non-fatal.
  */
-export function isCustomProvider(provider: string | undefined): boolean {
+export function isCustomProvider(provider: string | undefined, registry?: ProviderModelRegistry): boolean {
   if (!provider) return false;
   const candidates = [
     join(gsdHome(), "agent", "models.json"),
@@ -356,7 +386,21 @@ export function isCustomProvider(provider: string | undefined): boolean {
       // Ignore — malformed models.json must not break bootstrap.
     }
   }
-  return false;
+  try {
+    const normalizedProvider = provider.trim().toLowerCase();
+    if (!normalizedProvider) return false;
+    if (BUILTIN_EXTENSION_PROVIDERS.has(normalizedProvider)) return false;
+    const builtInProviders = new Set(getProviders().map((p) => p.toLowerCase()));
+    if (builtInProviders.has(normalizedProvider)) return false;
+    const registryModels =
+      registry?.getAllWithDiscovered?.()
+      ?? registry?.getAll?.()
+      ?? registry?.getAvailable?.()
+      ?? [];
+    return registryModels.some((m) => m.provider.toLowerCase() === normalizedProvider);
+  } catch {
+    return false;
+  }
 }
 
 /**

package/src/resources/extensions/gsd/preferences-types.ts

@@ -141,6 +141,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "git",
   "post_unit_hooks",
   "pre_dispatch_hooks",
+  "planning_subagent_registry",
   "planning_subagents",
   "dynamic_routing",
   "disabled_model_providers",
@@ -232,6 +233,12 @@ export type PlanningSubagentsConfig = Partial<
   Record<ConfigurablePlanningSubagentUnit, PlanningSubagentUnitConfig>
 >;
 
+export interface PlanningSubagentRegistryEntry {
+  read_only_specialist?: boolean;
+}
+
+export type PlanningSubagentRegistryConfig = Record<string, PlanningSubagentRegistryEntry>;
+
 
 export const SKILL_ACTIONS = new Set(["use", "prefer", "avoid"]);
 
@@ -245,10 +252,10 @@ export interface GSDSkillRule {
 /**
  * Reasoning effort levels. Mirrors `ThinkingLevel` in `@gsd/pi-agent-core`;
  * declared locally so preference parsing/validation does not import the agent
- * core package. `xhigh` is only honored by models whose `thinkingLevelMap`
+ * core package. `xhigh` and `max` are only honored by models whose `thinkingLevelMap`
  * advertises it — unsupported levels are clamped at dispatch (ADR-026).
  */
-export type GSDThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+export type GSDThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 
 /** The nine model-routing phase buckets. */
 export const GSD_MODEL_PHASE_KEYS = [
@@ -491,6 +498,7 @@ export interface GSDPreferences {
   git?: GitPreferences;
   post_unit_hooks?: PostUnitHookConfig[];
   pre_dispatch_hooks?: PreDispatchHookConfig[];
+  planning_subagent_registry?: PlanningSubagentRegistryConfig;
   planning_subagents?: PlanningSubagentsConfig;
   dynamic_routing?: DynamicRoutingConfig;
   /** Provider IDs to exclude from /model and automatic model routing while leaving tool auth intact. */

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -28,8 +28,8 @@ import {
   type GSDThinkingLevel,
 } from "./preferences-types.js";
 import {
-  ALLOWED_PLANNING_DISPATCH_AGENTS,
   allowedPlanningDispatchAgentsList,
+  isReadOnlyPlanningDispatchAgent,
 } from "./planning-subagent-registry.js";
 
 const VALID_TOKEN_PROFILES = new Set<TokenProfile>(["budget", "balanced", "quality", "burn-max"]);
@@ -40,6 +40,7 @@ const VALID_THINKING_LEVELS = new Set<GSDThinkingLevel>([
   "medium",
   "high",
   "xhigh",
+  "max",
 ]);
 const KNOWN_MODEL_PHASE_KEYS = new Set<string>(GSD_MODEL_PHASE_KEYS);
 const VALID_UOK_TURN_ACTIONS = new Set<"commit" | "snapshot" | "status-only">([
@@ -93,7 +94,7 @@ function sanitizeModelField(
       } else {
         warnings?.push(
           `${label} thinking "${String(obj.thinking)}" is not a valid thinking level ` +
-          `(off, minimal, low, medium, high, xhigh) — ignored`,
+          `(off, minimal, low, medium, high, xhigh, max) — ignored`,
         );
       }
     }
@@ -486,7 +487,7 @@ export function validatePreferences(preferences: GSDPreferences): {
           if (level !== undefined && !VALID_THINKING_LEVELS.has(level as GSDThinkingLevel)) {
             warnings.push(
               `models.${phase}.thinking "${String(level)}" is not a valid thinking level ` +
-              `(off, minimal, low, medium, high, xhigh) — ignored`,
+              `(off, minimal, low, medium, high, xhigh, max) — ignored`,
             );
             const { thinking: _ignored, ...rest } = entry as Record<string, unknown>;
             // If stripping the bad thinking leaves no usable model, drop the
@@ -521,7 +522,7 @@ export function validatePreferences(preferences: GSDPreferences): {
         if (!VALID_THINKING_LEVELS.has(level as GSDThinkingLevel)) {
           warnings.push(
             `thinking.${phase} "${String(level)}" is not a valid thinking level ` +
-            `(off, minimal, low, medium, high, xhigh) — ignored`,
+            `(off, minimal, low, medium, high, xhigh, max) — ignored`,
           );
           continue;
         }
@@ -752,6 +753,46 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Planning Subagent Registry ──────────────────────────────────────────
+  if (preferences.planning_subagent_registry !== undefined) {
+    if (
+      !preferences.planning_subagent_registry ||
+      typeof preferences.planning_subagent_registry !== "object" ||
+      Array.isArray(preferences.planning_subagent_registry)
+    ) {
+      errors.push("planning_subagent_registry must be an object keyed by agent id");
+    } else {
+      const validRegistry: NonNullable<GSDPreferences["planning_subagent_registry"]> = {};
+
+      for (const [rawAgentId, rawConfig] of Object.entries(preferences.planning_subagent_registry as Record<string, unknown>)) {
+        const agentId = rawAgentId.trim();
+        if (!agentId) {
+          errors.push("planning_subagent_registry includes an empty agent id");
+          continue;
+        }
+        if (!rawConfig || typeof rawConfig !== "object" || Array.isArray(rawConfig)) {
+          errors.push(`planning_subagent_registry.${agentId} must be an object with read_only_specialist: true`);
+          continue;
+        }
+
+        const readOnlySpecialist = (rawConfig as Record<string, unknown>).read_only_specialist;
+        if (readOnlySpecialist !== true) {
+          errors.push(
+            `planning_subagent_registry.${agentId}.read_only_specialist must be true to classify ` +
+            `"${agentId}" as a read-only planning specialist`,
+          );
+          continue;
+        }
+
+        validRegistry[agentId] = { read_only_specialist: true };
+      }
+
+      if (Object.keys(validRegistry).length > 0) {
+        validated.planning_subagent_registry = validRegistry;
+      }
+    }
+  }
+
   // ─── Planning Subagents ─────────────────────────────────────────────────
   if (preferences.planning_subagents !== undefined) {
     if (
@@ -785,10 +826,12 @@ export function validatePreferences(preferences: GSDPreferences): {
 
         const sanitizedAllowed: string[] = [];
         for (const agentId of allowed) {
-          if (!ALLOWED_PLANNING_DISPATCH_AGENTS.has(agentId)) {
+          if (!isReadOnlyPlanningDispatchAgent(agentId, validated.planning_subagent_registry)) {
             errors.push(
               `planning_subagents.${unitType}.allowed includes "${agentId}", which is not classified as a ` +
-              `read-only planning specialist. Allowed agents: ${allowedPlanningDispatchAgentsList()}`,
+              `read-only planning specialist. Allowed agents: ` +
+              `${allowedPlanningDispatchAgentsList(validated.planning_subagent_registry)}. ` +
+              `For custom planning agents, add planning_subagent_registry.${agentId}.read_only_specialist: true`,
             );
             continue;
           }

package/src/resources/extensions/gsd/preferences.ts

@@ -817,6 +817,10 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
       : undefined,
     post_unit_hooks: mergePostUnitHooks(base.post_unit_hooks, override.post_unit_hooks),
     pre_dispatch_hooks: mergePreDispatchHooks(base.pre_dispatch_hooks, override.pre_dispatch_hooks),
+    planning_subagent_registry: mergePlanningSubagentRegistry(
+      base.planning_subagent_registry,
+      override.planning_subagent_registry,
+    ),
     planning_subagents: mergePlanningSubagents(base.planning_subagents, override.planning_subagents),
     dynamic_routing: (base.dynamic_routing || override.dynamic_routing)
       ? { ...(base.dynamic_routing ?? {}), ...(override.dynamic_routing ?? {}) } as DynamicRoutingConfig
@@ -968,6 +972,15 @@ function mergePlanningSubagents(
   return Object.keys(merged).length > 0 ? merged : undefined;
 }
 
+function mergePlanningSubagentRegistry(
+  base?: GSDPreferences["planning_subagent_registry"],
+  override?: GSDPreferences["planning_subagent_registry"],
+): GSDPreferences["planning_subagent_registry"] | undefined {
+  if (!base && !override) return undefined;
+  const merged = { ...(base ?? {}), ...(override ?? {}) };
+  return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
 // ─── System Prompt Rendering ──────────────────────────────────────────────────
 
 export function renderPreferencesForSystemPrompt(

package/src/resources/extensions/gsd/templates/PREFERENCES.md

@@ -92,6 +92,9 @@ remote_questions:
 uat_dispatch:
 post_unit_hooks: []
 pre_dispatch_hooks: []
+# planning_subagent_registry:
+#   my-custom-planner:
+#     read_only_specialist: true
 # planning_subagents:
 #   plan-milestone:
 #     allowed: [scout, planner, security]