@nanhara/hara 0.48.0 → 0.62.0

package/CHANGELOG.md

@@ -5,6 +5,251 @@ 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.62.0 — unreleased (shell completions)
+
+- **`hara completions bash|zsh|fish`** prints a completion script (eval it in your shell rc) that
+  tab-completes the top-level subcommands and the subcommands of each group (`cron`, `memory`, `plugin`,
+  `roles`, `skills`, `config`), falling back to file completion. Generated from the live command tree so it
+  never drifts; hand-rolled (no new dependency).
+
+## 0.61.3 — unreleased (audit follow-through: session robustness + SECURITY.md)
+
+- **Corrupt/hand-edited session files no longer crash** `--resume` or `/sessions` (audit M4): `loadSession`
+  validates the shape (meta object + history array), `deriveTitle` tolerates a non-string, and `listSessions`
+  skips metaless files instead of throwing.
+- New **`SECURITY.md`** — the threat model, the controls (approval gate, read-only sub-agents, write-confinement
+  sandbox, `web_fetch` SSRF guard, 0600 secrets, plugin trust), what is deliberately *not* a security boundary,
+  and how to report a vulnerability. Captures the posture from the two audit passes.
+
+## 0.61.2 — unreleased (security hardening — second audit: SSRF, RPA, secrets)
+
+A second audit (RPA / network / auth / search) found more real issues; fixed:
+- **`web_fetch` SSRF (critical).** It would fetch any host — incl. `169.254.169.254` (cloud metadata),
+  `localhost`/`127.0.0.1` internal services, and private ranges — and followed redirects blindly. Now it
+  **refuses private/loopback/link-local/CGNAT targets** (resolving the hostname first), **re-checks on every
+  redirect hop** (manual redirects), and reads the body under a **byte ceiling** (no multi-GB / bomb body).
+- **`computer` "don't ask again" defeated the per-action grant (high).** Screen control is supposed to
+  confirm every action; the shared "always" approval silently auto-approved all future clicks/types. Now
+  `computer` is **never** satisfied by a prior "always" — it always prompts.
+- **Key blocklist bypassable (high).** It only caught spelled-out combos, so Windows SendKeys `%{F4}`/`^w`
+  and Linux `XF86LogOff`/`XF86PowerOff` slipped through. Now caught on all three platforms (bare editing
+  keys like Delete stay allowed).
+- **Secrets could be embedded into the semantic index (medium).** The asset/skill/memory dirs aren't
+  `.gitignore`-filtered, so a stray `credentials.json`/`secrets.yaml` there could be POSTed to the embedding
+  provider + persisted. Now secret-named files are skipped in both index collectors.
+- **Token/config files were world-readable (medium).** `~/.hara/qwen-oauth.json` (access+refresh tokens)
+  and `~/.hara/config.json` (`apiKey`) are now written **0600** (and tightened on save).
+- **RPA app allowlist was substring-matched (low).** `"Notes"` matched `"Notes - Evil"`; now an exact
+  (case-insensitive) frontmost-app match.
+
+The RPA + clipboard shell-outs were confirmed injection-safe (argv arrays, JSON-quoted scripts). 198 tests
+(2 new: the SSRF private-IP guard + the widened key blocklist).
+
+## 0.61.1 — unreleased (security + correctness hardening — core audit)
+
+A security/correctness audit of the core (sandbox, confirmation gate, file tools, MCP client) found real
+issues; fixed:
+- **Confirmation-gate bypass via sub-agents (critical).** The read-kind `agent` tool never prompts, yet
+  spawned sub-agents ran **full-auto, unconfirmed** — so a role granting `edit_file`/`bash` let a fan-out
+  sub-agent mutate files / run shell with no approval, even in `suggest` mode. Sub-agents are now **always
+  read-only** (a role may narrow further but can never grant write/exec — `subagentToolFilter`). Write-capable
+  roles run in the main loop via `hara org`, behind the gate.
+- **`apply_patch` wasn't actually atomic (critical / data-loss).** It claimed all-or-nothing but Phase 2 wrote
+  files sequentially — a mid-way failure left a half-patched tree with no undo. Now it **rolls back** every
+  applied write on any failure (restores updated/deleted, removes created), so it's truly all-or-nothing.
+- **Sandbox honesty.** It's **file-write confinement only** (not reads/network/exec; `/private/tmp` stays
+  writable) — clarified in the header, `--sandbox` docs, and label so it no longer oversells containment.
+- The non-macOS "runs unsandboxed" warning now fires from `runShell` (every entry point: `-p`, org, cron),
+  not just the REPL; a runaway `bash` whose output exceeds `maxBuffer` is now **killed** (not streamed to
+  the timeout); and `hara plugin add` now **shows the commands a plugin will run** on every launch (its MCP
+  servers + hooks are arbitrary code — surface the trust surface).
+
+196 tests (2 new: the sub-agent read-only guard + the apply_patch rollback). The edit tools, hooks matcher,
+and sandbox profile-injection safety were audited and confirmed solid.
+
+## 0.61.0 — unreleased (`hara memory` — inspect + distill durable memory)
+
+- New **`hara memory`** command group, giving memory a CLI surface it lacked:
+  - **`hara memory show`** — print the digest injected at session start (what the agent actually sees).
+  - **`hara memory init`** — scaffold the global + project memory dirs/seed files.
+  - **`hara memory distill [--days N] [--scope global|project|all]`** — **promote short-term → long-term**:
+    consolidate recent daily logs (`log/YYYY-MM-DD.md`) into durable `MEMORY.md`/`USER.md`, deduped against
+    what's already there, skipping the ephemeral. This closes the one tiering gap the PAI/hermes study
+    surfaced (the daily-log tier was previously write-only). The agent routes each fact to the right
+    target/scope (user pref → `USER.md`, project fact → project memory). Verified live with glm-5.
+- `.hara/` is now gitignored in this repo so dogfooding doesn't leave runtime state (memory/roles/plans).
+
+## 0.60.2 — unreleased (memory digest: per-source budgets)
+
+- After studying the PAI and hermes memory systems (both lexical-first; both treat vectors as an *optional*
+  optimization, not a requirement — which validates hara's design), tightened the frozen-snapshot digest:
+  the old `slice(0, 4000)` on the **concatenated** sources could cut an entry mid-line and let a large
+  project `MEMORY.md` **crowd `USER.md` out entirely**. Each source (project MEMORY / global MEMORY / USER)
+  now gets its **own** budget and is truncated at a **line boundary**, so high-value user prefs are always
+  injected and no entry is split. The rest stays reachable via `memory_search` (which is already hybrid
+  lexical + opt-in semantic). No behavior change when memory is small.
+
+## 0.60.1 — unreleased (cron hardening — from a code-review pass)
+
+A review of the fast-built `hara cron` module surfaced real bugs; fixed:
+- **Malformed cron expressions were silently accepted** (`Number("")===0` etc.) — `"0 9 * * 1,"`, `"/5 * * * *"`, `"5/"` parsed as valid jobs that fire at the wrong time. Now strictly validated and rejected; `N/step` correctly extends to max (Vixie semantics).
+- **`hara cron install` could emit a broken plist/crontab** when a path contained `&`/`<`/`>` (launchd XML) or a space/metacharacter (crontab shell line). Now XML-escaped / shell-quoted, and an install is refused if a path contains a newline.
+- **Per-job logs grew unbounded** — capped to the last ~256KB once over ~1MB.
+- **The tick lock could poison the scheduler for 30 min after a crash, or double-fire a long job** — now keyed on PID liveness (a dead owner is taken over within one tick; a live owner is respected for long runs).
+- **An ambiguous id-prefix silently deleted/toggled the *first* match** — `cron remove/enable/disable/run/logs` now error on an ambiguous prefix instead of guessing.
+
+The vim reducer, type-ahead steering, Anthropic message coalescing, the MCP allowlist, and the binary build were reviewed and confirmed clean. 192 tests (4 new hardening cases).
+
+## 0.60.0 — unreleased (single-binary distribution)
+
+- **Standalone binaries** — hara can now be a single self-contained executable (no Node required):
+  `curl -fsSL .../install.sh | sh`. Built with `bun build --compile` (`npm run build:binary`, or
+  `build:binaries` to cross-compile darwin-arm64/x64 + linux-x64/arm64 from one machine). A tagged
+  release (`.github/workflows/release.yml`) builds + attaches them; `install.sh` grabs the right one.
+- Build fixes for the bundled binary: a Bun plugin **stubs ink's dev-only `react-devtools-core`** (lazy-
+  imported under `DEV`, never in production) so it bundles clean; the version is **baked in via a build
+  define** (a compiled binary has no `package.json` to read at runtime); and cron's self-reinvoke now
+  detects script-vs-binary mode (`selfArgv`) so `hara cron` works from the binary too. The 60 MB binaries
+  are kept out of the npm tarball (`!dist/bin`), which stays ~140 kB.
+
+## 0.59.0 — unreleased (vim keybindings in the input box)
+
+- **Vim mode** (opt-in: `hara config set vimMode true`, or `HARA_VIM=1`). The TUI prompt becomes modal —
+  **Esc** → normal, **i/a/I/A/o** → insert. Normal-mode motions `h l 0 $ w b e` (+ `gg`/`G`), edits
+  `x D C dd cc dw cw`, and paste `p`/`P` with a delete/yank register. A distinct prompt marker (`◆` yellow)
+  + a `-- NORMAL -- / -- INSERT --` hint show the mode. Off by default (normal typing is unchanged). The
+  editing logic is a pure reducer (`src/tui/vim.ts`), fully unit-tested; `hara doctor` shows the input mode.
+
+## 0.58.0 — unreleased (`hara cron` — scheduled tasks)
+
+- **Scheduled tasks.** `hara cron add "<schedule>" "<task>"` runs a task on a schedule — the fired job is a
+  fresh `hara` session (the run *is* the agent, like openclaw/hermes). Schedules: a 5-field **cron expr**
+  (`"0 9 * * 1-5"`), an **interval** (`"every 30m"`), or a **one-shot** (`"in 2h"` / an ISO timestamp).
+  `--org` routes it through the role org instead of a plain prompt.
+- **Fires via your OS, no daemon to babysit.** `hara cron install` registers a per-minute `hara cron tick`
+  with **launchd** (macOS) or **crontab** (Linux); `tick` runs whatever's due (lock-guarded so a slow job
+  doesn't double-fire) and logs each run. Manage with `hara cron list / run <id> / enable / disable /
+  remove / logs / uninstall`. Jobs persist atomically in `~/.hara/cron/jobs.json`; `hara doctor` shows the
+  count + scheduler status. Cron matching is hand-rolled (no new dependency), minute-granular, local-time.
+
+## 0.57.0 — unreleased (in-session `/diff`, `/review`, `/commit` in the TUI)
+
+- The default TUI now wires three more slash commands so the **change → review → commit** loop happens
+  in-session instead of dropping to a subcommand (they used to print "isn't wired into the TUI yet"):
+  - **`/diff`** — show the working-tree diff vs HEAD (`/diff staged` for the index), rendered as a colored diff block. No model call.
+  - **`/review`** — a senior-reviewer pass over `git diff HEAD` (read-only), streamed inline.
+  - **`/commit`** — stage everything and commit with an AI-written message (reuses the review→commit machinery).
+  Reuses existing, already-verified pieces (`autoCommit`, `REVIEW_SYSTEM`, `runShell`). Other subcommands
+  (`init`/`index`/`plan`/`org`/…) still point you to `hara <cmd>` or `HARA_TUI=0`.
+
+## 0.56.0 — unreleased (review → commit capstone + robust verdict parsing)
+
+- **`hara org --review --commit`** closes the loop: once the reviewer approves, hara stages the work and
+  commits it with an AI-written message (reusing `hara commit`'s generation). **Guarded** — it only
+  auto-commits when the working tree was **clean before the run** (so it captures this run's work, never
+  pre-existing WIP), and with `--review` only **after approval** (a review that doesn't pass leaves the
+  changes in your tree, uncommitted). `--commit` works without `--review` too (commit the implementer's
+  result). Verified live end-to-end: implement → review → approve → `✓ committed`.
+- **Robust verdict parsing** (hardening v0.55, found via live smokes). Real models don't emit the literal
+  `VERDICT: APPROVED` token — across runs glm-5 wrote `**VERDICT**: No issues found`, `**VERDICT**: PASS`,
+  and `VERDICT: LGTM`. The parser now anchors on a markdown-tolerant `VERDICT` marker and **classifies the
+  phrase after it** (approve vs changes synonyms), with a changes-signal veto and an ambiguous-→-not-approved
+  safe default (worst case is one extra review round, never a bad auto-commit). `not approved` correctly
+  vetoes despite containing "approv". Unit tests now cover the exact shapes seen in live runs.
+
+## 0.55.0 — unreleased (multi-role review chain — `hara org --review`)
+
+- **Review chains** — `hara org --review "<task>"` runs the org like an actual engineering team: the owning
+  role implements, then a **reviewer** role inspects the diff and either **approves** or sends it back with
+  concrete fixes, looping implement → review → fix until approved or a round cap (`--rounds`, default 3).
+  This is hara's differentiation — not "one agent + temp sub-agents" but roles that hold each other to a
+  bar. The reviewer is read-only (uses your `reviewer` role if defined, else a built-in persona) and ends
+  with a machine-parseable `VERDICT: APPROVED | CHANGES_REQUESTED`; on changes-requested the issues feed
+  back into the implementer's own conversation so it keeps context. New `src/org/review-chain.ts` (verdict
+  parsing, non-destructive `git diff HEAD` capture, prompts) — all unit-tested. **Verified live end-to-end**
+  (implementer edits a file → reviewer approves → loop exits).
+
+## 0.54.0 — unreleased (`hara mcp` — run hara as an MCP server)
+
+- **MCP server mode** — `hara mcp` runs hara as an MCP server over stdio, so other MCP clients (Claude
+  Desktop, Cursor, another hara…) can call its tools. hara was already an MCP *client*; this completes
+  the loop. The high-value one is **`codebase_search`** — point any MCP client at a repo and it gets
+  hara's semantic/lexical code search, plus `read_file`/`grep`/`glob`/`ls`/`web_fetch`/`web_search`.
+  **Read-only by default** — no `edit_file`/`bash`/`computer`, so an external client can't mutate your
+  machine through hara; override the exposed set with `HARA_MCP_TOOLS=a,b,c` at your own risk. Reuses
+  hara's tool registry (`src/mcp/server.ts`, built on `@modelcontextprotocol/sdk` — already a dep).
+  Verified end-to-end (a real MCP client lists the tools + calls `ls`/`codebase_search`). `hara doctor`
+  now shows both the client (servers connected) and serve (tools exposed) sides.
+
+  ```jsonc
+  // e.g. in a client's mcpServers config:
+  "hara": { "command": "hara", "args": ["mcp"] }   // run from the repo you want searchable
+  ```
+
+## 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

@@ -11,7 +11,7 @@
 **Highlights**
 - **An org, not just an agent** — `hara org "<task>"` routes work to the role that *owns* it; `hara plan "<task>"` decomposes a task into a verified DAG of atoms (frame → atomize → sequence → execute → **verify gate**), and `hara plan --parallel` runs independent atoms concurrently.
 - **Real terminal UX** — an **ink TUI**: bottom-pinned input box, **plan mode** (read-only → propose a plan → approve → execute), selectable approvals with "don't ask again", windowed reasoning, **paste images** (Ctrl+V) for vision models, light/dark theme.
-- **Persistent memory + self-evolution** — `memory_*` tools over global/project `MEMORY.md`; the agent recalls before acting, **proactively saves** durable facts, and grows its own playbooks (a lexical guard screens what it writes).
+- **Persistent memory + self-evolution** — `memory_*` tools over global/project `MEMORY.md`; the agent recalls before acting, **proactively saves** durable facts, and grows its own playbooks (a lexical guard screens what it writes). Inspect/consolidate it with **`hara memory show`** and **`hara memory distill`** (promote recent daily logs → durable memory). Lexical-first by design — semantic search is opt-in, never required.
 - **Multi-provider, all streamed** — Anthropic (Claude) or any OpenAI-compatible endpoint (Qwen/DashScope, GLM, Kimi, OpenAI) with live Markdown + visible reasoning.
 - **Solid coding core** — `edit_file` / `apply_patch` (atomic multi-file) with colored diffs · `grep`/`glob`/`ls`/`codebase_search` (lexical + optional semantic search over the repo) /`web_fetch` · fuzzy `@file` · `/undo` · `/compact` · **Esc-to-interrupt** · parallel sub-agents · MCP client · macOS sandbox.
 
@@ -23,6 +23,14 @@ Track it: https://github.com/hara-cli/hara · https://hara.run
 npm i -g @nanhara/hara
 ```
 
+Or a **standalone binary** (no Node required):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/hara-cli/hara/main/install.sh | sh
+```
+
+Tab completion (optional): `eval "$(hara completions zsh)"` in your `~/.zshrc` (or `bash`/`fish`).
+
 Or from source:
 
 ```bash
@@ -171,14 +179,18 @@ vector DB needed, and lexical still works when there's no index. Re-running `har
 only changed files re-embed (a full repo rebuild that takes ~a minute re-runs in well under a second).
 
 **Approval modes**: `suggest` confirms edits & shell · `auto-edit` auto-applies file edits but confirms shell · `full-auto` runs everything.
-**Sandbox** (macOS): `--sandbox workspace-write|read-only` runs the `bash` tool under Seatbelt (writes confined to the project / blocked).
+**Sandbox** (macOS): `--sandbox workspace-write|read-only` runs the `bash` tool under Seatbelt — **file-write confinement** (writes confined to the project / blocked). It does not restrict reads, network, or process exec; on non-macOS the shell runs unsandboxed (with a warning).
 **Screen control** (opt-in): the `computer` tool drives desktop software (screenshot → click/type), native per OS
 (mac `screencapture`+`cliclick` · Windows PowerShell · Linux `scrot`+`xdotool`). Off by default — enable a tier with
 `hara config set computerUse read|click|full` and allowlist apps with `hara config set computerApps "App, …"`. Guarded
 by the tier, the frontmost-app allowlist, a dangerous-key blocklist, and a once-per-session grant. Screenshots are read via your
 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>`.
+**MCP**: add an `mcpServers` map to config (global or project `.hara/config.json`); their tools appear to the agent as `mcp__<server>__<tool>`. hara can also **be** an MCP server — `hara mcp` exposes its read/search tools (esp. **`codebase_search`**) over stdio so other clients (Claude Desktop, Cursor, another hara) can use them; read-only by default (`HARA_MCP_TOOLS` to override).
+**Vim mode**: `hara config set vimMode true` makes the prompt modal — Esc → normal, `i/a/A/I` insert, `h l 0 $ w b e` motions, `x D C dd cw p` edits. Off by default.
+**Scheduled tasks**: `hara cron add "0 9 * * 1-5" "<task>"` (or `"every 30m"`, `"in 2h"`) runs a task on a schedule — each run is a fresh hara session. `hara cron install` wires a per-minute tick into launchd/crontab (no daemon); `--org` routes through the role org. Manage with `hara cron list/run/enable/disable/remove/logs`.
+**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
@@ -187,7 +199,11 @@ Define role-agents in `.hara/roles/*.md` — each is a persona (the file body) p
 (keywords that route a task here), optional `rejects`, `model`, and `allowTools`/`denyTools`. `hara org
 "<task>"` routes the task to the role that **owns** it (keyword match, LLM fallback) and runs that role's
 agent — e.g. a read-only `reviewer` that reports issues vs an `implementer` that edits code. `hara roles`
-lists them, `hara roles init` scaffolds a starter set, and `--role <id>` forces a specific role. The
+lists them, `hara roles init` scaffolds a starter set, and `--role <id>` forces a specific role. Add
+**`--review`** and the org works like a team: the owning role implements, then a **reviewer** role inspects
+the diff and either approves or sends it back with fixes — looping implement → review → fix until approved
+(or `--rounds N`). Add **`--commit`** and it commits the approved result with an AI-written message (guarded
+to a clean start tree; a review that doesn't pass leaves the work uncommitted). The
 **`agent`** tool spawns **parallel read-only sub-agents** for fan-out — analyze / review / search
 several things at once (each can take a `role`).
 
@@ -207,15 +223,20 @@ A streaming agentic loop with built-in tools — `read_file`, `write_file`, **`e
 read-only **`grep`** / **`glob`** / **`ls`** / **`web_fetch`** — behind a human-in-the-loop confirmation gate on the
 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.
+turn, or **`/undo`** to revert the last edit. In-session **`/diff`**, **`/review`**, and **`/commit`** close the change → review → commit loop without leaving the prompt.
+- **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**.
 
 ### Roadmap
 
-**Shipped:** ink TUI · plan mode · persistent memory + self-evolution · atomization planner · parallel sub-agents · `/compact` context management.
-**Next:** parallel plan atoms · multi-role review chains · cron autonomy for the org · single-binary distribution · an enterprise control-plane (fleet + central token management).
+**Shipped:** ink TUI · plan mode · persistent memory + self-evolution · atomization planner · parallel plan atoms · **multi-role review chains** · parallel sub-agents · MCP client *and* server · **scheduled tasks (`hara cron`)** · **single-binary distribution** · `/compact` context management.
+**Next:** SSOT data authority · an enterprise control-plane (fleet + central token management).
+
+## Security
+
+Human-in-the-loop by default, with a layered model (approval gate · read-only sub-agents · write-confinement sandbox · `web_fetch` SSRF guard · `0600` secrets · reviewed plugin trust). Threat model, controls, and how to report a vulnerability: **[SECURITY.md](SECURITY.md)**.
 
 ## License
 

package/SECURITY.md

@@ -0,0 +1,54 @@
+# Security
+
+hara is a coding agent that reads/writes files, runs shell commands, drives a browser/desktop, and calls
+LLMs — so it takes a layered, **human-in-the-loop-by-default** stance. This documents the threat model, the
+controls, what is deliberately *not* a security boundary, and how to report a vulnerability.
+
+## Threat model
+
+hara runs on **your** machine under **your** account, on code **you** point it at. It is not a multi-tenant
+sandbox. The adversary we defend against is primarily **the model going wrong** — a bad suggestion, a
+prompt-injected web page or file steering it toward a destructive or exfiltrating action — not a malicious
+local user (who already has your shell).
+
+## Controls
+
+- **Approval gate.** Every file edit, shell command, and screen action is classified (`read` / `edit` /
+  `exec` / `computer`) and gated by an approval mode: `suggest` (confirm edits & commands), `auto-edit`
+  (auto-apply edits, confirm commands), `full-auto` (no prompts — opt-in). Read-only tools never prompt.
+- **Screen control is gated on *every* action.** The `computer` tool always asks before each click/type,
+  even in `full-auto`, and "don't ask again" never applies to it. Guarded further by a frontmost-app
+  **allowlist** (exact match), a dangerous-key **blocklist** (quit/close/logout across macOS/Windows/Linux
+  syntaxes), and a per-session grant. Off by default.
+- **Sub-agents are read-only.** The parallel `agent` fan-out tool runs sub-agents that can never edit or run
+  shell — a role may *narrow* their tools but never *grant* write/exec. Write-capable roles run in the main
+  loop (`hara org`), behind the gate.
+- **Shell sandbox (macOS).** `--sandbox workspace-write|read-only` runs the `bash` tool under Seatbelt —
+  **file-write confinement** (see the non-boundary note below). Commands/paths are passed as argv / a profile
+  file, not interpolated into a shell string.
+- **`web_fetch` SSRF guard.** Refuses to fetch private / loopback / link-local / CGNAT addresses (resolving
+  the hostname first), re-checks on every redirect hop, and reads the body under a byte ceiling — so the
+  model can't reach cloud-metadata endpoints or internal services.
+- **Secrets.** `~/.hara/config.json` (API keys) and `~/.hara/qwen-oauth.json` (tokens) are written `0600`.
+  The optional semantic index respects `.gitignore` and skips secret-named files, so keys aren't embedded or
+  sent to an embedding provider. The memory guard screens secret-shaped strings out of what the agent saves.
+- **Plugins are code you trust.** Installing a plugin (`hara plugin add`) grants its author code execution:
+  its MCP servers and hooks run shell commands on launch. `hara plugin add` **prints the exact commands** a
+  plugin will run so you can review them; disable with `hara plugin disable <name>`.
+- **Coding-plan keys.** Provider keys you configure are used only to call the model endpoint you set.
+
+## What is *not* a security boundary
+
+- **The sandbox confines file writes only** — not reads, not network, not process exec; `/private/tmp`
+  stays writable. It stops a stray `rm`/overwrite escaping the project, not a determined exfiltration. Treat
+  a `full-auto` + network-capable shell as able to read and send anything your account can.
+- **`@file` mentions** read any file *you* name (including outside the project) — that's you attaching
+  context, not the model exfiltrating; mentions are expanded on your typed input only, never on model output.
+- **`full-auto` / `-y`** removes the human gate by your explicit choice. Use it on code and in directories
+  you trust.
+
+## Reporting a vulnerability
+
+Please report security issues privately — open a GitHub **security advisory** on `hara-cli/hara`, or email
+the maintainers — rather than a public issue. Include a minimal reproduction and the impact. We'll
+acknowledge, fix, and credit you.

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;
@@ -127,14 +136,16 @@ export async function runAgent(history, opts) {
             const preview = String(input.path ?? input.command ?? input.pattern ?? input.url ?? input.task ?? "")
                 .replace(/\s+/g, " ")
                 .trim();
-            if (needsConfirm(tool.kind, opts.approval) && !opts.autoApprove?.has(tu.name)) {
+            // Screen control is gated on EVERY action — a prior "don't ask again" must never satisfy it.
+            const alwaysGate = tool.kind === "computer";
+            if (needsConfirm(tool.kind, opts.approval) && (alwaysGate || !opts.autoApprove?.has(tu.name))) {
                 const reply = await opts.confirm(`${c.yellow("⚠")}  ${c.bold(tu.name)} ${c.dim(preview)} — run?`);
                 if (reply === false) {
                     plans.push({ tu, tool, denied: "User denied this action." });
                     continue;
                 }
-                if (reply === "always")
-                    opts.autoApprove?.add(tu.name);
+                if (reply === "always" && !alwaysGate)
+                    opts.autoApprove?.add(tu.name); // computer: treat "always" as one-time yes
             }
             plans.push({ tu, tool });
             if (!opts.quiet) {
@@ -154,8 +165,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/completions.js

@@ -0,0 +1,49 @@
+// Shell completion scripts (bash / zsh / fish), generated from the command tree so they never drift.
+// `hara completions <shell>` prints one; the user evals it in their shell rc. Completes the top-level
+// subcommands, the subcommands of each group (cron/memory/plugin/roles/skills/config), and falls back to
+// file completion otherwise. Hand-rolled (no dependency) — same minimal-deps philosophy as the rest.
+const bash = ({ top, subs }) => {
+    const cases = Object.entries(subs)
+        .map(([cmd, sub]) => `    ${cmd}) COMPREPLY=( $(compgen -W "${sub.join(" ")}" -- "$cur") ); return;;`)
+        .join("\n");
+    return `# hara bash completion — add to ~/.bashrc:  eval "$(hara completions bash)"
+_hara() {
+  local cur prev; cur="\${COMP_WORDS[COMP_CWORD]}"; prev="\${COMP_WORDS[1]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=( $(compgen -W "${top.join(" ")}" -- "$cur") ); return; fi
+  case "$prev" in
+${cases}
+    *) COMPREPLY=( $(compgen -f -- "$cur") );;
+  esac
+}
+complete -F _hara hara
+`;
+};
+const zsh = ({ top, subs }) => {
+    const cases = Object.entries(subs)
+        .map(([cmd, sub]) => `    ${cmd}) compadd -- ${sub.join(" ")} ;;`)
+        .join("\n");
+    return `# hara zsh completion — add to ~/.zshrc:  eval "$(hara completions zsh)"
+_hara() {
+  if (( CURRENT == 2 )); then compadd -- ${top.join(" ")}; return; fi
+  case "\${words[2]}" in
+${cases}
+    *) _files ;;
+  esac
+}
+compdef _hara hara
+`;
+};
+const fish = ({ top, subs }) => {
+    const lines = [
+        "# hara fish completion — save to ~/.config/fish/completions/hara.fish:  hara completions fish > ~/.config/fish/completions/hara.fish",
+        "complete -c hara -f",
+        `complete -c hara -n __fish_use_subcommand -a "${top.join(" ")}"`,
+        ...Object.entries(subs).map(([cmd, sub]) => `complete -c hara -n "__fish_seen_subcommand_from ${cmd}" -a "${sub.join(" ")}"`),
+    ];
+    return lines.join("\n") + "\n";
+};
+/** Render the completion script for a shell, or null if the shell isn't supported. */
+export function completionScript(shell, tree) {
+    const gen = { bash, zsh, fish };
+    return gen[shell] ? gen[shell](tree) : null;
+}

package/dist/config.js

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { join, dirname, resolve } from "node:path";
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from "node:fs";
 const PROVIDER_DEFAULTS = {
     anthropic: { model: "claude-opus-4-8", envKey: "ANTHROPIC_API_KEY" },
     qwen: {
@@ -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", "vimMode"];
 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"];
@@ -51,12 +51,22 @@ function readProjectConfig(cwd) {
     }
     return {};
 }
+/** Write the config 0600 (it can hold `apiKey`) + tighten an existing file. */
+function persistConfig(p, cfg) {
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+    try {
+        chmodSync(p, 0o600);
+    }
+    catch {
+        /* best-effort */
+    }
+}
 export function writeConfigValue(key, value) {
     const p = configPath();
     const cfg = readRawConfig();
     cfg[key] = value;
-    mkdirSync(dirname(p), { recursive: true });
-    writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+    persistConfig(p, cfg);
 }
 /** Record (or clear, with cap=null) a confirmed per-model vision capability in `modelVision`. */
 export function setModelVisionOverride(model, cap) {
@@ -68,8 +78,7 @@ export function setModelVisionOverride(model, cap) {
     else
         map[model] = cap;
     cfg.modelVision = map;
-    mkdirSync(dirname(p), { recursive: true });
-    writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+    persistConfig(p, cfg);
 }
 /**
  * Effective config. Precedence (high→low): env vars > selected profile >
@@ -107,7 +116,10 @@ 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");
+    const vimMode = process.env.HARA_VIM === "1" || merged.vimMode === true || merged.vimMode === "true";
+    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, hooks, notify, vimMode, mcpServers, cwd: process.cwd() };
 }
 export function providerEnvKey(provider) {
     return (PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic).envKey;