@nanhara/hara 0.125.1 → 0.126.0

package/dist/serve/server.js

@@ -34,6 +34,7 @@ import { parseFrame, rpcResult, rpcError, rpcNotify, ERR, PROTOCOL_VERSION } fro
 import { readModelContextFileSync } from "../fs-read.js";
 import { optionalPosixOpenFlag } from "../fs-open-flags.js";
 import { sameOpenedFileIdentity } from "../fs-identity.js";
+import { redactSensitiveText, redactSensitiveValue } from "../security/secrets.js";
 import { consumePendingTaskSteering, createTaskExecution, continueTaskExecution, finishTaskExecution, newSteerInteraction, newTurnInteraction, recordTaskSteering, requestsTaskContinuation, taskExecutionContext, } from "../session/task.js";
 const APPROVAL_TIMEOUT_MS = 300_000; // an unanswered approval denies after 5 min (never hangs a turn)
 const COMPACT_TIMEOUT_MS = 60_000;
@@ -239,11 +240,11 @@ export async function startServe(opts, deps) {
     const token = opts.token ?? randomBytes(16).toString("hex");
     const instanceId = randomUUID();
     const hub = new SessionHub(deps.store ?? realStore);
-    const runtimeInfo = (cwd) => {
-        const live = deps.runtimeInfo?.(cwd);
+    const runtimeInfo = (cwd, model) => {
+        const live = deps.runtimeInfo?.(cwd, model);
         return {
             providerId: live?.providerId ?? deps.providerId,
-            model: live?.model ?? deps.model,
+            model: live?.model ?? model ?? deps.model,
             effortLevels: live?.effortLevels ?? deps.effortLevels ?? [],
         };
     };
@@ -251,12 +252,11 @@ export async function startServe(opts, deps) {
         const fresh = deps.buildProviderFor
             ? await deps.buildProviderFor(session.meta.model, session.effort, session.meta.cwd)
             : await deps.buildSessionProvider(session.meta.cwd);
-        if (!fresh)
+        if (!fresh || fresh.model !== session.meta.model)
             return false;
         session.provider = fresh;
         session.meta.provider = fresh.id;
-        // Preserve the user's pinned model in meta; provider factories should honor it, but fail closed if they do not.
-        return fresh.model === session.meta.model;
+        return true;
     };
     const wss = new WebSocketServer({ host: opts.host, port: opts.port, maxPayload: 10 * 1024 * 1024 });
     await new Promise((res, rej) => {
@@ -267,8 +267,66 @@ export async function startServe(opts, deps) {
     const authed = new Set();
     const pendingApprovals = new Map();
     const inFlightRequests = new Set();
+    // Physical provider/tool work can outlive its logical timeout. Keep a process-level ledger independent
+    // of SessionHub membership so detach/delete cannot make an updater believe the old engine is quiescent.
+    const activeOperations = new Set();
     let closing = false;
     let closePromise = null;
+    const trackActiveOperation = (operation) => {
+        activeOperations.add(operation);
+        const settled = () => {
+            activeOperations.delete(operation);
+            if (closing)
+                hub.releaseIdle();
+        };
+        void operation.then(settled, settled);
+        return operation;
+    };
+    const releaseSessionBusyIfIdle = (session) => {
+        if (session.abort === null &&
+            session.pendingProviderTurns === 0 &&
+            session.pendingToolRuns === 0) {
+            session.busy = false;
+        }
+    };
+    const observeProviderTurn = (session, turn) => {
+        session.pendingProviderTurns += 1;
+        trackActiveOperation(turn);
+        const settled = () => {
+            session.pendingProviderTurns = Math.max(0, session.pendingProviderTurns - 1);
+            // A logical timeout/interrupt may return before a non-cooperative provider physically settles.
+            // Retain the per-session lease so a second turn cannot share that provider instance concurrently.
+            releaseSessionBusyIfIdle(session);
+            if (closing)
+                hub.releaseIdle();
+        };
+        void turn.then(settled, settled);
+    };
+    const observeToolRun = (session, toolRun) => {
+        session.pendingToolRuns += 1;
+        trackActiveOperation(toolRun);
+        const settled = () => {
+            session.pendingToolRuns = Math.max(0, session.pendingToolRuns - 1);
+            // `abort === null` means the logical turn already returned. Keep the session busy/locked until
+            // every late side-effect-capable Promise has physically stopped.
+            releaseSessionBusyIfIdle(session);
+            if (closing)
+                hub.releaseIdle();
+        };
+        void toolRun.then(settled, settled);
+    };
+    /** An RPC-requested shutdown is a cooperative handoff (for example, before a Desktop update), not a
+     * force-stop. Refuse it while ANY client still owns live work. `inFlightRequests` covers async work that
+     * has not attached a session yet (provider factories/settings/filesystem scans); the session fields cover
+     * turns, compaction, provider reconfiguration, and physically late provider/tool promises. */
+    const hasActiveClientWork = () => inFlightRequests.size > 0 ||
+        activeOperations.size > 0 ||
+        pendingApprovals.size > 0 ||
+        hub.active().some((session) => session.busy ||
+            session.configuring ||
+            session.abort !== null ||
+            session.pendingProviderTurns > 0 ||
+            session.pendingToolRuns > 0);
     const broadcast = (method, params) => {
         const frame = rpcNotify(method, params);
         for (const ws of authed)
@@ -384,8 +442,8 @@ export async function startServe(opts, deps) {
             if (signal.aborted)
                 finish(false);
             else {
-                // `signal` is runAgent's combined Esc + total-deadline signal. Listening only to turnAbort would
-                // leave the approval map and Desktop prompt stale when the internal lifecycle deadline fires.
+                // `signal` composes the owning turn cancellation with runAgent's lifecycle cancellation. Listening
+                // only to turnAbort would leave the approval map and Desktop prompt stale after an internal stop.
                 signal.addEventListener("abort", onAbort, { once: true });
                 broadcast("approval.request", { sessionId, approvalId, question: q });
             }
@@ -419,7 +477,10 @@ export async function startServe(opts, deps) {
                         cwd: s.meta.cwd,
                         sandbox: deps.sandbox,
                         todoScope: sessionId,
-                        spawn: (t, role, signal) => deps.spawnSubagent(s.provider, s.meta.cwd, s.projectContext, s.stats, t, role, signal),
+                        spawn: (t, role, signal) => deps.spawnSubagent(s.provider, s.meta.cwd, s.projectContext, s.stats, t, role, signal, {
+                            onProviderTurn: (turn) => observeProviderTurn(s, turn),
+                            onToolRun: (toolRun) => observeToolRun(s, toolRun),
+                        }),
                         ui: sink,
                     },
                     approval: s.approval,
@@ -429,34 +490,25 @@ export async function startServe(opts, deps) {
                     memory: memoryDigest(s.meta.cwd),
                     continuationSession: s.continuationSession,
                     executionContext,
+                    taskIntake: {
+                        task: s.task,
+                        current: () => s.task,
+                        onUpdate: (next) => {
+                            s.task = next;
+                        },
+                        onCheckpoint: (next) => {
+                            s.task = next;
+                            hub.save(s);
+                        },
+                    },
                     pendingInput: async () => {
                         materializePendingSteering(s); // helper updates the shared live history after its write-ahead save
                         return [];
                     },
                     stats: s.stats,
                     signal: turnAbort.signal,
-                    onProviderTurn: (turn) => {
-                        s.pendingProviderTurns += 1;
-                        const settled = () => {
-                            s.pendingProviderTurns = Math.max(0, s.pendingProviderTurns - 1);
-                            if (closing)
-                                hub.releaseIdle();
-                        };
-                        void turn.then(settled, settled);
-                    },
-                    onToolRun: (toolRun) => {
-                        s.pendingToolRuns += 1;
-                        const settled = () => {
-                            s.pendingToolRuns = Math.max(0, s.pendingToolRuns - 1);
-                            // `abort === null` means the logical turn already returned. Keep the session busy/locked until
-                            // every late side-effect-capable Promise has physically stopped.
-                            if (s.pendingToolRuns === 0 && s.abort === null)
-                                s.busy = false;
-                            if (closing)
-                                hub.releaseIdle();
-                        };
-                        void toolRun.then(settled, settled);
-                    },
+                    onProviderTurn: (turn) => observeProviderTurn(s, turn),
+                    onToolRun: (toolRun) => observeToolRun(s, toolRun),
                     guardian: turnGuardian,
                     ...(deps.runLimits?.(s.meta.cwd) ?? {}),
                 });
@@ -497,7 +549,7 @@ export async function startServe(opts, deps) {
         }
         finally {
             s.abort = null;
-            s.busy = s.pendingToolRuns > 0;
+            s.busy = s.pendingProviderTurns > 0 || s.pendingToolRuns > 0;
         }
     };
     /** Context watermark for a session: how full the model's window was on the last turn. */
@@ -533,7 +585,7 @@ export async function startServe(opts, deps) {
             if (controller.signal.aborted)
                 return onAbort();
             // Promise.resolve protects this boundary even if a non-conforming provider throws synchronously.
-            void Promise.resolve().then(() => {
+            const providerTurn = Promise.resolve().then(() => {
                 // The abort can fire after scheduling this microtask but before it runs. Gate the provider call at
                 // the actual invocation boundary so an interrupted/expired compact cannot start a late request.
                 if (controller.signal.aborted)
@@ -545,7 +597,9 @@ export async function startServe(opts, deps) {
                     onText: () => { },
                     signal: controller.signal,
                 });
-            }).then((result) => finish(() => resolve(result)), (error) => finish(() => reject(error)));
+            });
+            observeProviderTurn(s, providerTurn);
+            void providerTurn.then((result) => finish(() => resolve(result)), (error) => finish(() => reject(error)));
         });
         if (controller.signal.aborted || r.stop === "error")
             return null;
@@ -608,18 +662,46 @@ export async function startServe(opts, deps) {
                         // clients feature-detect up front instead of probing for -32601 per call. `p.capabilities`
                         // (client-declared) is accepted and currently unused — reserved for opt-outs/experimental gating.
                         const methods = [
+                            "server.shutdown",
                             "session.list", "session.create", "session.resume", "session.send", "session.steer", "session.interrupt", "session.set-model",
                             "session.rename", "session.archive", "session.compact", "session.rewind", "session.context", "session.delete", "session.fork",
                             "approval.reply", "plugins.list", "plugins.set", "skills.list", "models.list", "files.search", "project.panels",
+                            "settings.providers.list", "settings.providers.test", "settings.providers.save",
                             "automation.list", "automation.add", "automation.toggle", "automation.delete",
                             "tasks.list", "approvals.list", "approvals.resolve",
                         ];
                         const runtime = runtimeInfo();
-                        return reply(rpcResult(id, { name: "hara", version: deps.version, protocol: PROTOCOL_VERSION, cwd: opts.cwd, provider: runtime.providerId, model: runtime.model, capabilities: { methods } }));
+                        const setupState = deps.providerSettings
+                            ? (deps.providerSettings(opts.cwd).current.authenticated ? "ready" : "needs-credentials")
+                            : "ready";
+                        return reply(rpcResult(id, {
+                            name: "hara",
+                            version: deps.version,
+                            protocol: PROTOCOL_VERSION,
+                            cwd: opts.cwd,
+                            provider: runtime.providerId,
+                            model: runtime.model,
+                            setupState,
+                            capabilities: { methods },
+                        }));
                     }
                     if (!authed.has(ws))
                         return reply(rpcError(id, ERR.UNAUTHORIZED, "initialize first"));
                     switch (req.method) {
+                        case "server.shutdown": {
+                            // The updater's stop request must never abort another client's turn or dismiss its approval.
+                            // The current shutdown request is not inserted into inFlightRequests until this synchronous
+                            // branch returns, so any entry observed here belongs to another request. Once accepted, close
+                            // admission atomically before replying/scheduling close: no new work can race into the gap.
+                            if (hasActiveClientWork()) {
+                                return reply(rpcError(id, ERR.BUSY, "server has active work — retry shutdown after all sessions and approvals are idle"));
+                            }
+                            closing = true;
+                            reply(rpcResult(id, { accepted: true }));
+                            const shutdown = setTimeout(() => void close(), 0);
+                            shutdown.unref();
+                            return;
+                        }
                         case "session.list":
                             return reply(rpcResult(id, { sessions: hub.list(typeof p.cwd === "string" ? p.cwd : undefined).filter((m) => !m.archived || p.archived === true).map((m) => ({ id: m.id, title: m.title, cwd: m.cwd, model: m.model, updatedAt: m.updatedAt, source: m.source ?? "interactive", sourceName: m.sourceName, archived: m.archived ?? false })) }));
                         case "session.create": {
@@ -810,8 +892,41 @@ export async function startServe(opts, deps) {
                             const session = typeof p.sessionId === "string" ? hub.get(p.sessionId) : undefined;
                             const targetCwd = typeof p.cwd === "string" && p.cwd ? p.cwd : (session?.meta.cwd ?? opts.cwd);
                             const models = deps.listModels ? await deps.listModels(targetCwd).catch(() => []) : [];
-                            const runtime = runtimeInfo(targetCwd);
-                            return reply(rpcResult(id, { models, current: session?.meta.model ?? runtime.model, effort: session?.effort ?? null, effortLevels: runtime.effortLevels }));
+                            const defaultRuntime = runtimeInfo(targetCwd);
+                            const current = session?.meta.model ?? defaultRuntime.model;
+                            const currentRuntime = runtimeInfo(targetCwd, current);
+                            return reply(rpcResult(id, { models, current, effort: session?.effort ?? null, effortLevels: currentRuntime.effortLevels }));
+                        }
+                        case "settings.providers.list": {
+                            if (!deps.providerSettings)
+                                return reply(rpcError(id, ERR.METHOD, "provider settings not supported by this server"));
+                            const targetCwd = typeof p.cwd === "string" && p.cwd ? p.cwd : opts.cwd;
+                            return reply(rpcResult(id, redactSensitiveValue(deps.providerSettings(targetCwd)).value));
+                        }
+                        case "settings.providers.test":
+                        case "settings.providers.save": {
+                            const callback = req.method === "settings.providers.test" ? deps.testProviderSettings : deps.saveProviderSettings;
+                            if (!callback)
+                                return reply(rpcError(id, ERR.METHOD, "provider settings not supported by this server"));
+                            if (typeof p.provider !== "string" ||
+                                typeof p.model !== "string" ||
+                                (p.baseURL !== undefined && typeof p.baseURL !== "string") ||
+                                (p.apiKey !== undefined && typeof p.apiKey !== "string") ||
+                                (p.clearApiKey !== undefined && typeof p.clearApiKey !== "boolean") ||
+                                (p.activatePersonal !== undefined && typeof p.activatePersonal !== "boolean")) {
+                                return reply(rpcError(id, ERR.PARAMS, "provider + model required; optional baseURL/apiKey/clearApiKey/activatePersonal have invalid types"));
+                            }
+                            const targetCwd = typeof p.cwd === "string" && p.cwd ? p.cwd : opts.cwd;
+                            const input = {
+                                provider: p.provider,
+                                model: p.model,
+                                ...(p.baseURL !== undefined ? { baseURL: p.baseURL } : {}),
+                                ...(p.apiKey !== undefined ? { apiKey: p.apiKey } : {}),
+                                ...(p.clearApiKey !== undefined ? { clearApiKey: p.clearApiKey } : {}),
+                                ...(p.activatePersonal !== undefined ? { activatePersonal: p.activatePersonal } : {}),
+                            };
+                            const result = await callback(input, targetCwd);
+                            return reply(rpcResult(id, redactSensitiveValue(result).value));
                         }
                         case "session.set-model": {
                             // per-session model / thinking-effort switch (the composer picker). Rebuilds the session's
@@ -976,9 +1091,9 @@ export async function startServe(opts, deps) {
                                 return reply(rpcResult(id, { sessionId: s.meta.id, ctx: ctxOf(s), notes: s.meta.workingSet?.length ?? 0, history: historyForClient(s.history) }));
                             }
                             finally {
-                                s.busy = false;
                                 if (s.abort === compactAbort)
                                     s.abort = null;
+                                s.busy = s.pendingProviderTurns > 0 || s.pendingToolRuns > 0;
                             }
                         }
                         case "session.rewind": {
@@ -1005,7 +1120,7 @@ export async function startServe(opts, deps) {
                     }
                 }
                 catch (e) {
-                    return reply(rpcError(id, ERR.INTERNAL, String(e?.message ?? e)));
+                    return reply(rpcError(id, ERR.INTERNAL, redactSensitiveText(String(e?.message ?? e)).text));
                 }
             })();
             inFlightRequests.add(task);
@@ -1064,7 +1179,9 @@ export async function startServe(opts, deps) {
                 await removeOwnedDiscovery(discoveryDir, discoveryPath, discovery).catch(() => { });
             let quiet = false;
             while (Date.now() < deadline) {
-                if (inFlightRequests.size === 0 && hub.active().every((session) => !session.busy && !session.configuring && session.pendingProviderTurns === 0 && session.pendingToolRuns === 0)) {
+                if (inFlightRequests.size === 0 &&
+                    activeOperations.size === 0 &&
+                    hub.active().every((session) => !session.busy && !session.configuring && session.pendingProviderTurns === 0 && session.pendingToolRuns === 0)) {
                     quiet = true;
                     break;
                 }

package/dist/serve/sessions.js

@@ -95,7 +95,12 @@ export class SessionHub {
      * when resume attached successfully but live provider validation failed before the client got a handle. */
     detach(id) {
         const live = this.sessions.get(id);
-        if (!live || live.busy || live.configuring)
+        if (!live ||
+            live.busy ||
+            live.configuring ||
+            live.abort !== null ||
+            live.pendingProviderTurns > 0 ||
+            live.pendingToolRuns > 0)
             return false;
         this.sessions.delete(id);
         this.store.release(id);
@@ -213,7 +218,11 @@ export class SessionHub {
      *  "gone" on success, "busy" when a turn is running, "missing" when unknown/held elsewhere. */
     delete(id) {
         const live = this.sessions.get(id);
-        if (live?.busy || live?.configuring)
+        if (live?.busy ||
+            live?.configuring ||
+            (live?.abort ?? null) !== null ||
+            (live?.pendingProviderTurns ?? 0) > 0 ||
+            (live?.pendingToolRuns ?? 0) > 0)
             return "busy";
         const ok = this.store.delete(id);
         if (!ok)

package/dist/session/operation-drain.js

@@ -0,0 +1,45 @@
+/**
+ * A dynamic physical-operation drain for session leases.
+ *
+ * A one-time `Promise.allSettled([...pending])` snapshot is insufficient: an observed outer tool may
+ * start and register a nested provider after shutdown begins. This drain checks the live Set after every
+ * settlement and releases only once it remains empty at a microtask boundary.
+ */
+export function createPhysicalOperationDrain(onDrained) {
+    const pending = new Set();
+    let closing = false;
+    let drained = false;
+    let drainQueued = false;
+    const requestDrain = () => {
+        if (!closing || drained || drainQueued || pending.size > 0)
+            return;
+        drainQueued = true;
+        queueMicrotask(() => {
+            drainQueued = false;
+            if (!closing || drained || pending.size > 0)
+                return;
+            drained = true;
+            onDrained();
+        });
+    };
+    const observe = (operation) => {
+        if (drained) {
+            throw new Error("cannot observe a physical operation after its session lease drained");
+        }
+        pending.add(operation);
+        const settled = () => {
+            pending.delete(operation);
+            requestDrain();
+        };
+        void operation.then(settled, settled);
+        return operation;
+    };
+    return {
+        observe,
+        close: () => {
+            closing = true;
+            requestDrain();
+        },
+        pendingCount: () => pending.size,
+    };
+}

package/dist/session/task.js

@@ -3,6 +3,9 @@ export const TASK_SCHEMA_VERSION = 1;
 export const MAX_TASK_OBJECTIVE_CHARS = 4096;
 export const MAX_TASK_STEERING_CHARS = 24_000;
 export const MAX_TASK_STEERING_ENTRIES = 24;
+export const MAX_TASK_BRIEF_GOAL_CHARS = 2_000;
+export const MAX_TASK_BRIEF_LIST_ENTRIES = 12;
+export const MAX_TASK_BRIEF_ITEM_CHARS = 800;
 function iso(at = new Date()) {
     return typeof at === "string" ? at : at.toISOString();
 }
@@ -16,12 +19,42 @@ function validId(value) {
 function validTimestamp(value) {
     return typeof value === "string" && value.length > 0 && Number.isFinite(Date.parse(value));
 }
+function boundedList(value, fallback) {
+    if (!Array.isArray(value))
+        return [fallback];
+    const out = value
+        .filter((item) => typeof item === "string")
+        .map((item) => boundedText(item, MAX_TASK_BRIEF_ITEM_CHARS))
+        .filter(Boolean)
+        .slice(0, MAX_TASK_BRIEF_LIST_ENTRIES);
+    return out.length ? out : [fallback];
+}
+function validBriefList(value) {
+    return Array.isArray(value) &&
+        value.length > 0 &&
+        value.length <= MAX_TASK_BRIEF_LIST_ENTRIES &&
+        value.every((item) => typeof item === "string" && item.length > 0 && item.length <= MAX_TASK_BRIEF_ITEM_CHARS);
+}
 export function newTurnInteraction() {
     return { kind: "turn", turnId: randomUUID() };
 }
 export function newSteerInteraction(expectedTurnId) {
     return { kind: "steer", expectedTurnId, turnId: randomUUID() };
 }
+/** Resolve a UI-delivery hint against authoritative task state. `steer` is never itself proof that an
+ * executable task is running: controls also occupy the composer briefly, and a real turn may finish between
+ * enqueue and dequeue. Preserve the submitted turn id but promote late input to a new turn. Only an explicit
+ * continuation path may opt into reopening a paused/completed task; stale live-turn ids remain hard errors
+ * in `continueTaskExecution`. */
+export function routeTaskInteraction(task, interaction, options = {}) {
+    const steerable = !!task && (task.status === "running" || options.allowInactive === true);
+    if (interaction.kind !== "steer" || steerable)
+        return { interaction, recoveredMissingTask: false };
+    return {
+        interaction: { kind: "turn", turnId: interaction.turnId },
+        recoveredMissingTask: true,
+    };
+}
 export function createTaskExecution(objective, turnId, at = new Date()) {
     const now = iso(at);
     return {
@@ -35,6 +68,35 @@ export function createTaskExecution(objective, turnId, at = new Date()) {
         startedAt: now,
     };
 }
+/** Attach or revise the explicit understanding checkpoint. Revision is intentional: steering may add a
+ * constraint or convert an investigation into an approved change, while the original request remains intact. */
+export function applyTaskBrief(task, input, at = new Date()) {
+    if (!task)
+        return { ok: false, reason: "there is no task to brief" };
+    if (task.status !== "running")
+        return { ok: false, reason: `task ${task.id} is ${task.status}, not running` };
+    const intent = input.intent;
+    if (intent !== "answer" && intent !== "investigate" && intent !== "change") {
+        return { ok: false, reason: "intent must be answer, investigate, or change" };
+    }
+    if (typeof input.goal !== "string" || !input.goal.trim()) {
+        return { ok: false, reason: "goal must be a non-empty string" };
+    }
+    const now = iso(at);
+    const brief = {
+        intent,
+        goal: boundedText(input.goal, MAX_TASK_BRIEF_GOAL_CHARS),
+        constraints: boundedList(input.constraints, "preserve unrelated user work and stated boundaries"),
+        acceptance: boundedList(input.acceptance, intent === "change" ? "the requested change is verified" : "the answer is supported by relevant evidence"),
+        steps: boundedList(input.steps, intent === "change" ? "inspect, change, and verify" : "inspect and report"),
+        createdAt: now,
+    };
+    return {
+        ok: true,
+        brief,
+        task: { ...task, brief, updatedAt: now },
+    };
+}
 export function continueTaskExecution(task, interaction, at = new Date()) {
     if (!task)
         return { ok: false, reason: "there is no task to steer" };
@@ -171,6 +233,9 @@ export function taskExecutionContext(task, interaction, todos = []) {
         steeringNote,
         "Conversation messages provide evidence and refinements, but the task objective above remains authoritative until an explicit new task starts.",
     ];
+    // The accepted brief is deliberately absent here. `taskExecutionContext` is the stable per-interaction
+    // identity/recovery snapshot, while runAgent composes the current brief dynamically on every model round.
+    // Duplicating it here would leave the pre-run version in the prompt after a mid-run task_intake revision.
     if (todos.length) {
         lines.push("## Persisted execution checkpoint", ...todos.slice(0, 24).map((todo) => {
             const mark = todo.status === "done" ? "done" : todo.status === "in_progress" ? "in progress" : "pending";
@@ -189,6 +254,7 @@ export function formatTaskExecution(task) {
         `task ${task.id.slice(0, 8)} · ${task.status}`,
         `turn ${task.turnId.slice(0, 8)} · outcome ${task.lastOutcome ?? "running"}`,
         `objective: ${task.objective}`,
+        `brief: ${task.brief ? `${task.brief.intent} · ${task.brief.goal}` : "(not accepted yet)"}`,
         `steering: ${task.steering?.length ?? 0}`,
     ].join("\n");
 }
@@ -205,6 +271,18 @@ export function isTaskExecution(value) {
         (task.endedAt !== undefined && !validTimestamp(task.endedAt)) ||
         (task.lastOutcome !== undefined && task.lastOutcome !== "completed" && task.lastOutcome !== "error" && task.lastOutcome !== "empty" && task.lastOutcome !== "halted" && task.lastOutcome !== "interrupted"))
         return false;
+    if (task.brief !== undefined) {
+        if (!task.brief || typeof task.brief !== "object" || Array.isArray(task.brief))
+            return false;
+        const brief = task.brief;
+        if ((brief.intent !== "answer" && brief.intent !== "investigate" && brief.intent !== "change") ||
+            typeof brief.goal !== "string" || brief.goal.length === 0 || brief.goal.length > MAX_TASK_BRIEF_GOAL_CHARS ||
+            !validBriefList(brief.constraints) ||
+            !validBriefList(brief.acceptance) ||
+            !validBriefList(brief.steps) ||
+            !validTimestamp(brief.createdAt))
+            return false;
+    }
     if (task.steering === undefined)
         return true;
     if (!Array.isArray(task.steering) || task.steering.length > MAX_TASK_STEERING_ENTRIES)

package/dist/statusbar.js

@@ -13,10 +13,23 @@ const fmtTok = (n) => (n >= 1000 ? `${(n / 1000).toFixed(1)}k` : `${n}`);
 const truncate = (s, max) => (s.length <= max ? s : s.slice(0, Math.max(0, max - 1)) + "…");
 const rule = (n) => c.dim("─".repeat(Math.max(0, n)));
 export function contextWindow(model) {
-    const m = model.toLowerCase();
+    // Provider prefixes are common (`qwen/qwen3.7-plus`). Match the actual model id and prefer exact
+    // documented Coding Plan families over broad words such as "coder"/"max": those previously labeled
+    // qwen3-coder-next and qwen3-max as 1M, causing the context guard to overfeed their 262k windows.
+    const m = model.toLowerCase().split("/").at(-1) ?? model.toLowerCase();
     if (/haiku/.test(m))
         return 200_000;
-    if (/(opus|sonnet|fable)|claude-4|qwen3|glm-[45]|max-2026|coder|1m/.test(m))
+    if (/^qwen3\.[567]-plus(?:-|$)/.test(m) || /^qwen3-coder-plus(?:-|$)/.test(m))
+        return 1_000_000;
+    if (/^(?:qwen3-max-2026-01-23|qwen3-coder-next)(?:-|$)/.test(m) || /^kimi-k2\.5(?:-|$)/.test(m))
+        return 262_144;
+    if (/^glm-(?:5|4\.7)(?:-|$)/.test(m))
+        return 202_752;
+    if (/^minimax-m2\.5(?:-|$)/.test(m))
+        return 196_608;
+    if (/qwen3\.6[-:]27b/.test(m))
+        return 262_144;
+    if (/(opus|sonnet|fable)|claude-4|1m/.test(m))
         return 1_000_000;
     return 200_000;
 }

package/dist/tools/agent.js

@@ -31,6 +31,7 @@ registerTool({
         required: ["task"],
     },
     kind: "read", // parallel-safe: multiple agent() calls in a turn run concurrently
+    concurrencySafe: true,
     async run(input, ctx) {
         if (!ctx.spawn)
             return "Error: sub-agents are not available in this context.";

package/dist/tools/all.js

@@ -3,6 +3,7 @@
 // never empty when runAgent plans a turn — an unregistered tool is silently unplannable, which shows up
 // as "the model called write_file and nothing happened".
 import "./builtin.js"; // read_file / write_file / bash / job
+import "./runtime.js"; // tool_search / tool_result_read
 import "./edit.js"; // edit_file
 import "./search.js"; // grep / glob / ls
 import "./patch.js"; // apply_patch

package/dist/tools/ask_user.js

@@ -6,11 +6,11 @@
 // the TUI. In headless / non-TTY / `-p` / gateway runs there is no interactive user (ctx.ask is absent) — the
 // tool returns a clear "proceed with your best judgment" string instead of hanging. kind:"read" so it never
 // itself triggers the approval gate (the interaction IS the prompt).
-import { registerTool } from "./registry.js";
+import { getTool, registerTool } from "./registry.js";
 /** Returned when nobody can answer (headless / non-TTY / -p / gateway / sub-agent). Phrased so the model
  *  keeps going on its own judgment rather than re-asking or stalling. */
 export const NO_INTERACTIVE_USER = "(no interactive user available — proceed with your best judgment)";
-registerTool({
+const definition = {
     name: "ask_user",
     description: "Ask the user ONE structured question mid-turn and wait for their answer, then continue. " +
         "Use this ONLY when you are genuinely blocked on a decision that ONLY the user can make — an ambiguous " +
@@ -23,6 +23,7 @@ registerTool({
         "In a non-interactive run (no terminal) it returns a 'proceed with your best judgment' note instead of " +
         "blocking, so prefer making a reasonable call over asking when context already answers the question.",
     kind: "read", // the prompt itself is the interaction; never route it through the approval gate
+    classify: () => ({ effect: "interactive", concurrencySafe: false }),
     input_schema: {
         type: "object",
         properties: {
@@ -65,4 +66,8 @@ registerTool({
             return `${NO_INTERACTIVE_USER} (ask failed: ${e?.message ?? e})`;
         }
     },
-});
+};
+registerTool(definition);
+/** Exact registered identity used by the agent loop to grant the engine-owned prompt its pausable
+ * active-budget semantics. A plugin that later shadows the public name does not inherit that authority. */
+export const askUserTool = getTool(definition.name);

package/dist/tools/builtin.js

@@ -13,6 +13,7 @@ import { BinaryFileError, readVerifiedRegularFileSnapshot, resolveVerifiedModelP
 import { startJob, listJobs, tailJob, killJob } from "../exec/jobs.js";
 import { sensitiveFileError, sensitiveShellCommandReason } from "../security/sensitive-files.js";
 import { createToolOutputLineRedactor, redactToolSubprocessOutput } from "../security/subprocess-env.js";
+import { isReadOnlyCommand, splitCompound } from "../security/permissions.js";
 import { hostsInCommand, isNetworkGitOp, hostFromConnectError, isConnectFailure, markHostUnreachable, isHostUnreachable, unreachableHostsSnapshot, } from "./net-reachability.js";
 const MAX = 100_000;
 /** Package installs are network-bound and routinely exceed the ordinary foreground cap. */
@@ -123,6 +124,7 @@ registerTool({
         required: ["path"],
     },
     kind: "read",
+    concurrencySafe: true,
     async run(input, ctx) {
         const p = abs(input.path, ctx.cwd);
         const denied = sensitiveFileError(p, "read");
@@ -211,8 +213,21 @@ registerTool({
         required: ["command"],
     },
     kind: "exec",
+    classify(input) {
+        const command = typeof input?.command === "string" ? input.command : "";
+        const parts = command ? splitCompound(command) : null;
+        const readOnly = !Boolean(input?.background)
+            && !!parts?.length
+            && parts.every(isReadOnlyCommand);
+        return readOnly
+            ? { effect: "read", concurrencySafe: true }
+            : { effect: "exec", concurrencySafe: false };
+    },
     requiresProjectWorkspace: true,
     async run(input, ctx) {
+        if (input.background !== undefined && typeof input.background !== "boolean") {
+            return "Error: `background` must be a boolean (true or false), not a string or another truthy value.";
+        }
         const protectedReason = sensitiveShellCommandReason(String(input.command ?? ""), ctx.cwd);
         if (protectedReason) {
             return (`Blocked: shell command crosses Hara's protected secret boundary (${protectedReason}). ` +
@@ -307,7 +322,13 @@ registerTool({
         },
         required: ["action"],
     },
-    kind: "read", // manages only the agent's own background jobs; safe to run unconfirmed
+    kind: "exec", // conservative default; list/tail are downgraded per input, kill remains approval-gated
+    classify(input) {
+        const action = String(input?.action ?? "");
+        return action === "list" || action === "tail"
+            ? { effect: "read", concurrencySafe: true }
+            : { effect: "exec", concurrencySafe: false, destructive: action === "kill" };
+    },
     async run(input) {
         const action = String(input.action);
         if (action === "list") {