@nanhara/hara 0.124.4 → 0.125.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to `@nanhara/hara`.
 > Versioning (pre-1.0, SemVer-style): the **minor** (middle) number bumps for a **new feature**; the
 > **patch** (last) number bumps for **optimizations/fixes of existing features**.
 
+## 0.125.0 — 2026-07-18 — Claude-compatible specialist orchestration
+
+- **Personal Claude Code subagents now work in Hara without copying prompts.** Hara discovers
+  `~/.claude/agents/*.md` as portable global roles in addition to project `.claude/agents`, translates common
+  Claude tool names, inherits the active Hara model for Claude aliases/provider-specific ids, and preserves
+  native/project Hara precedence on id collisions. Workflow-only prompts and prompts that require a private
+  Claude notification/skill dependency stay explicit-only rather than being selected automatically.
+- **Ordinary Hara conversations can now discover the right specialist.** The main agent receives a bounded,
+  guarded name/description catalog and loads only the selected role body. Delegation guidance requires a
+  minimal self-contained brief, distinct non-overlapping work, and parent-side synthesis; fan-out specialists
+  remain read-only so role prompts cannot bypass the edit/command approval boundary.
+- **Plans route by responsibility instead of role name alone.** The atom planner receives bounded role
+  descriptions and read-only status, excludes `disable-model-invocation` roles from automatic selection, and
+  removes unknown role ids instead of silently executing under a generic persona. Explicit role execution
+  remains available for host-coupled prompts.
+
 ## 0.124.4 — 2026-07-18 — deadline-aware task checkpoints
 
 - **The 80% run-budget warning now reaches the Agent, not only the user.** Before the next model turn,

package/README.md

@@ -162,6 +162,7 @@ hara                       # interactive REPL (offers to create AGENTS.md on fir
 hara init                  # analyze the project & (re)generate AGENTS.md
 hara doctor                # check your setup (auth / model / node / assets / roles)
 hara roles init            # scaffold role-agents (implementer / reviewer / docs)
+hara roles                 # list Hara roles + compatible personal/project Claude Code agents
 hara org "review src/ for bugs"   # dispatch a task to the role that owns it (or --role <id>)
 hara projects add shop /absolute/path/to/shop   # register an agent home
 hara agents                # list global + registered project agents
@@ -312,6 +313,18 @@ to a clean start tree; a review that doesn't pass leaves the work uncommitted).
 **`agent`** tool spawns **parallel read-only sub-agents** for fan-out — analyze / review / search
 several things at once (each can take a `role`), bounded to 8 concurrent (`HARA_MAX_CONCURRENCY`).
 
+Claude Code role collections work in place: Hara discovers both `~/.claude/agents/*.md` and project
+`.claude/agents/*.md`, translates common Claude tool names (`Read`, `Edit`, `Bash`, `WebSearch`, …), and
+treats Claude aliases and Claude-only model ids as “inherit the current Hara model” (a role cannot silently
+switch the active provider). Precedence is plugin < managed org < personal Claude < personal Hara < project
+Claude < project Hara. Ordinary Hara turns receive only a compact,
+guarded catalog of role names and descriptions; a role's full prompt is loaded only after that role is
+selected. This lets the main agent ask an architect, debugger, tester, or reviewer for bounded independent
+analysis without copying every prompt into every request. Claude prompts that declare themselves workflow-only
+or require a private notification server / Claude-only local skill are automatically kept explicit-only; they
+remain available through `--role` / `agent(role)` but cannot be picked by automatic routing. Set
+`disable-model-invocation: true` to make the same boundary explicit for any other host-coupled role.
+
 Register project homes with `hara projects add <name> <absolute-path>`, then `hara agents` becomes a global
 address book across `~/.hara/roles` and each registered project's roles. A qualified address such as
 `shop:reviewer` is unambiguous; both `hara org --role shop:reviewer "<task>"` and one-shot `hara -p "<task>"
@@ -326,7 +339,10 @@ command, so verification is **objective** (e.g. `npm test`, `tsc --noEmit`) rath
 self-assessment. Plan state is the SSOT at `.hara/org/plan.json` (inspectable; execution stops on the
 first failed verification — fix it and **`hara plan resume`** continues, skipping the atoms already done).
 With **`hara plan --parallel`**, independent atoms (the same dependency wave) run **concurrently** — the org
-works the independent parts at once, not one step at a time.
+works the independent parts at once, not one step at a time. The planner sees each automatically-invocable
+role's bounded description and read-only status—not only its id—so it can assign the right specialist and
+will discard a hallucinated, removed, or explicit-only role instead of silently running the atom as a generic
+agent.
 
 ### What it can do
 

package/dist/agent/loop.js

@@ -20,6 +20,7 @@ import { resolve as resolvePath } from "node:path";
 import { redactSensitiveText } from "../security/secrets.js";
 import { redactToolSubprocessOutput } from "../security/subprocess-env.js";
 import { prepareHistoryForModel } from "./context-budget.js";
+import { rolesDigest } from "../org/roles.js";
 /** File tools whose `path` input marks the file as "recently worked with" (post-compaction restore). */
 const FILE_TOUCH_TOOLS = new Set(["read_file", "edit_file", "write_file"]);
 /** Stall watchdog ceiling: a model attempt that streams NOTHING for this long is treated as a dead /
@@ -88,7 +89,12 @@ are disabled without an interactive approval channel unless the user launched wi
 HARA_ALLOW_TRUSTED_EXTENSIONS=1.
 For broad,
 open-ended exploration (more than ~3 searches), spawn \`agent\` sub-agents — several in one response for
-independent questions (role "explore") — each returns conclusions, not dumps. Messages the user sends
+independent questions (role "explore") — each returns conclusions, not dumps. When specialist roles are
+listed below, delegate only a bounded question that materially benefits from that expertise; give each role
+the minimum self-contained context, relevant paths, constraints, and expected output. Do not dump the whole
+conversation, spawn overlapping roles, or delegate a simple lookup. Reconcile conflicting specialist advice
+yourself before acting. Role-based \`agent\` calls stay read-only; the main agent owns approved edits, while
+\`hara org\` / \`hara plan\` provide write-capable role execution behind their normal gates. Messages the user sends
 mid-task arrive marked as interjections — triage them (refine current / queue as todo / urgent-switch)
 instead of blindly folding everything into the current task; the todo list is your task queue. For a multi-step task, call \`todo_write\` to plan a short checklist and keep it updated as
 you go (one item in_progress at a time) — skip it for trivial one-step tasks. You have a persistent
@@ -139,12 +145,14 @@ const CONTINUATION_SYSTEM = "# Existing-session continuity\n" +
 function composeSystem(cwd, projectContext, override, memory, continuationSession = false, executionContext) {
     const head = override ? `${override}\n\nWorking directory: ${cwd}` : HARA_SYSTEM(cwd);
     const skills = skillsDigest(cwd);
+    const roles = override ? "" : rolesDigest(cwd);
     return (head +
         gatewayNote() +
         (continuationSession ? `\n\n${CONTINUATION_SYSTEM}` : "") +
         (executionContext ? `\n\n${executionContext}` : "") +
         (projectContext ? `\n\n# Project context (AGENTS.md)\n${projectContext}` : "") +
         (memory ? `\n\n# Memory (durable — facts/decisions/prefs you've saved; use memory_search/get for more)\n${memory}` : "") +
+        (roles ? `\n\n# Specialist roles (metadata only — use \`agent\` with a role id for bounded read-only expertise)\n${roles}` : "") +
         (skills ? `\n\n# Skills (capabilities you can load — call the \`skill\` tool with the id for full instructions before using one)\n${skills}` : ""));
 }
 const RUN_STOPPED = Symbol("agent-run-stopped");

package/dist/index.js

@@ -503,20 +503,25 @@ async function runOrg(task, o) {
         }
     }
     else {
-        const kw = routeByKeywords(task, roles);
+        const routableRoles = roles.filter((candidate) => candidate.modelInvocable !== false);
+        if (!routableRoles.length) {
+            out(c.yellow("No automatically routable roles — choose an explicit role with --role <id>.\n"));
+            return { status: "error", error: "no roles allow automatic invocation" };
+        }
+        const kw = routeByKeywords(task, routableRoles);
         if (kw) {
             role = kw.role;
         }
         else {
             const r = await boundedProviderTurn(o.baseProvider, {
                 system: "You are a task dispatcher. Reply with only a role id.",
-                history: [{ role: "user", content: buildDispatchPrompt(task, roles) }],
+                history: [{ role: "user", content: buildDispatchPrompt(task, routableRoles) }],
                 tools: [],
                 onText: () => { },
             }, { timeoutMs: 20_000, label: "role dispatch" });
             if (r.stop === "error")
-                out(c.yellow(`(role dispatch unavailable — using ${roles[0].id})\n`));
-            role = parseRoleId(r.text, roles) ?? roles[0];
+                out(c.yellow(`(role dispatch unavailable — using ${routableRoles[0].id})\n`));
+            role = parseRoleId(r.text, routableRoles) ?? routableRoles[0];
         }
     }
     out(c.dim(`→ ${role.id} owns this task\n`));
@@ -626,6 +631,13 @@ async function executeAtom(atom, plan, done, roles, o) {
     atom.status = "running";
     await savePlan(o.cwd, plan);
     const role = atom.role ? roles.find((r) => r.id === atom.role) : undefined;
+    if (atom.role && !role) {
+        atom.status = "failed";
+        atom.note = `planned role '${atom.role}' is no longer available`;
+        await savePlan(o.cwd, plan);
+        out(c.red(`  ✗ ${atom.id} ${atom.note}\n`));
+        return false;
+    }
     const __atomModel = effectiveRoleModel(role?.model, o.cfg.model);
     const roleProvider = __atomModel ? ((await buildProvider({ ...o.cfg, model: __atomModel })) ?? o.baseProvider) : o.baseProvider;
     const toolFilter = roleToolFilter(role);
@@ -1039,6 +1051,14 @@ async function runSubagent(cfg, baseProvider, cwd, sandbox, projectContext, stat
     return "(sub-agent produced no output)";
 }
 /** Check the hara setup and print a health summary (provider/auth/model/node/assets/roles). */
+function roleMeta(role) {
+    return [
+        role.source,
+        role.readOnly ? "read-only" : "",
+        role.modelInvocable === false ? "explicit-only" : "",
+        ...(role.compatibilityWarnings ?? []),
+    ].filter(Boolean).join(" · ");
+}
 function runDoctor(cfg) {
     const ok = (b) => (b ? c.green("✓") : c.red("✗"));
     const dot = c.dim("·");
@@ -1057,7 +1077,7 @@ function runDoctor(cfg) {
         `${ok(authed)} auth ${authed ? c.dim("configured") : c.yellow("missing — " + authHint(cfg))}`,
         `${ok(existsSync(configPath()))} config ${c.dim(configPath())}`,
         `${dot} code-assets ${existsSync(ad) ? c.dim(ad) : c.dim("none — run: hara recall --init")}`,
-        `${dot} roles ${roles.length ? c.dim(roles.map((r) => r.id).join(", ")) : c.dim("none — run: hara roles init")}`,
+        `${dot} roles ${roles.length ? c.dim(`${roles.length} (${roles.slice(0, 8).map((r) => r.id).join(", ")}${roles.length > 8 ? ", …" : ""})`) : c.dim("none — run: hara roles init")}`,
         `${dot} skills ${(() => { const n = loadSkillIndex(cfg.cwd).length; return n ? c.dim(`${n} (${loadSkillIndex(cfg.cwd).map((s) => s.id).slice(0, 6).join(", ")})`) : c.dim("none — run: hara skills init"); })()}`,
         `${dot} memory ${existsSync(join(homedir(), ".hara", "memory")) ? c.dim("~/.hara/memory + project") : c.dim("none yet (created on first write)")} ${c.dim("· evolve")} ${c.bold(cfg.evolve)} ${c.dim("· capture")} ${c.bold(cfg.assetCapture)}`,
         `${dot} search ${c.dim("lexical (always on)")}${cfg.embedProvider === "off" ? c.dim(" · semantic off (hara config set embedProvider ollama|qwen)") : c.dim(" · semantic ") + c.bold(cfg.embedProvider) + (() => { const idx = ["repo", "assets", "memory"].filter((n) => indexExists(n, cfg.cwd)); return c.dim(" · indexed: ") + (idx.length ? c.green(idx.join(", ")) : c.yellow("none — run: hara index --all")); })()}`,
@@ -1286,7 +1306,7 @@ program
     .action(() => {
     const idx = buildAgentsIndex();
     if (!idx.length) {
-        out(c.dim("(no agents — add roles to ~/.hara/roles, or register projects: hara projects add <name> <path>)\n"));
+        out(c.dim("(no agents — add roles to ~/.hara/roles or ~/.claude/agents, or register projects: hara projects add <name> <path>)\n"));
         return;
     }
     for (const e of idx) {
@@ -2445,7 +2465,7 @@ memoryCmd
     if (stats.input || stats.output)
         out(statusLine(cfg.model, stats.input, stats.output) + "\n");
 });
-const rolesCmd = program.command("roles").description("manage org roles (.hara/roles)");
+const rolesCmd = program.command("roles").description("list/manage Hara roles and compatible Claude Code agents");
 rolesCmd
     .command("init")
     .description("scaffold example roles")
@@ -2462,7 +2482,8 @@ rolesCmd.action(() => {
         return;
     }
     for (const r of roles) {
-        out(`${c.bold(r.id)}${r.model ? c.dim(` (${r.model})`) : ""}  ${c.dim("owns: " + r.owns.join(", "))}\n  ${r.description}\n`);
+        const meta = roleMeta(r);
+        out(`${c.bold(r.id)}${r.model ? c.dim(` (${r.model})`) : ""}${meta ? c.dim(`  [${meta}]`) : ""}  ${c.dim("owns: " + r.owns.join(", "))}\n  ${r.description}\n`);
     }
 });
 program
@@ -3668,7 +3689,7 @@ program.action(async (opts) => {
                 if (!rs.length)
                     return void out(c.dim("No roles. Run `hara roles init`.\n"));
                 for (const r of rs)
-                    out(`  ${r.id}  ${c.dim("owns: " + r.owns.join(", "))}\n`);
+                    out(`  ${r.id}  ${c.dim(`[${roleMeta(r)}] owns: ${r.owns.join(", ")}`)}\n`);
             },
         },
         {
@@ -4358,7 +4379,7 @@ program.action(async (opts) => {
                         return void h.sink.notice(applyVision(arg));
                     if (nm === "roles") {
                         const rs = loadRoles(cwd);
-                        return void h.sink.notice(rs.length ? rs.map((r) => `  ${r.id} — owns: ${r.owns.join(", ")}`).join("\n") : "No roles. Run `hara roles init`.");
+                        return void h.sink.notice(rs.length ? rs.map((r) => `  ${r.id} [${roleMeta(r)}] — owns: ${r.owns.join(", ")}`).join("\n") : "No roles. Run `hara roles init`.");
                     }
                     if (nm === "skills") {
                         const ss = loadSkillIndex(cwd);

package/dist/org/planner.js

@@ -5,6 +5,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { boundedProviderTurn } from "../providers/bounded-turn.js";
+import { roleCatalog } from "./roles.js";
 import { runShell } from "../sandbox.js";
 import { readModelContextFileSync, readVerifiedRegularFileSnapshot } from "../fs-read.js";
 import { atomicWriteText, bindAtomicWritePath } from "../fs-write.js";
@@ -17,7 +18,13 @@ Return ONLY a JSON object, no prose:
 Rules: short ids (a1,a2,…); deps reference earlier ids only; typically 3-8 atoms; each atom small and verifiable. Prefer a concrete 'check' command (e.g. "npm test", "tsc --noEmit", "test -f src/x.ts") so a step is verified objectively; omit 'check' if none fits.`;
 /** Ask the model to decompose `task` into an atomized, sequenced plan. */
 export async function decompose(provider, task, roles, opts = {}) {
-    const roleHint = roles.length ? `\nAvailable roles for the optional "role" field: ${roles.map((r) => r.id).join(", ")}.` : "";
+    const eligibleRoles = roles.filter((role) => role.modelInvocable !== false);
+    const catalog = roleCatalog(eligibleRoles);
+    const roleHint = catalog
+        ? `\nAvailable roles for the optional "role" field:\n${catalog}\n` +
+            "Assign a role only when its specialization materially fits the atom. A read-only role may analyze, " +
+            "research, or verify, but must not own an atom that changes files or executes deployment."
+        : "";
     const r = await boundedProviderTurn(provider, {
         system: PLAN_SYSTEM + roleHint,
         history: [{ role: "user", content: `Task: ${task}\n\nReturn the JSON plan.` }],
@@ -26,7 +33,13 @@ export async function decompose(provider, task, roles, opts = {}) {
     }, { timeoutMs: opts.timeoutMs ?? 60_000, signal: opts.signal, label: "plan decomposition" });
     if (r.stop === "error")
         return { task, atoms: [], createdAt: new Date().toISOString() };
-    return { task, atoms: parsePlan(r.text), createdAt: new Date().toISOString() };
+    const roleIds = new Set(eligibleRoles.map((role) => role.id));
+    const atoms = parsePlan(r.text);
+    for (const atom of atoms) {
+        if (atom.role && !roleIds.has(atom.role))
+            atom.role = undefined;
+    }
+    return { task, atoms, createdAt: new Date().toISOString() };
 }
 /** Extract + normalize atoms from the model's (possibly fenced/noisy) JSON reply. */
 export function parsePlan(text) {

package/dist/org/projects.js

@@ -280,7 +280,9 @@ function sameRoleDefinition(a, b) {
         sameList(a.rejects, b.rejects) &&
         sameList(a.allowTools, b.allowTools) &&
         sameList(a.denyTools, b.denyTools) &&
-        a.readOnly === b.readOnly);
+        a.readOnly === b.readOnly &&
+        a.modelInvocable === b.modelInvocable &&
+        sameList(a.compatibilityWarnings, b.compatibilityWarnings));
 }
 /** Build the global index: inherited globals are listed once; any project override gets its qualified home. */
 export function buildAgentsIndex() {

package/dist/org/roles.js

@@ -1,12 +1,16 @@
-// Org roles — markdown agent definitions in <project>/.hara/roles/*.md.
-// Frontmatter: name, description, owns[], rejects[], model?, allowTools[], denyTools[], readOnly?. Body = persona/system.
+// Org roles — markdown agent definitions from Hara and Claude Code.
+// Frontmatter: name, description, owns[], rejects[], model?, allowTools[]/tools, denyTools[],
+// readOnly?, disable-model-invocation?. Body = persona/system, loaded only for the selected role.
 import { writeFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { findProjectRoot } from "../context/agents-md.js";
 import { pluginRoleDirs } from "../plugins/plugins.js";
 import { readModelContextFileSync } from "../fs-read.js";
+import { scanMemory } from "../memory/guard.js";
 const MAX_ROLE_BYTES = 512 * 1024;
+const ROLE_DIGEST_CAP = 16_000;
+const ROLE_DESCRIPTION_CAP = 180;
 export function rolesDir(cwd) {
     return join(findProjectRoot(cwd), ".hara", "roles");
 }
@@ -14,6 +18,11 @@ export function rolesDir(cwd) {
 export function globalRolesDir() {
     return join(homedir(), ".hara", "roles");
 }
+/** Claude Code's personal subagents are portable role prompts. Read them in place so users do not need
+ *  to copy or fork the prompt collection into Hara. Native ~/.hara/roles overrides an id collision. */
+export function globalClaudeAgentsDir() {
+    return join(homedir(), ".claude", "agents");
+}
 /** Org-pushed roles (B-end): the digital-employee bundle synced from hara-control's `/v1/roles` into
  *  `~/.hara/org-roles/*.md` (see org-fleet/enroll.ts syncOrgRoles). A managed baseline — above
  *  third-party plugins, but a dev's own global/project roles still win. */
@@ -57,13 +66,16 @@ export function claudeTools(v) {
     return raw.map((t) => CLAUDE_TOOL_MAP[t.toLowerCase().replace(/[^a-z]/g, "")] ?? t);
 }
 function parseFrontmatter(text) {
-    const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(text);
+    const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
     if (!m)
         return { fm: {}, body: text.trim() };
     const fm = {};
-    for (const raw of m[1].split("\n")) {
-        const line = raw.trim();
-        const kv = /^([A-Za-z0-9_]+)\s*:\s*(.*)$/.exec(line);
+    for (const raw of m[1].split(/\r?\n/)) {
+        // This is intentionally a small top-level parser, not YAML. Do not trim before matching: nested
+        // metadata such as `persona:\n  name: Vera` must never overwrite the role's top-level `name`.
+        if (/^\s/.test(raw))
+            continue;
+        const kv = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(raw);
         if (!kv)
             continue;
         const key = kv[1];
@@ -106,39 +118,80 @@ export function roleToolFilter(role) {
     return role.allowTools || role.denyTools ? declared : undefined;
 }
 export function loadRoles(cwd) {
-    // lowest→highest precedence: plugins < org(B-end push) < global < .claude/agents < .hara/roles (project wins)
-    return [...rolesFromDirs([...pluginRoleDirs(), orgRolesDir(), globalRolesDir(), claudeAgentsDir(cwd), rolesDir(cwd)]).values()];
+    // lowest→highest precedence: plugins < org(B-end push) < personal Claude < personal Hara
+    // < project Claude < project Hara. A user's native Hara definition intentionally wins an id collision.
+    return [...rolesFromDirs([
+            ...pluginRoleDirs().map((dir) => ({ dir, source: "plugin" })),
+            { dir: orgRolesDir(), source: "org" },
+            { dir: globalClaudeAgentsDir(), source: "claude-global" },
+            { dir: globalRolesDir(), source: "global" },
+            { dir: claudeAgentsDir(cwd), source: "claude-project" },
+            { dir: rolesDir(cwd), source: "project" },
+        ]).values()];
 }
-/** The project-independent layers only (plugins + org-pushed + ~/.hara/roles) — what the global agent
- *  index lists as "runs anywhere". Excludes cwd-derived layers by construction. */
+/** The project-independent layers only — what the global agent index lists as "runs anywhere".
+ *  Personal Claude Code agents participate directly; no copy/import step is required. */
 export function loadGlobalRoles() {
-    return [...rolesFromDirs([...pluginRoleDirs(), orgRolesDir(), globalRolesDir()]).values()];
+    return [...rolesFromDirs([
+            ...pluginRoleDirs().map((dir) => ({ dir, source: "plugin" })),
+            { dir: orgRolesDir(), source: "org" },
+            { dir: globalClaudeAgentsDir(), source: "claude-global" },
+            { dir: globalRolesDir(), source: "global" },
+        ]).values()];
+}
+const isTrue = (value) => value === true || String(value).toLowerCase() === "true";
+function claudeCompatibilityWarnings(description, body) {
+    const warnings = [];
+    if (/\bcalled by\b.*\b(?:only|workflows? only)\b/i.test(description))
+        warnings.push("workflow-only");
+    if (/\b(?:must be used|mandatory before|always use)\b/i.test(description)) {
+        warnings.push("mandatory auto-invocation directive");
+    }
+    if (/localhost:\d+\/notify|YOUR_VOICE_ID(?:_HERE)?|voice notification/i.test(body)) {
+        warnings.push("local notification dependency");
+    }
+    if (/(?:~|\/Users\/[^/\s]+)\/\.claude\/skills\//i.test(body))
+        warnings.push("Claude-only skill dependency");
+    return [...new Set(warnings)];
 }
 function rolesFromDirs(dirs) {
     const byId = new Map();
-    for (const dir of dirs) {
+    for (const { dir, source } of dirs) {
         if (!existsSync(dir))
             continue;
         for (const f of readdirSync(dir)) {
             if (!f.endsWith(".md") || f === "README.md")
                 continue;
             try {
-                const { fm, body } = parseFrontmatter(readModelContextFileSync(join(dir, f), MAX_ROLE_BYTES));
+                const file = join(dir, f);
+                const { fm, body } = parseFrontmatter(readModelContextFileSync(file, MAX_ROLE_BYTES));
                 const id = fm.name || f.replace(/\.md$/, "");
                 const explicitReadOnly = /^(true|false)$/i.test(String(fm.readOnly ?? ""))
                     ? String(fm.readOnly).toLowerCase() === "true"
                     : undefined;
+                const claudeSource = source === "claude-global" || source === "claude-project";
+                const compatibilityWarnings = claudeSource
+                    ? claudeCompatibilityWarnings(String(fm.description ?? ""), body)
+                    : [];
+                const rawModel = fm.model ? String(fm.model) : "";
+                const foreignClaudeModel = claudeSource && /^claude(?:[-_.]|$)/i.test(rawModel);
                 byId.set(id, {
                     id,
                     description: fm.description || "",
                     owns: Array.isArray(fm.owns) ? fm.owns : [],
                     rejects: Array.isArray(fm.rejects) ? fm.rejects : [],
-                    // Claude-Code model ALIASES (sonnet/opus/haiku/inherit) aren't hara model ids — treat as
-                    // "inherit the session model" rather than passing a string no provider resolves.
-                    model: fm.model && !/^(sonnet|opus|haiku|inherit)$/i.test(String(fm.model)) ? fm.model : undefined,
+                    // Claude aliases and Claude-provider ids cannot safely switch Hara's active provider — inherit
+                    // the session model instead of passing a foreign id to (for example) a Qwen/OpenAI endpoint.
+                    model: rawModel && !/^(sonnet|opus|haiku|inherit)$/i.test(rawModel) && !foreignClaudeModel
+                        ? rawModel
+                        : undefined,
                     allowTools: Array.isArray(fm.allowTools) ? fm.allowTools : claudeTools(fm.tools),
                     denyTools: Array.isArray(fm.denyTools) ? fm.denyTools : undefined,
                     readOnly: explicitReadOnly ?? (id.toLowerCase() === "reviewer" ? true : undefined),
+                    modelInvocable: !isTrue(fm["disable-model-invocation"]) && compatibilityWarnings.length === 0,
+                    compatibilityWarnings,
+                    source,
+                    file,
                     system: body,
                 });
             }
@@ -149,6 +202,65 @@ function rolesFromDirs(dirs) {
     }
     return byId;
 }
+function compactRoleDescription(role) {
+    const description = role.description.replace(/\s+/g, " ").trim();
+    if (!description || !scanMemory(description).ok)
+        return "";
+    return description.length > ROLE_DESCRIPTION_CAP
+        ? description.slice(0, ROLE_DESCRIPTION_CAP - 1).trimEnd() + "…"
+        : description;
+}
+/** Compact metadata catalog for dispatch/planning. Role bodies remain progressive: only the selected role's
+ *  persona is injected into its run. Descriptions are bounded and guarded because plugin roles can be
+ *  untrusted. */
+export function roleCatalog(roles, cap = ROLE_DIGEST_CAP) {
+    const lines = [];
+    const sourceRank = {
+        project: 0,
+        "claude-project": 1,
+        global: 2,
+        "claude-global": 3,
+        org: 4,
+        plugin: 5,
+    };
+    const ordered = [...roles].sort((a, b) => {
+        const source = (sourceRank[a.source ?? "plugin"] ?? 9) - (sourceRank[b.source ?? "plugin"] ?? 9);
+        if (source)
+            return source;
+        const ownership = Number(b.owns.length > 0) - Number(a.owns.length > 0);
+        if (ownership)
+            return ownership;
+        return a.id.localeCompare(b.id);
+    });
+    for (const role of ordered) {
+        if (role.modelInvocable === false)
+            continue;
+        const description = compactRoleDescription(role);
+        if (!description)
+            continue;
+        const flags = [role.readOnly ? "read-only" : "", role.source?.startsWith("claude-") ? "Claude-compatible" : ""]
+            .filter(Boolean)
+            .join(", ");
+        lines.push(`- ${role.id}${flags ? ` [${flags}]` : ""}: ${description}`);
+    }
+    let digest = lines.join("\n");
+    if (digest.length > cap)
+        digest = digest.slice(0, cap) + "\n…";
+    return digest;
+}
+let roleDigestCache = new Map();
+/** Frozen-per-session specialist index for the ordinary Hara agent. This is the missing Claude-style
+ *  discovery layer: the main agent sees role metadata, then loads only the chosen persona through agent/org. */
+export function rolesDigest(cwd) {
+    if (roleDigestCache.has(cwd))
+        return roleDigestCache.get(cwd);
+    const digest = roleCatalog(loadRoles(cwd));
+    roleDigestCache.set(cwd, digest);
+    return digest;
+}
+export function invalidateRolesCache() {
+    roleDigestCache.clear();
+}
 export function hasRoles(cwd) {
     return loadRoles(cwd).length > 0;
 }
@@ -193,6 +305,7 @@ Each \`*.md\` here is a role-agent. Frontmatter:
 - \`model\` — optional model override
 - \`allowTools\` / \`denyTools\` — restrict the role's tools
 - \`readOnly\` — enforce read/search-only tools (defaults on for a role named \`reviewer\`)
+- \`disable-model-invocation\` — hide the role from automatic routing while keeping explicit \`--role\` use
 
 Run \`hara org "<task>"\` to dispatch a task to the owning role, or \`hara org --role <id> "<task>"\`.
 `,
@@ -208,5 +321,7 @@ export function scaffoldRoles(cwd) {
             written.push(name);
         }
     }
+    if (written.length)
+        invalidateRolesCache();
     return written;
 }

package/dist/org/router.js

@@ -1,3 +1,5 @@
+// Dispatcher — route a task to the role that OWNs it (keyword match first, LLM fallback).
+import { roleCatalog } from "./roles.js";
 /** Deterministic routing by `owns`/`rejects` keywords. null if no clear owner. */
 export function routeByKeywords(task, roles) {
     const t = task.toLowerCase();
@@ -13,7 +15,7 @@ export function routeByKeywords(task, roles) {
 }
 /** Prompt for the LLM dispatcher fallback. */
 export function buildDispatchPrompt(task, roles) {
-    const list = roles.map((r) => `- ${r.id}: ${r.description}`).join("\n");
+    const list = roleCatalog(roles);
     return `You are the dispatcher in an engineering org. Pick the single best role to own this task.
 
 Roles:

package/dist/tools/agent.js

@@ -14,6 +14,8 @@ export const EXPLORE_SYSTEM = "You are a fast, READ-ONLY codebase explorer. Navi
 registerTool({
     name: "agent",
     description: "Delegate an independent sub-task to a fresh READ-ONLY sub-agent and get its conclusions. " +
+        "Specialist role ids and descriptions appear under `# Specialist roles` in the system context; pass one " +
+        "only when its distinct expertise helps, and give it a minimal self-contained brief instead of conversation dumps. " +
         "WHEN TO USE: open-ended exploration ('how does X work across the codebase', 'find everything that touches Y') " +
         "that would take more than ~3 searches — pass role \"explore\" for a fast search specialist; and spawning " +
         "SEVERAL agents in ONE response for independent questions (they run in parallel). " +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.124.4",
+  "version": "0.125.0",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "runtime-bootstrap.cjs"