@nanhara/hara 0.48.0 → 0.53.0

package/CHANGELOG.md

@@ -5,6 +5,70 @@ 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.53.0 — unreleased (task-done notifications + steering in plan mode)
+
+- **Notifications** — get pinged when a turn finishes so you can walk away during a long run
+  (codex/Claude-Code parity). `hara config set notify bell` rings the terminal BEL; `notify system` fires
+  an OS notification (macOS `osascript` / Linux `notify-send`) plus the bell; default `off`. Gated on
+  elapsed time (≥8s) so quick turns you were watching stay silent. Wired into the TUI turn, plan-mode
+  execute, and the plain REPL; `hara doctor` shows the setting. New `src/notify.ts` (`notifyDone`).
+- **Type-ahead steering now covers plan mode too.** v0.52 wired steering into the regular turn only;
+  the `pendingInput` builder is now hoisted so plan-mode *investigation* and *execution* also fold in
+  messages you type mid-turn (previously they fell back to the old wait-for-turn-end behavior — an
+  inconsistency). All three turn paths now steer.
+
+## 0.52.0 — unreleased (type-ahead steering — mid-turn messages course-correct the live task)
+
+- **Type-ahead now *steers* the running turn** instead of waiting for it to finish. Previously a message
+  typed while hara worked was held and replayed as a brand-new turn once the turn ended — so a
+  supplement ("also handle the error case", "use TS not JS") arrived *after* the task had already
+  finished on the old understanding, becoming rework. Now, studying how **codex** does it (its
+  `pending_input` drains at the next model-call boundary *inside* the same turn) vs **cc-haha/Claude
+  Code** (waits for full completion), hara adopts the codex model: queued messages are **folded into the
+  next model call** (drained after each tool round), so the model course-corrects mid-task. Each shows
+  inline in the transcript at the point it's folded in. Messages typed during the *final* step (no more
+  tool rounds) still start a fresh turn; **Esc** drops the queue and stops.
+- New `RunOpts.pendingInput` (the loop drains it before each model call; unused outside the TUI = zero
+  change for `-p`/sub-agents/plain REPL). The TUI hands the queue through `Helpers.drainQueue`.
+- **`toAnthropic` now coalesces consecutive `user` messages** — required since a steered message lands
+  right after tool-results (which map to a `user` message) and Anthropic rejects two `user` turns in a
+  row. Dormant in normal alternating histories. Unit-tested.
+
+## 0.51.0 — unreleased (lifecycle hooks — PreToolUse / PostToolUse)
+
+- **Hooks dispatch** — run your own shell commands around every tool call (codex / Claude-Code parity, which
+  hara lacked). A **`PreToolUse`** hook runs *before* a tool and can **veto** it (non-zero exit blocks the
+  call; its stdout/stderr becomes the denial the model sees) — e.g. forbid `bash rm -rf`, gate edits to a
+  path, require a clean tree. A **`PostToolUse`** hook runs *after* (observe-only) — e.g. `prettier` a file
+  the agent just wrote, log/notify. The command gets `{tool, payload}` as JSON on stdin + `HARA_TOOL_NAME`
+  in its env; each is matched by a `matcher` (regex/literal on the tool name, `*`/omitted = all) with a 30s
+  timeout. Configure in `config.json` `"hooks"`; **plugins can contribute hooks** too. `hara doctor` shows
+  the active count. No hooks configured = zero overhead (fast no-op).
+
+  ```jsonc
+  // ~/.hara/config.json
+  "hooks": {
+    "PreToolUse":  [{ "matcher": "bash", "command": "grep -q 'rm -rf' && { echo 'no rm -rf'; exit 1; } || exit 0" }],
+    "PostToolUse": [{ "matcher": "edit_file|write_file", "command": "prettier --write \"$(jq -r .payload.input.path)\" 2>/dev/null; exit 0" }]
+  }
+  ```
+
+## 0.50.0 — unreleased (web_search — find pages, not just fetch)
+
+- New **`web_search`** tool — search the web (title/URL/snippet), then `web_fetch` a result to read it. Closes
+  the other codex/cc-haha gap (hara could previously only fetch a *known* URL). **Reliable with a Tavily key**
+  (`HARA_SEARCH_API_KEY` / `TAVILY_API_KEY`, free tier); a **keyless DuckDuckGo** fallback works best-effort
+  (POST endpoint; may rate-limit). Read-kind, available to sub-agents. Verified live (keyless: "anthropic
+  claude" → real results); parser unit-tested (incl. the DDG `uddg` redirect decode).
+
+## 0.49.0 — unreleased (inline todo tool — `todo_write`)
+
+- New **`todo_write`** tool — the agent maintains a live task checklist during multi-step work (codex's
+  `update_plan` / Claude Code's `TodoWrite`, which hara lacked). Plan up front, keep one item `in_progress`,
+  flip to `done` as you go; pass the full list each call. Read-kind (never prompts); the system prompt nudges
+  its use for multi-step tasks; sub-agents can use it too. Renders a `☐/▶/☑` checklist with a done count.
+  *(Gap analysis vs codex + cc-haha: this was the top missing capability.)*
+
 ## 0.48.0 — unreleased (chrome plugin: drive your real logged-in Chrome)
 
 - New first-party **`chrome` plugin** — web automation via **`chrome-devtools-mcp`** against a **real Chrome with

package/README.md

@@ -179,6 +179,8 @@ by the tier, the frontmost-app allowlist, a dangerous-key blocklist, and a once-
 vision model into **actionable** output — interactive elements + positions (pass `focus` to target what you're after) — so even a text-only main model can click.
 **Sessions**: conversations are saved automatically — `-c` / `--resume <id>` to continue, `hara sessions` to list.
 **MCP**: add an `mcpServers` map to config (global or project `.hara/config.json`); their tools appear to the agent as `mcp__<server>__<tool>`.
+**Notifications**: `hara config set notify bell` (terminal bell) or `notify system` (OS notification) pings you when a turn finishes — handy for long runs you've stepped away from. Gated on elapsed time so quick turns stay quiet; off by default.
+**Hooks**: run your own shell commands around tool calls via a `"hooks"` map in config. A **`PreToolUse`** hook can **veto** a call (non-zero exit blocks it; its output becomes the reason the model sees) — gate `bash`, forbid edits outside a path, require a clean tree. A **`PostToolUse`** hook observes (format/lint a file the agent just wrote, log, notify). Each has a `matcher` (regex/literal on the tool name, `*` = all) and gets `{tool, payload}` on stdin + `HARA_TOOL_NAME` in env. Plugins can contribute hooks too.
 **Profiles**: add a `profiles` map to `~/.hara/config.json` (`--profile <name>`), or drop a project-level `.hara/config.json` that overrides the global config.
 
 ### The org — what makes hara different
@@ -208,6 +210,7 @@ read-only **`grep`** / **`glob`** / **`ls`** / **`web_fetch`** — behind a huma
 dangerous ones unless `-y`. Read-only tools run in parallel within a turn, and edits print a
 **colored diff** of what changed. Shell output streams live; press **Esc** to interrupt a running
 turn, or **`/undo`** to revert the last edit.
+- **Type-ahead steering**: keep typing while hara works — your message is held, then **folded into the next model call** (not deferred to a new turn), so a clarification or "also do X" course-corrects the task already in flight (codex-style). Messages typed after the final step start a fresh turn; **Esc** drops the queue and stops.
 - **Project context**: auto-loads `AGENTS.md` (the cross-tool standard) walking up to the repo root; `hara init` writes one by analyzing the repo.
 - **`@file` mentions**: attach file contents to a message (`@path`); Tab-completes with a **fuzzy** matcher over the project (subdirs, git-tracked + untracked) — `@idx` → `src/index.ts`. `@<dir>` loads a directory listing, `@src/`+Tab drills into a folder, and mistyped tool/file paths get a "did you mean" suggestion.
 - **Multi-provider**: Anthropic (Claude) or any OpenAI-compatible endpoint (Qwen/DashScope, GLM, Kimi, OpenAI) — **all streamed live**.

package/dist/agent/loop.js

@@ -4,6 +4,7 @@ import { c, out } from "../ui.js";
 import { activity } from "../activity.js";
 import { makeRenderer } from "../md.js";
 import { skillsDigest } from "../skills/skills.js";
+import { runHooks } from "../hooks.js";
 /** Whether a tool call needs user confirmation under the given approval mode. */
 export function needsConfirm(kind, mode) {
     if (kind === "read")
@@ -20,7 +21,9 @@ const HARA_SYSTEM = (cwd) => `You are hara, a coding agent running in the user's
 Working directory: ${cwd}
 Be concise and direct. Use the provided tools to read files, edit/write files, and run shell
 commands. Prefer small, verifiable steps; edit existing files with edit_file rather than rewriting
-them whole. You have a persistent memory: use memory_search before answering about prior decisions,
+them whole. 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
+memory: use memory_search before answering about prior decisions,
 conventions, or the user's preferences, and memory_write to proactively save durable facts you learn.
 When a task matches one of the Skills listed below, call the \`skill\` tool to load its full instructions
 before acting; save a reusable how-to as a new skill with skill_create. If you discover a durable project
@@ -38,6 +41,12 @@ function composeSystem(cwd, projectContext, override, memory) {
 export async function runAgent(history, opts) {
     const { provider, ctx } = opts;
     for (;;) {
+        // Type-ahead steering: fold in anything the user submitted while the previous step ran, so it
+        // reaches the model on this next call (drained after the last tool round; empty on the 1st pass).
+        if (opts.pendingInput) {
+            for (const m of await opts.pendingInput())
+                history.push(m);
+        }
         const specs = opts.toolFilter ? toolSpecs().filter((t) => opts.toolFilter(t.name)) : toolSpecs();
         const sink = ctx.ui; // TUI mode: route output to ink instead of stdout
         const tty = stdout.isTTY && !opts.quiet && !sink;
@@ -154,8 +163,14 @@ export async function runAgent(history, opts) {
             }
             activity.inc();
             try {
+                const pre = runHooks("PreToolUse", p.tu.name, p.tu.input, ctx.cwd); // a hook may veto the call
+                if (pre.block) {
+                    results[idx] = { id: p.tu.id, name: p.tu.name, content: pre.message, isError: true };
+                    return;
+                }
                 const res = await p.tool.run(p.tu.input, ctx);
                 results[idx] = { id: p.tu.id, name: p.tu.name, content: res };
+                runHooks("PostToolUse", p.tu.name, { input: p.tu.input, result: res }, ctx.cwd); // observe-only
             }
             catch (e) {
                 results[idx] = { id: p.tu.id, name: p.tu.name, content: `Error: ${e.message}`, isError: true };

package/dist/config.js

@@ -11,7 +11,7 @@ const PROVIDER_DEFAULTS = {
     "qwen-oauth": { model: "coder-model", envKey: "QWEN_OAUTH_TOKEN" },
     openai: { model: "gpt-4o-mini", envKey: "OPENAI_API_KEY" },
 };
-export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey"];
+export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "notify"];
 export const APPROVAL_MODES = ["suggest", "auto-edit", "full-auto"];
 export const SANDBOX_MODES = ["off", "workspace-write", "read-only"];
 const PROJECT_ROOT_MARKERS = [".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", ".hg"];
@@ -107,7 +107,9 @@ export function loadConfig(opts = {}) {
         ...(project.mcpServers ?? {}),
         ...(profile.mcpServers ?? {}),
     };
-    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, mcpServers, cwd: process.cwd() };
+    const hooks = (merged.hooks && typeof merged.hooks === "object" ? merged.hooks : {});
+    const notify = (process.env.HARA_NOTIFY ?? merged.notify ?? "off");
+    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, hooks, notify, mcpServers, cwd: process.cwd() };
 }
 export function providerEnvKey(provider) {
     return (PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic).envKey;

package/dist/hooks.js

@@ -0,0 +1,64 @@
+// Lifecycle hooks — run user/plugin shell commands around tool calls (codex/Claude-Code parity).
+// PreToolUse runs BEFORE a tool: a non-zero exit BLOCKS the call (its output becomes the denial message).
+// PostToolUse runs AFTER: observe-only (format, log, notify). Configured in config.json `hooks` + contributed
+// by plugins. The command receives {tool, payload} as JSON on stdin + HARA_TOOL_NAME in the env.
+import { spawnSync } from "node:child_process";
+import { loadConfig } from "./config.js";
+import { pluginHooks } from "./plugins/plugins.js";
+let cache = null;
+export function resetHooksCache() {
+    cache = null;
+}
+function merged() {
+    if (cache)
+        return cache;
+    const cfg = loadConfig().hooks ?? {};
+    const plg = pluginHooks();
+    cache = {
+        PreToolUse: [...(cfg.PreToolUse ?? []), ...(plg.PreToolUse ?? [])],
+        PostToolUse: [...(cfg.PostToolUse ?? []), ...(plg.PostToolUse ?? [])],
+    };
+    return cache;
+}
+const matches = (m, name) => {
+    if (!m || m === "*")
+        return true;
+    try {
+        return new RegExp(m).test(name);
+    }
+    catch {
+        return m === name;
+    }
+};
+/** True if any hook is configured (lets the loop skip the work entirely in the common case). */
+export function hasHooks() {
+    const h = merged();
+    return !!(h.PreToolUse?.length || h.PostToolUse?.length);
+}
+/** Run hooks for an event matching `toolName`. PreToolUse: a non-zero exit BLOCKS (returns the message);
+ *  PostToolUse: observe-only, never blocks. Sync (hooks are short, opt-in); 30s timeout each. */
+export function runHooks(event, toolName, payload, cwd) {
+    for (const h of merged()[event] ?? []) {
+        if (!matches(h.matcher, toolName))
+            continue;
+        let r;
+        try {
+            r = spawnSync(h.command, {
+                shell: true,
+                cwd,
+                input: JSON.stringify({ tool: toolName, payload }),
+                encoding: "utf8",
+                timeout: 30_000,
+                env: { ...process.env, HARA_TOOL_NAME: toolName },
+            });
+        }
+        catch {
+            continue;
+        }
+        if (event === "PreToolUse" && r.status !== 0 && r.status !== null) {
+            const msg = (String(r.stdout ?? "") + String(r.stderr ?? "")).trim();
+            return { block: true, message: `⛔ blocked by a PreToolUse hook${msg ? `: ${msg}` : ` (exit ${r.status})`}` };
+        }
+    }
+    return { block: false, message: "" };
+}

package/dist/index.js

@@ -15,6 +15,7 @@ import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { loadConfig, configPath, readRawConfig, writeConfigValue, setModelVisionOverride, providerEnvKey, CONFIG_KEYS, APPROVAL_MODES, SANDBOX_MODES, } from "./config.js";
 import { runAgent } from "./agent/loop.js";
+import { notifyDone } from "./notify.js";
 import { getTools } from "./tools/registry.js";
 import { createAnthropicProvider } from "./providers/anthropic.js";
 import { createOpenAIProvider } from "./providers/openai.js";
@@ -27,7 +28,7 @@ import { expandMentions, fileCandidates } from "./context/mentions.js";
 import { newSessionId, shortId, resolveSessionId, saveSession, loadSession, listSessions, latestForCwd, titleFrom, slugify, } from "./session/store.js";
 import { loadRoles, scaffoldRoles } from "./org/roles.js";
 import { loadSkillIndex, loadSkillBody, scaffoldSkills, globalSkillsDir } from "./skills/skills.js";
-import { installPlugin, uninstallPlugin, listInstalled, enabledPlugins, setPluginEnabled, pluginMcpServers } from "./plugins/plugins.js";
+import { installPlugin, uninstallPlugin, listInstalled, enabledPlugins, setPluginEnabled, pluginMcpServers, pluginHooks } from "./plugins/plugins.js";
 import { routeByKeywords, buildDispatchPrompt, parseRoleId } from "./org/router.js";
 import { decompose, topoOrder, topoWaves, savePlan, loadPlan, atomPrompt, verify, runCheck } from "./org/planner.js";
 import { connectMcpServers, closeMcp } from "./mcp/client.js";
@@ -46,6 +47,7 @@ import "./tools/agent.js"; // register agent (subagent spawn)
 import "./tools/memory.js"; // register memory_search/get/write/forget/skill_create
 import "./tools/skill.js"; // register the skill loader tool
 import "./tools/codebase.js"; // register codebase_search (repo as a knowledge base)
+import "./tools/todo.js"; // register todo_write (inline task checklist)
 import { computerBackends } from "./tools/computer.js"; // register the computer tool + expose the backend probe
 const here = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
@@ -271,7 +273,7 @@ async function runResume(o) {
     savePlan(o.cwd, plan);
     await executePlan(plan, roles, o);
 }
-const READONLY_TOOLS = new Set(["read_file", "grep", "glob", "ls", "web_fetch", "codebase_search"]);
+const READONLY_TOOLS = new Set(["read_file", "grep", "glob", "ls", "web_fetch", "web_search", "codebase_search", "todo_write"]);
 const REVIEW_SYSTEM = "You are a senior code reviewer. Review the git diff the user provides for: correctness bugs, security " +
     "issues, missing error handling, unclear naming, and missing/weak tests. You may read files (read-only) " +
     "for context. Be concise and specific — cite file:line and the concrete fix. Group findings by severity: " +
@@ -376,6 +378,8 @@ function runDoctor(cfg) {
         `${dot} screen ${cfg.computerUse === "off" ? c.dim("off (hara config set computerUse read|click|full)") : c.bold(cfg.computerUse) + c.dim(` · ${computerBackends()}${cfg.computerApps.length ? " · apps: " + cfg.computerApps.join(", ") : " · no app allowlist"}`)}`,
         `${dot} plugins ${(() => { const inst = listInstalled(); const on = enabledPlugins().length; return inst.length ? c.dim(`${on}/${inst.length} enabled: ${inst.map((p) => p.name).slice(0, 6).join(", ")}`) : c.dim("none — hara plugin add <source>"); })()}`,
         `${dot} mcp servers ${c.dim(String(Object.keys({ ...pluginMcpServers(), ...cfg.mcpServers }).length))}`,
+        `${dot} hooks ${(() => { const ph = pluginHooks(); const pre = (cfg.hooks.PreToolUse ?? []).length + (ph.PreToolUse ?? []).length; const post = (cfg.hooks.PostToolUse ?? []).length + (ph.PostToolUse ?? []).length; return pre + post ? c.dim(`${pre} pre · ${post} post`) : c.dim("none — config.json \"hooks\""); })()}`,
+        `${dot} notify ${cfg.notify === "off" ? c.dim("off — hara config set notify bell|system") : c.bold(cfg.notify)}`,
     ];
     return lines.join("\n");
 }
@@ -1423,6 +1427,22 @@ program.action(async (opts) => {
                 }
                 const ui = { text: h.sink.assistantDelta, reasoning: h.sink.reasoningDelta, tool: h.sink.tool, diff: h.sink.diff, notice: h.sink.notice };
                 const appr = h.approval;
+                // Type-ahead steering: fold messages typed mid-turn into the next model call (codex-style) so a
+                // clarification/addition course-corrects the live task, rather than waiting for a fresh turn.
+                // Shared by every turn below (plan investigate, plan execute, and the regular turn).
+                const pendingInput = async () => {
+                    const out = [];
+                    for (const it of h.drainQueue()) {
+                        const r2 = await resolveImages(it.images, h);
+                        const body = expandMentions(it.line, cwd) + (r2.skip ? "" : (r2.extraText ?? ""));
+                        const attach = !r2.skip && r2.attach?.length ? r2.attach : undefined;
+                        if (!body.trim() && !attach)
+                            continue; // image-only message whose image was skipped → nothing to add
+                        out.push({ role: "user", content: `[I sent this while you were working on the above]\n\n${body}`, ...(attach ? { images: attach } : {}) });
+                    }
+                    return out;
+                };
+                const turnStart = Date.now(); // for the task-done notification (gated on elapsed)
                 if (appr === "plan") {
                     // PLAN MODE: read-only investigate → propose a plan → selectable proceed → execute.
                     const planImg = await resolveImages(images, h);
@@ -1443,6 +1463,7 @@ program.action(async (opts) => {
                         projectContext,
                         stats,
                         signal: h.signal,
+                        pendingInput,
                     });
                     if (!meta.title) {
                         meta.title = await nameSession(provider, history);
@@ -1470,10 +1491,12 @@ program.action(async (opts) => {
                             projectContext,
                             stats,
                             signal: h.signal,
+                            pendingInput,
                         });
                         h.sink.usage(stats.input - xin, stats.output - xout);
                         saveSession(meta, history);
                     }
+                    notifyDone(cfg.notify, { message: meta.title || "plan turn complete", elapsedMs: Date.now() - turnStart });
                     return;
                 }
                 const ri = await resolveImages(images, h);
@@ -1494,12 +1517,14 @@ program.action(async (opts) => {
                     projectContext,
                     stats,
                     signal: h.signal,
+                    pendingInput,
                 });
                 if (!meta.title) {
                     meta.title = await nameSession(provider, history);
                     h.sink.session(meta.title);
                 }
                 h.sink.usage(stats.input - beforeIn, stats.output - beforeOut);
+                notifyDone(cfg.notify, { message: meta.title || "turn complete", elapsedMs: Date.now() - turnStart });
                 saveSession(meta, history);
             },
         });
@@ -1546,6 +1571,7 @@ program.action(async (opts) => {
         recalledContext = "";
         history.push({ role: "user", content: userContent });
         currentTurn = new AbortController();
+        const t0 = Date.now();
         try {
             await runAgent(history, { provider, ctx: { cwd, sandbox, spawn }, approval, confirm, autoApprove, projectContext, memory: buildMemory(), stats, signal: currentTurn.signal });
         }
@@ -1555,6 +1581,7 @@ program.action(async (opts) => {
         finally {
             currentTurn = null;
         }
+        notifyDone(cfg.notify, { message: meta.title || "turn complete", elapsedMs: Date.now() - t0 });
         if (!meta.title)
             meta.title = await nameSession(provider, history);
         if (bar.isActive()) {

package/dist/notify.js

@@ -0,0 +1,42 @@
+// Task-done notifications — ping the user when a turn finishes (or needs them) so they can walk away
+// during a long run (codex/Claude-Code parity). off = nothing; bell = terminal BEL; system = an OS
+// notification (best-effort, fire-and-forget) + bell. Gated on elapsed so quick turns you watched stay quiet.
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+export const NOTIFY_MODES = ["off", "bell", "system"];
+/** AppleScript double-quoted string (escape " and \). */
+const osaStr = (s) => '"' + s.replace(/[\\"]/g, "\\$&") + '"';
+/** Fire a notification for a finished/awaiting turn. No-op under `off` or when the turn was quicker than
+ *  `minMs` (default 8s) — you were watching those. `system` shells out without blocking and also rings the bell. */
+export function notifyDone(mode, opts) {
+    if (mode === "off")
+        return;
+    if (opts.elapsedMs < (opts.minMs ?? 8000))
+        return;
+    const bell = () => {
+        try {
+            process.stderr.write("\x07");
+        }
+        catch {
+            /* no tty */
+        }
+    };
+    if (mode === "bell")
+        return bell();
+    const title = (opts.title ?? "hara").slice(0, 80);
+    const msg = opts.message.slice(0, 200).replace(/\s*\n+\s*/g, " ").trim() || "done";
+    try {
+        const os = platform();
+        if (os === "darwin") {
+            spawn("osascript", ["-e", `display notification ${osaStr(msg)} with title ${osaStr(title)}`], { stdio: "ignore", detached: true }).unref();
+        }
+        else if (os === "linux") {
+            spawn("notify-send", ["-a", "hara", title, msg], { stdio: "ignore", detached: true }).unref();
+        }
+        // Windows (and any platform): the bell is the reliable cross-terminal signal; toast needs extra modules.
+    }
+    catch {
+        /* best-effort — a notification must never break the turn */
+    }
+    bell();
+}

package/dist/plugins/plugins.js

@@ -66,6 +66,20 @@ export function pluginMcpServers() {
         Object.assign(out, p.manifest.mcpServers ?? {});
     return out;
 }
+/** Lifecycle hooks contributed by enabled plugins (appended after user-config hooks). */
+export function pluginHooks() {
+    const out = { PreToolUse: [], PostToolUse: [] };
+    for (const p of enabledPlugins()) {
+        const h = p.manifest.hooks;
+        if (!h || typeof h !== "object")
+            continue;
+        if (Array.isArray(h.PreToolUse))
+            out.PreToolUse.push(...h.PreToolUse);
+        if (Array.isArray(h.PostToolUse))
+            out.PostToolUse.push(...h.PostToolUse);
+    }
+    return out;
+}
 /** Install a plugin from `file:<path>`, `github:<owner/repo>`, or `git:<url>` into ~/.hara/plugins/<name>. */
 export function installPlugin(source) {
     mkdirSync(pluginsDir(), { recursive: true });

package/dist/providers/anthropic.js

@@ -2,6 +2,19 @@ import Anthropic from "@anthropic-ai/sdk";
 import { imageToBase64 } from "../images.js";
 export function toAnthropic(history) {
     const msgs = [];
+    // Append a user message, merging into the previous one if it's also `user` — Anthropic requires
+    // alternating roles, and tool-results map to a user message, so a mid-turn-injected user message
+    // (type-ahead steering) lands right after one. Merging keeps the request valid; dormant otherwise.
+    const pushUser = (content) => {
+        const last = msgs[msgs.length - 1];
+        if (last && last.role === "user") {
+            const toBlocks = (c) => typeof c === "string" ? [{ type: "text", text: c }] : c;
+            last.content = [...toBlocks(last.content), ...toBlocks(content)];
+        }
+        else {
+            msgs.push({ role: "user", content });
+        }
+    };
     for (const m of history) {
         if (m.role === "user") {
             if (m.images?.length) {
@@ -13,10 +26,10 @@ export function toAnthropic(history) {
                     if (data)
                         blocks.push({ type: "image", source: { type: "base64", media_type: img.mediaType, data } });
                 }
-                msgs.push({ role: "user", content: blocks.length ? blocks : m.content });
+                pushUser(blocks.length ? blocks : m.content);
             }
             else {
-                msgs.push({ role: "user", content: m.content });
+                pushUser(m.content);
             }
         }
         else if (m.role === "assistant") {
@@ -28,15 +41,12 @@ export function toAnthropic(history) {
             msgs.push({ role: "assistant", content: content.length ? content : [{ type: "text", text: "(no output)" }] });
         }
         else {
-            msgs.push({
-                role: "user",
-                content: m.results.map((r) => ({
-                    type: "tool_result",
-                    tool_use_id: r.id,
-                    content: r.content,
-                    is_error: r.isError,
-                })),
-            });
+            pushUser(m.results.map((r) => ({
+                type: "tool_result",
+                tool_use_id: r.id,
+                content: r.content,
+                is_error: r.isError,
+            })));
         }
     }
     return msgs;

package/dist/tools/todo.js

@@ -0,0 +1,51 @@
+// todo_write — an inline task checklist the agent maintains during a turn (like codex's update_plan /
+// Claude Code's TodoWrite). Keeps the model organized on multi-step work and shows the user live progress.
+// In-memory, replace-whole-list semantics; kind:"read" so it never prompts and is safe to call freely.
+import { registerTool } from "./registry.js";
+let todos = [];
+/** The current checklist (latest todo_write wins) — for a TUI/statusline to render. */
+export function currentTodos() {
+    return todos;
+}
+const MARK = { pending: "☐", in_progress: "▶", done: "☑" };
+export function renderTodos(list) {
+    if (!list.length)
+        return "(todo list cleared)";
+    const done = list.filter((t) => t.status === "done").length;
+    return `Todos (${done}/${list.length} done):\n` + list.map((t) => `  ${MARK[t.status]} ${t.text}`).join("\n");
+}
+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.",
+    input_schema: {
+        type: "object",
+        properties: {
+            todos: {
+                type: "array",
+                description: "the full checklist, in order",
+                items: {
+                    type: "object",
+                    properties: {
+                        text: { type: "string", description: "the task, a short imperative phrase" },
+                        status: { type: "string", enum: ["pending", "in_progress", "done"] },
+                    },
+                    required: ["text", "status"],
+                },
+            },
+        },
+        required: ["todos"],
+    },
+    kind: "read", // pure state + display: never prompts, parallel-safe
+    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"),
+        }))
+            .filter((t) => t.text);
+        return renderTodos(todos);
+    },
+});

package/dist/tools/web.js

@@ -24,6 +24,103 @@ export function htmlToText(html) {
         .replace(/\n{3,}/g, "\n\n")
         .trim();
 }
+/** Parse DuckDuckGo HTML results → [{title, url, snippet}]. Best-effort HTML scrape (no key, no dependency). */
+export function parseSearchResults(html, limit) {
+    const strip = (s) => s
+        .replace(/<[^>]+>/g, "")
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#x27;|&#39;/g, "'")
+        .replace(/\s+/g, " ")
+        .trim();
+    const snippets = [];
+    const snipRe = /class="result__snippet"[^>]*>([\s\S]*?)<\/a>/g;
+    let m;
+    while ((m = snipRe.exec(html)))
+        snippets.push(strip(m[1]));
+    const out = [];
+    const linkRe = /class="result__a"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/g;
+    let i = 0;
+    while ((m = linkRe.exec(html)) && out.length < limit) {
+        let href = m[1].replace(/&amp;/g, "&");
+        const uddg = /[?&]uddg=([^&]+)/.exec(href); // DuckDuckGo wraps results in a /l/?uddg=<real-url> redirect
+        if (uddg)
+            href = decodeURIComponent(uddg[1]);
+        else if (href.startsWith("//"))
+            href = "https:" + href;
+        out.push({ title: strip(m[2]), url: href, snippet: snippets[i++] ?? "" });
+    }
+    return out;
+}
+registerTool({
+    name: "web_search",
+    description: "Search the web and return the top results (title, URL, snippet). Use it to FIND information or pages you " +
+        "don't already have a URL for, then `web_fetch` a result to read it. Read-only. Reliable with a Tavily key " +
+        "(env HARA_SEARCH_API_KEY); otherwise a best-effort keyless fallback that may be rate-limited.",
+    input_schema: {
+        type: "object",
+        properties: {
+            query: { type: "string" },
+            limit: { type: "number", description: "max results (default 6, max 10)" },
+        },
+        required: ["query"],
+    },
+    kind: "read",
+    async run(input) {
+        const q = String(input.query ?? "").trim();
+        if (!q)
+            return "(empty query)";
+        const limit = Math.min(Math.max(1, Number(input.limit) || 6), 10);
+        const fmt = (rs) => rs.map((r, n) => `${n + 1}. ${r.title}\n   ${r.url}${r.snippet ? `\n   ${r.snippet}` : ""}`).join("\n\n");
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), 20_000);
+        try {
+            // Reliable path: Tavily (designed for agents, free tier) when a key is configured.
+            const key = process.env.HARA_SEARCH_API_KEY || process.env.TAVILY_API_KEY;
+            if (key) {
+                const res = await fetch("https://api.tavily.com/search", {
+                    method: "POST",
+                    signal: ctrl.signal,
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ api_key: key, query: q, max_results: limit }),
+                });
+                if (res.ok) {
+                    const j = (await res.json());
+                    const rs = (j.results ?? []).map((x) => ({ title: String(x.title ?? x.url ?? ""), url: String(x.url ?? ""), snippet: String(x.content ?? "").slice(0, 200) }));
+                    if (rs.length)
+                        return fmt(rs);
+                }
+                // Tavily failed → fall through to the keyless best-effort path.
+            }
+            // Keyless fallback: DuckDuckGo HTML (POST — GET returns a 202 challenge). May be rate-limited.
+            const res = await fetch("https://html.duckduckgo.com/html/", {
+                method: "POST",
+                signal: ctrl.signal,
+                redirect: "follow",
+                headers: {
+                    "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36",
+                    "content-type": "application/x-www-form-urlencoded",
+                    accept: "text/html",
+                },
+                body: `q=${encodeURIComponent(q)}`,
+            });
+            if (!res.ok)
+                return `Search failed: HTTP ${res.status}. Keyless search is rate-limited — set HARA_SEARCH_API_KEY (Tavily) for reliable search, or web_fetch a known URL.`;
+            const results = parseSearchResults(await res.text(), limit);
+            if (!results.length)
+                return "(no results — the keyless endpoint is rate-limited or changed. Set HARA_SEARCH_API_KEY (Tavily) for reliable search, or web_fetch a known URL.)";
+            return fmt(results);
+        }
+        catch (e) {
+            return `Search failed: ${e?.name === "AbortError" ? "timed out (20s)" : (e?.message ?? e)}`;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    },
+});
 registerTool({
     name: "web_fetch",
     description: "Fetch an http(s) URL and return its text content (HTML is reduced to readable text). Read-only. " +

package/dist/tui/App.js

@@ -92,6 +92,19 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
             return [...cur, { id: nid(), kind, text }];
         });
     }, []);
+    // Type-ahead steering: hand the runner everything queued while the turn ran, showing each message
+    // inline (as a user block) at the point it gets folded into the conversation. Drained mid-turn so an
+    // addition reaches the model on its next call; whatever's still queued at turn end is the effect below.
+    const drainQueue = useCallback(() => {
+        if (!queueRef.current.length)
+            return [];
+        const batch = queueRef.current;
+        queueRef.current = [];
+        setPool([]);
+        for (const b of batch)
+            pushCurrent("user", b.line.trim() || "🖼 (image)");
+        return batch;
+    }, [pushCurrent]);
     const handleSubmit = useCallback(async (line, images) => {
         const t = line.trim();
         if ((!t && !images?.length) || prompt)
@@ -127,7 +140,7 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
         const selectFn = (title, options) => openPrompt(title, options);
         const setApprovalFn = (m) => setStatus((s) => ({ ...s, approval: m }));
         try {
-            await onSubmit(t, { sink, confirm: confirmFn, select: selectFn, setApproval: setApprovalFn, signal: ctrl.signal, exit, approval: statusRef.current.approval }, images);
+            await onSubmit(t, { sink, confirm: confirmFn, select: selectFn, setApproval: setApprovalFn, signal: ctrl.signal, exit, approval: statusRef.current.approval, drainQueue }, images);
         }
         catch (e) {
             pushCurrent("notice", `error: ${e instanceof Error ? e.message : String(e)}`);
@@ -139,7 +152,7 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
         setCurrent([]);
         setWorking(false);
         ctrlRef.current = null;
-    }, [working, prompt, onSubmit, pushCurrent, model, exit]);
+    }, [working, prompt, onSubmit, pushCurrent, model, exit, drainQueue]);
     // Drain the type-ahead pool: when the turn finishes (working → false) and nothing awaits a choice, COALESCE
     // every pooled message into ONE turn and send it — additions/clarifications go to the agent together, in order.
     useEffect(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.48.0",
+  "version": "0.53.0",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "dist/index.js"