@pi-ohm/subagents 0.6.4-dev.22319043817.1.ac398fc → 0.6.4-dev.22329800727.1.c214423

package/README.md

@@ -102,6 +102,63 @@ Per-subagent model override is supported via `ohm.json`:
 - SDK backend validates against Pi model registry (built-ins + custom `models.json`)
 - interactive-shell backend forwards the same `--model` pattern to nested `pi`
 
+Subagent runtime profiles now support prompt/description/usage overrides, custom
+subagent entries, and wildcard variants:
+
+```jsonc
+{
+  "subagents": {
+    "librarian": {
+      "model": "openai/gpt-5.3-codex:medium",
+      "prompt": "{file:./prompts/librarian.general.txt}",
+      "description": "Optional summary override",
+      "whenToUse": ["Optional guidance override"],
+    },
+    "my-custom-agent": {
+      "model": "openai/gpt-5.3-codex:medium",
+      "prompt": "{file:./prompts/my-custom-agent.general.txt}",
+      "description": "Custom delegated helper",
+      "whenToUse": ["Use for custom workflows"],
+      "permissions": {
+        "bash": "allow",
+        "edit": "deny",
+      },
+      "variants": {
+        "*gemini*": {
+          "model": "github-copilot/gemini-3.1-pro-preview:high",
+          "prompt": "{file:./prompts/my-custom-agent.gemini.txt}",
+          "permissions": {
+            "edit": "inherit",
+            "apply_patch": "deny",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Variant matching rules:
+
+- variant keys are wildcard matchers (for example `*gemini*`)
+- match target is normalized model pattern + model token (provider is optional)
+- first matching variant wins
+- variant fields override base profile fields (`model`, `prompt`, `description`, `whenToUse`)
+- permissions support `allow|deny|inherit` (inherit falls back to base profile map)
+
+Prompt file references:
+
+- prompt fields support `{file:...}` references
+- relative paths resolve from task `cwd` first, then Pi config dir fallback
+
+Built-in prompt management:
+
+- catalog metadata (`packages/subagents/src/catalog.ts`) is now display/orchestration metadata for
+  main-agent exposure (name/description/when-to-use/invocation)
+- execution prompt text is resolved separately
+- built-in execution prompts are file-backed under `packages/subagents/src/runtime/backend/prompts/*`
+- built-in variant selection uses wildcard model keys (`*gemini*`, `*gpt*`, `*claude*`)
+
 ## Dynamic prompt profile routing
 
 SDK prompt profile selection is runtime-driven and deterministic:
@@ -259,6 +316,16 @@ H7-004 provider-add repro demo (config-only mapping + end-to-end validation):
 yarn test:subagents --test-name-pattern "new provider mapping can be added via rules"
 ```
 
+System prompt harness snapshots:
+
+```bash
+# verify full main-agent + subagent-sdk prompt/tool snapshots
+yarn test:subagents:golden
+
+# regenerate snapshot goldens from current code
+yarn test:subagents:golden:update
+```
+
 ### 3.2) Provider onboarding playbook (no core router edits)
 
 1. Add a rule in `ohm.providers.json` under `subagents.promptProfiles.rules`:

package/dist/extension.d.ts

@@ -6,10 +6,13 @@ import { z } from "zod";
 
 //#region src/catalog.d.ts
 type OhmSubagentId = "librarian" | "oracle" | "finder" | "task" | "painter";
+type OhmSubagentIdentifier = OhmSubagentId | (string & {});
 interface OhmSubagentDefinition {
-  id: OhmSubagentId;
+  id: OhmSubagentIdentifier;
   name: string;
-  summary: string;
+  description?: string;
+  /** @deprecated use description */
+  summary?: string;
   /**
    * When true, this profile should be exposed as a directly invokable primary tool
    * instead of requiring delegated Task-style invocation.
@@ -20,11 +23,14 @@ interface OhmSubagentDefinition {
    * policy explicitly allows internal routing.
    */
   internal?: boolean;
-  whenToUse: string[];
-  scaffoldPrompt: string;
+  whenToUse: readonly string[];
+  whenNotToUse?: readonly string[];
+  usageGuidelines?: readonly string[];
+  examples?: readonly string[];
+  /** @deprecated execution prompt now resolves outside catalog */
+  scaffoldPrompt?: string;
   requiresPackage?: string;
 }
-declare const OHM_SUBAGENT_CATALOG: readonly OhmSubagentDefinition[];
 //#endregion
 //#region src/runtime/live-ui.d.ts
 type TaskLiveUiMode = "off" | "compact" | "verbose";
@@ -39,7 +45,7 @@ declare function buildSubagentsOverviewText(input: {
 }): string;
 declare function buildSubagentDetailText(input: {
   readonly config: OhmRuntimeConfig;
-  readonly subagent: (typeof OHM_SUBAGENT_CATALOG)[number];
+  readonly subagent: OhmSubagentDefinition;
 }): string;
 interface ResolveSubagentsLiveUiModeResult {
   readonly ok: boolean;