@nanhara/hara 0.125.1 → 0.125.3

package/CHANGELOG.md

@@ -5,6 +5,43 @@ All notable changes to `@nanhara/hara`.
 > Versioning (pre-1.0, SemVer-style): the **minor** (middle) number bumps for a **new feature**; the
 > **patch** (last) number bumps for **optimizations/fixes of existing features**.
 
+## 0.125.3 — 2026-07-18 — conversation/task boundary and deliberate execution
+
+- **Chat delivery is now separate from task execution.** Slash controls such as `/model` no longer create a
+  fake steer target; input typed while a picker or other local control is busy is visibly queued as the next
+  turn. If a real turn ends between enqueue and delivery, Hara promotes the raced steer to a normal turn
+  instead of rejecting it with `there is no task to steer` or dropping the input. Queued controls execute
+  alone rather than absorbing the following task as command arguments, and paused/completed tasks are never
+  implicit steer targets—only explicit `/continue` may reopen one. User-invocable slash Skills remain real
+  Agent turns, so refinements typed while `/design`, `/video`, or another Skill is running steer that Skill
+  instead of becoming an unrelated task.
+- **Main tasks now establish an explicit understanding checkpoint before side effects.** The engine-owned
+  `task_intake` records intent, interpreted goal, constraints, acceptance checks, and short steps in the
+  durable task state. Reads and diagnosis may happen first, but edits, non-read-only commands, computer
+  actions, external agents, and MCP connections are blocked until the brief is accepted in a completed tool
+  round. Starting or stopping a background process is also treated as a state change even when its command or
+  job tool is otherwise read-only; malformed string-valued `background` flags are rejected. Read-only actions
+  inside mixed tools (`task list`, `cronjob list`) stay available for evidence gathering. Brief revisions
+  replace the old prompt copy and cannot share a round with a side effect. A later steer cannot be overwritten
+  by a concurrent or revised checkpoint.
+- **Alibaba Coding Plan discovery follows the current exact model contract.** `/model` prefers the endpoint's
+  live response and uses the documented ten-model list only for official Coding Plan hosts. Context guards now
+  use each model's published window, and `qwen3-coder-next` / `qwen3-coder-plus` no longer expose an unsupported
+  thinking control. Desktop/serve derives the reasoning dial from each session's pinned model rather than the
+  current global default.
+- **Configured MCP servers no longer execute or ask for permission when Hara starts.** Hara exposes a
+  zero-side-effect `mcp_connect` capability; the agent calls it only when the current task materially needs
+  one named server, receives the existing external-boundary approval, and discovers that server's tools for
+  the next model round. Other configured servers remain stopped.
+- Interactive calls to connected MCP tools still require confirmation every time, protected-file-shaped
+  inputs remain blocked, read-only roles cannot receive the launcher, and headless runs remain fail-closed
+  unless `HARA_ALLOW_TRUSTED_EXTENSIONS=1` was set before launch.
+- MCP stderr now drops only npm 11's repeated `Unknown user config "always-auth"` and `"home"` deprecation
+  lines. Other npm warnings and all actual server errors remain visible and redacted. Hara does not read,
+  rewrite, or weaken the user's `.npmrc`. Esc, interruption, and the total task deadline now also cancel a
+  lazy MCP startup/tool call and close an unresponsive child instead of leaving it behind.
+- Upgrade with `npm i -g @nanhara/hara@0.125.3`.
+
 ## 0.125.1 — 2026-07-18 — installed plugin commands inside agent tasks
 
 - **Commands contributed by an installed Hara plugin are now available to Hara's own tool subprocesses.**

package/README.md

@@ -109,8 +109,11 @@ hara config set model    qwen-plus   # or qwen-max, qwen3-coder-plus, …
 # coding-plan keys (sk-sp-…) use the coding endpoint instead:
 #   hara config set baseURL https://coding.dashscope.aliyuncs.com/v1
 #   hara config set model   qwen3.7-plus
-#   plan models: qwen3.7-plus, qwen3.6-plus, qwen3-coder-plus, qwen3-coder-next,
-#                qwen3-max-2026-01-23, glm-5, glm-4.7  (switch with -m or /model)
+#   supported exact ids (2026-07-18):
+#     qwen3.7-plus, qwen3.6-plus, qwen3.5-plus, qwen3-max-2026-01-23,
+#     qwen3-coder-next, qwen3-coder-plus, kimi-k2.5, glm-5, glm-4.7,
+#     MiniMax-M2.5
+#   /model uses the endpoint's live list first and this official list only as a fallback.
 ```
 
 > Plan keys (Coding Plan / Token Plan) are licensed **only** for use inside AI coding agents /
@@ -266,7 +269,7 @@ Type-ahead Enter steers the exact live turn; `/next <message>` queues a separate
 clients use `session.steer` with `expectedTurnId` (durable before ACK) and may pass `newTask: true` to force a
 new execution. The `hara resume` launcher preserves terminal input in both npm/Node and standalone-binary
 installs.
-**MCP**: add an `mcpServers` map to global config (a reviewed project config additionally needs `HARA_TRUST_PROJECT_CONFIG=1` at launch); their tools appear to the agent as `mcp__<server>__<tool>`. Configured MCP servers, like `external_agent`, are trusted host extensions outside Hara's protected-file boundary. Every interactive tool call requires confirmation (even in `full-auto`), and non-interactive runs disable them by default; reviewed automation can explicitly opt in before launch with `HARA_ALLOW_TRUSTED_EXTENSIONS=1`. 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).
+**MCP**: add an `mcpServers` map to global config (a reviewed project config additionally needs `HARA_TRUST_PROJECT_CONFIG=1` at launch). Hara starts with every configured server stopped and exposes only `mcp_connect`; when the current task first needs one server, the agent requests permission to connect that server and its tools appear on the next round as `mcp__<server>__<tool>`. Unrelated servers remain stopped. Configured MCP servers, like `external_agent`, are trusted host extensions outside Hara's protected-file boundary. Every interactive external-tool call requires confirmation (even in `full-auto`), and non-interactive runs disable them by default; reviewed automation can explicitly opt in before launch with `HARA_ALLOW_TRUSTED_EXTENSIONS=1`. 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`. Every job has a 30-minute deadline and the whole sequential tick has a non-renewable 60-minute watchdog: a job timeout kills its process tree, records `timed out` + duration/error, then continues with the next due job; a tick timeout stops the remainder and releases the global lock. Add `--deliver feishu:<chatId>` (or Telegram/webhook) for outcomes and `--alert-after N` for the consecutive-failure 🚨 threshold (default 3). Delivery intent is durable before transport, uses a stable idempotency key, and retries with bounded backoff on later ticks until confirmed. A failed channel cannot grow `jobs.json` forever: each job keeps at most 64 pending effects, reserves outcome/alert room before launch, and disables itself with a visible backlog error when full; restore delivery, let the queue drain, then re-enable it. Tune milliseconds with `HARA_CRON_JOB_TIMEOUT_MS` (hard max 24h) and `HARA_CRON_TICK_TIMEOUT_MS` (hard max 5h); scheduled jobs are also capped by the tick. After upgrading from a version whose tick is already stuck, terminate that specific legacy `hara cron tick` process tree once (or reboot); the next scheduler minute marks over-age state interrupted/disabled and recovers the lock without replaying a possibly orphaned task.
 **Work coordination**: `todo_write` is the agent's short, session-scoped checklist; it persists with that
@@ -274,6 +277,14 @@ session and is isolated between simultaneous sub-agents and serve sessions. `tas
 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.
+**Conversation and execution**: the composer first routes an input as a local control, a new task, a steer of
+the exact live task, or an explicit next task. User-invocable slash Skills are executable turns and accept
+live steering; local controls such as `/model` are serialized without pretending to own a task. A main task keeps the raw user request and a separate accepted
+brief (intent, interpreted goal, constraints, acceptance checks, and steps). Hara permits read-only
+investigation before that brief, but its engine blocks side effects until the understanding has been
+checkpointed in its own model/tool round. Mixed tools are classified by action (`task list` is a read), and
+a brief revision cannot share its round with a side effect. `/task` shows the current execution identity and brief. See
+[`docs/conversation-task-execution.md`](docs/conversation-task-execution.md).
 **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.
 **Run limits and loop alarms**: every agent turn has a non-renewable 30-minute total deadline and a 64-round
 model/tool cap. Hara warns after five minutes or at 75% of the round budget, stops the third identical failing
@@ -286,8 +297,8 @@ provider that ignores cancellation cannot strand the CLI outside the main loop.
 **Hooks**: run your own shell commands around tool calls via a `"hooks"` map in global config; hooks from a reviewed project config require the launch-time `HARA_TRUST_PROJECT_CONFIG=1` opt-in. 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.
 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.
+They also omit the lazy connector for configured and plugin-provided MCP servers, so a read-only role cannot
+start an external tool server.
 **Profiles and live config**: select an identity with `--profile <name>`; use `overlays` in
 `~/.hara/config.json` for named config overlays. Project `.hara/config.json` files get the safe preference
 allowlist above; project-specific routing requires `HARA_TRUST_PROJECT_CONFIG=1` before launch.

package/SECURITY.md

@@ -70,11 +70,13 @@ local user (who already has your shell).
 - **MCP/external agents are trusted extensions.** They execute outside Hara's protected-file boundary. Every
   interactive tool call requires confirmation, including in `full-auto`; non-interactive runs disable them by
   default. Reviewed automation can explicitly enable them before launch with
-  `HARA_ALLOW_TRUSTED_EXTENSIONS=1`. Their inherited environment is still scrubbed, but the extension may use
-  its own credentials or access anything its host process permits.
+  `HARA_ALLOW_TRUSTED_EXTENSIONS=1`. Merely configuring an MCP server does not start it: `mcp_connect` requests
+  permission and starts one named server only when a task needs it. Their inherited environment is still
+  scrubbed, but the extension may use its own credentials or access anything its host process permits.
 - **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>`.
+  its MCP servers may run on first relevant use and its hooks may run around matching tool calls. `hara plugin
+  add` **prints the exact commands** a plugin can 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

package/dist/agent/loop.js

@@ -6,7 +6,7 @@ import { makeRenderer } from "../md.js";
 import { skillsDigest } from "../skills/skills.js";
 import { runHooks } from "../hooks.js";
 import { mapLimit, maxParallel } from "../concurrency.js";
-import { decideCommand, loadPermissionRules } from "../security/permissions.js";
+import { decideCommand, isReadOnlyCommand, loadPermissionRules, splitCompound, } from "../security/permissions.js";
 import { classifyRisk, guardianVeto, guardianEnabled, newBreaker, recordBlock } from "../security/guardian.js";
 import { keyOf, looksFailed, recordCall } from "./repeat-guard.js";
 import { agentMaxRounds, agentRunTimeoutMs, formatAgentDuration } from "./limits.js";
@@ -21,6 +21,7 @@ import { redactSensitiveText } from "../security/secrets.js";
 import { redactToolSubprocessOutput } from "../security/subprocess-env.js";
 import { prepareHistoryForModel } from "./context-budget.js";
 import { rolesDigest } from "../org/roles.js";
+import { applyTaskBrief } from "../session/task.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 /
@@ -86,7 +87,9 @@ mask to existing protected paths; Linux/Windows shell checks are
 static guardrails, not a kernel sandbox. MCP and external coding agents run outside this boundary: use them
 only as reviewed trusted extensions. Their tool calls require confirmation every time in interactive use and
 are disabled without an interactive approval channel unless the user launched with
-HARA_ALLOW_TRUSTED_EXTENSIONS=1.
+HARA_ALLOW_TRUSTED_EXTENSIONS=1. Configured MCP servers stay stopped by default; when a task materially needs
+one, call \`mcp_connect\` for that server only, then use the newly available tools on the next round. Never
+connect every configured server speculatively.
 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. When specialist roles are
@@ -142,14 +145,34 @@ const CONTINUATION_SYSTEM = "# Existing-session continuity\n" +
     "re-inventory the workspace, or summarize files merely to understand what happened before. Follow the latest user request " +
     "and reuse prior conclusions and tool results. Inspect files only when the latest request requires it. If the working " +
     "directory is Home, ask the user to start Hara from a concrete project instead of enumerating Home or its children.";
-function composeSystem(cwd, projectContext, override, memory, continuationSession = false, executionContext) {
+function composeSystem(cwd, projectContext, override, memory, continuationSession = false, executionContext, intake) {
     const head = override ? `${override}\n\nWorking directory: ${cwd}` : HARA_SYSTEM(cwd);
     const skills = skillsDigest(cwd);
     const roles = override ? "" : rolesDigest(cwd);
+    const intakeContext = !intake?.enabled
+        ? ""
+        : intake.brief
+            ? ("\n\n# Understanding → execution boundary\n" +
+                "The task brief below is the accepted interpretation for this run. Keep actions inside it. If new " +
+                "user input materially changes the goal, constraints, acceptance checks, or intended side effects, " +
+                "call `task_intake` again before further side effects.\n" +
+                `Intent: ${intake.brief.intent}\n` +
+                `Goal: ${intake.brief.goal}\n` +
+                `Constraints:\n${intake.brief.constraints.map((item) => `- ${item}`).join("\n")}\n` +
+                `Acceptance:\n${intake.brief.acceptance.map((item) => `- ${item}`).join("\n")}\n` +
+                `Steps:\n${intake.brief.steps.map((item, index) => `${index + 1}. ${item}`).join("\n")}`)
+            : ("\n\n# Understanding → execution boundary\n" +
+                "Do not jump from a raw request straight into side effects. You may answer, inspect files, search, " +
+                "ask a necessary question, or build a todo list first. BEFORE the first edit, non-read-only command, " +
+                "background-process start/stop, computer action, external agent, or MCP connection, call `task_intake` in its OWN tool round with " +
+                "the interpreted goal, intent, constraints, acceptance checks, and short steps. Use intent `answer` " +
+                "for a direct answer, `investigate` for evidence gathering/diagnosis, and `change` when the user asked " +
+                "you to modify or deliver something. Do not claim completion until the acceptance checks are verified.");
     return (head +
         gatewayNote() +
         (continuationSession ? `\n\n${CONTINUATION_SYSTEM}` : "") +
         (executionContext ? `\n\n${executionContext}` : "") +
+        intakeContext +
         (projectContext ? `\n\n# Project context (AGENTS.md)\n${projectContext}` : "") +
         (memory ? `\n\n# Memory (durable — facts/decisions/prefs you've saved; use memory_search/get for more)\n${memory}` : "") +
         (roles ? `\n\n# Specialist roles (metadata only — use \`agent\` with a role id for bounded read-only expertise)\n${roles}` : "") +
@@ -286,6 +309,54 @@ async function runAgentInner(history, opts, life) {
     const { provider, ctx } = opts;
     const runSignal = life.signal;
     const toolCtx = { ...ctx, signal: runSignal };
+    let intakeTask = opts.taskIntake?.task;
+    let intakeDirty = false;
+    const syncIntakeTask = () => {
+        const current = opts.taskIntake?.current?.();
+        if (current && (!intakeTask || current.id === intakeTask.id))
+            intakeTask = current;
+    };
+    const taskIntakeTool = opts.taskIntake
+        ? {
+            name: "task_intake",
+            description: "Record or revise your explicit understanding of the active task before side effects. Call this " +
+                "in its own tool round only after using the conversation and any needed read-only evidence to identify " +
+                "the real goal. Required before edits, non-read-only commands, background-process start/stop, computer actions, external agents, or MCP.",
+            input_schema: {
+                type: "object",
+                properties: {
+                    intent: {
+                        type: "string",
+                        enum: ["answer", "investigate", "change"],
+                        description: "answer = direct response, investigate = evidence/diagnosis, change = modify or deliver",
+                    },
+                    goal: { type: "string", description: "One concrete interpreted outcome; include the actual target, not generic 'help the user'." },
+                    constraints: { type: "array", items: { type: "string" }, description: "User/project boundaries that must remain true." },
+                    acceptance: { type: "array", items: { type: "string" }, description: "Observable checks that prove the task is done." },
+                    steps: { type: "array", items: { type: "string" }, description: "Short ordered approach, normally 2–6 steps." },
+                },
+                required: ["intent", "goal", "constraints", "acceptance", "steps"],
+            },
+            kind: "read",
+            run: async (input) => {
+                syncIntakeTask();
+                const applied = applyTaskBrief(intakeTask, input);
+                if (!applied.ok)
+                    return `Error: task brief rejected — ${applied.reason}`;
+                intakeTask = applied.task;
+                intakeDirty = true;
+                return (`Task brief accepted (${applied.brief.intent}).\n` +
+                    `Goal: ${applied.brief.goal}\n` +
+                    `Acceptance:\n${applied.brief.acceptance.map((item) => `- ${item}`).join("\n")}\n` +
+                    "Proceed within this brief; revise task_intake first if the user's intent materially changes.");
+            },
+        }
+        : undefined;
+    // `task_intake` is engine-owned and cannot be shadowed by an ad-hoc tool with the same name.
+    const runExtraTools = [
+        ...(opts.extraTools ?? []).filter((tool) => tool.name !== "task_intake"),
+        ...(taskIntakeTool ? [taskIntakeTool] : []),
+    ];
     const permRules = loadPermissionRules(ctx.cwd); // command-level allow/ask/deny policy for the bash tool
     let activeProvider = provider; // may switch to a fallback model on a recoverable error (app-failover)
     let triedFallback = false;
@@ -381,6 +452,9 @@ async function runAgentInner(history, opts, life) {
                 return stoppedOutcome();
             for (const m of pending)
                 history.push(m);
+            // pendingInput may have durably accepted steering into the owner's immutable task snapshot. Refresh
+            // before composing the system or applying a later brief so that state is never overwritten.
+            syncIntakeTask();
         }
         // system-reminder injection: event-driven context queued since the last call (todo staleness today)
         // lands as ONE wrapped user message the UI never renders. Quiet runs don't drain — a parallel
@@ -391,11 +465,11 @@ async function runAgentInner(history, opts, life) {
                 history.push({ role: "user", content: wrapReminders(reminders) });
         }
         const baseSpecs = opts.toolFilter ? toolSpecs().filter((t) => opts.toolFilter(t.name)) : toolSpecs();
-        const specs = opts.extraTools?.length
-            ? [...baseSpecs, ...opts.extraTools.map((t) => ({ name: t.name, description: t.description, input_schema: t.input_schema }))]
+        const specs = runExtraTools.length
+            ? [...baseSpecs, ...runExtraTools.map((t) => ({ name: t.name, description: t.description, input_schema: t.input_schema }))]
             : baseSpecs;
         const sink = ctx.ui; // TUI mode: route output to ink instead of stdout
-        const system = composeSystem(ctx.cwd, opts.projectContext, opts.systemOverride, opts.memory, opts.continuationSession, opts.executionContext);
+        const system = composeSystem(ctx.cwd, opts.projectContext, opts.systemOverride, opts.memory, opts.continuationSession, opts.executionContext, { enabled: !!opts.taskIntake, brief: intakeTask?.brief });
         const prepared = prepareHistoryForModel(history, {
             model: activeProvider.model,
             system,
@@ -736,7 +810,12 @@ async function runAgentInner(history, opts, life) {
         };
         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);
+        const resolveTool = (name) => runExtraTools.find((t) => t.name === name) ?? getTool(name);
+        // Planning happens before dispatch, so a previously accepted `change` brief must not let the model
+        // revise that brief and perform a side effect in the same response. Treat every intake call as a
+        // transaction boundary for the whole response: accept/checkpoint the interpretation first, then let
+        // the next model round act against the newly authoritative brief.
+        const taskBriefTransitionInRound = r.toolUses.some((tu) => tu.name === "task_intake");
         for (const tu of r.toolUses) {
             if (runSignal.aborted)
                 return finalizeStoppedToolRound();
@@ -752,9 +831,71 @@ async function runAgentInner(history, opts, life) {
                 continue;
             }
             const input = tu.input;
-            const preview = redactToolSubprocessOutput(String(input.path ?? input.command ?? input.pattern ?? input.url ?? input.task ?? "")
+            const preview = redactToolSubprocessOutput(String(input.path ?? input.command ?? input.pattern ?? input.url ?? input.task ?? input.server ?? "")
                 .replace(/\s+/g, " ")
                 .trim());
+            // Resolve shell read-only policy before the understanding gate: an `investigate` brief may run a
+            // command already classified safe/read-only, while edits and unknown/non-read-only commands require
+            // an explicit `change` brief. Opaque external tools always require a brief and retain their separate
+            // per-action approval boundary.
+            const command = tool.kind === "exec" && typeof input.command === "string" ? input.command : null;
+            const cmdDecision = command !== null ? decideCommand(command, permRules) : null;
+            // Permission rules answer whether a command may auto-run; they do not answer whether it mutates state.
+            // In particular, an explicit `allow: ["git commit"]` must not let an `investigate` brief perform a
+            // commit. Classify read-only semantics independently for the understanding boundary.
+            const commandParts = command !== null ? splitCompound(command) : null;
+            const commandReadOnly = !!commandParts?.length && commandParts.every(isReadOnlyCommand);
+            // Bash intentionally treats `background` as a boolean. Be conservative at the policy boundary even
+            // for a malformed model call: any truthy value would otherwise reach a truthiness-based/custom exec
+            // implementation as a process start and bypass an investigate brief.
+            const startsBackgroundProcess = tool.kind === "exec" && Boolean(input.background);
+            const stopsBackgroundProcess = tool.name === "job" && input.action === "kill";
+            if (opts.taskIntake && tool.name !== "task_intake") {
+                // Some action-style tools contain both inspection and mutation behind one registry kind. Classify
+                // the concrete operation, not only the approval class: listing tasks/cron jobs is evidence gathering,
+                // while their other actions remain state changes.
+                const readOnlyAction = (tool.name === "task" || tool.name === "cronjob") &&
+                    input.action === "list";
+                const operationReadOnly = readOnlyAction ||
+                    (tool.kind === "read" && !stopsBackgroundProcess) ||
+                    (tool.kind === "exec" && commandReadOnly && !startsBackgroundProcess);
+                const needsBrief = tool.trustBoundary === "external" || !operationReadOnly;
+                const requiresChange = tool.trustBoundary !== "external" &&
+                    !operationReadOnly &&
+                    (tool.kind === "edit" ||
+                        tool.kind === "computer" ||
+                        stopsBackgroundProcess ||
+                        startsBackgroundProcess ||
+                        (tool.kind === "exec" && !commandReadOnly));
+                if (taskBriefTransitionInRound && (requiresChange || tool.trustBoundary === "external")) {
+                    plans.push({
+                        tu,
+                        tool,
+                        denied: "Understanding gate: task_intake establishes or revises the brief in this tool round, so this " +
+                            "side effect was NOT executed. Wait for the next model round, then act against the checkpointed brief.",
+                    });
+                    continue;
+                }
+                if (needsBrief && !intakeTask?.brief) {
+                    plans.push({
+                        tu,
+                        tool,
+                        denied: "Understanding gate: this action was NOT executed. First inspect/ask what is needed, then call " +
+                            "task_intake in its own tool round with goal, intent, constraints, acceptance, and steps.",
+                    });
+                    continue;
+                }
+                if (requiresChange && intakeTask?.brief?.intent !== "change") {
+                    plans.push({
+                        tu,
+                        tool,
+                        denied: `Understanding gate: task brief intent is '${intakeTask?.brief?.intent ?? "unset"}', so this ` +
+                            "side effect was NOT executed. Revise task_intake to intent 'change' with the user's authorized " +
+                            "goal and acceptance checks before trying again.",
+                    });
+                    continue;
+                }
+            }
             // Screen control and opaque host extensions are gated on EVERY action — a prior "don't ask again"
             // and even full-auto must never silently turn them into a side channel.
             const alwaysGate = tool.kind === "computer" || tool.trustBoundary === "external";
@@ -769,7 +910,6 @@ async function runAgentInner(history, opts, life) {
             }
             // Command-level policy for shell commands: a deny rule blocks even in full-auto; an allow rule (or a
             // read-only command) auto-runs even in suggest mode. Composes with, doesn't replace, the approval mode.
-            const cmdDecision = tool.kind === "exec" && typeof input.command === "string" ? decideCommand(input.command, permRules) : null;
             if (cmdDecision === "deny") {
                 plans.push({ tu, tool, denied: "Denied by a permission rule (~/.hara/permissions.json). Loosen the rule or run it yourself." });
                 continue;
@@ -970,8 +1110,9 @@ async function runAgentInner(history, opts, life) {
                 return finalizeStoppedToolRound();
             const p = plans[i];
             // ask_user is interaction-safe but not parallel-safe: the TUI deliberately owns one prompt slot.
-            // Flush other reads and ask sequentially so two questions cannot overwrite each other and hang.
-            if (p.denied === undefined && p.tool?.kind === "read" && p.tool.name !== "ask_user") {
+            // task_intake is also a state transition: run it alone so its persisted brief has a deterministic
+            // boundary before the next model round. Flush other reads before either.
+            if (p.denied === undefined && p.tool?.kind === "read" && p.tool.name !== "ask_user" && p.tool.name !== "task_intake") {
                 batch.push(i); // safe → accumulate to run concurrently
             }
             else {
@@ -987,6 +1128,29 @@ async function runAgentInner(history, opts, life) {
         if (runSignal.aborted)
             return finalizeStoppedToolRound();
         history.push({ role: "tool", results });
+        if (intakeDirty && intakeTask) {
+            try {
+                // The tool-use/result pair is now protocol-complete. Persist here—never inside the tool—so a crash
+                // cannot leave a session ending in an orphaned tool_use, and no later side effect starts before the
+                // accepted understanding has a durable checkpoint. A steer can be acknowledged while another read
+                // from this same tool round is still settling, so merge from the authoritative owner once more at
+                // this exact boundary instead of overwriting that acknowledged input with the earlier snapshot.
+                const acceptedBrief = intakeTask.brief;
+                syncIntakeTask();
+                // The current owner may still carry the previous brief when this call is a revision. The accepted
+                // brief is the state transition from this round; authoritative refresh contributes newer steering,
+                // while this assignment contributes the new interpretation.
+                if (acceptedBrief && intakeTask) {
+                    intakeTask = { ...intakeTask, brief: acceptedBrief };
+                }
+                opts.taskIntake?.onUpdate?.(intakeTask);
+                opts.taskIntake?.onCheckpoint?.(intakeTask);
+                intakeDirty = false;
+            }
+            catch (error) {
+                return interactionFailure("task-intake checkpoint", error);
+            }
+        }
         if (repeatHalt)
             return hardStop(opts, life, "repeat_loop", repeatHalt);
         // Synthesis nudge (CC's KN5, hara-shaped): a round that fanned out to several parallel agents just