@nanhara/hara 0.125.3 → 0.126.1

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";
@@ -22,8 +23,12 @@ 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
@@ -90,6 +95,9 @@ are disabled without an interactive approval channel unless the user launched wi
 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
@@ -181,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. " +
@@ -206,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);
@@ -248,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,
@@ -267,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.`;
@@ -308,7 +427,33 @@ 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 = () => {
@@ -338,6 +483,7 @@ async function runAgentInner(history, opts, life) {
                 required: ["intent", "goal", "constraints", "acceptance", "steps"],
             },
             kind: "read",
+            classify: () => ({ effect: "state", concurrencySafe: false }),
             run: async (input) => {
                 syncIntakeTask();
                 const applied = applyTaskBrief(intakeTask, input);
@@ -418,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;
@@ -464,7 +610,10 @@ 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 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;
@@ -560,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({
@@ -666,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") {
@@ -758,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",
@@ -785,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) => {
@@ -810,14 +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) => runExtraTools.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
@@ -831,42 +988,42 @@ async function runAgentInner(history, opts, life) {
                 continue;
             }
             const input = tu.input;
+            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());
-            // 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;
+            // 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;
-            // 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 operationReadOnly = operation.effect === "read"
+                    || operation.effect === "state"
+                    || operation.effect === "interactive";
                 const needsBrief = tool.trustBoundary === "external" || !operationReadOnly;
                 const requiresChange = tool.trustBoundary !== "external" &&
                     !operationReadOnly &&
-                    (tool.kind === "edit" ||
-                        tool.kind === "computer" ||
-                        stopsBackgroundProcess ||
-                        startsBackgroundProcess ||
-                        (tool.kind === "exec" && !commandReadOnly));
+                    (operation.effect === "edit" || operation.effect === "exec" || operation.effect === "computer");
                 if (taskBriefTransitionInRound && (requiresChange || tool.trustBoundary === "external")) {
                     plans.push({
                         tu,
@@ -898,7 +1055,7 @@ async function runAgentInner(history, opts, life) {
             }
             // 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,
@@ -919,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)
@@ -934,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
@@ -958,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) {
@@ -981,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)
@@ -1002,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)
@@ -1012,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 };
@@ -1042,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: "" }
@@ -1051,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").
@@ -1062,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);
@@ -1081,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
@@ -1097,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;
@@ -1106,27 +1276,27 @@ 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.
-            // 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") {
+            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 {
@@ -1189,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++;