@nanhara/hara 0.121.0 → 0.122.0

package/CHANGELOG.md

@@ -5,6 +5,91 @@ 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.122.0 — 2026-07-13 — structured runs, durable work, and a fail-closed gateway
+
+- **Machine-safe headless runs.** `hara -p … --schema <json|file>` installs a run-scoped
+  `structured_output` contract, validates the value against JSON Schema, and writes exactly one JSON value to
+  stdout. Prose, auth notices, retries, and provider/schema failures cannot masquerade as machine output:
+  diagnostics go to stderr and failures exit non-zero. `hara -p … --role <id>` now applies the role's persona,
+  model, and allow/deny tool policy instead of changing the prompt alone.
+- **Agents have stable homes.** `hara projects add/list/remove` maintains a private, atomic registry of project
+  homes; `hara agents` builds one address book from global and registered-project roles.
+  `hara org --role project:agent …` resolves unambiguously and executes at that home with its project context/config. Concurrent
+  CLIs safely share the registry, and dead lock owners can be reclaimed without stealing a live lock.
+- **Two levels of work state.** `todo_write` is now isolated per interactive/headless/sub-agent/serve session
+  and persists with the session, so concurrent agents cannot overwrite each other's checklist. The new `task`
+  tool is a durable cross-session project pool with owners, statuses, `blockedBy` dependencies, cycle checks,
+  and private atomic cross-process persistence. `hara serve` exposes the pool through `tasks.list`.
+- **10-platform gateway, with project-agent roaming.** Telegram, WeChat, Discord, Feishu/Lark, Slack,
+  Mattermost, Matrix, DingTalk, WeCom, and Signal adapters now classify direct vs multi-party chats
+  conservatively. The full coding agent accepts only verified private messages; unknown channel shapes fail
+  closed. `/agent <name|project:name>` pins a thread to an indexed agent and its home, while `/agent main`
+  restores the prior project thread. Chat/session preferences survive project round-trips and group-member
+  state is isolated.
+- **Untrusted group flows cannot reach coding tools.** Opt-in `~/.hara/flows.json` rules are hot-reloaded and
+  evaluated through a bounded, stateless provider call with `tools: []` — no shell, files, MCP, session, or
+  project context. Rules support trigger filters, JSON Schema, disposition-based notification/auto-reply,
+  redacted rotating logs, and rate/concurrency caps. Proposed sends and agent dispatches are parked unless an
+  explicitly configured safe `replyOn` disposition applies.
+- **Single-owner, idempotent approvals.** Consequential flow actions require a unique allowlisted owner and a
+  verified private channel. Deterministic `/approve <id>`, `/edit <id> <content>`, and `/reject <id>` commands
+  avoid “latest draft” ambiguity; blank edits fail closed. Pending actions use private atomic storage and a
+  compare-and-set execution claim, shared by chat and the new serve `approvals.list/resolve` inbox, so two
+  approval surfaces cannot double-send. Deferred actions are parked only for one-shot delivery targets
+  (Telegram, Feishu/Lark, or WeChat); other adapters fail closed instead of presenting an unusable approval.
+- **Bounded gateway execution and media.** Turns are FIFO per session (depth 8), with four active children,
+  bounded global/session-key backlogs, a 15-minute default/30-minute hard timeout, and TERM-to-KILL shutdown;
+  non-zero or signalled children fail visibly. Inbound attachments are authorized before download, limited to
+  four files and 20 MiB each, streamed into private random paths with time/concurrency/retention quotas, and
+  expired after 24 hours. Progress markers are recalled in `finally`, gateway chat/session files are `0600`
+  with lock-before-load persistence, and ambiguous/stale locks are never reclaimed merely by age.
+- **Layered flow admission.** Group classifiers are capped globally (20/minute, 120/hour), per rule/platform/chat
+  (10/minute, 60/hour), per sender (5/minute), and at four active runs. Rate maps and key sizes are bounded and
+  saturation fails closed, so rotating identities cannot grow memory or bypass the host-wide ceiling.
+- **Live config for persistent clients.** `hara serve` rebuilds cwd-specific provider routes, credentials, and
+  guardian settings on sessions/turns; `initialize`, `models.list`, and new sessions reflect current defaults.
+  Resumed sessions retain their explicit model pin while using the live provider route, so credential rotation
+  and project config edits no longer require a server restart.
+- **Coding-path robustness.** File reads/search/edit/patch now reject FIFOs/devices and symlink races, cap reads,
+  use bounded subprocess search with a linear glob matcher, preserve exact file modes, and roll back multi-file
+  patches without overwriting concurrent replacements; writes move-claim the expected inode and commit with
+  create-if-absent semantics, while `/undo` applies the same identity checks. Blank
+  project/env routing values no longer mask valid global config; precedence is environment > project > overlay
+  > global. Web fetch/search blocks IPv4-mapped and full link-local IPv6 SSRF forms and tries regional providers
+  sequentially instead of broadcasting a successful query. Package installs stay attached with bounded
+  long-operation timeouts, tunnel commands preflight their binaries, TUI resize repaints reliably, persisted/
+  public text redacts secrets, and session writes are private, atomic, and cross-process safe.
+- **Interrupts and non-interactive outcomes are honest.** Cancelling a parallel tool round records matching
+  interrupted results while preserving completed side effects; serve approvals settle immediately on interrupt.
+  The stream-stall watchdog is a hard Promise boundary even when a provider ignores its abort signal.
+  Headless and org runs now exit non-zero on provider errors, empty/halted turns, schema failures, and rejected
+  reviews; plan atoms stop on the same outcomes instead of being verified as done, and failed implementers are
+  never committed. Read-only roles are resolved before startup and launch neither hooks nor configured/plugin
+  MCP subprocesses.
+- **Private serve lifecycle.** `~/.hara`/`serve.json` are tightened to `0700`/`0600` and discovery is fsynced,
+  atomically replaced without following symlinks, and removed only by its owning instance. Discovery failures
+  close the listening socket. Serve-side compaction is mutually exclusive with turns/config changes, carries an
+  abort signal, releases locks on interrupt/shutdown, and has a 60-second hard deadline.
+
+## 0.121.1 — field-feedback reliability & credential safety
+
+- **Terminal resize no longer erases the composer.** Hara clears stale Ink output only before a real
+  width change; height-only window drags keep the input box visible and width changes repaint immediately.
+- **Credentials stay out of durable transcripts and generated code.** Session writes deeply redact likely
+  keys/tokens/passwords (including tool inputs/results); legacy content is redacted when loaded and migrated
+  on its next atomic, private save. Interactive pastes get a warning without echoing the value. The agent must use environment references,
+  never literal secrets in code/commands, and may only populate a real-secret `.env` when explicitly asked.
+- **`web_search` has a verified mainland path.** A configured Tavily request races the keyless Bing China
+  HTML path; Baidu, Google, and DuckDuckGo remain concurrent secondary fallbacks. Provider timeouts are
+  isolated, and JavaScript-only `web_fetch` pages now explain that a browser/API/connector is required
+  instead of returning a misleading empty body.
+- **Long setup commands fail usefully.** Package installs automatically become background jobs unless the
+  caller explicitly sets timeout/background, while ngrok tunnels preflight local authentication once and
+  stop with a focused fix instead of cycling through unrelated tunnel tools.
+- **Persistent desktop sessions re-read configuration.** New/resumed `hara serve` sessions pick up rotated
+  `apiKey`/model/baseURL values without a restart; empty env/project values no longer mask valid global
+  config, and a 401 says the configured credential expired rather than asking users to paste it into chat.
+
 ## 0.121.0 — `hara desk` · crash-safe coding/files · bounded interactive I/O
 
 - **`hara desk` connects the CLI to the shared coordination desk.** Register an agent, post/list/

package/README.md

@@ -12,7 +12,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.
-- **Drive it from chat** — `hara gateway` runs your local hara from **Telegram · WeChat · Discord · Feishu/Lark · Slack · Mattermost · Matrix · DingTalk · WeCom · Signal** (10 platforms), with **two-way images** (send a photo → it sees it; ask for a file → it sends one), per-chat resumable sessions, and project roaming. Connects out — no public webhook. See **[docs/gateway.md](docs/gateway.md)**.
+- **Drive it from chat** — `hara gateway` runs your local hara from **Telegram · WeChat · Discord · Feishu/Lark · Slack · Mattermost · Matrix · DingTalk · WeCom · Signal** (10 platforms), with **two-way images**, resumable per-chat sessions, project/agent roaming, bounded per-thread queues, and approval-gated group automations. Connects out — no public webhook. See **[docs/gateway.md](docs/gateway.md)**.
 - **Real terminal UX** — an **ink TUI**: bottom-pinned input box, **plan mode** (read-only investigation → the model submits its plan via `exit_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). 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.
@@ -135,8 +135,11 @@ hara expresses it the way each endpoint wants (OpenAI `reasoning_effort`, Anthro
 DashScope `enable_thinking`, **DeepSeek** V4 `thinking` + `reasoning_effort` where `max` genuinely raises the
 effort). In the TUI, bare `/model` opens a picker — ↑↓ pick a model, **←→ set the thinking level**.
 
-Config lives in `~/.hara/config.json`. Env vars override it: `HARA_PROVIDER`, `HARA_MODEL`,
-`HARA_BASE_URL`, `HARA_API_KEY`, or the provider key (`ANTHROPIC_API_KEY` / `DASHSCOPE_API_KEY`).
+Config lives in `~/.hara/config.json`; the nearest project `.hara/config.json` can specialize it. Effective
+precedence is **environment > project > selected overlay > global**. Empty routing values are ignored, so an
+empty project/env value cannot hide a working global credential or endpoint. Env overrides include
+`HARA_PROVIDER`, `HARA_MODEL`, `HARA_BASE_URL`, `HARA_API_KEY`, and the provider key
+(`ANTHROPIC_API_KEY` / `DASHSCOPE_API_KEY`).
 
 ## Use
 
@@ -146,12 +149,17 @@ hara init                  # analyze the project & (re)generate AGENTS.md
 hara doctor                # check your setup (auth / model / node / assets / roles)
 hara roles init            # scaffold role-agents (implementer / reviewer / docs)
 hara org "review src/ for bugs"   # dispatch a task to the role that owns it (or --role <id>)
+hara projects add shop /absolute/path/to/shop   # register an agent home
+hara agents                # list global + registered project agents
+hara org --role shop:reviewer "audit auth"     # run that agent at its own home
 hara plan "add a /health endpoint with a test"   # decompose → sequence (DAG) → run each step + verify
 hara plan --parallel "..."  # run independent atoms concurrently  ·  hara plan resume  # continue a stopped plan
 hara review                 # review uncommitted changes for bugs/security/missing tests (--staged · --base main)
 hara commit                 # AI commit message from staged changes, then commit (-a to stage all · -y to skip confirm)
 hara index                 # build the semantic search index (after: hara config set embedProvider ollama|qwen)
 hara -p "summarize @README.md and fix the lint errors in src/"   # one-shot; @path attaches a file
+hara -p "extract package metadata" --schema ./schema.json         # stdout is exactly schema-valid JSON
+hara -p "review the current diff" --role reviewer                 # persona + model + tool policy from the role
 hara --approval auto-edit  # suggest (default) | auto-edit | full-auto   (-y = full-auto)
 hara --sandbox workspace-write   # confine shell writes to the project (macOS Seatbelt)
 hara -c                    # resume the most recent session in this directory
@@ -159,6 +167,12 @@ hara --profile work        # use a named profile from ~/.hara/config.json
 hara -m glm-5              # pick a model
 ```
 
+For automation, `--schema` accepts inline JSON Schema or a schema file. The model must return through the
+validated `structured_output` tool; on success stdout contains only the JSON value, while diagnostics go to
+stderr and missing/invalid output exits non-zero. `--role reviewer` resolves locally, `--role global:reviewer`
+uses the portable global persona in the current project, and `--role shop:reviewer` runs at that registered
+project home. Each form enforces the role's persona, model, `allowTools`/`denyTools`, and `readOnly` policy.
+
 Inside the REPL: `/help` `/init` `/tools` `/model` `/approval` `/org` `/plan` `/roles` `/usage` `/doctor` `/sessions` `/undo` `/compact` `/recall` `/reset` `/exit` (type `/`+Tab to complete). Type `@` + Tab to attach a file (fuzzy, walks subdirectories).
 
 The interactive REPL is an **ink TUI**: a bordered **input box pinned at the bottom** — session name in
@@ -216,9 +230,22 @@ vision model into **actionable** output — interactive elements + positions (pa
 **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`.
+**Work coordination**: `todo_write` is the agent's short, session-scoped checklist; it persists with that
+session and is isolated between simultaneous sub-agents and serve sessions. `task` is the durable project pool
+for work that outlives a conversation: add/update/list/remove items with `pending|in_progress|done`, an optional
+owner, and `blockedBy` dependencies. The private, atomic store is shared by concurrent hara processes for the
+same project and rejects missing/self/cyclic dependencies.
 **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.
+Reviewer/read-only/plan runs and parallel read-only sub-agents suppress both hook phases: PreToolUse and
+PostToolUse commands are arbitrary shell, so either could otherwise bypass their read-only contract indirectly.
+They also skip configured and plugin-provided MCP server processes, so starting an external tool server cannot
+bypass the same contract before the first model turn.
+**Profiles and live config**: select an identity with `--profile <name>`; use `overlays` in
+`~/.hara/config.json` for named config overlays, and a project `.hara/config.json` for project-specific routing.
+Long-lived `hara serve` processes reload provider credentials/routes and guardian settings for the target cwd on
+new sessions and turns. `models.list` and new sessions see current defaults; a resumed session keeps its explicit
+model pin while using the live provider route. No server restart is required after a credential rotation.
 
 ### The org — what makes hara different
 
@@ -234,6 +261,13 @@ to a clean start tree; a review that doesn't pass leaves the work uncommitted).
 **`agent`** tool spawns **parallel read-only sub-agents** for fan-out — analyze / review / search
 several things at once (each can take a `role`), bounded to 8 concurrent (`HARA_MAX_CONCURRENCY`).
 
+Register project homes with `hara projects add <name> <absolute-path>`, then `hara agents` becomes a global
+address book across `~/.hara/roles` and each registered project's roles. A qualified address such as
+`shop:reviewer` is unambiguous; both `hara org --role shop:reviewer "<task>"` and one-shot `hara -p "<task>"
+--role shop:reviewer` execute at that agent's home, with its own `AGENTS.md`, live project config, role model,
+and allow/deny/read-only tool policy. `global:<name>` is portable and runs in the current project. A bare name
+uses the local role first and otherwise must resolve unambiguously.
+
 Beyond routing, **`hara plan "<task>"`** makes the org *plan*: it decomposes the task into atoms,
 sequences them as a DAG, and executes each step (optionally routed to a role) behind a per-step
 **verify gate** — frame → atomize → sequence → execute → verify. Each atom may carry a `check` shell
@@ -255,11 +289,11 @@ turn, or **`/undo`** to revert the last edit. In-session **`/diff`**, **`/review
 - **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**.
-- **Chat gateway**: drive your local hara from a chat app — **Telegram · WeChat · Discord · Feishu/Lark · Slack · Mattermost · Matrix · DingTalk**. The daemon connects out (no public webhook), with per-chat sessions, project roaming (`/cd`), and **two-way images** (send a photo → it sees it; ask for a file → it sends one). Setup per platform: **[docs/gateway.md](docs/gateway.md)**.
+- **Chat gateway**: drive your local hara from **Telegram · WeChat · Discord · Feishu/Lark · Slack · Mattermost · Matrix · DingTalk · WeCom · Signal**. The daemon connects out (no public webhook), with per-chat sessions, project roaming (`/cd`), agent switching (`/agent`), and **two-way images** (send a photo → it sees it; ask for a file → it sends one). Setup and the group-flow security model: **[docs/gateway.md](docs/gateway.md)**.
 
 ### Roadmap
 
-**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`)** · **chat gateway (8 platforms, two-way images)** · **single-binary distribution** · **Docker image** · `/compact` context management.
+**Shipped:** ink TUI · plan mode · persistent memory + self-evolution · atomization planner · parallel plan atoms · **multi-role review chains** · global project-agent index · durable project tasks · parallel sub-agents · MCP client *and* server · **scheduled tasks (`hara cron`)** · **chat gateway (10 platforms, two-way images)** · **single-binary distribution** · **Docker image** · `/compact` context management.
 **Next:** SSOT data authority · an enterprise control-plane (fleet + central token management).
 
 ## Security

package/dist/agent/failover.js

@@ -38,7 +38,7 @@ export function failoverAction(kind, s) {
 export function errorHint(kind) {
     switch (kind) {
         case "auth":
-            return " — check your API key / auth (try `hara setup`)";
+            return " — the configured credential was rejected or expired; update ~/.hara/config.json, the active profile, or its environment variable, then retry. Do not paste the key into chat";
         case "rate_limit":
             return " — rate-limited; wait a moment, or set `fallbackModel` to auto-switch";
         case "overloaded":

package/dist/agent/loop.js

@@ -16,6 +16,7 @@ import { drainReminders, wrapReminders, pushReminder, todoStaleReminder, TODO_ST
 import { setTurnPhase } from "./phase.js";
 import { recordTouch } from "./touched.js";
 import { resolve as resolvePath } from "node:path";
+import { redactSensitiveText } from "../security/secrets.js";
 /** File tools whose `path` input marks the file as "recently worked with" (post-compaction restore). */
 const FILE_TOUCH_TOOLS = new Set(["read_file", "edit_file", "write_file"]);
 /** Stall watchdog ceiling: a model attempt that streams NOTHING for this long is treated as a dead /
@@ -65,7 +66,14 @@ re-reading a big file after every edit is the slowest habit an agent can have.
 When an attempt FAILS, never repeat it unchanged — read the error, form a hypothesis about the cause, and
 change something (arguments / approach / tool) before trying again. After two failed variants of the same
 approach, stop: re-plan from what you learned, or ask the user, stating concisely what you tried and what
-the errors said. Repeating a failed action hoping for a different result is how sessions die. For broad,
+the errors said. Repeating a failed action hoping for a different result is how sessions die.
+Never put a literal password, API key, token, App Secret, Authorization header, or other credential in a
+source file or shell command. Reference an environment variable instead (for example process.env.API_KEY or
+$API_KEY). Keep real values in the user's environment or an approved secret store; do not create/populate a
+.env file with a real secret unless the user explicitly asks and it is excluded from version control. Never
+echo credentials back. Session persistence redacts likely secrets as a last line of defense, but that does
+not make embedding credentials acceptable.
+For broad,
 open-ended exploration (more than ~3 searches), spawn \`agent\` sub-agents — several in one response for
 independent questions (role "explore") — each returns conclusions, not dumps. Messages the user sends
 mid-task arrive marked as interjections — triage them (refine current / queue as todo / urgent-switch)
@@ -88,7 +96,10 @@ site, build output), check they are newer than their sources (compare mtimes or
 the sources changed since the artifacts were built, run the project's documented build/render steps FIRST.
 When AGENTS.md / README / package.json document a command sequence (e.g. pull → render → build → preview),
 that ordering is authoritative — never skip the middle steps, or you serve stale output and the user sees
-two-day-old work. After completing a task, give a one-line summary.`;
+two-day-old work. Package-manager installs receive a longer attached timeout by default; use background jobs
+only when explicitly appropriate, and poll a background job before depending on it. Before opening a public tunnel,
+verify that provider's authentication/config once; if it is missing, stop and ask instead of trying a chain
+of unrelated tunnel tools. After completing a task, give a one-line summary.`;
 /** When running inside `hara gateway`, tell the agent it's in a chat — so it delivers files via send_file
  *  (the only channel that reaches the peer) and never reaches for the desktop client / computer tool. */
 function gatewayNote() {
@@ -100,7 +111,9 @@ function gatewayNote() {
         `To send a file or image to them, call the \`send_file\` tool with an absolute path; that is the ONLY channel ` +
         `that reaches this chat. Do NOT use the \`computer\` tool, AppleScript, or any desktop/${plat}-client automation ` +
         `to deliver files — that drives a different window and silently fails to reach the user. Never tell the user a ` +
-        `file was sent unless \`send_file\` returned success. Keep replies short and chat-friendly.`);
+        `file was sent unless \`send_file\` returned success. Keep replies short and chat-friendly. ` +
+        `PLAIN TEXT ONLY: chat bubbles render markdown literally — never use **bold**, # headers, backticks, tables, ` +
+        `or [text](url); write list items as "- " lines and links as bare URLs.`);
 }
 function composeSystem(cwd, projectContext, override, memory) {
     const head = override ? `${override}\n\nWorking directory: ${cwd}` : HARA_SYSTEM(cwd);
@@ -118,6 +131,27 @@ export async function runAgent(history, opts) {
     let activeProvider = provider; // may switch to a fallback model on a recoverable error (app-failover)
     let triedFallback = false;
     let emptyRetried = false; // one-shot: a genuinely empty model turn gets a single nudge before we give up
+    const interruptedOutcome = () => {
+        const msg = "(interrupted)";
+        if (!opts.quiet) {
+            if (ctx.ui)
+                ctx.ui.notice(msg);
+            else
+                out(c.dim(`\n${msg}\n`));
+        }
+        return { status: "error", error: msg };
+    };
+    // Warn at the interaction boundary without echoing the value. Headless/gateway stdout is the response
+    // transport, so keep the banner to interactive surfaces; persistence is still redacted everywhere.
+    const latestUser = [...history].reverse().find((m) => m.role === "user");
+    const sensitive = latestUser?.role === "user" ? redactSensitiveText(latestUser.content).redactions : [];
+    if (sensitive.length && !opts.quiet) {
+        const note = "⚠ possible credential detected — the saved session copy will be redacted; prefer passing secrets through environment variables.";
+        if (ctx.ui)
+            ctx.ui.notice(note);
+        else if (stdout.isTTY)
+            out(c.yellow(note + "\n"));
+    }
     // Stuck/loop guard — only in headless chat (`hara gateway`), where a wrong approach can grind forever with
     // nobody to hit Esc (e.g. screenshots it can't read). Once per run, when the agent keeps repeating one
     // non-read tool or acting blind, we inject a reflection nudge so it steps back instead of spinning.
@@ -144,7 +178,7 @@ export async function runAgent(history, opts) {
         // lands as ONE wrapped user message the UI never renders. Quiet runs don't drain — a parallel
         // sub-agent must not steal the main conversation's reminders.
         if (!opts.quiet) {
-            const reminders = drainReminders();
+            const reminders = drainReminders(ctx.todoScope);
             if (reminders.length)
                 history.push({ role: "user", content: wrapReminders(reminders) });
         }
@@ -190,7 +224,12 @@ export async function runAgent(history, opts) {
         const STALL_MS = stallMs();
         const attempt = new AbortController();
         const onUserAbort = () => attempt.abort();
-        opts.signal?.addEventListener("abort", onUserAbort, { once: true });
+        // AbortSignal does not replay an already-fired event to a late listener. A serve shutdown can cancel
+        // while provider routing is still refreshing, so inherit that state synchronously before the call.
+        if (opts.signal?.aborted)
+            attempt.abort();
+        else
+            opts.signal?.addEventListener("abort", onUserAbort, { once: true });
         let lastEvent = Date.now();
         let stalled = false;
         const stallTimer = setInterval(() => {
@@ -207,17 +246,33 @@ export async function runAgent(history, opts) {
         if (!opts.quiet)
             setTurnPhase("waiting"); // request sent, nothing streamed yet — the status row shows it
         let r;
+        let removeAttemptStop = () => { };
         try {
-            r = await activeProvider.turn({
+            // AbortSignal is advisory: a custom/provider SDK can ignore it and leave its Promise pending forever.
+            // Race the attempt itself so the watchdog and user cancellation remain hard boundaries. The abandoned
+            // Promise retains a rejection handler through Promise.race, and all late stream callbacks below are muted.
+            const attemptStopped = new Promise((resolveStopped) => {
+                const onAttemptStop = () => resolveStopped({ text: "", toolUses: [], stop: "error", errorMsg: "interrupted" });
+                removeAttemptStop = () => attempt.signal.removeEventListener("abort", onAttemptStop);
+                if (attempt.signal.aborted)
+                    onAttemptStop();
+                else
+                    attempt.signal.addEventListener("abort", onAttemptStop, { once: true });
+            });
+            const providerTurn = activeProvider.turn({
                 system: composeSystem(ctx.cwd, opts.projectContext, opts.systemOverride, opts.memory),
                 history,
                 tools: specs,
                 // Any stream chunk keeps the connection considered alive — even suppressed reasoning_content, so a
                 // reasoning model thinking for a long while before its first `content` token can't be false-timed-out.
                 onActivity: () => {
+                    if (attempt.signal.aborted)
+                        return;
                     lastEvent = Date.now();
                 },
                 onText: (d) => {
+                    if (attempt.signal.aborted)
+                        return;
                     alive();
                     if (opts.quiet)
                         return;
@@ -234,6 +289,8 @@ export async function runAgent(history, opts) {
                 },
                 onReasoning: sink || tty
                     ? (d) => {
+                        if (attempt.signal.aborted)
+                            return;
                         alive();
                         if (opts.quiet)
                             return;
@@ -259,12 +316,23 @@ export async function runAgent(history, opts) {
                             }
                         }
                     }
-                    : (d) => alive(), // quiet runs still feed the watchdog (reasoning-only stretches are progress)
+                    : () => {
+                        if (!attempt.signal.aborted)
+                            alive();
+                    }, // quiet runs still feed the watchdog (reasoning-only stretches are progress)
                 signal: attempt.signal,
             });
+            opts.onProviderTurn?.(providerTurn);
+            r = await Promise.race([providerTurn, attemptStopped]);
+        }
+        catch (error) {
+            if (!opts.signal?.aborted)
+                throw error;
+            r = { text: "", toolUses: [], stop: "error", errorMsg: "interrupted" };
         }
         finally {
             clearInterval(stallTimer);
+            removeAttemptStop();
             opts.signal?.removeEventListener("abort", onUserAbort);
         }
         // A watchdog abort surfaces from the provider as "interrupted" — rewrite it to a timeout-class
@@ -282,6 +350,10 @@ export async function runAgent(history, opts) {
             opts.stats.output += r.usage.output;
             opts.stats.lastInput = r.usage.input;
         }
+        // A provider may ignore AbortSignal and return a perfectly valid-looking tool_use after cancellation.
+        // The original run signal is authoritative: do not append/approve/execute any late response.
+        if (opts.signal?.aborted)
+            return interruptedOutcome();
         history.push({ role: "assistant", text: r.text, toolUses: r.toolUses });
         if (r.stop === "error") {
             const kind = classifyError(r.errorMsg ?? "");
@@ -299,13 +371,26 @@ export async function runAgent(history, opts) {
                 continue; // retry once on the fallback model (guarded by triedFallback)
             }
             const msg = kind === "interrupted" ? "(interrupted)" : `[${activeProvider.id} error] ${r.errorMsg ?? "unknown"}${errorHint(kind)}`;
+            if (r.toolUses.length) {
+                // A provider can fail after partially assembling tool calls. The assistant turn is already persisted;
+                // close every call explicitly so the next request is valid, while never executing partial work.
+                history.push({
+                    role: "tool",
+                    results: r.toolUses.map((toolUse) => ({
+                        id: toolUse.id,
+                        name: toolUse.name,
+                        content: `Error: provider failed before this tool call could be executed. ${r.errorMsg ?? "unknown provider error"}`,
+                        isError: true,
+                    })),
+                });
+            }
             if (!opts.quiet) {
                 if (sink)
                     sink.notice(msg);
                 else
                     out(kind === "interrupted" ? c.dim(`\n${msg}\n`) : c.red(`${msg}\n`));
             }
-            return;
+            return { status: "error", error: msg };
         }
         // Empty-turn guard. The model returned nothing actionable — no text AND no tool calls (a blank
         // completion, or a "tool_use" stop with an empty tool list). Silently returning here leaves the
@@ -333,16 +418,37 @@ export async function runAgent(history, opts) {
                 else
                     out(c.dim(`${note}\n`));
             }
-            return;
+            return { status: "empty" };
         }
         // A "tool_use" stop with text but no tools (rare) has nothing to execute — end after showing the text
         // rather than pushing an empty tool round and re-requesting in a loop.
         if (r.stop !== "tool_use" || r.toolUses.length === 0)
-            return;
+            return { status: "completed" };
+        // Once an assistant tool_use turn enters history, every tool_use MUST receive a matching tool result.
+        // OpenAI/Anthropic both reject a later user turn after an unclosed tool round. Cancellation can happen
+        // while planning, approving, or executing, so finalize the round with real results for work that already
+        // completed and explicit interruption errors for everything else before persisting the session.
+        const results = new Array(r.toolUses.length);
+        const finalizeInterruptedToolRound = () => {
+            history.push({
+                role: "tool",
+                results: r.toolUses.map((tu, idx) => results[idx] ?? ({
+                    id: tu.id,
+                    name: tu.name,
+                    content: "Error: interrupted before this tool call completed.",
+                    isError: true,
+                })),
+            });
+            return interruptedOutcome();
+        };
+        if (opts.signal?.aborted)
+            return finalizeInterruptedToolRound();
         const plans = [];
         // Extra (per-run) tools win over the registry so a run-scoped tool can't be shadowed by a global one.
         const resolveTool = (name) => opts.extraTools?.find((t) => t.name === name) ?? getTool(name);
         for (const tu of r.toolUses) {
+            if (opts.signal?.aborted)
+                return finalizeInterruptedToolRound();
             if (breakerHalt) {
                 // Circuit-breaker halted the run: refuse every remaining call in this round with a clear message
                 // (no hang, no further tools) so the model + user get a definitive stop.
@@ -376,6 +482,8 @@ export async function runAgent(history, opts) {
                 if (risk.level === "high") {
                     const detail = String(input.command ?? input.path ?? "").replace(/\s+/g, " ").trim().slice(0, 400);
                     const verdict = await guardianVeto(opts.guardian.provider, { tool: tu.name, detail, classifierReason: risk.reason }, history, { signal: opts.signal });
+                    if (opts.signal?.aborted)
+                        return finalizeInterruptedToolRound();
                     if (verdict.decision === "block") {
                         const tripped = recordBlock(breaker); // deterministic circuit-breaker: N blocks → hard stop
                         plans.push({
@@ -399,6 +507,8 @@ export async function runAgent(history, opts) {
                             const cont = interactive
                                 ? await opts.confirm(`${c.red("⛔ guardian circuit-breaker")} — ${breaker.blocks} high-risk actions blocked this turn. Continue anyway?`)
                                 : false;
+                            if (opts.signal?.aborted)
+                                return finalizeInterruptedToolRound();
                             if (cont === false) {
                                 breakerHalt = true;
                             }
@@ -413,6 +523,8 @@ export async function runAgent(history, opts) {
             }
             if (cmdDecision !== "allow" && 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 (opts.signal?.aborted)
+                    return finalizeInterruptedToolRound();
                 if (reply === false) {
                     plans.push({ tu, tool, denied: "User denied this action." });
                     continue;
@@ -430,8 +542,11 @@ export async function runAgent(history, opts) {
             }
         }
         // Execute: read-only tools run concurrently; edit/exec run alone, in order.
-        const results = new Array(plans.length);
+        if (opts.signal?.aborted)
+            return finalizeInterruptedToolRound();
         const runOne = async (idx, p) => {
+            if (opts.signal?.aborted)
+                return;
             if (p.denied !== undefined) {
                 results[idx] = { id: p.tu.id, name: p.tu.name, content: p.denied, isError: true };
                 return;
@@ -445,28 +560,42 @@ export async function runAgent(history, opts) {
                 if (missing.length) {
                     const msg = `Error: tool call NOT executed — missing required parameter${missing.length > 1 ? "s" : ""}: ` +
                         `${missing.join(", ")}. Send the call again with ALL required parameters (${(p.tool.input_schema.required ?? []).join(", ")}) present and complete.`;
-                    results[idx] = { id: p.tu.id, name: p.tu.name, content: msg + recordCall(p.tu.name, p.tu.input, msg, true), isError: true };
+                    results[idx] = { id: p.tu.id, name: p.tu.name, content: msg + recordCall(p.tu.name, p.tu.input, msg, true, ctx.todoScope), isError: true };
                     return;
                 }
-                const pre = runHooks("PreToolUse", p.tu.name, p.tu.input, ctx.cwd); // a hook may veto the call
+                if (opts.signal?.aborted)
+                    return;
+                const pre = opts.hooks === false
+                    ? { block: false, message: "" }
+                    : 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;
                 }
+                if (opts.signal?.aborted)
+                    return;
                 // Track the MAIN conversation's working files for post-compaction restore (quiet fan-out
                 // sub-agents read broadly — their files aren't "what the user was working on").
                 if (!opts.quiet && FILE_TOUCH_TOOLS.has(p.tu.name) && typeof p.tu.input?.path === "string") {
-                    recordTouch(resolvePath(ctx.cwd, String(p.tu.input.path)));
+                    recordTouch(resolvePath(ctx.cwd, String(p.tu.input.path)), ctx.todoScope);
                 }
                 const res = await p.tool.run(p.tu.input, ctx);
                 // append any not-yet-seen subdirectory AGENTS.md/CLAUDE.md this call touched (monorepo-local conventions)
                 // + the repeat-guard's anti-spinning note when this exact call keeps failing (repeat-guard.ts)
-                results[idx] = { id: p.tu.id, name: p.tu.name, content: res + subdirHint(p.tu.input, ctx.cwd) + recordCall(p.tu.name, p.tu.input, res) };
-                runHooks("PostToolUse", p.tu.name, { input: p.tu.input, result: res }, ctx.cwd); // observe-only
+                results[idx] = { id: p.tu.id, name: p.tu.name, content: res + subdirHint(p.tu.input, ctx.cwd) + recordCall(p.tu.name, p.tu.input, res, false, ctx.todoScope) };
+                // The tool may have completed a side effect and then triggered/observed cancellation. Preserve its
+                // actual result in the closing tool round, but do not run any post hook or later tool afterward.
+                if (opts.signal?.aborted)
+                    return;
+                if (opts.hooks !== false) {
+                    runHooks("PostToolUse", p.tu.name, { input: p.tu.input, result: res }, ctx.cwd); // observe-only
+                }
             }
             catch (e) {
                 const msg = `Error: ${e.message}`;
-                results[idx] = { id: p.tu.id, name: p.tu.name, content: msg + recordCall(p.tu.name, p.tu.input, msg, true), isError: true };
+                results[idx] = { id: p.tu.id, name: p.tu.name, content: msg + recordCall(p.tu.name, p.tu.input, msg, true, ctx.todoScope), isError: true };
+                if (opts.signal?.aborted)
+                    return;
             }
             finally {
                 activity.dec();
@@ -481,16 +610,24 @@ export async function runAgent(history, opts) {
             await mapLimit(idx, maxParallel(), (i) => runOne(i, plans[i])); // bounded fan-out (e.g. 20 parallel agents → 8 at a time)
         };
         for (let i = 0; i < plans.length; i++) {
+            if (opts.signal?.aborted)
+                return finalizeInterruptedToolRound();
             const p = plans[i];
             if (p.denied === undefined && p.tool?.kind === "read") {
                 batch.push(i); // safe → accumulate to run concurrently
             }
             else {
                 await flush(); // flush pending reads before an edit/exec
+                if (opts.signal?.aborted)
+                    return finalizeInterruptedToolRound();
                 await runOne(i, p);
+                if (opts.signal?.aborted)
+                    return finalizeInterruptedToolRound();
             }
         }
         await flush();
+        if (opts.signal?.aborted)
+            return finalizeInterruptedToolRound();
         history.push({ role: "tool", results });
         // Synthesis nudge (CC's KN5, hara-shaped): a round that fanned out to several parallel agents just
         // produced N independent reports — remind the model to merge/reconcile them before acting, instead
@@ -498,7 +635,7 @@ export async function runAgent(history, opts) {
         if (!opts.quiet) {
             const fanout = r.toolUses.filter((tu) => tu.name === "agent").length;
             if (fanout >= SYNTHESIS_MIN_AGENTS)
-                pushReminder(synthesisReminder(fanout));
+                pushReminder(synthesisReminder(fanout), ctx.todoScope);
         }
         // Todo attention-refresh: a round that touched the checklist resets the clock; rounds that leave
         // unfinished items untouched accumulate, and at TODO_STALE_ROUNDS the model gets a system-reminder
@@ -507,10 +644,10 @@ export async function runAgent(history, opts) {
             if (r.toolUses.some((tu) => tu.name === "todo_write")) {
                 todoIdleRounds = 0;
             }
-            else if (currentTodos().some((t) => t.status !== "done")) {
+            else if (currentTodos(ctx.todoScope).some((t) => t.status !== "done")) {
                 todoIdleRounds++;
                 if (todoIdleRounds >= TODO_STALE_ROUNDS) {
-                    pushReminder(todoStaleReminder(renderTodos(currentTodos())));
+                    pushReminder(todoStaleReminder(renderTodos(currentTodos(ctx.todoScope))), ctx.todoScope);
                     todoIdleRounds = 0;
                 }
             }
@@ -525,7 +662,7 @@ export async function runAgent(history, opts) {
                 else
                     out(c.red(`${note}\n`));
             }
-            return;
+            return { status: "halted" };
         }
         if (guard && !nudged) {
             for (const p of plans)