@nanhara/hara 0.89.0 → 0.98.0

package/dist/security/guardian.js

@@ -0,0 +1,261 @@
+// Guardian — an internal safety layer that sits ON TOP of the existing stack (permission rules →
+// PreToolUse hooks → approval gate → soft stuck-guard). It exists for the one failure mode those don't
+// cover: a genuinely dangerous, irreversible action that slips through (no deny rule, auto-approved mode,
+// a cron/gateway run with `confirm: () => true`). Two moving parts:
+//
+//   1. A DETERMINISTIC risk classifier that runs FIRST and is the whole point of "zero latency on normal
+//      work": read tools, in-project edits, and ordinary shell commands are classified `low` in pure Node
+//      (no LLM, no I/O) and skip the guardian entirely. Only a handful of genuinely destructive shapes
+//      (rm -rf, dd, mkfs, curl|sh, sudo, force-push, broad chmod -R, writes outside the project root, …)
+//      are classified `high` and escalate.
+//   2. A conservative LLM veto that runs ONLY on `high` actions: it asks a cheap model "is this action
+//      clearly dangerous or clearly off-task?" and defaults to ALLOW. Any glitch (timeout, error, no model
+//      configured) FAILS OPEN — a guardian hiccup must never break legitimate work, because the permission
+//      rules + the user's own approval gate still apply independently.
+//
+// Plus a deterministic circuit-breaker: N guardian BLOCKS in one run (or an escalating-destructive runaway)
+// trips a hard stop that requires explicit user confirmation to continue — a harder stop than the soft
+// stuck-guard nudge, and one that aborts safely (never hangs) when there's no interactive user.
+import { resolve, isAbsolute } from "node:path";
+import { canonicalize, splitCompound } from "./permissions.js";
+// ── Deterministic risk classifier ────────────────────────────────────────────────────────────────────
+// The classifier is intentionally NARROW: false positives here cost latency + an LLM call + potential
+// annoyance, so we only flag shapes that are destructive/irreversible in practice. Everything else is `low`.
+// A path is "broad" (a whole tree / outside the sandbox) when it's `/`, a top-level system dir, a home dir,
+// `.`/`*`/`~`, or absolute-outside-cwd. `chmod -R`/`chown -R`/`rm -rf` on a broad path is the danger, not on
+// a project-local subdir.
+const SYSTEM_ROOTS = /^(\/|\/(bin|boot|dev|etc|home|lib|opt|proc|root|sbin|srv|sys|usr|var|Users|Applications|System|Library|Volumes)(\/|$)|~|\$HOME)/;
+/** Genuinely destructive/irreversible single-command shapes (checked against the canonical form of each
+ *  part of a compound command). Kept tight — see the module header. */
+function isDestructiveCommand(canonical) {
+    const c = canonical;
+    if (!c)
+        return false;
+    // rm -rf / rm -fr / recursive-forced removal (the classic).
+    if (/\brm\s+(-[a-z]*r[a-z]*f|-[a-z]*f[a-z]*r|-r\s+-f|-f\s+-r|--recursive\s+--force|--force\s+--recursive)\b/.test(c))
+        return true;
+    // rm -r/-rf targeting a broad/system path (rm -rf / , rm -rf ~ , rm -r /etc …).
+    if (/\brm\s+-[a-z]*r/.test(c) && /\brm\s+-[a-z]*r[a-z]*\s+(\/|~|\$HOME|\*|\.\s|\.$)/.test(c))
+        return true;
+    // Raw-disk / filesystem-destroying tools.
+    if (/\b(dd)\b/.test(c) && /\bof=\/dev\//.test(c))
+        return true;
+    if (/\b(mkfs(\.\w+)?|mke2fs|fdisk|parted|wipefs|shred)\b/.test(c))
+        return true;
+    if (/\bdiskutil\s+(erase|reformat|partitionDisk)/i.test(c))
+        return true;
+    // Fork bomb.
+    if (/:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/.test(c) || /\.\(\)\{\s*\.\|\.&\s*\}/.test(c))
+        return true;
+    // Pipe-to-shell from the network (curl … | sh, wget … | bash) — arbitrary remote code execution.
+    if (/\b(curl|wget|fetch)\b[^|]*\|\s*(sudo\s+)?(ba|z)?sh\b/.test(c))
+        return true;
+    // Privilege escalation.
+    if (/\bsudo\b/.test(c))
+        return true;
+    if (/\bkillall\b/.test(c))
+        return true;
+    // Force-push (rewrites shared history irreversibly).
+    if (/\bgit\s+push\b[^\n]*(--force\b|--force-with-lease\b|(^|\s)-f\b)/.test(c))
+        return true;
+    // Broad recursive permission/ownership change.
+    if (/\b(chmod|chown|chgrp)\s+(-[a-z]*R|--recursive)/.test(c)) {
+        if (SYSTEM_ROOTS.test(commandTarget(c)) || /\s(\/|~|\$HOME|\*|\.)(\s|$)/.test(c))
+            return true;
+    }
+    // Destructive git tree resets / clean.
+    if (/\bgit\s+clean\b[^\n]*-[a-z]*f/.test(c) && /-[a-z]*d/.test(c))
+        return true;
+    // History overwrite: `> /path` (truncation) onto a system/absolute-outside path is handled by the
+    // out-of-project write check below (redirection carries a path); nothing extra here.
+    return false;
+}
+/** The last whitespace token that looks like a path target of a command (best-effort, for chmod/chown). */
+function commandTarget(canonical) {
+    const toks = canonical.split(/\s+/).filter((t) => t && !t.startsWith("-"));
+    return toks[toks.length - 1] ?? "";
+}
+/** Extract `> file` / `>> file` redirection targets from a canonical command (quote-naive; classifier only). */
+function redirectionTargets(canonical) {
+    const out = [];
+    const re = />>?\s*("([^"]*)"|'([^']*)'|([^\s;|&]+))/g;
+    let m;
+    while ((m = re.exec(canonical))) {
+        const p = m[2] ?? m[3] ?? m[4];
+        if (p && p !== "/dev/null" && !p.startsWith("&") && !/^\d$/.test(p))
+            out.push(p);
+    }
+    return out;
+}
+/** True if `p` resolves OUTSIDE the project/cwd root (a write/delete escaping the sandbox). Non-file
+ *  pseudo-paths (/dev/null) and empties are treated as in-scope. */
+export function isOutsideRoot(p, cwd) {
+    if (!p || p === "/dev/null" || p === "-")
+        return false;
+    const expanded = p.replace(/^~(?=\/|$)/, process.env.HOME ?? "~");
+    const abs = isAbsolute(expanded) ? resolve(expanded) : resolve(cwd, expanded);
+    const root = resolve(cwd);
+    return abs !== root && !abs.startsWith(root + "/");
+}
+/** Collect the file paths an edit-kind tool would write/delete, from its tool input. */
+export function editPaths(name, input) {
+    const paths = [];
+    if (typeof input.path === "string")
+        paths.push(input.path);
+    // apply_patch: { changes: [{ path, ... }] }
+    if (Array.isArray(input.changes)) {
+        for (const ch of input.changes)
+            if (ch && typeof ch.path === "string")
+                paths.push(ch.path);
+    }
+    return paths;
+}
+/** Deterministic risk classifier. Runs FIRST, in pure Node — this is what keeps normal work at zero cost.
+ *  Returns `low` for read tools, in-project edits, and ordinary shell commands (→ guardian is skipped
+ *  entirely); `high` only for destructive/irreversible bash or writes/deletes outside the project root. */
+export function classifyRisk(toolName, toolKind, input, cwd) {
+    if (toolKind === "read" || !input)
+        return { level: "low", reason: "" };
+    if (toolKind === "edit") {
+        for (const p of editPaths(toolName, input)) {
+            if (isOutsideRoot(p, cwd))
+                return { level: "high", reason: `writes/deletes outside the project root: ${p}` };
+        }
+        return { level: "low", reason: "" };
+    }
+    if (toolKind === "exec" && typeof input.command === "string") {
+        const command = input.command;
+        const whole = canonicalize(command);
+        // Whole-command check FIRST — catches cross-part shapes a compound split would hide (curl … | sh, where
+        // the danger is the pipe connecting two individually-benign parts).
+        if (isDestructiveCommand(whole))
+            return { level: "high", reason: `destructive/irreversible command: ${whole.slice(0, 120)}` };
+        // Then per-part: strictest part wins; if we can't safely parse it, fall back to the whole canonical form.
+        const parts = splitCompound(command) ?? [whole];
+        for (const part of parts) {
+            if (isDestructiveCommand(part))
+                return { level: "high", reason: `destructive/irreversible command: ${part.slice(0, 120)}` };
+            for (const t of redirectionTargets(part)) {
+                if (isOutsideRoot(t, cwd))
+                    return { level: "high", reason: `writes outside the project root via redirection: ${t}` };
+                if (SYSTEM_ROOTS.test(t))
+                    return { level: "high", reason: `writes to a system path: ${t}` };
+            }
+        }
+        return { level: "low", reason: "" };
+    }
+    // computer / unknown non-read kinds are already gated hard elsewhere (always-confirm); leave them to that.
+    return { level: "low", reason: "" };
+}
+// ── LLM veto (conservative; high-risk only) ──────────────────────────────────────────────────────────
+const GUARDIAN_SYSTEM = `You are a safety guardian for a coding agent. You are shown a SINGLE high-risk action the agent is about ` +
+    `to take, plus a short summary of the user's task. Decide whether to ALLOW or BLOCK it. Default to ALLOW. ` +
+    `Only BLOCK when the action is CLEARLY dangerous/irreversible AND not plausibly part of the stated task ` +
+    `(e.g. deleting unrelated files, wiping a disk, exfiltrating data, force-pushing over shared history when ` +
+    `the task never asked for it), or when it is CLEARLY misaligned with the task. If the action is a ` +
+    `reasonable step toward the task — even a destructive one the user likely wants — ALLOW it. When unsure, ` +
+    `ALLOW. Reply with ONLY compact JSON: {"decision":"allow"|"block","reason":"<one short sentence>"}.`;
+/** Parse the model's reply into a verdict. Anything we can't confidently read as a BLOCK is treated as
+ *  ALLOW (fail-open on ambiguity). */
+export function parseVerdict(text) {
+    const raw = (text ?? "").trim();
+    // Try strict JSON first, then the first {...} blob.
+    const tryParse = (s) => {
+        try {
+            const j = JSON.parse(s);
+            if (j && (j.decision === "block" || j.decision === "allow")) {
+                return { decision: j.decision, reason: typeof j.reason === "string" ? j.reason : "" };
+            }
+        }
+        catch {
+            /* fall through */
+        }
+        return null;
+    };
+    const direct = tryParse(raw);
+    if (direct)
+        return direct;
+    const m = /\{[\s\S]*\}/.exec(raw);
+    if (m) {
+        const blob = tryParse(m[0]);
+        if (blob)
+            return blob;
+    }
+    // No parseable verdict → fail open.
+    return { decision: "allow", reason: "" };
+}
+/** A brief, safe task-context summary for the guardian prompt: the most recent genuine user message,
+ *  truncated. Kept short (cheap call, and we don't want to leak the whole transcript). */
+export function taskSummary(history) {
+    for (let i = history.length - 1; i >= 0; i--) {
+        const m = history[i];
+        if (m.role === "user" && typeof m.content === "string" && m.content.trim()) {
+            return m.content.trim().replace(/\s+/g, " ").slice(0, 500);
+        }
+    }
+    return "(no task context available)";
+}
+const DEFAULT_TIMEOUT_MS = 6000;
+/** Ask the cheap model to veto a single high-risk action. Conservative + fail-open:
+ *   - no provider            → allow (guardian effectively off; deterministic layers still apply)
+ *   - timeout / error        → allow (a guardian glitch must never break legit work)
+ *   - unparseable reply      → allow
+ *  Only a clean, parsed `block` blocks. */
+export async function guardianVeto(provider, action, history, opts = {}) {
+    if (!provider)
+        return { decision: "allow", reason: "" }; // fail-open: no model → deterministic layers still guard
+    const prompt = `TASK CONTEXT:\n${taskSummary(history)}\n\n` +
+        `HIGH-RISK ACTION (flagged: ${action.classifierReason}):\n` +
+        `tool: ${action.tool}\n${action.detail}\n\n` +
+        `Allow or block this action? Reply with only the JSON verdict.`;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    // Chain the caller's interrupt signal so Esc also aborts the guardian call.
+    if (opts.signal) {
+        if (opts.signal.aborted)
+            ac.abort();
+        else
+            opts.signal.addEventListener("abort", () => ac.abort(), { once: true });
+    }
+    try {
+        const r = await provider.turn({
+            system: GUARDIAN_SYSTEM,
+            history: [{ role: "user", content: prompt }],
+            tools: [],
+            onText: () => { },
+            signal: ac.signal,
+        });
+        if (r.stop === "error")
+            return { decision: "allow", reason: "" }; // fail-open on model error
+        return parseVerdict(r.text);
+    }
+    catch {
+        return { decision: "allow", reason: "" }; // fail-open on timeout/abort/throw
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function newBreaker() {
+    return { blocks: 0, tripped: false };
+}
+/** Record a guardian BLOCK; trip the breaker at the threshold. Returns the (possibly updated) state's
+ *  tripped flag. Deterministic — a harder stop than the soft stuck-guard nudge. */
+export function recordBlock(state, threshold = GUARDIAN_BLOCK_THRESHOLD) {
+    state.blocks += 1;
+    if (state.blocks >= threshold)
+        state.tripped = true;
+    return state.tripped;
+}
+export const GUARDIAN_BLOCK_THRESHOLD = 3;
+// ── Config ─────────────────────────────────────────────────────────────────────────────────────────────
+/** Guardian is ON by default and only engages on high-risk actions (so normal turns are untouched).
+ *  Off via `HARA_GUARDIAN=0` (or config key `guardian: "off"`). Any other value / unset → on. */
+export function guardianEnabled(config) {
+    const env = process.env.HARA_GUARDIAN;
+    if (env !== undefined)
+        return !(env === "0" || env.toLowerCase() === "off" || env.toLowerCase() === "false");
+    if (config?.guardian !== undefined)
+        return !(config.guardian === "off" || config.guardian === "false");
+    return true; // default on
+}

package/dist/session/session-model.js

@@ -0,0 +1,36 @@
+// Session-level model selection — small module so the four role-provider call sites in index.ts
+// (runOrg / executeAtom / review-chain / runSubagent) can consult "is the user forcing all roles
+// to the session model?" without importing index.ts. The state is plain process-local, reset
+// between processes (we never persist `--force` across runs — only the session-pinned model).
+//
+// Priority chain (highest first):
+//   /model X --force  (this session, all roles)  ← sessionForceModel === true
+//   /model X          (this session, defaults respect role.model)
+//   --model X         (CLI flag, written into meta.model)
+//   meta.model        (resume; restored into cfg.model at startup)
+//   role.model        (org role frontmatter — respected by default)
+//   profile.model / defaultModel / provider default
+let _forced = false;
+/** Switch on/off "force all roles to use the session model" for this process. */
+export function setSessionForceModel(on) {
+    _forced = !!on;
+}
+/** Is the session-force flag on? */
+export function isSessionForceModel() {
+    return _forced;
+}
+/** Resolve the model a role should run under given current force state.
+ *  - default (no --force): role's frontmatter model wins if set, else fall back to session model.
+ *  - with --force: session model wins, role.model is ignored.
+ *  Returns undefined when there's no override needed (role.model is unset OR equals cfg.model OR
+ *  force is on AND we should rebuild with cfg.model only when role.model would otherwise have
+ *  switched providers — i.e. callers should still gate "rebuild provider only if different"). */
+export function effectiveRoleModel(roleModel, sessionModel) {
+    if (_forced)
+        return undefined; // force → use the session/base provider, ignore role.model entirely
+    if (!roleModel)
+        return undefined;
+    if (roleModel === sessionModel)
+        return undefined;
+    return roleModel;
+}

package/dist/statusbar.js

@@ -21,11 +21,20 @@ export function contextWindow(model) {
     return 200_000;
 }
 export const ctxPctFor = (model, lastInput) => lastInput > 0 ? Math.min(99, Math.round((lastInput / contextWindow(model)) * 100)) : 0;
-/** Top border with the session name in the right corner: `────────── ⏺ session ─` */
+/** Top border with the session name in the right corner: `────── [profile] ⏺ session ─`.
+ *  The profile chip on the left flank surfaces "which identity am I as right now". gateway
+ *  profiles get a cyan ORG badge (drawing the eye — your traffic is going somewhere else),
+ *  personal/byok profiles get a dim badge so they fade into the background. */
 export function borderTop(s, cols) {
     const name = truncate(s.sessionName || "new session", Math.max(8, cols - 14));
-    const label = `${c.cyan("⏺")} ${c.bold(name)}`;
-    return rule(cols - vlen(label) - 3) + " " + label + " " + rule(1);
+    const right = `${c.cyan("⏺")} ${c.bold(name)}`;
+    const chip = s.profileId
+        ? (s.profileKind === "gateway" ? c.cyan(`[${s.profileId} · ORG]`) : c.dim(`[${s.profileId}]`))
+        : "";
+    const left = chip ? chip + " " : "";
+    const innerLen = vlen(left) + vlen(right);
+    const pad = Math.max(0, cols - innerLen - 4);
+    return rule(1) + " " + left + rule(pad) + " " + right + " " + rule(1);
 }
 /** Bottom border carrying mode · tokens · concurrency: `── ◆suggest auto-edit full-auto · ↑0 ↓0 · ⛁ ──` */
 export function borderBottom(s, cols, agents) {

package/dist/tools/ask_user.js

@@ -0,0 +1,64 @@
+// ask_user — pause mid-turn to ask the user a structured question and continue with their answer.
+// Mirrors Claude Code's AskUserQuestion / cc-haha + hermes `ask_user`: use it ONLY when genuinely blocked
+// on a decision only the user can make (an ambiguous requirement, a real fork in approach) — never for
+// anything you can derive from the code/context. The question (and optional numbered choices) is shown
+// through the SAME input channel as the approval prompt (ctx.ask), so it works in both the classic REPL and
+// the TUI. In headless / non-TTY / `-p` / gateway runs there is no interactive user (ctx.ask is absent) — the
+// tool returns a clear "proceed with your best judgment" string instead of hanging. kind:"read" so it never
+// itself triggers the approval gate (the interaction IS the prompt).
+import { registerTool } from "./registry.js";
+/** Returned when nobody can answer (headless / non-TTY / -p / gateway / sub-agent). Phrased so the model
+ *  keeps going on its own judgment rather than re-asking or stalling. */
+export const NO_INTERACTIVE_USER = "(no interactive user available — proceed with your best judgment)";
+registerTool({
+    name: "ask_user",
+    description: "Ask the user ONE structured question mid-turn and wait for their answer, then continue. " +
+        "Use this ONLY when you are genuinely blocked on a decision that ONLY the user can make — an ambiguous " +
+        "requirement, a missing preference, or a real fork in approach where guessing wrong is costly. " +
+        "Do NOT use it for anything you can infer from the code, files, or context, and do NOT use it to narrate " +
+        "or ask permission for an action (the approval gate already handles that). " +
+        "Provide `options` (a short list of likely answers) when the choice is constrained — they are shown as a " +
+        "numbered menu — but the user may always type a free-text answer instead. The tool returns the user's " +
+        "answer (chosen option or free text) as its result. " +
+        "In a non-interactive run (no terminal) it returns a 'proceed with your best judgment' note instead of " +
+        "blocking, so prefer making a reasonable call over asking when context already answers the question.",
+    kind: "read", // the prompt itself is the interaction; never route it through the approval gate
+    input_schema: {
+        type: "object",
+        properties: {
+            question: { type: "string", description: "the single, specific question to put to the user" },
+            options: {
+                type: "array",
+                items: { type: "string" },
+                description: "optional likely answers, shown as a numbered menu (the user may still type their own answer)",
+            },
+            header: { type: "string", description: "optional short label/topic for the question (e.g. 'Database choice')" },
+            context: { type: "string", description: "optional one-line context shown before the question (keep it short)" },
+        },
+        required: ["question"],
+    },
+    async run(input, ctx) {
+        const question = typeof input.question === "string" ? input.question.trim() : "";
+        if (!question)
+            return "ask_user needs a non-empty `question`.";
+        // No interactive user (headless / non-TTY / -p / gateway / sub-agent): do NOT block — let the model proceed.
+        if (typeof ctx.ask !== "function")
+            return NO_INTERACTIVE_USER;
+        const options = Array.isArray(input.options)
+            ? input.options.map((o) => String(o ?? "").trim()).filter((o) => o.length > 0)
+            : undefined;
+        const header = typeof input.header === "string" ? input.header.trim() : "";
+        const context = typeof input.context === "string" ? input.context.trim() : "";
+        // Compose a compact prompt: [header] (context) question — the channel renders it.
+        const prompt = [header ? `[${header}] ` : "", context ? `${context}\n` : "", question].join("");
+        try {
+            const answer = await ctx.ask(prompt, options && options.length ? options : undefined);
+            const text = typeof answer === "string" ? answer.trim() : "";
+            return text || "(the user gave an empty answer)";
+        }
+        catch (e) {
+            // If the interactive prompt fails for any reason, degrade gracefully rather than crash the turn.
+            return `${NO_INTERACTIVE_USER} (ask failed: ${e?.message ?? e})`;
+        }
+    },
+});

package/dist/tools/external_agent.js

@@ -0,0 +1,118 @@
+// external_agent — delegate a self-contained task to an EXTERNAL coding-agent CLI (claude-code / codex / …)
+// running headless on the host, and return its final text. Inspired by openclaw's ACP subagent feature, but
+// zero-dep: we drive each agent's native headless flag (`claude -p`, `codex exec`) over node:child_process
+// instead of the heavy ACP/acpx stack.
+//
+// Safety: kind:"exec" → inherits the loop's approval gate. It can read/write/run on the host, so it is the most
+// privileged tool — and because fan-out sub-agents only get the read-only allow-list (READONLY_TOOLS), they
+// never see this tool. Trust tiers (off|gated|full) gate the dangerous bypass/full-access sub-modes.
+import { spawn, execFileSync } from "node:child_process";
+import { registerTool } from "./registry.js";
+import { capHeadTail } from "./builtin.js";
+import { loadConfig } from "../config.js";
+/** Pure: build the spawn (cmd, args) for a backend, or null if unknown. Maps hara's sandbox/trust → the agent's
+ *  own permission flags; the dangerous bypass/full-access modes are only reachable at trust "full". */
+export function buildExternalArgv(backend, task, o) {
+    if (backend === "claude") {
+        const mode = o.trust === "full" ? "bypassPermissions" : o.sandbox === "workspace-write" ? "acceptEdits" : "plan";
+        return { cmd: "claude", args: ["-p", task, "--output-format", "text", ...(o.model ? ["--model", o.model] : []), "--permission-mode", mode] };
+    }
+    if (backend === "codex") {
+        const sb = o.trust === "full" ? "danger-full-access" : o.sandbox === "workspace-write" ? "workspace-write" : "read-only";
+        return { cmd: "codex", args: ["exec", task, "--cd", o.cwd, ...(o.model ? ["-m", o.model] : []), "--sandbox", sb] };
+    }
+    return null;
+}
+const BUILTIN_BACKENDS = ["claude", "codex"];
+/** Probe a CLI's availability via `<bin> --version` (cached per process). */
+const availCache = new Map();
+function available(bin) {
+    if (availCache.has(bin))
+        return availCache.get(bin);
+    let ok = false;
+    try {
+        execFileSync(bin, ["--version"], { stdio: "ignore", timeout: 5000 });
+        ok = true;
+    }
+    catch {
+        ok = false;
+    }
+    availCache.set(bin, ok);
+    return ok;
+}
+function resolveTrust() {
+    const cfg = loadConfig();
+    const v = (process.env.HARA_EXTERNAL_AGENT_TRUST ?? cfg.externalAgentTrust ?? "gated");
+    return v === "off" || v === "full" ? v : "gated";
+}
+registerTool({
+    name: "external_agent",
+    description: "Delegate a self-contained coding task to an EXTERNAL agent CLI — `claude` (Claude Code) or `codex` — " +
+        "running headless in the current directory, and return its result. Use for heavy, isolated work you want " +
+        "another agent to own end-to-end. It can read/write/run on the host, so it's gated by approval. " +
+        "Args: task (required), backend (claude|codex; default = first installed), model (optional).",
+    kind: "exec", // → approval gate; never exposed to read-only fan-out sub-agents
+    input_schema: {
+        type: "object",
+        properties: {
+            task: { type: "string", description: "the self-contained task for the external agent" },
+            backend: { type: "string", description: "claude | codex (default: first available on PATH)" },
+            model: { type: "string", description: "optional model id override for the external agent" },
+            timeout_ms: { type: "number", description: "hard cap in ms (default 600000, max 1800000)" },
+        },
+        required: ["task"],
+    },
+    async run(input, ctx) {
+        const trust = resolveTrust();
+        if (trust === "off")
+            return "external_agent is disabled (set externalAgentTrust to gated|full, or HARA_EXTERNAL_AGENT_TRUST).";
+        const task = typeof input.task === "string" ? input.task.trim() : "";
+        if (!task)
+            return "external_agent needs a non-empty `task`.";
+        const installed = BUILTIN_BACKENDS.filter((b) => available(b));
+        const backend = String(input.backend ?? "").trim() || installed[0] || "";
+        if (!BUILTIN_BACKENDS.includes(backend))
+            return `Unknown backend '${backend || "(none)"}'. Supported: ${BUILTIN_BACKENDS.join(", ")}.`;
+        if (!available(backend))
+            return `'${backend}' CLI not found on PATH. Installed external agents: ${installed.join(", ") || "none"}.`;
+        const built = buildExternalArgv(backend, task, { cwd: ctx.cwd, model: input.model ? String(input.model) : undefined, sandbox: ctx.sandbox ?? "off", trust });
+        if (!built)
+            return `Unknown backend '${backend}'.`;
+        const timeout = Math.min(Math.max(30_000, Number(input.timeout_ms) || 600_000), 1_800_000);
+        return await new Promise((resolve) => {
+            const child = spawn(built.cmd, built.args, { cwd: ctx.cwd, env: process.env });
+            let out = "";
+            let err = "";
+            let done = false;
+            const finish = (s) => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(timer);
+                resolve(capHeadTail(s));
+            };
+            const timer = setTimeout(() => {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    /* already gone */
+                }
+                finish(`[${backend}] timed out after ${timeout}ms\n${out}`);
+            }, timeout);
+            child.stdin.end(); // task is passed via argv
+            child.stdout.on("data", (d) => {
+                out += d.toString();
+                ctx.ui?.notice?.(d.toString().trimEnd());
+            });
+            child.stderr.on("data", (d) => {
+                err += d.toString();
+            });
+            child.on("error", (e) => finish(`[${backend}] failed to start: ${e.message} (is it installed?)`));
+            child.on("close", (code) => {
+                const text = out.trim() || "(external agent produced no output)";
+                finish(code === 0 ? text : `[${backend} exit ${code}]\n${text}${err ? `\n[stderr]\n${err.trim()}` : ""}`);
+            });
+        });
+    },
+});

package/dist/tools/skill.js

@@ -1,6 +1,7 @@
 // The `skill` tool — load a skill's full instructions on demand. The system prompt lists available
 // skills (id + description); the model calls this to pull the body before doing a task the skill covers.
 // Returning the body as a tool RESULT (not editing the system prompt) keeps the cached prefix stable.
+import { dirname } from "node:path";
 import { registerTool } from "./registry.js";
 import { loadSkillIndex, loadSkillBody } from "../skills/skills.js";
 import { scanMemory } from "../memory/guard.js";
@@ -21,10 +22,13 @@ registerTool({
         const scan = scanMemory(body); // skills may come from plugins (untrusted) — guard at load time
         if (!scan.ok)
             return `Skill '${id}' blocked: its content looks unsafe (${scan.hits.join(", ")}).`;
+        // Tell the model where this skill lives so it can read sibling files (assets/, references/) by absolute
+        // path — relying on "~" or cwd-relative guessing is unreliable across tools/sandboxes.
+        const located = `Skill directory (absolute): ${dirname(sk.file)}\nRead any sibling files this skill mentions (e.g. references/…, assets/…) from under that directory.\n\n${body}`;
         if (sk.context === "fork" && ctx.spawn) {
             // fork: run the skill as a delegated sub-agent rather than inlining it into this turn
-            return await ctx.spawn(`Follow this skill to complete the current task:\n\n${body}`);
+            return await ctx.spawn(`Follow this skill to complete the current task:\n\n${located}`);
         }
-        return body; // inline (default): the body enters the conversation as this tool's result
+        return located; // inline (default): the body enters the conversation as this tool's result
     },
 });

package/dist/tools/todo.js

@@ -7,6 +7,29 @@ let todos = [];
 export function currentTodos() {
     return todos;
 }
+const listeners = new Set();
+/** Subscribe to checklist changes. Returns an unsubscribe fn. */
+export function onTodosChange(fn) {
+    listeners.add(fn);
+    return () => {
+        listeners.delete(fn);
+    };
+}
+function emit() {
+    for (const fn of listeners) {
+        try {
+            fn(todos);
+        }
+        catch {
+            /* listeners must not break the tool */
+        }
+    }
+}
+/** Reset between sessions/turns if a runner wants a clean slate (not used by the tool itself). */
+export function clearTodos() {
+    todos = [];
+    emit();
+}
 const MARK = { pending: "☐", in_progress: "▶", done: "☑" };
 export function renderTodos(list) {
     if (!list.length)
@@ -16,9 +39,33 @@ export function renderTodos(list) {
 }
 registerTool({
     name: "todo_write",
-    description: "Maintain a short task checklist for the CURRENT work. Use it to plan a multi-step task up front, then " +
-        "update it as you go: keep exactly one item 'in_progress', flip items to 'done' as you finish, add items " +
-        "you discover. Pass the FULL list each call (it replaces the previous). Skip it for trivial one-step tasks.",
+    description: "Maintain a short task checklist for the CURRENT work. Pass the FULL list each call (it replaces the previous). " +
+        "Each item has `text` (imperative, e.g. 'Run tests') AND `activeForm` (present-continuous, e.g. 'Running tests') — " +
+        "the UI shows activeForm while the item is in_progress. Exactly ONE item should be in_progress at a time; flip " +
+        "items to 'done' as you finish; add items you discover. " +
+        "\n\n## Use this tool when" +
+        "\n  - the task takes 3+ distinct steps (refactor across files, new feature, multi-file fix, migrations)" +
+        "\n  - the user gave you a numbered/comma-separated list of things to do" +
+        "\n  - you discover mid-work that scope grew past a single edit" +
+        "\n  - the user explicitly asks for a plan/checklist" +
+        "\n\n## Skip this tool when" +
+        "\n  - reading one file or answering one question" +
+        "\n  - running one shell command and reporting output" +
+        "\n  - a single straight-line edit to one location" +
+        "\n  - pure conversation / explanation" +
+        "\n\n## Examples — use it" +
+        "\n  user: \"add a dark-mode toggle and run tests\" → 4-5 items (component, state, styles, tests)" +
+        "\n  user: \"rename getCwd to getCurrentWorkingDirectory across the project\" → one item per file after grepping" +
+        "\n  user: \"implement registration, catalog, cart, checkout\" → break each feature into 2-3 sub-items" +
+        "\n  user: \"optimize this slow React app\" → one item per identified bottleneck" +
+        "\n\n## Examples — skip it" +
+        "\n  user: \"how do I print 'hello' in python?\" → answer directly" +
+        "\n  user: \"what does git status do?\" → explain" +
+        "\n  user: \"add a comment to calculateTotal\" → one edit, no plan needed" +
+        "\n  user: \"run npm install\" → one exec, report output" +
+        "\n\n## After updating the list" +
+        "\nBriefly say what changed in one short line (e.g. \"marked 2 done, starting on tests\"); do NOT repeat the full " +
+        "checklist back to the user — the UI already renders it live.",
     input_schema: {
         type: "object",
         properties: {
@@ -28,7 +75,11 @@ registerTool({
                 items: {
                     type: "object",
                     properties: {
-                        text: { type: "string", description: "the task, a short imperative phrase" },
+                        text: { type: "string", description: "the task, a short imperative phrase (e.g. 'Run tests')" },
+                        activeForm: {
+                            type: "string",
+                            description: "present-continuous form shown while in_progress (e.g. 'Running tests'). Always provide.",
+                        },
                         status: { type: "string", enum: ["pending", "in_progress", "done"] },
                     },
                     required: ["text", "status"],
@@ -41,11 +92,17 @@ registerTool({
     async run(input) {
         const raw = Array.isArray(input.todos) ? input.todos : [];
         todos = raw
-            .map((t) => ({
-            text: String(t?.text ?? "").trim(),
-            status: (["pending", "in_progress", "done"].includes(t?.status) ? t.status : "pending"),
-        }))
+            .map((t) => {
+            const text = String(t?.text ?? "").trim();
+            const status = (["pending", "in_progress", "done"].includes(t?.status) ? t.status : "pending");
+            const activeFormRaw = typeof t?.activeForm === "string" ? t.activeForm.trim() : "";
+            const item = { text, status };
+            if (activeFormRaw)
+                item.activeForm = activeFormRaw;
+            return item;
+        })
             .filter((t) => t.text);
+        emit();
         return renderTodos(todos);
     },
 });