@heretek-ai/epistemic-swarm 0.7.6 → 0.7.8

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "epistemic-swarm",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "description": "High-Integrity Dialectic Research Agent Harness for Claude Code enforcing empirical evidence over parametric hallucination.",
   "author": {
     "name": "Heretek AI",

package/config/opencode-snippet.json

@@ -1,10 +1,12 @@
 {
   "$schema": "https://opencode.ai/config.json",
   "mcp": {
-    "iumbtems": {
-      "type": "local",
-      "command": ["python3", "<IUMBTEMS_ROOT>/runner/mcp_server.py"],
-      "enabled": true
+    "servers": {
+      "iumbtems": {
+        "type": "local",
+        "command": ["python3", "<IUMBTEMS_ROOT>/runner/mcp_server.py"],
+        "enabled": true
+      }
     }
   },
   "plugins": [
@@ -17,187 +19,138 @@
       }
     }
   ],
-  "agent": {
+  "agents": {
     "code-auditor": {
       "description": "IUMBTEMS Codebase Auditor: Dialectic architecture mapping and vulnerability red-teaming with line-level proof.",
-      "tools": {
-        "read": true,
-        "write": true,
-        "grep": true,
-        "glob": true,
-        "iumbtems_code_audit": true,
-        "iumbtems_config": true
-      }
+      "mode": "all",
+      "permissions": [
+        { "action": "read", "resource": "*", "effect": "allow" },
+        { "action": "grep", "resource": "*", "effect": "allow" },
+        { "action": "glob", "resource": "*", "effect": "allow" },
+        { "action": "edit", "resource": "*", "effect": "allow" },
+        { "action": "shell", "resource": "*", "effect": "ask" }
+      ]
     },
     "oss-scout": {
       "description": "IUMBTEMS Open Source Scout: Discovers mature OSS packages, audits copyleft licensing, and generates clean-room blueprints.",
-      "tools": {
-        "read": true,
-        "write": true,
-        "grep": true,
-        "glob": true,
-        "iumbtems_oss_scout": true,
-        "iumbtems_config": true
-      }
+      "mode": "all",
+      "permissions": [
+        { "action": "read", "resource": "*", "effect": "allow" },
+        { "action": "grep", "resource": "*", "effect": "allow" },
+        { "action": "glob", "resource": "*", "effect": "allow" },
+        { "action": "edit", "resource": "*", "effect": "allow" },
+        { "action": "shell", "resource": "*", "effect": "ask" }
+      ]
     },
     "alpha-thesis": {
       "description": "IUMBTEMS Proponent Agent: Gathers corroborating primary sources, benchmark results, and empirical proofs.",
-      "tools": {
-        "bash": true,
-        "read": true,
-        "write": true,
-        "grep": true,
-        "glob": true,
-        "task": true,
-        "iumbtems_swarm_research": true,
-        "iumbtems_verify_quote": true,
-        "iumbtems_config": true
-      }
+      "mode": "all",
+      "permissions": [
+        { "action": "read", "resource": "*", "effect": "allow" },
+        { "action": "grep", "resource": "*", "effect": "allow" },
+        { "action": "glob", "resource": "*", "effect": "allow" },
+        { "action": "edit", "resource": "*", "effect": "allow" },
+        { "action": "shell", "resource": "*", "effect": "ask" },
+        { "action": "subagent", "resource": "*", "effect": "allow" }
+      ]
     },
     "beta-redteam": {
       "description": "IUMBTEMS Adversary Agent: Active falsification, red-teaming, hunting for counter-benchmarks, and edge-case failure modes.",
-      "tools": {
-        "bash": true,
-        "read": true,
-        "write": true,
-        "grep": true,
-        "glob": true,
-        "task": true,
-        "iumbtems_swarm_research": true,
-        "iumbtems_verify_quote": true
-      }
+      "mode": "all",
+      "permissions": [
+        { "action": "read", "resource": "*", "effect": "allow" },
+        { "action": "grep", "resource": "*", "effect": "allow" },
+        { "action": "glob", "resource": "*", "effect": "allow" },
+        { "action": "edit", "resource": "*", "effect": "allow" },
+        { "action": "shell", "resource": "*", "effect": "ask" },
+        { "action": "subagent", "resource": "*", "effect": "allow" }
+      ]
     },
     "epistemic-auditor": {
       "description": "IUMBTEMS Synthesizer & Auditor: Verifies verbatim source quotes, downgrades unverified claims, and calculates divergence.",
-      "tools": {
-        "read": true,
-        "write": true,
-        "grep": true,
-        "glob": true,
-        "iumbtems_verify_quote": true
-      }
+      "mode": "all",
+      "permissions": [
+        { "action": "read", "resource": "*", "effect": "allow" },
+        { "action": "grep", "resource": "*", "effect": "allow" },
+        { "action": "glob", "resource": "*", "effect": "allow" },
+        { "action": "edit", "resource": "*", "effect": "allow" }
+      ]
     },
     "brainstormer": {
       "description": "IUMBTEMS Lateral Brainstormer: divergent what-if features, paradigm inversions, falsifiable spikes (never bug fixes).",
-      "tools": {
-        "read": true,
-        "write": true,
-        "grep": true,
-        "glob": true,
-        "iumbtems_brainstorm": true,
-        "iumbtems_config": true
-      }
+      "mode": "all",
+      "permissions": [
+        { "action": "read", "resource": "*", "effect": "allow" },
+        { "action": "grep", "resource": "*", "effect": "allow" },
+        { "action": "glob", "resource": "*", "effect": "allow" },
+        { "action": "edit", "resource": "*", "effect": "allow" }
+      ]
     },
     "darkharvester": {
       "description": "IUMBTEMS Competitor Teardown: seed plus expand, product plus code matrix, per-feature harvest verdicts with SPDX attribution.",
-      "tools": {
-        "read": true,
-        "write": true,
-        "grep": true,
-        "glob": true,
-        "iumbtems_darkharvest": true,
-        "iumbtems_verify_quote": true,
-        "iumbtems_config": true
-      }
+      "mode": "all",
+      "permissions": [
+        { "action": "read", "resource": "*", "effect": "allow" },
+        { "action": "grep", "resource": "*", "effect": "allow" },
+        { "action": "glob", "resource": "*", "effect": "allow" },
+        { "action": "edit", "resource": "*", "effect": "allow" }
+      ]
     },
     "manager": {
       "description": "IUMBTEMS Factory Manager: grill-gated phased builds. Owns gates, swarm dispatch, roadmap synthesis, QA tiebreaks. Never writes code.",
       "mode": "primary",
-      "temperature": 0.2,
-      "permission": {
-        "edit": "deny",
-        "bash": "ask",
-        "task": {
-          "*": "deny",
-          "factory-*": "allow",
-          "programmer": "allow",
-          "qa-a": "allow",
-          "qa-b": "allow",
-          "brainstormer": "allow",
-          "darkharvester": "allow"
-        }
-      },
-      "tools": {
-        "read": true,
-        "write": true,
-        "grep": true,
-        "glob": true,
-        "task": true,
-        "iumbtems_brainstorm": true,
-        "iumbtems_darkharvest": true,
-        "iumbtems_verify_quote": true,
-        "iumbtems_socratic_frontier": true,
-        "iumbtems_config": true
-      }
+      "system": "You are the IUMBTEMS Factory Manager. Own gate discipline: grill until the frontier is settled, run the brainstorm and darkharvest swarms, synthesize .roadmap phase dossiers, spawn the programmer per phase, run qa-a and qa-b, and tiebreak their disagreements. Never write implementation code. Use the iumbtems_factory tool for run state. Explicit user approval advances each gate.",
+      "permissions": [
+        { "action": "edit", "resource": "*", "effect": "deny" },
+        { "action": "shell", "resource": "*", "effect": "ask" },
+        { "action": "subagent", "resource": "*", "effect": "deny" },
+        { "action": "subagent", "resource": "programmer", "effect": "allow" },
+        { "action": "subagent", "resource": "qa-a", "effect": "allow" },
+        { "action": "subagent", "resource": "qa-b", "effect": "allow" },
+        { "action": "subagent", "resource": "brainstormer", "effect": "allow" },
+        { "action": "subagent", "resource": "darkharvester", "effect": "allow" }
+      ]
     },
     "programmer": {
       "description": "IUMBTEMS Factory Programmer: implements exactly one phase brief per spawn. Cites phase evidence hashes. Never invokes swarms or other programmers.",
       "mode": "subagent",
-      "temperature": 0.3,
-      "permission": {
-        "edit": "allow",
-        "bash": "ask",
-        "task": {
-          "*": "deny"
-        }
-      },
-      "tools": {
-        "read": true,
-        "write": true,
-        "bash": true,
-        "grep": true,
-        "glob": true,
-        "iumbtems_verify_quote": true
-      }
+      "system": "You are the IUMBTEMS Factory Programmer. Implement exactly one phase brief per spawn. Cite phase evidence hashes. Never invoke swarms or other programmers. If the brief is ambiguous or untestable, stop and ask the manager.",
+      "permissions": [
+        { "action": "edit", "resource": "*", "effect": "allow" },
+        { "action": "shell", "resource": "*", "effect": "ask" },
+        { "action": "subagent", "resource": "*", "effect": "deny" }
+      ]
     },
     "qa-a": {
       "description": "IUMBTEMS Factory QA (functional): verifies phase acceptance criteria pass on the real surface. Read-only plus test execution. Diverged prompt from qa-b.",
       "mode": "subagent",
-      "temperature": 0.1,
-      "permission": {
-        "edit": "deny",
-        "bash": "ask",
-        "task": {
-          "*": "deny"
-        }
-      },
-      "tools": {
-        "read": true,
-        "bash": true,
-        "grep": true,
-        "glob": true
-      }
+      "system": "You are the IUMBTEMS Factory functional QA. Verify each phase acceptance criterion on the real surface with tests and inspection. Read-only plus test execution; never edit code. Return pass|fail(reason)|conditional(note).",
+      "permissions": [
+        { "action": "edit", "resource": "*", "effect": "deny" },
+        { "action": "shell", "resource": "*", "effect": "ask" },
+        { "action": "subagent", "resource": "*", "effect": "deny" }
+      ]
     },
     "qa-b": {
       "description": "IUMBTEMS Factory QA (adversarial): hunts edge cases, regressions, and acceptance loopholes the functional pass missed. Read-only plus test execution. Diverged prompt from qa-a.",
       "mode": "subagent",
-      "temperature": 0.4,
-      "permission": {
-        "edit": "deny",
-        "bash": "ask",
-        "task": {
-          "*": "deny"
-        }
-      },
-      "tools": {
-        "read": true,
-        "bash": true,
-        "grep": true,
-        "glob": true
-      }
+      "system": "You are the IUMBTEMS Factory adversarial QA. Attack the phase: edge cases, regressions, vacuous acceptance criteria, error paths, resource limits. Read-only plus test execution; never edit code. Return pass|fail(reason)|conditional(note) with reproductions.",
+      "permissions": [
+        { "action": "edit", "resource": "*", "effect": "deny" },
+        { "action": "shell", "resource": "*", "effect": "ask" },
+        { "action": "subagent", "resource": "*", "effect": "deny" }
+      ]
     }
   },
-  "skills": {
-    "paths": [
-      "./skills/grilling",
-      "./skills/research_cache",
-      "./skills/epistemic_search",
-      "./skills/swarm_config",
-      "./skills/code_audit",
-      "./skills/oss_scout",
-      "./skills/brainstorming",
-      "./skills/darkharvest",
-      "./skills/factory"
-    ]
-  }
+  "skills": [
+    "./skills/grilling",
+    "./skills/research_cache",
+    "./skills/epistemic_search",
+    "./skills/swarm_config",
+    "./skills/code_audit",
+    "./skills/oss_scout",
+    "./skills/brainstorming",
+    "./skills/darkharvest",
+    "./skills/factory"
+  ]
 }

package/install.sh

@@ -109,7 +109,7 @@ except Exception as e:
 EOF
 fi
 
-# 5. OpenCode V2 integration (plugin tuple, agents, MCP server — merge only)
+# 5. OpenCode V2 integration (plugins/agents/skills/mcp.servers — merge only)
 OPENCODE_JSON="$HOME/.config/opencode/opencode.json"
 echo "🔧 Merging OpenCode V2 configuration into $OPENCODE_JSON..."
 python3 - <<EOF
@@ -124,91 +124,114 @@ OPTION_KEYS = {"search_engine", "max_iterations", "mode", "divergence_threshold"
 oc_path.parent.mkdir(parents=True, exist_ok=True)
 cfg = json.loads(oc_path.read_text(encoding="utf-8")) if oc_path.exists() else {}
 
-# --- plugin entry: tuple form [package, options]; repair bare-object form ---
-plugins = cfg.get("plugin", [])
+# --- plugins (V2): object form {"package", "options"}; migrate legacy `plugin` ---
+plugins = cfg.get("plugins")
 if not isinstance(plugins, list):
-    print("   ⚠️ 'plugin' is not a list; leaving untouched")
-    plugins = cfg.get("plugin", [])
-else:
-    repaired = []
+    plugins = []
+
+# Migrate any legacy V1 `plugin` entries: bare strings, [pkg, options] tuples,
+# and the "wild" malformation where a bare options object trails our package.
+legacy = cfg.get("plugin")
+if isinstance(legacy, list):
     i = 0
-    changed = False
-    while i < len(plugins):
-        item = plugins[i]
-        # Bare options object following our package string (or standalone):
-        # fold into a tuple instead of leaving an invalid entry.
-        if isinstance(item, dict) and set(item) & OPTION_KEYS:
-            prev_is_pkg = repaired and repaired[-1] == PKG
-            prev_is_tuple = (
-                repaired and isinstance(repaired[-1], list)
-                and repaired[-1] and repaired[-1][0] == PKG
-            )
-            if prev_is_pkg:
-                repaired[-1] = [PKG, item]
-                changed = True
-                print("   ~ Repaired bare options object into tuple entry")
-            elif prev_is_tuple:
-                merged = {**(repaired[-1][1] if len(repaired[-1]) > 1 else {}), **item}
-                repaired[-1] = [PKG, merged]
-                changed = True
-                print("   ~ Folded stray options into existing tuple entry")
+    while i < len(legacy):
+        item = legacy[i]
+        if isinstance(item, str):
+            if item == PKG and i + 1 < len(legacy) and isinstance(legacy[i + 1], dict) and (set(legacy[i + 1]) & OPTION_KEYS):
+                plugins.append({"package": PKG, "options": legacy[i + 1]})
+                i += 2
+                continue
+            plugins.append(item)
+        elif isinstance(item, list) and item:
+            opts = item[1] if len(item) > 1 and isinstance(item[1], dict) else {}
+            plugins.append({"package": item[0], "options": opts})
+        elif isinstance(item, dict):
+            if "package" in item:
+                plugins.append(item)
+            elif set(item) & OPTION_KEYS:
+                plugins.append({"package": PKG, "options": item})
             else:
-                repaired.append([PKG, item])
-                changed = True
-                print("   ~ Attached stray options object to new tuple entry")
-        else:
-            repaired.append(item)
+                plugins.append(item)
         i += 1
-    if not any((p == PKG or (isinstance(p, list) and p and p[0] == PKG)) for p in repaired):
-        repaired.append([PKG, {"search_engine": "duckduckgo", "max_iterations": 2, "mode": "research"}])
-        changed = True
-        print(f"   + Added plugin entry: {PKG}")
-    else:
-        print(f"   ℹ️ Plugin entry already configured: {PKG}")
-    cfg["plugin"] = repaired
-
-# --- agents: merge snippet definitions, never overwrite user agents ---
+    cfg.pop("plugin", None)
+    print("   ~ Migrated legacy 'plugin' entries to V2 'plugins' (object form)")
+
+# Normalize our entry to the V2 object form and ensure default options exist.
+DEFAULT_OPTIONS = {"search_engine": "duckduckgo", "max_iterations": 2, "mode": "research"}
+our = None
+for idx, entry in enumerate(plugins):
+    if entry == PKG:
+        our = {"package": PKG, "options": {}}
+        plugins[idx] = our
+    elif isinstance(entry, dict) and entry.get("package") == PKG:
+        our = entry
+        entry["options"] = {**DEFAULT_OPTIONS, **(entry.get("options") or {})}
+if our is None:
+    our = {"package": PKG, "options": dict(DEFAULT_OPTIONS)}
+    plugins.append(our)
+    print(f"   + Added plugin entry: {PKG}")
+else:
+    print(f"   ℹ️ Plugin entry already configured: {PKG}")
+cfg["plugins"] = plugins
+
+# --- agents (V2 plural): merge snippet definitions, never overwrite users ---
 try:
     snippet = json.loads((repo / "config" / "opencode-snippet.json").read_text(encoding="utf-8"))
-    agents = cfg.setdefault("agent", {})
-    for name, definition in snippet.get("agent", {}).items():
+    agents = cfg.setdefault("agents", {})
+    legacy_agents = cfg.get("agent")
+    if isinstance(legacy_agents, dict):
+        for name, definition in legacy_agents.items():
+            agents.setdefault(name, definition)
+        cfg.pop("agent", None)
+        print("   ~ Migrated legacy 'agent' entries to V2 'agents'")
+    for name, definition in (snippet.get("agents") or snippet.get("agent") or {}).items():
         if name not in agents:
             agents[name] = definition
             print(f"   + Added agent: {name}")
         else:
             print(f"   ℹ️ Agent already configured: {name}")
 
-    # Skills: snippet paths are repo-relative ("./skills/x") which breaks
-    # from ~/.config — merge as absolute paths, repairing relative entries.
+    # Skills: V2 is a list of directories/URLs. Snippet paths are repo-relative
+    # ("./skills/x") which breaks from ~/.config — merge as absolute paths and
+    # repair a legacy `{"paths": [...]}` object or relative entries in place.
     import os as _os
     wanted = []
-    for sp in snippet.get("skills", {}).get("paths", []):
+    for sp in snippet.get("skills") or []:
         wanted.append(sp if _os.path.isabs(sp) else str(repo / sp.lstrip("./")))
-    skills_cfg = cfg.setdefault("skills", {})
-    paths = skills_cfg.setdefault("paths", [])
-    # Repair repo-relative entries in place, then append missing absolutes.
-    for i, existing in enumerate(list(paths)):
+    skills = cfg.get("skills")
+    if isinstance(skills, dict):
+        skills = cfg["skills"] = list(skills.get("paths") or [])
+        print("   ~ Migrated legacy skills.paths to the V2 skills list")
+    elif not isinstance(skills, list):
+        skills = cfg["skills"] = []
+    for i, existing in enumerate(list(skills)):
+        if existing in wanted:
+            continue
         for abs_sp in wanted:
-            if existing == abs_sp:
-                break
             rel = "./" + str(Path(abs_sp).relative_to(repo)) if str(abs_sp).startswith(str(repo)) else None
             if rel and existing == rel:
-                paths[i] = abs_sp
+                skills[i] = abs_sp
                 print(f"   ~ Repaired relative skill path: {rel} -> {abs_sp}")
                 break
     for abs_sp in wanted:
-        if abs_sp not in paths:
-            paths.append(abs_sp)
+        if abs_sp not in skills:
+            skills.append(abs_sp)
             print(f"   + Added skill path: {abs_sp}")
         else:
             print(f"   ℹ️ Skill path already configured: {abs_sp}")
 except Exception as e:
     print(f"   ⚠️ Non-critical warning merging agents: {e}")
 
-# --- MCP server: absolute runner path (relative paths only work at repo root) ---
+# --- MCP server (V2 `mcp.servers`): absolute runner path ---
 mcp = cfg.setdefault("mcp", {})
-if "iumbtems" not in mcp:
-    mcp["iumbtems"] = {
+servers = mcp.setdefault("servers", {})
+legacy_mcp = mcp.get("iumbtems")
+if isinstance(legacy_mcp, dict):
+    servers.setdefault("iumbtems", legacy_mcp)
+    mcp.pop("iumbtems", None)
+    print("   ~ Migrated legacy mcp.iumbtems to V2 mcp.servers.iumbtems")
+if "iumbtems" not in servers:
+    servers["iumbtems"] = {
         "type": "local",
         "command": ["python3", str(repo / "runner" / "mcp_server.py")],
         "enabled": True,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "description": "IUMBTEMS: I Use My Brain To Express My Self — High-Integrity Dialectic Research Agent Harness for Claude Code, OpenCode V2, Pi, OMP (oh-my-pi), Gemini CLI, Codex CLI, and AntiGravity",
   "main": "bin/cli.js",
   "bin": {

package/plugins/opencode/index.js

@@ -920,7 +920,8 @@ async function registerHostCommands(host) {
           await host.session.prompt({
             ...prompt,
             sessionID: input?.sessionID,
-            ...(cmd.agent ? { agent: cmd.agent } : {}),
+            // No `agent` field here: V2's SessionPromptInput has none (agent
+            // mentions only). Pinning happens via switchAgent above.
             text: cmd.template.split('$ARGUMENTS').join(String(args).trim()),
             delivery: input?.delivery,
           });
@@ -1028,7 +1029,9 @@ async function registerHostAgents(host) {
   // every step of a factory session executed as `build`, not `manager`).
   if (typeof host?.agent?.transform !== 'function') return [];
   const snippet = readPkgJson(path.join(PKG_ROOT, 'config', 'opencode-snippet.json'));
-  const agentDefs = (snippet && snippet.agent) || {};
+  // V2 config key is `agents` (plural); accept the legacy `agent` key for one
+  // release so older snippet copies keep working.
+  const agentDefs = (snippet && (snippet.agents || snippet.agent)) || {};
   if (Object.keys(agentDefs).length === 0) return [];
 
   let existing = new Set();
@@ -1046,7 +1049,7 @@ async function registerHostAgents(host) {
       if (claimed.has(name)) continue;
       claimed.add(name);
       added.push(name);
-      draft.add(toAgentInfo(name, def));
+      registerAgent(draft, name, def);
     }
     log(host, 'debug', 'agent.transform pass', { added });
   });
@@ -1071,18 +1074,49 @@ const FACTORY_SYSTEM = {
     'You are the IUMBTEMS Factory adversarial QA. Attack the phase: edge cases, regressions, vacuous acceptance criteria, error paths, resource limits. Read-only plus test execution; never edit code. Return pass|fail(reason)|conditional(note) with reproductions.',
 };
 
-/** Map one snippet agent definition to an Agent.Info shape. */
+/** V1 permission/tool action names -> V2 permission action names. */
+const ACTION_ALIASES = { bash: 'shell', task: 'subagent', patch: 'edit', write: 'edit' };
+
+function normalizeAction(action) {
+  const key = String(action || '').trim();
+  return ACTION_ALIASES[key] || key;
+}
+
+function normalizeEffect(effect) {
+  return effect === 'deny' || effect === 'ask' ? effect : 'allow';
+}
+
+/**
+ * Map one snippet agent definition to an Agent.Info shape.
+ *
+ * Accepts the V2 config form (`permissions: [{action,resource,effect}]`) and
+ * still understands the legacy V1 form (`tools` map + `permission` map) so an
+ * older snippet copy is not silently dropped.
+ */
 function toAgentInfo(name, def) {
   const permissions = [];
+  for (const rule of def?.permissions || []) {
+    if (rule && typeof rule === 'object' && typeof rule.action === 'string') {
+      permissions.push({
+        action: normalizeAction(rule.action),
+        resource: typeof rule.resource === 'string' ? rule.resource : '*',
+        effect: normalizeEffect(rule.effect),
+      });
+    }
+  }
   for (const [tool, enabled] of Object.entries(def?.tools || {})) {
-    permissions.push({ action: tool, resource: '*', effect: enabled ? 'allow' : 'deny' });
+    permissions.push({
+      action: normalizeAction(tool),
+      resource: '*',
+      effect: enabled ? 'allow' : 'deny',
+    });
   }
   for (const [key, value] of Object.entries(def?.permission || {})) {
     if (typeof value === 'string') {
-      permissions.push({ action: key, resource: '*', effect: value });
+      permissions.push({ action: normalizeAction(key), resource: '*', effect: normalizeEffect(value) });
     } else if (value && typeof value === 'object') {
       for (const [resource, effect] of Object.entries(value)) {
-        permissions.push({ action: key, resource, effect });
+        permissions.push({ action: normalizeAction(key), resource, effect: normalizeEffect(effect) });
       }
     }
   }
@@ -1097,11 +1131,41 @@ function toAgentInfo(name, def) {
   };
   if (def?.steps) info.steps = def.steps;
   if (def?.color) info.color = def.color;
-  const system = FACTORY_SYSTEM[name];
+  // The canonical short role prompt wins; fall back to a snippet-provided one.
+  const system = FACTORY_SYSTEM[name] || def?.system;
   if (system) info.system = system;
   return info;
 }
 
+/**
+ * Register one agent profile through a V2 `AgentEditor`.
+ *
+ * V2's AgentEditor has NO `add()` — only `list/get/default/update/remove`
+ * (verified against @opencode/plugin@2.0.18 dist/promise/agent.d.ts). Calling
+ * `draft.add(...)` threw `draft.add is not a function` and the host disabled
+ * the whole plugin ("disabled plugin after transform failure", state=agent).
+ *
+ * `update(id, mutate)` upserts: when the id is new the host seeds the draft
+ * from `Agent.Info.default(id)` plus global permission rules, then hands it to
+ * the callback (opencode v2.0.18 agent registry:
+ * `c = agents.get(d) ?? {...default(d), permissions:[...default.permissions, ...I]}`).
+ * The first-party `opencode.config.agent` plugin registers config agents the
+ * same way, so this is the supported path for creating profile agents.
+ *
+ * Seeded permissions are kept and ours appended: rule matching is
+ * last-match-wins, so an explicit `edit: deny` still beats the default allow.
+ */
+function registerAgent(editor, name, def) {
+  const info = toAgentInfo(name, def);
+  const rules = info.permissions || [];
+  const profile = { ...info };
+  delete profile.permissions;
+  editor.update(name, (agent) => {
+    Object.assign(agent, profile);
+    agent.permissions = [...(agent.permissions || []), ...rules];
+  });
+}
+
 /** Canonical skills the plugin registers so agents never hunt the filesystem. */
 const BUNDLED_SKILLS = [
   'factory',