@loicngr/kobo 2.1.1 → 2.1.4

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to Kōbō are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/). Each release is an `## <version>`
 section — the in-app "What's new" dialog reads this file.
 
+## 2.1.4
+
+- chore(deps): update server client and pwa packages
+
+## 2.1.3
+
+- fix(subagents): reliable lifecycle tracking and a stop button
+
+## 2.1.2
+
+- fix: read-only returning reviews, resumed-turn stdin, feed and tag filter
+- chore: npm deps update
+
 ## 2.1.1
 
 - feat(dashboard): allow resetting the model reliability table

package/dist/server/routes/workspaces.js

@@ -4621,4 +4621,43 @@ app.post('/:id/interrupt', migrationGuard, async (c) => {
         return c.json({ error: message }, workspaceErrorStatus(err));
     }
 });
+// POST /api/workspaces/:id/subagents/stop - stop one running sub-agent (body
+// `{ id }`, its canonical card id) or all of them, without interrupting the turn
+app.post('/:id/subagents/stop', migrationGuard, async (c) => {
+    try {
+        const id = c.req.param('id');
+        const workspace = workspaceService.getWorkspace(id);
+        if (!workspace) {
+            return c.json({ error: `Workspace '${id}' not found` }, 404);
+        }
+        const rawBody = await c.req.text();
+        let body = {};
+        if (rawBody.trim().length > 0) {
+            let parsed;
+            try {
+                parsed = JSON.parse(rawBody);
+            }
+            catch {
+                return c.json({ error: 'Request body must be valid JSON' }, 400);
+            }
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                return c.json({ error: 'Request body must be a JSON object' }, 400);
+            }
+            body = parsed;
+        }
+        if (body.id !== undefined && (typeof body.id !== 'string' || body.id.trim().length === 0)) {
+            return c.json({ error: 'id must be a non-empty string when provided' }, 400);
+        }
+        const stopped = agentManager.stopSubagents(id, body.id);
+        return c.json({ stopped });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (err instanceof agentManager.StopSubagentsError) {
+            const status = err.code === 'subagent_not_running' ? 404 : 409;
+            return c.json({ error: message, code: err.code }, status);
+        }
+        return c.json({ error: message }, workspaceErrorStatus(err));
+    }
+});
 export default app;

package/dist/server/services/agent/engines/claude-code/engine.js

@@ -48,6 +48,11 @@ export const SUBAGENT_STALL_TIMEOUT_MS = 10 * 60_000;
  *  every permission request of it fail with "Stream closed", so wait this long
  *  for a parent message before draining a stream that did not continue. */
 export const BACKGROUND_CONTINUATION_GRACE_MS = 60_000;
+/** A `result` does not always end the stream: resuming a session killed
+ *  mid-turn first settles the interrupted turn with an empty result, then
+ *  runs the new prompt right away. Wait this long for a follow-up before
+ *  closing the input it still needs for permission requests. */
+export const RESULT_CONTINUATION_GRACE_MS = 3_000;
 const MAX_PENDING_USER_MESSAGES = 20;
 function toMcpServersMap(specs) {
     if (!specs || specs.length === 0)
@@ -119,9 +124,52 @@ export function createClaudeCodeEngine() {
         async start(options, onEvent) {
             const abortController = new AbortController();
             const mapperState = createMapperState();
-            // UI/tool ids can differ from the SDK task id. Key by the stable UI id
-            // so a terminal notification that omits task_id still clears the task.
-            const activeSubagentTaskIds = new Map();
+            // Active sub-agents keyed by their canonical id (SDK task id when known,
+            // else the tool call id), which is also the id passed to `q.stopTask`.
+            // One task can surface under both ids (relaunch, kill/restart), so
+            // running and terminal events must resolve to the same entry.
+            const activeSubagentTaskIds = new Set();
+            // tool call id -> SDK task id, learned from events carrying both.
+            const subagentTaskIdByToolCallId = new Map();
+            // Ambient tasks (SDK `ambient`, e.g. Monitor watchers) are not activity:
+            // they never enter `activeSubagentTaskIds`, so they never block
+            // turn:completed, keep the input open or arm the stall watchdog. They are
+            // tracked apart only so a user interrupt still stops them.
+            const ambientSubagentTaskIds = new Set();
+            // Canonical ids whose last lifecycle event was terminal: a late
+            // `progress` for them is ignored, only a `started` relaunch revives them.
+            const terminalSubagentTaskIds = new Set();
+            const trackSubagentProgress = (ev) => {
+                if (ev.taskId) {
+                    subagentTaskIdByToolCallId.set(ev.toolCallId, ev.taskId);
+                    // Merge an entry first tracked under its tool call id alone.
+                    if (ev.toolCallId !== ev.taskId) {
+                        activeSubagentTaskIds.delete(ev.toolCallId);
+                        ambientSubagentTaskIds.delete(ev.toolCallId);
+                        if (terminalSubagentTaskIds.delete(ev.toolCallId))
+                            terminalSubagentTaskIds.add(ev.taskId);
+                    }
+                }
+                const taskId = ev.taskId ?? subagentTaskIdByToolCallId.get(ev.toolCallId);
+                const key = taskId ?? ev.toolCallId;
+                if (ev.status !== 'running') {
+                    activeSubagentTaskIds.delete(key);
+                    ambientSubagentTaskIds.delete(key);
+                    terminalSubagentTaskIds.add(key);
+                    return;
+                }
+                if (ev.phase === 'progress' && terminalSubagentTaskIds.has(key))
+                    return;
+                terminalSubagentTaskIds.delete(key);
+                if (ev.ambient) {
+                    activeSubagentTaskIds.delete(key);
+                    ambientSubagentTaskIds.add(key);
+                }
+                else {
+                    ambientSubagentTaskIds.delete(key);
+                    activeSubagentTaskIds.add(key);
+                }
+            };
             // Foreground tool calls currently awaiting their tool_result. Cleared on
             // every `result` message: a turn cannot end with a tool still in flight.
             const pendingToolCallIds = new Set();
@@ -130,6 +178,16 @@ export function createClaudeCodeEngine() {
             const isInteractive = options.agentPermissionMode === 'interactive';
             const canUseTool = (toolName, input, ctx) => {
                 const toolCallId = typeof ctx.toolUseID === 'string' && ctx.toolUseID.length > 0 ? ctx.toolUseID : `tu_${nanoid()}`;
+                // Plan mode alone is not read-only here: the non-interactive allow below
+                // would approve ExitPlanMode and then every edit. Anything that needs a
+                // permission, a question included, is refused outright instead.
+                if (options.readOnly) {
+                    return Promise.resolve({
+                        behavior: 'deny',
+                        message: 'This is a read-only review session: do not modify anything or ask the user. Put the finding in your final report instead.',
+                        interrupt: false,
+                    });
+                }
                 // Non-interactive modes: the SDK has already applied its permissionMode
                 // rules before reaching us, so allow through unchanged. AskUserQuestion
                 // is the exception — it always defers to the user.
@@ -245,6 +303,17 @@ export function createClaudeCodeEngine() {
                 sdkOptions.pathToClaudeCodeExecutable = explicitBinary;
             const inputStream = new ClaudeInputStream(effectivePrompt);
             const q = query({ prompt: inputStream, options: sdkOptions });
+            // Best-effort SDK stop of one background task; failures are ignored.
+            const requestStopTask = (taskId) => {
+                try {
+                    void q.stopTask(taskId).catch(() => {
+                        /* best-effort */
+                    });
+                }
+                catch {
+                    /* best-effort */
+                }
+            };
             let resolveReady;
             let rejectReady;
             const ready = new Promise((resolve, reject) => {
@@ -411,9 +480,9 @@ export function createClaudeCodeEngine() {
                 clearTimeout(resultDrainTimer);
                 resultDrainTimer = undefined;
             };
-            // Drain for a stream whose last background subagent completed without
-            // a parent continuation. Any parent message cancels it: that
-            // continuation's own `result` then closes the input.
+            // Drain for a stream that may still continue: after a result, or after
+            // the last background subagent completed. Any new init or parent
+            // message cancels it, and that continuation's own `result` re-arms it.
             let continuationGraceTimer;
             const clearContinuationGrace = () => {
                 if (!continuationGraceTimer)
@@ -421,7 +490,7 @@ export function createClaudeCodeEngine() {
                 clearTimeout(continuationGraceTimer);
                 continuationGraceTimer = undefined;
             };
-            const armContinuationGrace = () => {
+            const armContinuationGrace = (delayMs) => {
                 clearContinuationGrace();
                 continuationGraceTimer = setTimeout(() => {
                     continuationGraceTimer = undefined;
@@ -430,9 +499,12 @@ export function createClaudeCodeEngine() {
                         pendingToolCallIds.size > 0 ||
                         inputStream.hasUnansweredInput(completedResponses))
                         return;
+                    // Settled only now: a result the CLI follows up on (e.g. a resumed
+                    // turn's empty result) must not hide the busy banner meanwhile.
+                    emitTurnCompletedIfSettled();
                     inputStream.close();
                     armResultDrainWatchdog();
-                }, BACKGROUND_CONTINUATION_GRACE_MS);
+                }, delayMs);
                 continuationGraceTimer.unref?.();
             };
             // Safety net for the "waiting on a background subagent" branch below:
@@ -478,6 +550,10 @@ export function createClaudeCodeEngine() {
                             waitingForBackground = false;
                             clearContinuationGrace();
                         }
+                        else if (msg.type === 'system' && msg.subtype === 'init') {
+                            // A new run starts on this stream (e.g. after a resumed turn's empty result).
+                            clearContinuationGrace();
+                        }
                         // This SDK message proves that any drain condition armed by a
                         // *previous* message is no longer current. A drain armed while
                         // processing this message remains active if the generator then
@@ -485,15 +561,14 @@ export function createClaudeCodeEngine() {
                         clearResultDrainWatchdog();
                         const events = mapSdkMessage(msg, mapperState);
                         for (const ev of events) {
-                            if (ev.kind !== 'subagent:progress')
-                                continue;
-                            if (ev.status === 'running')
-                                activeSubagentTaskIds.set(ev.toolCallId, ev.taskId ?? ev.toolCallId);
-                            else
-                                activeSubagentTaskIds.delete(ev.toolCallId);
+                            if (ev.kind === 'subagent:progress')
+                                trackSubagentProgress(ev);
                         }
                         if (activeSubagentTaskIds.size > 0 &&
-                            (events.some((ev) => ev.kind === 'subagent:progress' ||
+                            (events.some((ev) => 
+                            // An ambient watcher's progress is not proof that a real
+                            // sub-agent advanced: it must not reset the stall bound.
+                            (ev.kind === 'subagent:progress' && !ev.ambient) ||
                                 ev.kind === 'message:text' ||
                                 ev.kind === 'message:thinking' ||
                                 ev.kind === 'tool:call' ||
@@ -539,7 +614,7 @@ export function createClaudeCodeEngine() {
                             activeSubagentTaskIds.size === 0 &&
                             !inputStream.hasUnansweredInput(completedResponses)) {
                             clearSubagentStallWatchdog();
-                            armContinuationGrace();
+                            armContinuationGrace(BACKGROUND_CONTINUATION_GRACE_MS);
                         }
                         for (const ev of events) {
                             if (ev.kind === 'session:started')
@@ -561,13 +636,11 @@ export function createClaudeCodeEngine() {
                             clearContinuationGrace();
                             pendingToolCallIds.clear();
                             completedResponses++;
-                            emitTurnCompletedIfSettled();
                             // A queued forced message starts the next response on this same SDK stream.
                             if (!inputStream.hasUnansweredInput(completedResponses)) {
                                 if (activeSubagentTaskIds.size === 0) {
                                     clearSubagentStallWatchdog();
-                                    inputStream.close();
-                                    armResultDrainWatchdog();
+                                    armContinuationGrace(RESULT_CONTINUATION_GRACE_MS);
                                 }
                                 else {
                                     waitingForBackground = true;
@@ -669,6 +742,28 @@ export function createClaudeCodeEngine() {
                     armSubagentStallWatchdog();
                     return true;
                 },
+                stopSubagents(ids) {
+                    const isRunning = (taskId) => activeSubagentTaskIds.has(taskId) || ambientSubagentTaskIds.has(taskId);
+                    const targets = new Set();
+                    if (ids === undefined) {
+                        for (const taskId of [...activeSubagentTaskIds, ...ambientSubagentTaskIds])
+                            targets.add(taskId);
+                    }
+                    else {
+                        for (const id of ids) {
+                            // A card id is the SDK task id, or the tool call id when the
+                            // task id was not known yet: resolve both to the tracked entry.
+                            const taskId = isRunning(id) ? id : subagentTaskIdByToolCallId.get(id);
+                            if (taskId && isRunning(taskId))
+                                targets.add(taskId);
+                        }
+                    }
+                    // The main turn keeps running: only the targeted tasks are stopped.
+                    // Their terminal notification clears the tracking as usual.
+                    for (const taskId of targets)
+                        requestStopTask(taskId);
+                    return targets.size;
+                },
                 interrupt() {
                     userInterrupted = true;
                     // The SDK ends an interrupted run by emitting a `result` with
@@ -679,16 +774,8 @@ export function createClaudeCodeEngine() {
                     // background subagent task keeps running unless told to stop via
                     // its own API, which would otherwise leave the Stop button
                     // appearing to do nothing for up to SUBAGENT_STALL_TIMEOUT_MS.
-                    for (const taskId of activeSubagentTaskIds.values()) {
-                        try {
-                            void q.stopTask(taskId).catch(() => {
-                                /* best-effort */
-                            });
-                        }
-                        catch {
-                            /* best-effort */
-                        }
-                    }
+                    for (const taskId of [...activeSubagentTaskIds, ...ambientSubagentTaskIds])
+                        requestStopTask(taskId);
                     const qq = q;
                     if (typeof qq.interrupt === 'function') {
                         try {

package/dist/server/services/agent/engines/claude-code/event-mapper.js

@@ -77,6 +77,21 @@ export const QUOTA_PATTERN = /\b429\b|out of extra usage|rate[_ ]limit|usage lim
  * of a previous attempt, a sub-agent failure, or application HTTP handling.
  */
 const ASSISTANT_QUOTA_NOTICE = /^(?:you(?:'|’)re out of extra usage|you(?:'|’)ve hit your (?:session|weekly|usage) limit|claude ai usage limit reached|usage limit reached|quota exceeded|rate limit exceeded)(?:[.!]?(?:[ \t]*[·—-]?[ \t]*resets?\b[^\r\n]*)?)?[.!]?$/i;
+/** SDKTaskNotificationMessage.status -> subagent:progress terminal status. */
+const TASK_NOTIFICATION_STATUS = {
+    completed: 'done',
+    failed: 'failed',
+    stopped: 'stopped',
+};
+/**
+ * SDKTaskUpdatedMessage.patch.status values that end a task. `pending`,
+ * `running` and `paused` are not lifecycle edges and are ignored.
+ */
+const TASK_UPDATED_TERMINAL_STATUS = {
+    completed: 'done',
+    failed: 'failed',
+    killed: 'stopped',
+};
 export function createMapperState() {
     return {
         sessionStartedEmitted: false,
@@ -84,6 +99,8 @@ export function createMapperState() {
         sawErrorResult: false,
         quotaErrorEmitted: false,
         userInterrupted: false,
+        taskToolUseIds: new Map(),
+        taskFlags: new Map(),
     };
 }
 /** Known SDK `result` subtypes that indicate the run failed. */
@@ -191,30 +208,79 @@ export function mapSdkMessage(msg, state) {
             events.push({ kind: 'session:compacting', active: sdkStatus === 'compacting' });
             return events;
         }
-        if (subtype === 'task_started' || subtype === 'task_progress' || subtype === 'task_notification') {
+        if (subtype === 'task_started' ||
+            subtype === 'task_progress' ||
+            subtype === 'task_notification' ||
+            subtype === 'task_updated') {
             const taskId = typeof parsed.task_id === 'string' ? parsed.task_id : undefined;
-            const toolCallId = typeof parsed.tool_use_id === 'string' ? parsed.tool_use_id : taskId;
-            if (toolCallId) {
-                const usage = parsed.usage;
-                // Unlike task_started/task_progress (in-flight signals), task_notification
-                // is only ever emitted once a task settles — its `status` value is a
-                // reason, not a liveness signal. Treat every task_notification as
-                // terminal instead of matching against a status whitelist, so an SDK
-                // status value added later doesn't leave the subagent stuck 'running'.
-                const isDone = subtype === 'task_notification';
-                events.push({
-                    kind: 'subagent:progress',
-                    toolCallId,
-                    ...(taskId ? { taskId } : {}),
-                    status: isDone ? 'done' : 'running',
-                    description: typeof parsed.description === 'string' ? parsed.description : undefined,
-                    taskType: typeof parsed.task_type === 'string' ? parsed.task_type : undefined,
-                    lastToolName: typeof parsed.last_tool_name === 'string' ? parsed.last_tool_name : undefined,
-                    totalTokens: typeof usage?.total_tokens === 'number' ? usage.total_tokens : undefined,
-                    toolUses: typeof usage?.tool_uses === 'number' ? usage.tool_uses : undefined,
-                    durationMs: typeof usage?.duration_ms === 'number' ? usage.duration_ms : undefined,
-                });
+            const toolUseId = typeof parsed.tool_use_id === 'string' ? parsed.tool_use_id : undefined;
+            if (taskId && toolUseId)
+                state.taskToolUseIds.set(taskId, toolUseId);
+            const toolCallId = toolUseId ?? (taskId ? (state.taskToolUseIds.get(taskId) ?? taskId) : undefined);
+            if (!toolCallId)
+                return events;
+            let status;
+            let phase;
+            if (subtype === 'task_updated') {
+                // Only a terminal patch status is a lifecycle signal; other patches
+                // (pending/running/paused, description, is_backgrounded...) are ignored.
+                const patch = parsed.patch;
+                const patchStatus = TASK_UPDATED_TERMINAL_STATUS[String(patch?.status)];
+                if (!patchStatus)
+                    return events;
+                status = patchStatus;
+            }
+            else if (subtype === 'task_notification') {
+                // task_notification is only ever emitted once a task settles: an
+                // unknown status value is still terminal (`done`), so a future SDK
+                // value never leaves the sub-agent stuck 'running'.
+                status = TASK_NOTIFICATION_STATUS[String(parsed.status)] ?? 'done';
+            }
+            else {
+                status = 'running';
+                phase = subtype === 'task_started' ? 'started' : 'progress';
+            }
+            if (taskId) {
+                const hasAmbient = typeof parsed.ambient === 'boolean';
+                const hasSkip = typeof parsed.skip_transcript === 'boolean';
+                if (subtype === 'task_started') {
+                    // A (re)launch defines the task's classification afresh.
+                    state.taskFlags.set(taskId, {
+                        ...(hasAmbient ? { ambient: parsed.ambient } : {}),
+                        ...(hasSkip ? { skipTranscript: parsed.skip_transcript } : {}),
+                    });
+                }
+                else if (hasAmbient || hasSkip) {
+                    state.taskFlags.set(taskId, {
+                        ...state.taskFlags.get(taskId),
+                        ...(hasAmbient ? { ambient: parsed.ambient } : {}),
+                        ...(hasSkip ? { skipTranscript: parsed.skip_transcript } : {}),
+                    });
+                }
             }
+            const flags = taskId ? state.taskFlags.get(taskId) : undefined;
+            const usage = parsed.usage;
+            const description = typeof parsed.description === 'string'
+                ? parsed.description
+                : subtype === 'task_updated' &&
+                    typeof parsed.patch?.description === 'string'
+                    ? parsed.patch.description
+                    : undefined;
+            events.push({
+                kind: 'subagent:progress',
+                toolCallId,
+                ...(taskId ? { taskId } : {}),
+                status,
+                ...(phase ? { phase } : {}),
+                ...(flags?.ambient ? { ambient: true } : {}),
+                ...(flags?.skipTranscript ? { skipTranscript: true } : {}),
+                description,
+                taskType: typeof parsed.task_type === 'string' ? parsed.task_type : undefined,
+                lastToolName: typeof parsed.last_tool_name === 'string' ? parsed.last_tool_name : undefined,
+                totalTokens: typeof usage?.total_tokens === 'number' ? usage.total_tokens : undefined,
+                toolUses: typeof usage?.tool_uses === 'number' ? usage.tool_uses : undefined,
+                durationMs: typeof usage?.duration_ms === 'number' ? usage.duration_ms : undefined,
+            });
             return events;
         }
         if (subtype === 'init') {

package/dist/server/services/agent/engines/claude-code/options-builder.js

@@ -14,6 +14,7 @@ const KOBO_MCP_BRIEF = [
     '• `kobo__set_workspace_status` when the mission is done or irrecoverably blocked. Never set `idle` while this session is active; use AskUserQuestion for clarification, or end the turn.',
     '• `kobo__schedule_wakeup` / `kobo__cancel_wakeup` to schedule (or cancel) a follow-up session — prefer these over the built-in `ScheduleWakeup` tool.',
     'Each tool carries its own "WHEN to use" guidance in its description — follow it.',
+    'Only one agent edits the worktree at a time: do not run background subagents that modify files while you or another subagent modify files too. Parallel read-only subagents (search, analysis, review) are fine. Wait for a file-editing subagent to finish before editing or running tests yourself, and remember that changes appearing in the worktree may come from your own subagents.',
 ].join('\n');
 /**
  * Appended to the Claude Code preset system prompt so the rule is always in

package/dist/server/services/agent/engines/codex/engine.js

@@ -77,6 +77,7 @@ export function createCodexEngine() {
                 model: options.model,
                 effort: options.effort,
                 agentPermissionMode: options.agentPermissionMode ?? 'bypass',
+                readOnly: options.readOnly,
                 resumeFromEngineSessionId: options.resumeFromEngineSessionId,
                 workingDir: options.workingDir,
                 mcpServers: options.mcpServers,
@@ -339,13 +340,35 @@ export function createCodexEngine() {
                         if (n.item.type === 'fileChange')
                             fileChanges.set(itemKey(n.threadId, n.turnId, n.item.id), n.item);
                         const events = mapTurnEvents(n, (state) => handleItemCompleted(n.item, state));
+                        const collabItem = n.item.type === 'collabAgentToolCall' ? n.item : undefined;
+                        const isActiveAgent = (status) => status === 'pendingInit' || status === 'running';
+                        const progressIndex = events.findIndex((event) => event.kind === 'subagent:progress');
+                        if (collabItem && progressIndex >= 0) {
+                            // The card that first tracked a thread (normally its spawnAgent)
+                            // owns it until it finishes. A later wait/sendInput/resumeAgent
+                            // on an already-owned thread (e.g. a wait that timed out) must
+                            // not steal it, or the owner card is orphaned in `running`; such
+                            // a card is done as soon as its own call completes.
+                            const progress = events[progressIndex];
+                            const ownsActiveThread = Object.entries(collabItem.agentsStates).some(([threadId, agentState]) => {
+                                if (!isActiveAgent(agentState.status))
+                                    return false;
+                                const owner = activeSubagentThreads.get(threadId);
+                                return !owner || owner.toolCallId === progress.toolCallId;
+                            });
+                            if (progress.status === 'running' && !ownsActiveThread) {
+                                events[progressIndex] = { ...progress, status: 'done' };
+                            }
+                        }
                         for (const ev of events)
                             safeEmit(ev);
-                        if (n.item.type === 'collabAgentToolCall') {
-                            const progress = events.find((event) => event.kind === 'subagent:progress');
-                            for (const [threadId, agentState] of Object.entries(n.item.agentsStates)) {
-                                if (agentState.status === 'pendingInit' || agentState.status === 'running') {
-                                    if (progress) {
+                        if (collabItem) {
+                            const progress = progressIndex >= 0
+                                ? events[progressIndex]
+                                : undefined;
+                            for (const [threadId, agentState] of Object.entries(collabItem.agentsStates)) {
+                                if (isActiveAgent(agentState.status)) {
+                                    if (progress && !activeSubagentThreads.has(threadId)) {
                                         activeSubagentThreads.set(threadId, {
                                             toolCallId: progress.toolCallId,
                                             description: progress.description,

package/dist/server/services/agent/engines/codex/options-builder.js

@@ -11,6 +11,7 @@ const CODEX_KOBO_MCP_BRIEF = [
     '• `mcp__kobo-tasks__set_workspace_status` when the mission is done or irrecoverably blocked. Never set `idle` while this session is active; ask the user or end the turn instead.',
     '• `mcp__kobo-tasks__schedule_wakeup` / `mcp__kobo-tasks__cancel_wakeup` to schedule (or cancel) a follow-up session.',
     'Each tool carries its own "WHEN to use" guidance in its description — follow it.',
+    'Only one agent edits the worktree at a time: do not run background subagents that modify files while you or another subagent modify files too. Parallel read-only subagents (search, analysis, review) are fine. Wait for a file-editing subagent to finish before editing or running tests yourself, and remember that changes appearing in the worktree may come from your own subagents.',
 ].join('\n');
 export function buildCodexOptions(input) {
     const isResume = input.resumeFromEngineSessionId !== undefined;
@@ -38,6 +39,10 @@ export function buildCodexOptions(input) {
             threadParams.approvalPolicy = 'unless-trusted';
             break;
     }
+    if (input.readOnly) {
+        threadParams.sandbox = 'read-only';
+        threadParams.approvalPolicy = 'never';
+    }
     // Model: omit when undefined or 'auto', let Codex use its default
     if (input.model && input.model !== 'auto') {
         threadParams.model = input.model;
@@ -70,7 +75,8 @@ export function buildCodexOptions(input) {
     // model/effort because collaborationMode takes precedence over them. Automatic
     // model selection is filled from thread/start or thread/resume by the engine.
     const collaborationMode = {
-        mode: input.agentPermissionMode === 'plan' ? 'plan' : 'default',
+        // A read-only review must not stop on a plan-mode question (see readOnly).
+        mode: input.agentPermissionMode === 'plan' && !input.readOnly ? 'plan' : 'default',
         settings: {
             ...(threadParams.model ? { model: threadParams.model } : {}),
             reasoning_effort: threadParams.modelReasoningEffort ?? null,

package/dist/server/services/agent/orchestrator.js

@@ -34,6 +34,14 @@ export class InterruptAgentError extends Error {
         this.name = 'InterruptAgentError';
     }
 }
+export class StopSubagentsError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'StopSubagentsError';
+    }
+}
 // ── State ──────────────────────────────────────────────────────────────────────
 /** Actual bound port of the running backend — set at startup via setBackendPort() */
 let backendPort = process.env.PORT ? Number.parseInt(process.env.PORT, 10) : 3000;
@@ -1373,6 +1381,9 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
     activateSession(workspaceId, agentSessionId);
     captureTaskProgressBaseline(workspaceId, agentSessionId);
     const settings = ws ? readEffectiveSettingsSafe(ws.projectPath) : readEffectiveSettingsSafe(workingDir);
+    // A review whose report returns to the original session must end by itself:
+    // enforce read-only plan mode here, not only through its prompt.
+    const readOnly = getReviewReturn(workspaceId, agentSessionId) !== null;
     const unavailableIntegrations = [];
     const integrationServers = buildIntegrationMcpServers(getGlobalSettings(), (name) => unavailableIntegrations.push(name));
     const options = {
@@ -1382,7 +1393,8 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
         model,
         effort: reasoningEffort,
         // Cascade: explicit caller override → workspace setting → 'bypass'.
-        agentPermissionMode: agentPermissionMode ?? ws?.agentPermissionMode ?? 'bypass',
+        agentPermissionMode: readOnly ? 'plan' : (agentPermissionMode ?? ws?.agentPermissionMode ?? 'bypass'),
+        readOnly,
         resumeFromEngineSessionId,
         backendUrl: `http://127.0.0.1:${backendPort}`,
         koboHome: (() => {
@@ -1490,6 +1502,33 @@ export function interruptAgent(workspaceId, options = {}) {
         autoLoopService.disable(workspaceId, 'user-action');
     }
 }
+/**
+ * Stop one running sub-agent (by its canonical id: task id or tool call id)
+ * or, without id, every running sub-agent. The main turn keeps running.
+ * Returns the number of sub-agents a stop was requested for.
+ */
+export function stopSubagents(workspaceId, id) {
+    const ctrl = controllers.get(workspaceId);
+    if (!ctrl) {
+        throw new StopSubagentsError(`No agent running for workspace '${workspaceId}'`, 'no_agent_running');
+    }
+    let stopped;
+    try {
+        stopped = ctrl.stopSubagents(id === undefined ? undefined : [id]);
+    }
+    catch (err) {
+        // A controller whose engine has not started yet has nothing to stop.
+        const message = err instanceof Error ? err.message : String(err);
+        throw new StopSubagentsError(`No agent running for workspace '${workspaceId}': ${message}`, 'no_agent_running');
+    }
+    if (stopped === undefined) {
+        throw new StopSubagentsError(`The agent engine of workspace '${workspaceId}' cannot stop a single sub-agent`, 'unsupported');
+    }
+    if (id !== undefined && stopped === 0) {
+        throw new StopSubagentsError(`Sub-agent '${id}' is not running for workspace '${workspaceId}'`, 'subagent_not_running');
+    }
+    return stopped;
+}
 /** Bound the caller's wait, retaining ownership until actual engine shutdown. */
 export const STOP_AGENT_TIMEOUT_MS = 15_000;
 async function stopController(workspaceId, ctrl, cause = 'user') {

package/dist/server/services/agent/session-controller.js

@@ -121,6 +121,18 @@ export class SessionController {
             throw new Error('SessionController not started');
         this._engineProcess.interrupt();
     }
+    /**
+     * Stop running sub-agents without interrupting the main turn. Returns the
+     * number of sub-agents a stop was requested for, or `undefined` when the
+     * engine cannot stop a single sub-agent.
+     */
+    stopSubagents(ids) {
+        if (!this._engineProcess)
+            throw new Error('SessionController not started');
+        if (typeof this._engineProcess.stopSubagents !== 'function')
+            return undefined;
+        return this._engineProcess.stopSubagents(ids);
+    }
     stop() {
         if (!this._stopPromise) {
             this._stopPromise = this.stopEngine().catch((err) => {

package/dist/server/services/review-service.js

@@ -44,7 +44,8 @@ function resolveConfiguration(workspace, body) {
         engine: engineId,
         model: body.model ?? (changedEngine ? 'auto' : workspace.model),
         reasoningEffort: body.reasoningEffort ?? (changedEngine ? 'auto' : workspace.reasoningEffort),
-        agentPermissionMode: body.agentPermissionMode ?? workspace.agentPermissionMode,
+        // A review that hands its report back must end by itself: always read-only.
+        agentPermissionMode: body.returnToSession ? 'plan' : (body.agentPermissionMode ?? workspace.agentPermissionMode),
     };
     // Preserve an existing custom model when unchanged; reject incompatible selections.
     if ((changedEngine || config.model !== workspace.model) &&
@@ -115,9 +116,12 @@ export async function startWorkspaceReview(id, input) {
             baseCommit,
             additionalInstructions: (body.additionalInstructions ?? '').trim(),
         });
+        // The return fires only when the review session ends by itself: a reviewer
+        // that starts fixing, or waits on a question, never hands back.
         if (body.returnToSession)
             rendered +=
-                '\n\nFinish with a standalone summary of your review findings, including severity, file/line references, recommended fixes and any remaining uncertainty. This final message will be handed back to the original agent session. Do not rely on earlier messages to explain your findings.';
+                '\n\nThis is a read-only review session; these rules override any template instruction or skill that suggests fixing issues. Do not modify, create or delete files, and do not commit or push: the original agent session applies the fixes. Running read-only checks such as tests or linters is fine. Do not ask the user questions or wait for input: note any decision that needs the user in your summary instead.' +
+                    '\n\nFinish with a standalone summary of your review findings, including severity, file/line references, recommended fixes and any remaining uncertainty. This final message will be handed back to the original agent session. Do not rely on earlier messages to explain your findings.';
         assertWorkspaceLifecycleAvailable(id);
         const current = workspaceService.getWorkspace(id);
         if (!current || current.archivedAt || current.worktreePurgedAt || current.status === 'compacting')