@nanhara/hara 0.125.1 → 0.126.0

package/dist/agent/loop.js

@@ -1,4 +1,5 @@
-import { getTool, toolSpecs, missingRequired } from "../tools/registry.js";
+import { approvalKindForOperation, getTool, missingRequired, toolOperationTraits, toolSpecs, } from "../tools/registry.js";
+import { limitToolResultBatch } from "../tools/result-limit.js";
 import { stdout } from "node:process";
 import { c, out } from "../ui.js";
 import { activity } from "../activity.js";
@@ -6,7 +7,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,8 +22,13 @@ 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";
+import { askUserTool } from "../tools/ask_user.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"]);
+/** Engine-owned, non-authority helpers. Role filters still govern every deferred target activated by
+ * tool_search; these two only reveal an allowed schema or page an already-redacted result. */
+const RUNTIME_HELPER_TOOLS = new Set(["tool_search", "tool_result_read"]);
 /** Stall watchdog ceiling: a model attempt that streams NOTHING for this long is treated as a dead /
  *  stalled connection and aborted into the normal error→failover path — instead of hanging on
  *  "working Ns" forever (the "pressed Enter, thought it failed" report). Generous default because
@@ -86,7 +92,12 @@ 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.
+Optional web, desktop, scheduler, external-agent, and connected-MCP schemas may be deferred to keep context
+focused. If a needed capability is absent from the current tool list, call \`tool_search\` once with the
+capability/service name; use the activated tool on the next round. Do not search 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 +153,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}` : "") +
@@ -158,7 +189,7 @@ function composeSystem(cwd, projectContext, override, memory, continuationSessio
 const RUN_STOPPED = Symbol("agent-run-stopped");
 const REPEATED_FAILURE_LIMIT = 3;
 export function deadlineCheckpointReminder(timeoutMs) {
-    return (`Turn budget checkpoint: about 20% remains before the ${formatAgentDuration(timeoutMs)} safety pause. ` +
+    return (`Turn active-execution budget checkpoint: about 20% remains before the ${formatAgentDuration(timeoutMs)} safety pause. ` +
         "Stop expanding scope. Finish only the current atomic step, persist any usable artifact, update todo_write, " +
         "and reply with the completed checkpoint plus the next exact step. Do not start another generation batch, " +
         "install, full validation suite, preview, render, deployment, or other multi-minute stage in this turn. " +
@@ -183,39 +214,149 @@ function requestRunCheckpoint(opts, life) {
     if (life.disposed || life.checkpointDue || life.signal.aborted)
         return;
     life.checkpointDue = true;
-    const remainingMs = Math.max(0, life.timeoutMs - (Date.now() - life.startedAt));
-    showRunNotice(opts, `⚠ agent turn nearing its safety pause: ${formatAgentDuration(remainingMs)} remains. The agent will be told to finish the current atomic step and checkpoint; use \`/continue\` for the next expensive stage.`);
+    const remainingMs = Math.max(0, life.timeoutMs - runActiveElapsedMs(life));
+    showRunNotice(opts, `⚠ active turn budget is 80% used: about ${formatAgentDuration(remainingMs)} of active execution remains. The agent will be told to finish the current atomic step and checkpoint; use \`/continue\` for the next expensive stage.`);
 }
 function warnRun(opts, life) {
     if (life.disposed || life.warned || life.signal.aborted)
         return;
     life.warned = true;
-    const elapsedMs = Date.now() - life.startedAt;
+    const elapsedMs = runActiveElapsedMs(life);
     const remainingMs = Math.max(0, life.timeoutMs - elapsedMs);
-    showRunNotice(opts, `⚠ agent still running: ${formatAgentDuration(elapsedMs)} elapsed, round ${life.rounds}/${life.maxRounds}; ${formatAgentDuration(remainingMs)} remains before this turn pauses. Finish the current step or leave a checklist checkpoint; unfinished session work can resume with \`/continue\`.`);
+    showRunNotice(opts, `⚠ agent is still actively working: ${formatAgentDuration(elapsedMs)} active execution elapsed, round ${life.rounds}/${life.maxRounds}; ${formatAgentDuration(remainingMs)} remains before this turn pauses. Finish the current step or leave a checklist checkpoint; unfinished session work can resume with \`/continue\`.`);
+}
+function runActiveElapsedMs(life) {
+    const current = life.activeStartedAt === null ? 0 : Date.now() - life.activeStartedAt;
+    return Math.max(0, life.activeElapsedMs + current);
+}
+function clearRunTimers(life) {
+    if (life.timeoutTimer)
+        clearTimeout(life.timeoutTimer);
+    if (life.warningTimer)
+        clearTimeout(life.warningTimer);
+    if (life.checkpointTimer)
+        clearTimeout(life.checkpointTimer);
+    life.timeoutTimer = null;
+    life.warningTimer = null;
+    life.checkpointTimer = null;
+}
+/** Timer callbacks are macrotasks. A synchronous provider can overrun the budget and return a tool request
+ * before that callback gets CPU, so every authority boundary also performs this synchronous check. */
+function expireRunBudgetIfNeeded(life) {
+    if (life.signal.aborted)
+        return true;
+    if (life.disposed || life.pauseDepth > 0)
+        return false;
+    const elapsedMs = runActiveElapsedMs(life);
+    if (elapsedMs < life.timeoutMs)
+        return false;
+    life.activeElapsedMs = elapsedMs;
+    life.activeStartedAt = null;
+    clearRunTimers(life);
+    life.timedOut = true;
+    life.timeoutController.abort(new Error("agent active-execution deadline reached"));
+    return true;
+}
+/** Re-arm every threshold from the active clock. Human wait time is excluded, but active provider/tool
+ * promises remain bounded even when they ignore AbortSignal or own no event-loop handles. */
+function armRunTimers(opts, life) {
+    clearRunTimers(life);
+    if (life.disposed || life.signal.aborted || life.pauseDepth > 0 || life.activeStartedAt === null)
+        return;
+    if (expireRunBudgetIfNeeded(life))
+        return;
+    const elapsedMs = runActiveElapsedMs(life);
+    const timeoutDelay = life.timeoutMs - elapsedMs;
+    life.timeoutTimer = setTimeout(() => {
+        if (life.disposed || life.signal.aborted || life.pauseDepth > 0)
+            return;
+        if (!expireRunBudgetIfNeeded(life))
+            armRunTimers(opts, life);
+    }, timeoutDelay);
+    // The hard timer stays referenced while the agent is actively executing. Human prompts have their own
+    // visible UI plus Esc/shutdown cancellation and deliberately do not keep this active budget running.
+    const warningAt = Math.min(5 * 60_000, Math.max(250, Math.floor(life.timeoutMs * 0.8)));
+    if (!life.warned) {
+        life.warningTimer = setTimeout(() => warnRun(opts, life), Math.max(0, warningAt - elapsedMs));
+        life.warningTimer.unref?.();
+    }
+    const checkpointAt = Math.max(250, Math.floor(life.timeoutMs * 0.8));
+    if (!life.checkpointDue) {
+        life.checkpointTimer = setTimeout(() => requestRunCheckpoint(opts, life), Math.max(0, checkpointAt - elapsedMs));
+        life.checkpointTimer.unref?.();
+    }
+}
+function pauseRunBudget(life) {
+    if (life.disposed || life.signal.aborted || expireRunBudgetIfNeeded(life))
+        return false;
+    life.pauseDepth += 1;
+    if (life.pauseDepth > 1)
+        return true;
+    life.activeElapsedMs = runActiveElapsedMs(life);
+    life.activeStartedAt = null;
+    clearRunTimers(life);
+    return true;
+}
+function resumeRunBudget(opts, life, paused) {
+    if (!paused || life.pauseDepth <= 0)
+        return;
+    life.pauseDepth -= 1;
+    if (life.pauseDepth > 0 || life.disposed || life.signal.aborted)
+        return;
+    life.activeStartedAt = Date.now();
+    if (expireRunBudgetIfNeeded(life))
+        return;
+    armRunTimers(opts, life);
+}
+/** Only engine-owned human interaction may suspend the active clock. A plugin cannot acquire this authority
+ * by labelling an arbitrary long-running operation "interactive". Parent Esc/shutdown cancellation remains
+ * connected through life.signal and dismisses the prompt immediately. */
+async function withAbortSignal(signal, action) {
+    let removeAbort = () => { };
+    const aborted = new Promise((_resolve, reject) => {
+        const stop = () => reject(signal.reason ?? new Error("agent run interrupted"));
+        removeAbort = () => signal.removeEventListener("abort", stop);
+        if (signal.aborted)
+            stop();
+        else
+            signal.addEventListener("abort", stop, { once: true });
+    });
+    try {
+        const guardedAction = Promise.resolve().then(() => {
+            // Promise.race does not cancel its losing branch. Re-check inside the queued microtask so an Esc
+            // that lands after waitForHuman() is entered but before the UI callback runs cannot open a stale prompt.
+            if (signal.aborted)
+                throw signal.reason ?? new Error("agent run interrupted");
+            return action();
+        });
+        return await Promise.race([guardedAction, aborted]);
+    }
+    finally {
+        removeAbort();
+    }
+}
+async function waitForHuman(opts, life, action) {
+    const outermost = life.pauseDepth === 0;
+    const paused = pauseRunBudget(life);
+    if (!paused)
+        throw life.signal.reason ?? new Error("agent run ended before human interaction");
+    if (outermost && !opts.quiet)
+        setTurnPhase("awaiting_user");
+    try {
+        return await withAbortSignal(life.signal, action);
+    }
+    finally {
+        resumeRunBudget(opts, life, paused);
+        if (outermost && !opts.quiet)
+            setTurnPhase("streaming");
+    }
 }
 function createRunLifecycle(opts) {
     const timeoutMs = agentRunTimeoutMs(opts.timeoutMs);
     const maxRounds = agentMaxRounds(opts.maxRounds);
     const timeoutController = new AbortController();
     const signal = opts.signal ? AbortSignal.any([opts.signal, timeoutController.signal]) : timeoutController.signal;
-    const startedAt = Date.now();
-    const life = {};
-    const timeoutTimer = setTimeout(() => {
-        if (life.disposed || signal.aborted)
-            return;
-        life.timedOut = true;
-        timeoutController.abort(new Error("agent run deadline reached"));
-    }, timeoutMs);
-    // This timer is the hard boundary for a provider/tool Promise that owns no event-loop handles. Keep it
-    // referenced while the run is active; unref would let headless Node exit with the run still unresolved.
-    // Long legitimate work gets an in-band heads-up; a fast active loop gets the same warning at 75% rounds.
-    const warningDelay = Math.min(5 * 60_000, Math.max(250, Math.floor(timeoutMs * 0.8)));
-    const warningTimer = setTimeout(() => warnRun(opts, life), warningDelay);
-    warningTimer.unref?.();
-    const checkpointDelay = Math.max(250, Math.floor(timeoutMs * 0.8));
-    const checkpointTimer = setTimeout(() => requestRunCheckpoint(opts, life), checkpointDelay);
-    checkpointTimer.unref?.();
+    const activeStartedAt = Date.now();
     let removeStopListener = () => { };
     const stopPromise = new Promise((resolveStopped) => {
         const stopped = () => resolveStopped(RUN_STOPPED);
@@ -225,15 +366,17 @@ function createRunLifecycle(opts) {
         else
             signal.addEventListener("abort", stopped, { once: true });
     });
-    Object.assign(life, {
+    const life = {
         signal,
         timeoutController,
-        timeoutTimer,
-        warningTimer,
-        checkpointTimer,
+        timeoutTimer: null,
+        warningTimer: null,
+        checkpointTimer: null,
         stopPromise,
         removeStopListener,
-        startedAt,
+        activeStartedAt,
+        activeElapsedMs: 0,
+        pauseDepth: 0,
         timeoutMs,
         maxRounds,
         rounds: 0,
@@ -244,20 +387,19 @@ function createRunLifecycle(opts) {
         limitAnnounced: false,
         disposed: false,
         failedCalls: new Map(),
-    });
+    };
+    armRunTimers(opts, life);
     return life;
 }
 function disposeRunLifecycle(life) {
     life.disposed = true;
-    clearTimeout(life.timeoutTimer);
-    clearTimeout(life.warningTimer);
-    clearTimeout(life.checkpointTimer);
+    clearRunTimers(life);
     life.removeStopListener();
 }
 function hardStop(opts, life, kind, detail) {
-    const elapsedMs = Date.now() - life.startedAt;
+    const elapsedMs = runActiveElapsedMs(life);
     const message = kind === "deadline"
-        ? `⏸ agent run paused: total deadline ${formatAgentDuration(life.timeoutMs)} reached after ${life.rounds} round(s). No further model or tool calls will start in this turn. Session-backed work keeps its task and checklist checkpoint; type \`/continue\` to resume in a fresh bounded turn. Only for intentionally long single turns, use \`hara config set runTimeoutMs 45m\` (maximum 2h).`
+        ? `⏸ agent run paused: active-execution deadline ${formatAgentDuration(life.timeoutMs)} reached after ${life.rounds} round(s). Waiting for your answers did not consume this budget. No further model or tool calls will start in this turn. Session-backed work keeps its task and checklist checkpoint; type \`/continue\` to resume in a fresh bounded turn. Only for intentionally long single turns, use \`hara config set runTimeoutMs 45m\` (maximum 2h).`
         : kind === "max_rounds"
             ? `⛔ agent run stopped: ${life.maxRounds}-round safety limit reached after ${formatAgentDuration(elapsedMs)}. This usually means the model is looping. Increase it with \`hara config set maxAgentRounds <n>\` (maximum 256) only if the extra rounds are intentional.`
             : `⛔ agent run stopped: the same failing ${detail?.tool ?? "tool"} call repeated ${detail?.count ?? REPEATED_FAILURE_LIMIT} times. Change the approach or fix the reported cause before retrying.`;
@@ -285,7 +427,82 @@ export async function runAgent(history, opts) {
 async function runAgentInner(history, opts, life) {
     const { provider, ctx } = opts;
     const runSignal = life.signal;
-    const toolCtx = { ...ctx, signal: runSignal };
+    const activatedDeferredTools = new Set();
+    const askWithRunCancellation = ctx.ask
+        ? (question, options, signal) => {
+            const combined = signal && signal !== runSignal
+                ? AbortSignal.any([runSignal, signal])
+                : runSignal;
+            return withAbortSignal(combined, () => ctx.ask(question, options, combined));
+        }
+        : undefined;
+    const toolCtx = {
+        ...ctx,
+        signal: runSignal,
+        ...(askWithRunCancellation ? { ask: askWithRunCancellation } : {}),
+        activateTools(names) {
+            const accepted = [];
+            for (const name of names) {
+                const tool = getTool(name);
+                if (!tool || tool.visibility !== "deferred")
+                    continue;
+                if (opts.toolFilter && !opts.toolFilter(name))
+                    continue;
+                activatedDeferredTools.add(name);
+                accepted.push(name);
+            }
+            return accepted;
+        },
+    };
+    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",
+            classify: () => ({ effect: "state", concurrencySafe: false }),
+            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;
@@ -347,14 +564,14 @@ async function runAgentInner(history, opts, life) {
     for (;;) {
         // A cancellation that already happened is authoritative: do not start pending-input work, a provider
         // request, or any later tool round merely to give it an already-aborted signal.
-        if (runSignal.aborted)
+        if (expireRunBudgetIfNeeded(life) || runSignal.aborted)
             return stoppedOutcome();
         if (life.rounds >= life.maxRounds)
             return hardStop(opts, life, "max_rounds");
         life.rounds += 1;
         if (life.rounds >= Math.ceil(life.maxRounds * 0.75))
             warnRun(opts, life);
-        if (Date.now() - life.startedAt >= Math.floor(life.timeoutMs * 0.8))
+        if (runActiveElapsedMs(life) >= Math.floor(life.timeoutMs * 0.8))
             requestRunCheckpoint(opts, life);
         if (!opts.quiet && life.checkpointDue && !life.checkpointInjected) {
             life.checkpointInjected = true;
@@ -381,6 +598,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
@@ -390,12 +610,15 @@ async function runAgentInner(history, opts, life) {
             if (reminders.length)
                 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 visibleSpecs = toolSpecs({ activatedDeferred: activatedDeferredTools });
+        const baseSpecs = opts.toolFilter
+            ? visibleSpecs.filter((t) => RUNTIME_HELPER_TOOLS.has(t.name) || opts.toolFilter(t.name))
+            : visibleSpecs;
+        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,
@@ -486,7 +709,7 @@ async function runAgentInner(history, opts, life) {
             // immediately before the provider side effect starts. Promise.resolve(activeProvider.turn(...)) is
             // insufficient here: a custom provider can throw synchronously before Promise.resolve ever sees it.
             const providerTurn = Promise.resolve().then(() => {
-                if (attempt.signal.aborted || runSignal.aborted) {
+                if (expireRunBudgetIfNeeded(life) || attempt.signal.aborted || runSignal.aborted) {
                     return { text: "", toolUses: [], stop: "error", errorMsg: "interrupted" };
                 }
                 return activeProvider.turn({
@@ -592,7 +815,7 @@ async function runAgentInner(history, opts, life) {
         }
         // 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 (runSignal.aborted)
+        if (expireRunBudgetIfNeeded(life) || runSignal.aborted)
             return stoppedOutcome();
         history.push({ role: "assistant", text: r.text, toolUses: r.toolUses });
         if (r.stop === "error") {
@@ -684,7 +907,7 @@ async function runAgentInner(history, opts, life) {
         const results = new Array(r.toolUses.length);
         const finalizeStoppedToolRound = () => {
             const pendingMessage = life.timedOut
-                ? `Error: agent run deadline ${formatAgentDuration(life.timeoutMs)} reached before this tool call completed.`
+                ? `Error: agent active-execution deadline ${formatAgentDuration(life.timeoutMs)} reached before this tool call completed.`
                 : "Error: interrupted before this tool call completed.";
             history.push({
                 role: "tool",
@@ -711,7 +934,7 @@ async function runAgentInner(history, opts, life) {
             });
             return outcome;
         };
-        if (runSignal.aborted)
+        if (expireRunBudgetIfNeeded(life) || runSignal.aborted)
             return finalizeStoppedToolRound();
         let repeatHalt = null;
         const noteCall = (name, input, content, isError = false) => {
@@ -736,9 +959,22 @@ 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) => {
+            const extra = runExtraTools.find((tool) => tool.name === name);
+            if (extra)
+                return extra;
+            const registered = getTool(name);
+            if (registered?.visibility === "deferred" && !activatedDeferredTools.has(name))
+                return undefined;
+            return registered;
+        };
+        // 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)
+            if (expireRunBudgetIfNeeded(life) || runSignal.aborted)
                 return finalizeStoppedToolRound();
             if (breakerHalt) {
                 // Circuit-breaker halted the run: refuse every remaining call in this round with a clear message
@@ -752,12 +988,74 @@ 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 command = tool.kind === "exec" && typeof input.command === "string" ? input.command : null;
+            let operation = toolOperationTraits(tool, input, toolCtx);
+            // One-release compatibility for embedders/older plugins that only implement static kind. New built-ins
+            // declare classify(); legacy command/action tools retain the established safe semantics until migrated.
+            if (!tool.classify) {
+                if (command !== null) {
+                    const parts = splitCompound(command);
+                    const readOnly = !Boolean(input.background)
+                        && !!parts?.length
+                        && parts.every(isReadOnlyCommand);
+                    operation = readOnly
+                        ? { effect: "read", concurrencySafe: true }
+                        : { effect: "exec", concurrencySafe: false };
+                }
+                else if ((tool.name === "task" || tool.name === "cronjob") && input.action === "list") {
+                    operation = { effect: "read", concurrencySafe: true };
+                }
+                else if (tool.name === "job" && input.action === "kill") {
+                    operation = { effect: "exec", concurrencySafe: false, destructive: true };
+                }
+            }
+            const approvalKind = approvalKindForOperation(operation);
+            const preview = redactToolSubprocessOutput(String(input.path ?? input.command ?? input.pattern ?? input.url ?? input.task ?? input.server ?? "")
                 .replace(/\s+/g, " ")
                 .trim());
+            // Command rules apply only to the concrete shell tool. Input-level traits independently answer whether
+            // this exact operation mutates state; an allow rule must never turn a mutation into an investigation.
+            const cmdDecision = command !== null ? decideCommand(command, permRules) : null;
+            if (opts.taskIntake && tool.name !== "task_intake") {
+                const operationReadOnly = operation.effect === "read"
+                    || operation.effect === "state"
+                    || operation.effect === "interactive";
+                const needsBrief = tool.trustBoundary === "external" || !operationReadOnly;
+                const requiresChange = tool.trustBoundary !== "external" &&
+                    !operationReadOnly &&
+                    (operation.effect === "edit" || operation.effect === "exec" || operation.effect === "computer");
+                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";
+            const alwaysGate = approvalKind === "computer" || tool.trustBoundary === "external";
             if (tool.trustBoundary === "external" && !ctx.ask && process.env.HARA_ALLOW_TRUSTED_EXTENSIONS !== "1") {
                 plans.push({
                     tu,
@@ -769,7 +1067,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;
@@ -779,13 +1076,16 @@ async function runAgentInner(history, opts, life) {
             // commands classify `low` (pure Node, no LLM) and skip everything below — zero added latency. Only a
             // genuinely HIGH-RISK action pays for a cheap-model veto, and that veto fails OPEN on any glitch.
             if (guardianOn && !breakerHalt) {
-                const risk = classifyRisk(tu.name, tool.kind, input, ctx.cwd);
+                const risk = classifyRisk(tu.name, approvalKind, input, ctx.cwd);
+                if (expireRunBudgetIfNeeded(life) || runSignal.aborted)
+                    return finalizeStoppedToolRound();
                 if (risk.level === "high") {
                     const safeRiskReason = redactToolSubprocessOutput(risk.reason);
                     const detail = redactToolSubprocessOutput(String(input.command ?? input.path ?? "").replace(/\s+/g, " ").trim().slice(0, 400));
                     let verdictResult;
                     try {
-                        verdictResult = await bounded(Promise.resolve().then(() => guardianVeto(opts.guardian.provider, { tool: tu.name, detail, classifierReason: safeRiskReason }, history, { signal: runSignal })));
+                        const guardianTurn = Promise.resolve().then(() => guardianVeto(opts.guardian.provider, { tool: tu.name, detail, classifierReason: safeRiskReason }, history, { signal: runSignal, onProviderTurn: opts.onProviderTurn }));
+                        verdictResult = await bounded(guardianTurn);
                     }
                     catch (error) {
                         if (runSignal.aborted)
@@ -794,6 +1094,8 @@ async function runAgentInner(history, opts, life) {
                     }
                     if (verdictResult === RUN_STOPPED)
                         return finalizeStoppedToolRound();
+                    if (expireRunBudgetIfNeeded(life) || runSignal.aborted)
+                        return finalizeStoppedToolRound();
                     const verdict = verdictResult;
                     if (verdict.decision === "block") {
                         const tripped = recordBlock(breaker); // deterministic circuit-breaker: N blocks → hard stop
@@ -818,7 +1120,7 @@ async function runAgentInner(history, opts, life) {
                             let contResult;
                             try {
                                 contResult = interactive
-                                    ? await bounded(Promise.resolve().then(() => opts.confirm(`${c.red("⛔ guardian circuit-breaker")} — ${breaker.blocks} high-risk actions blocked this turn. Continue anyway?`, runSignal)))
+                                    ? await bounded(waitForHuman(opts, life, () => Promise.resolve().then(() => opts.confirm(`${c.red("⛔ guardian circuit-breaker")} — ${breaker.blocks} high-risk actions blocked this turn. Continue anyway?`, runSignal))))
                                     : false;
                             }
                             catch (error) {
@@ -841,11 +1143,11 @@ async function runAgentInner(history, opts, life) {
                     }
                 }
             }
-            const shouldConfirm = alwaysGate || (cmdDecision !== "allow" && needsConfirm(tool.kind, opts.approval) && !opts.autoApprove?.has(tu.name));
+            const shouldConfirm = alwaysGate || (cmdDecision !== "allow" && needsConfirm(approvalKind, opts.approval) && !opts.autoApprove?.has(tu.name));
             if (shouldConfirm) {
                 let replyResult;
                 try {
-                    replyResult = await bounded(Promise.resolve().then(() => opts.confirm(`${c.yellow("⚠")}  ${c.bold(tu.name)} ${c.dim(preview)} — run?`, runSignal)));
+                    replyResult = await bounded(waitForHuman(opts, life, () => Promise.resolve().then(() => opts.confirm(`${c.yellow("⚠")}  ${c.bold(tu.name)} ${c.dim(preview)} — run?`, runSignal))));
                 }
                 catch (error) {
                     if (runSignal.aborted)
@@ -862,7 +1164,7 @@ async function runAgentInner(history, opts, life) {
                 if (reply === "always" && !alwaysGate)
                     opts.autoApprove?.add(tu.name); // computer: treat "always" as one-time yes
             }
-            plans.push({ tu, tool });
+            plans.push({ tu, tool, operation, approvalKind });
             if (!opts.quiet) {
                 const pv = preview ? preview.slice(0, 80) : "";
                 if (sink)
@@ -872,10 +1174,10 @@ async function runAgentInner(history, opts, life) {
             }
         }
         // Execute: read-only tools run concurrently; edit/exec run alone, in order.
-        if (runSignal.aborted)
+        if (expireRunBudgetIfNeeded(life) || runSignal.aborted)
             return finalizeStoppedToolRound();
         const runOne = async (idx, p) => {
-            if (runSignal.aborted)
+            if (expireRunBudgetIfNeeded(life) || runSignal.aborted)
                 return;
             if (repeatHalt) {
                 results[idx] = { id: p.tu.id, name: p.tu.name, content: "Error: not executed because the repeated-failure circuit-breaker stopped this run.", isError: true };
@@ -902,7 +1204,7 @@ async function runAgentInner(history, opts, life) {
                     results[idx] = { id: p.tu.id, name: p.tu.name, content: msg + noteCall(p.tu.name, p.tu.input, msg, true), isError: true };
                     return;
                 }
-                if (runSignal.aborted)
+                if (expireRunBudgetIfNeeded(life) || runSignal.aborted)
                     return;
                 const pre = opts.hooks === false
                     ? { block: false, message: "" }
@@ -911,7 +1213,7 @@ async function runAgentInner(history, opts, life) {
                     results[idx] = { id: p.tu.id, name: p.tu.name, content: pre.message + noteCall(p.tu.name, p.tu.input, pre.message, true), isError: true };
                     return;
                 }
-                if (runSignal.aborted)
+                if (expireRunBudgetIfNeeded(life) || runSignal.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").
@@ -922,9 +1224,17 @@ async function runAgentInner(history, opts, life) {
                 // A plain Promise.race can let the abort branch win the same microtask turn and falsely report the
                 // completed action as not run. Non-cooperative pending tools still lose to the hard stop immediately.
                 let settled;
-                const observedTool = p.tool.run(p.tu.input, toolCtx).then((value) => { settled = { ok: true, value }; return value; }, (error) => { settled = { ok: false, error }; throw error; });
+                if (expireRunBudgetIfNeeded(life) || runSignal.aborted)
+                    return;
+                const executionToolCtx = p.tool === askUserTool && askWithRunCancellation
+                    ? {
+                        ...toolCtx,
+                        ask: (question, options, signal) => waitForHuman(opts, life, () => askWithRunCancellation(question, options, signal)),
+                    }
+                    : toolCtx;
+                const observedTool = p.tool.run(p.tu.input, executionToolCtx).then((value) => { settled = { ok: true, value }; return value; }, (error) => { settled = { ok: false, error }; throw error; });
                 try {
-                    opts.onToolRun?.(observedTool, { name: p.tool.name, kind: p.tool.kind });
+                    opts.onToolRun?.(observedTool, { name: p.tool.name, kind: p.approvalKind });
                 }
                 catch { /* observers cannot affect execution */ }
                 const toolResult = await bounded(observedTool);
@@ -941,7 +1251,7 @@ async function runAgentInner(history, opts, life) {
                 results[idx] = { id: p.tu.id, name: p.tu.name, content: res + subdirHint(p.tu.input, ctx.cwd) + noteCall(p.tu.name, p.tu.input, res) };
                 // 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 (runSignal.aborted)
+                if (expireRunBudgetIfNeeded(life) || runSignal.aborted)
                     return;
                 if (opts.hooks !== false) {
                     await runHooks("PostToolUse", p.tu.name, { input: p.tu.input, result: res }, ctx.cwd, 30_000, runSignal); // observe-only
@@ -957,7 +1267,7 @@ async function runAgentInner(history, opts, life) {
                 activity.dec();
             }
         };
-        let batch = []; // indices of pending read-kind tools (run concurrently, capped)
+        let batch = []; // indices of input-classified concurrency-safe operations
         const flush = async () => {
             if (!batch.length)
                 return;
@@ -966,27 +1276,51 @@ async function runAgentInner(history, opts, life) {
             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 (runSignal.aborted)
+            if (expireRunBudgetIfNeeded(life) || runSignal.aborted)
                 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") {
+            if (p.denied === undefined && p.operation?.concurrencySafe === true) {
                 batch.push(i); // safe → accumulate to run concurrently
             }
             else {
-                await flush(); // flush pending reads before an edit/exec
-                if (runSignal.aborted)
+                await flush(); // flush safe operations before a serial/shared-state operation
+                if (expireRunBudgetIfNeeded(life) || runSignal.aborted)
                     return finalizeStoppedToolRound();
                 await runOne(i, p);
-                if (runSignal.aborted)
+                if (expireRunBudgetIfNeeded(life) || runSignal.aborted)
                     return finalizeStoppedToolRound();
             }
         }
         await flush();
-        if (runSignal.aborted)
+        if (expireRunBudgetIfNeeded(life) || runSignal.aborted)
             return finalizeStoppedToolRound();
+        const boundedContents = limitToolResultBatch(results.map((result) => result.content));
+        for (let i = 0; i < results.length; i++)
+            results[i].content = boundedContents[i];
         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
@@ -1025,9 +1359,11 @@ async function runAgentInner(history, opts, life) {
             return { status: "halted" };
         }
         if (guard && !nudged) {
-            for (const p of plans)
-                if (p.tool && p.tool.kind !== "read")
+            for (const p of plans) {
+                if (p.tool && p.operation && p.operation.effect !== "read" && p.operation.effect !== "state" && p.operation.effect !== "interactive") {
                     toolCounts.set(p.tu.name, (toolCounts.get(p.tu.name) ?? 0) + 1);
+                }
+            }
             for (const res of results)
                 if (typeof res.content === "string" && /Configure a vision model/.test(res.content))
                     blindShots++;