@loicngr/kobo 1.6.15 → 1.7.1

package/README.md

@@ -11,8 +11,9 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 
 ## Features
 
-- **Isolated git worktrees** — every workspace runs on its own branch in its own directory, so concurrent Claude sessions never step on each other
-- **Pluggable agent engine** — Kōbō talks to agents through an `AgentEngine` contract with a normalised `AgentEvent` stream (`src/server/services/agent/engines/`). Claude Code is the first engine; dropping in another runtime (e.g. the Claude Agent SDK) only requires a new adapter, not a rewrite of the UI or orchestration layer. Migration to the official Claude Agent SDK is tracked in [#9](https://github.com/loicngr/Kobo/issues/9)
+- **Isolated git worktrees** — every workspace runs on its own branch in its own directory, with a configurable global worktrees root for new workspaces, so concurrent Claude sessions never step on each other
+- **Pluggable agent engine** — Kōbō talks to agents through an `AgentEngine` contract with a normalised `AgentEvent` stream (`src/server/services/agent/engines/`). The `claude-code` engine runs on the official [`@anthropic-ai/claude-agent-sdk`](https://github.com/anthropics/claude-agent-sdk-typescript); adding a second runtime (e.g. Codex) only requires a new adapter, not a rewrite of the UI or orchestration layer
+- **Interactive `AskUserQuestion`** — when the agent invokes `AskUserQuestion`, Kōbō pauses the session via the SDK's `defer` pattern, surfaces a question panel in the UI, and resumes the agent once the user answers. The session does not occupy any resources while it waits
 - **Rich chat feed** — live streaming text, thinking blocks, inline tool calls with expandable diffs for Edit/Write, per-turn session cards, markdown rendering, jump-to-previous-user-message button, and infinite scroll-up over persisted history
 - **Task & acceptance criteria tracking** — the agent reports progress through a dedicated MCP server (`kobo-tasks`) that reads and updates tasks directly from the SQLite database
 - **Documents panel** — tree view in the right drawer that surfaces every AI-generated markdown file under `docs/plans/`, `docs/superpowers/`, and `.ai/thoughts/`. Paths mentioned in chat messages are auto-detected against the catalogue and become one-click deep-links into the panel
@@ -31,7 +32,7 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 - **Soft interrupt** — pause an agent mid-execution (SIGINT, like pressing Escape in Claude Code) without killing the process; the agent stops the current tool and waits for the next message
 - **Archive instead of delete** — soft-remove workspaces without losing the worktree, branches, or history; unarchive restores the exact pre-archive state
 - **Auto-loop mode** — opt-in, per-workspace: when enabled, Kōbō spawns a fresh Claude session for the next pending task after every `session:ended`, walking through the task list until all are `done`. Stops automatically on error, on stall (3 consecutive sessions with no task completed), or when the user clicks Stop. A grooming step (`/kobo-prep-autoloop`) ensures tasks are atomic before the loop runs; Notion-imported workspaces with both todos and acceptance criteria are auto-unlocked. **E2E grooming** — when a project declares an E2E framework in Settings (Cypress, Playwright, Vitest, etc.), the grooming phase injects an `[E2E] ` test sub-task between every parent task; each iteration then runs the matching E2E suite as part of its acceptance check
-- **Attach existing worktrees** — Kōbō detects orphan worktrees under `.worktrees/` (created outside Kōbō, or left over from an earlier install) and lets you attach them to a new workspace from the creation form, picking up the existing branch and folder instead of cloning a new one
+- **Attach existing worktrees** — Kōbō detects orphan git worktrees for the selected project (created outside Kōbō, or left over from an earlier install) and lets you attach them to a new workspace from the creation form, picking up the existing branch and folder instead of cloning a new one
 - **Quota-aware retry backoff** — when a Claude rate limit is hit mid-session, Kōbō schedules the retry at the actual reset time reported by the API (via `rate_limit.info.buckets[].resetsAt`), falling back to a 15 → 30 → 60 → 180 → 300 min ladder only when the reset info is missing or implausible
 - **Scheduled wakeups** — the `ScheduleWakeup` tool is honoured server-side: Kōbō persists the wakeup in SQLite, rehydrates on restart, and respawns the agent with `--resume` at the target time
 
@@ -47,7 +48,7 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 ### Prerequisites
 
 - Node.js ≥ 20
-- [Claude Code CLI](https://claude.com/claude-code) installed and authenticated (`claude` on your `PATH`)
+- [Claude Code](https://claude.com/claude-code) authenticated via `claude /login` once. The `claude` CLI is **no longer required at runtime** — Kōbō embeds the official [`@anthropic-ai/claude-agent-sdk`](https://github.com/anthropics/claude-agent-sdk-typescript), which reuses the same login.
 - Git
 - Optional: Docker (if you configure per-workspace dev servers)
 - Optional: `gh` CLI (if you use the PR automation)
@@ -62,7 +63,7 @@ SERVER_PORT=9998 PORT=9999 npx @loicngr/kobo@latest
 
 That's it. npm downloads the package, installs dependencies, starts the Kōbō server on the port you specified, and serves the web UI at `http://localhost:9999`. Data is persisted to `~/.config/kobo/` (overridable via `KOBO_HOME`).
 
-On first launch Kōbō creates `~/.config/kobo/` if it doesn't exist. If the `claude` CLI is missing from your `PATH` you will see a warning in the terminal — install Claude Code before creating your first workspace.
+On first launch Kōbō creates `~/.config/kobo/` if it doesn't exist. If you have not yet logged in to Claude Code (`claude /login`), the SDK will prompt for an `ANTHROPIC_API_KEY` instead — log in once to share the same authentication across Claude Code, the embedded SDK, and the quota poller.
 
 ### Run from source (contributors)
 
@@ -251,7 +252,7 @@ See [`AGENTS.md`](./AGENTS.md) for a deeper dive into conventions, data model, W
 
 | Table | Purpose |
 |---|---|
-| `workspaces` | the unit of work — branch, status, model, engine, `archived_at`, `favorited_at`, `tags`, Notion link, … |
+| `workspaces` | the unit of work — branch, `worktree_path`, status, model, engine, `archived_at`, `favorited_at`, `tags`, Notion link, … |
 | `tasks` | workspace sub-items — tasks and acceptance criteria |
 | `agent_sessions` | agent runs — pid, `engine_session_id`, lifecycle |
 | `ws_events` | persisted WebSocket events (chat history, `agent:event` stream, user messages) for replay on reconnect |
@@ -268,9 +269,10 @@ The MCP server reads and writes the same SQLite database as the main backend. Is
 
 ## Configuration
 
-Kōbō reads settings from `~/.config/kobo/settings.json` (or falls back to defaults). Global settings cascade into per-project overrides:
+Kōbō reads settings from `~/.config/kobo/settings.json` (or falls back to defaults). Global settings define defaults, with per-project overrides for project-scoped fields:
 
 - `defaultModel` — Claude model to use (e.g. `claude-opus-4-6`)
+- `worktreesPath` — where new workspace worktrees are created. Defaults to `.worktrees`, resolved relative to the project. Absolute Linux/macOS paths, Windows paths (`C:\kobo\worktrees`, UNC shares), `$HOME/...`, `${HOME}/...`, `~/...`, and `%USERPROFILE%\...` are accepted. Paths containing parent-directory traversal (`..`) or drive-relative Windows syntax (`C:foo`) are rejected.
 - `prPromptTemplate` — template rendered when opening a PR via the `/open-pr` endpoint; supports `{{pr_number}}`, `{{pr_url}}`, `{{branch_name}}`, `{{diff_stats}}`, `{{commits}}`, etc.
 - `gitConventions` — markdown-formatted git conventions written to `.ai/.git-conventions.md` in every workspace so the agent follows them when committing
 - `devServer` — per-project `startCommand` / `stopCommand` for launching workspace-scoped dev servers
@@ -287,6 +289,10 @@ This is a personal tool, but PRs and issues are welcome. Before submitting:
 
 CI runs lint + type check + tests on every PR to `develop`.
 
+## Release
+
+Releases are cut from `main`. Bump `package.json` and `package-lock.json` on `develop`, merge `develop` into `main`, then push `main`. The release workflow builds, tests, publishes the current package version to npm, tags it as `v<version>`, and creates the GitHub Release. If the npm version or tag already exists, the workflow fails before publishing.
+
 ## License
 
 GNU General Public License v3.0 or later. See [`LICENSE`](./LICENSE) for the full text.

package/dist/mcp-server/kobo-tasks-handlers.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { nanoid } from 'nanoid';
+import { resolveWorkspaceWorktreePath } from '../server/utils/worktree-paths.js';
 /** Allowed task status values. */
 export const VALID_TASK_STATUSES = ['pending', 'in_progress', 'done'];
 function rowToDto(row) {
@@ -163,7 +164,7 @@ export function getWorkspaceInfoHandler(db, workspaceId) {
         projectPath: row.project_path,
         sourceBranch: row.source_branch,
         workingBranch: row.working_branch,
-        worktreePath: row.worktree_path ?? path.join(row.project_path, '.worktrees', row.working_branch),
+        worktreePath: row.worktree_path ?? resolveWorkspaceWorktreePath(row.project_path, row.working_branch),
         status: row.status,
         model: row.model,
         notionUrl: row.notion_url,

package/dist/mcp-server/kobo-tasks-server.js

@@ -292,6 +292,33 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description: 'CALL when you need to self-regulate on long missions — returns token/cost totals for the workspace lifetime and for the currently running agent_session. Useful before spawning heavy subagents or deep reasoning on already-expensive sessions.',
             inputSchema: { type: 'object', properties: {}, required: [] },
         },
+        {
+            name: 'schedule_wakeup',
+            description: 'CALL to schedule a follow-up turn on THIS workspace after a delay. End the current turn normally; once it finishes and the workspace is idle, Kōbō waits `delaySeconds`, then resumes the same conversation by injecting `prompt` as the next user message. The wakeup is scoped to the current workspace and resumes its latest session — you cannot target another workspace or another session. If a turn is still active when the timer fires, the wakeup is skipped (status: `session-active`). Replaces any previously pending wakeup on this workspace. Delay is clamped to [60, 3600] seconds. Prefer this over the built-in `ScheduleWakeup` tool — it is the SDK-supported entry point.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    delaySeconds: {
+                        type: 'number',
+                        description: 'Seconds from now until the wakeup fires. Clamped to [60, 3600].',
+                    },
+                    prompt: {
+                        type: 'string',
+                        description: 'Prompt sent to the agent when the wakeup fires.',
+                    },
+                    reason: {
+                        type: 'string',
+                        description: 'Short label shown to the user explaining the wakeup (optional).',
+                    },
+                },
+                required: ['delaySeconds', 'prompt'],
+            },
+        },
+        {
+            name: 'cancel_wakeup',
+            description: 'CALL to cancel any pending wakeup on this workspace (e.g. the condition you were waiting on resolved early, or you decided not to continue). Idempotent — safe to call when nothing is pending.',
+            inputSchema: { type: 'object', properties: {}, required: [] },
+        },
     ],
 }));
 /** Wrap a successful result as an MCP tool response with JSON text content. */
@@ -441,6 +468,30 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (name === 'get_session_usage') {
             return ok(getSessionUsageHandler(db, workspaceId));
         }
+        if (name === 'schedule_wakeup') {
+            const delaySeconds = a.delaySeconds;
+            const prompt = a.prompt;
+            if (typeof delaySeconds !== 'number' || !Number.isFinite(delaySeconds) || delaySeconds <= 0) {
+                return fail('delaySeconds must be a positive number');
+            }
+            if (typeof prompt !== 'string' || prompt.trim().length === 0) {
+                return fail('prompt is required');
+            }
+            const reason = a.reason;
+            if (reason !== undefined && typeof reason !== 'string') {
+                return fail('reason must be a string when provided');
+            }
+            const result = await backendRequest('POST', `/api/workspaces/${workspaceId}/pending-wakeup`, {
+                delaySeconds,
+                prompt,
+                reason,
+            });
+            return ok(result);
+        }
+        if (name === 'cancel_wakeup') {
+            const result = await backendRequest('DELETE', `/api/workspaces/${workspaceId}/pending-wakeup`);
+            return ok(result);
+        }
         if (name === 'search_codebase') {
             const query = a.query;
             if (!query)

package/dist/server/db/migrations.js

@@ -154,6 +154,46 @@ export const migrations = [
         )`).run();
         },
     },
+    {
+        version: 17,
+        name: 'add-agent-permission-mode',
+        migrate: (db) => {
+            // Unifies the legacy `permission_mode` (auto-accept | plan) and
+            // `permission_profile` (bypass | strict | interactive) into a single
+            // SDK-aligned column with four values: plan | bypass | strict | interactive.
+            //
+            // Migration rule (preserves user-visible behaviour):
+            //   permission_mode='plan'                                  → 'plan'
+            //   permission_mode='auto-accept' + permission_profile=*    → permission_profile (default 'bypass')
+            //
+            // The two legacy columns are kept for backward compatibility — they are
+            // no longer the source of truth but stay readable so older code paths
+            // (or in-flight requests during deploy) don't crash.
+            db.transaction(() => {
+                db.prepare("ALTER TABLE workspaces ADD COLUMN agent_permission_mode TEXT NOT NULL DEFAULT 'bypass'").run();
+                // Plan mode is preserved verbatim.
+                db.prepare("UPDATE workspaces SET agent_permission_mode = 'plan' WHERE permission_mode = 'plan'").run();
+                // For 'auto-accept' rows, promote the profile (or fall back to bypass).
+                db.prepare(`UPDATE workspaces
+           SET agent_permission_mode = CASE
+             WHEN permission_profile IN ('bypass', 'strict', 'interactive') THEN permission_profile
+             ELSE 'bypass'
+           END
+           WHERE permission_mode != 'plan'`).run();
+            })();
+        },
+    },
+    {
+        version: 18,
+        name: 'add-pending-wakeup-agent-session-id',
+        migrate: (db) => {
+            // Pin a wakeup to the session that scheduled it, so the wakeup resumes
+            // that conversation instead of whichever session happens to be the
+            // latest at fire time. Nullable: pre-migration rows fall back to the
+            // legacy "last session" behaviour.
+            db.prepare('ALTER TABLE pending_wakeups ADD COLUMN agent_session_id TEXT').run();
+        },
+    },
 ];
 /** Current schema version — always equals the highest migration version. */
 export const SCHEMA_VERSION = migrations.length > 0 ? migrations[migrations.length - 1].version : 1;

package/dist/server/db/schema.js

@@ -26,6 +26,7 @@ export function initSchema(db) {
       auto_loop_ready INTEGER NOT NULL DEFAULT 0,
       no_progress_streak INTEGER NOT NULL DEFAULT 0,
       permission_profile TEXT NOT NULL DEFAULT 'bypass',
+      agent_permission_mode TEXT NOT NULL DEFAULT 'bypass',
       created_at TEXT NOT NULL,
       updated_at TEXT NOT NULL
     );
@@ -62,11 +63,12 @@ export function initSchema(db) {
     );
 
     CREATE TABLE IF NOT EXISTS pending_wakeups (
-      workspace_id TEXT PRIMARY KEY REFERENCES workspaces(id) ON DELETE CASCADE,
-      target_at    TEXT NOT NULL,
-      prompt       TEXT NOT NULL,
-      reason       TEXT,
-      created_at   TEXT NOT NULL
+      workspace_id     TEXT PRIMARY KEY REFERENCES workspaces(id) ON DELETE CASCADE,
+      target_at        TEXT NOT NULL,
+      prompt           TEXT NOT NULL,
+      reason           TEXT,
+      created_at       TEXT NOT NULL,
+      agent_session_id TEXT
     );
 
     CREATE TABLE IF NOT EXISTS usage_snapshots (

package/dist/server/index.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { serve } from '@hono/node-server';
@@ -34,14 +33,6 @@ import { emit, emitEphemeral, handleConnection, setMessageHandler } from './serv
 import { getActiveSession, getWorkspace, updateWorkspaceStatus } from './services/workspace-service.js';
 import { getClientSpaPath, getDbPath, getKoboHome, getPackageVersion } from './utils/paths.js';
 import { initProcessCleanup, killAll as killAllTrackedProcesses } from './utils/process-tracker.js';
-// Runtime prerequisite check — warn if the claude CLI is missing. Don't block
-// startup: the user may still want to configure settings or browse workspaces.
-{
-    const check = spawnSync('claude', ['--version'], { stdio: 'ignore' });
-    if (check.error && check.error.code === 'ENOENT') {
-        console.warn("[kobo] WARNING: 'claude' CLI not found on PATH. Kōbō will fail to spawn agents until Claude Code is installed. See https://claude.com/claude-code");
-    }
-}
 console.log(`[kobo] Kōbō home: ${getKoboHome()}`);
 // Initialize DB + run migrations
 const db = getDb();
@@ -250,6 +241,16 @@ setMessageHandler((type, payload) => {
             });
             return;
         }
+        // Reject chat input while paused on canUseTool — sending here would spawn
+        // a parallel session and orphan the pending callback.
+        const wsRow = getWorkspace(p.workspaceId);
+        if (wsRow?.status === 'awaiting-user') {
+            emitEphemeral(p.workspaceId, 'chat:rejected', {
+                reason: 'awaiting-user',
+                message: 'Answer via the question panel — typing in chat would orphan the pending callback',
+            });
+            return;
+        }
         // Prefer the session explicitly selected by the client (sessionId hint),
         // falling back to the running/most-recent non-idle session so idle sessions
         // never steal the tagging.
@@ -278,7 +279,7 @@ setMessageHandler((type, payload) => {
                     // Plan mode blocks MCP tools — when the caller knows the message
                     // requires them (e.g. grooming), it sets the override to bypass the
                     // workspace default for this spawn only.
-                    const effectiveMode = p.permissionModeOverride ?? workspace.permissionMode;
+                    const effectiveMode = p.agentPermissionModeOverride ?? workspace.agentPermissionMode;
                     startAgent(p.workspaceId, worktreePath, p.content, workspace.model, true, effectiveMode, p.sessionId, workspace.reasoningEffort);
                     updateWorkspaceStatus(p.workspaceId, 'executing');
                 }
@@ -297,7 +298,7 @@ setMessageHandler((type, payload) => {
             }
             const worktreePath = workspace.worktreePath;
             const prompt = p.prompt ?? 'Continue the previous task where you left off.';
-            startAgent(p.workspaceId, worktreePath, prompt, workspace.model, false, workspace.permissionMode, undefined, workspace.reasoningEffort);
+            startAgent(p.workspaceId, worktreePath, prompt, workspace.model, false, workspace.agentPermissionMode, undefined, workspace.reasoningEffort);
         }
         catch (err) {
             console.error('[ws] Failed to start agent:', err);

package/dist/server/routes/health.js

@@ -1,11 +1,11 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
-import path from 'node:path';
 import { Hono } from 'hono';
 import { getDb } from '../db/index.js';
 import { SCHEMA_VERSION } from '../db/migrations.js';
 import { getGlobalSettings, SETTINGS_SCHEMA_VERSION } from '../services/settings-service.js';
 import { getDbPath, getKoboHome } from '../utils/paths.js';
+import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
 const app = new Hono();
 function checkClaudeCli() {
     try {
@@ -51,7 +51,7 @@ app.get('/report', (c) => {
     for (const ws of workspaces) {
         if (ws.archived_at)
             continue;
-        const wtPath = ws.worktree_path ?? path.join(ws.project_path, '.worktrees', ws.working_branch);
+        const wtPath = ws.worktree_path ?? resolveWorkspaceWorktreePath(ws.project_path, ws.working_branch);
         if (!fs.existsSync(wtPath)) {
             worktreesMissing.push({ workspaceId: ws.id, name: ws.name, path: wtPath, exists: false });
         }

package/dist/server/routes/settings.js

@@ -45,7 +45,8 @@ app.put('/global', async (c) => {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return c.json({ error: message }, 500);
+        const status = err instanceof Error && err.name === 'InvalidWorktreesPathError' ? 400 : 500;
+        return c.json({ error: message }, status);
     }
 });
 // GET /api/settings/projects — list all projects

package/dist/server/routes/workspaces.js

@@ -23,10 +23,34 @@ import * as wsService from '../services/websocket-service.js';
 import * as workspaceService from '../services/workspace-service.js';
 import * as worktreeService from '../services/worktree-service.js';
 import * as gitOps from '../utils/git-ops.js';
+import { resolveSiblingWorkspaceWorktreePath } from '../utils/worktree-paths.js';
 /** Hono sub-router for workspace CRUD, tasks, agent lifecycle, git operations, and PR creation. */
 const app = new Hono();
 /** Tracks workspaces currently running a setup script to prevent concurrent executions. */
 const setupScriptRunning = new Set();
+const VALID_AGENT_PERMISSION_MODES = ['plan', 'bypass', 'strict', 'interactive'];
+function isAgentPermissionMode(value) {
+    return typeof value === 'string' && VALID_AGENT_PERMISSION_MODES.includes(value);
+}
+/**
+ * Resolve the unified permission mode for a new workspace.
+ *
+ * Cascade: explicit body field → global default (validated) → 'bypass'.
+ *
+ * Legacy `defaultPermissionMode` values ('plan' / 'auto-accept') are honored:
+ * 'plan' stays 'plan'; 'auto-accept' falls through to 'bypass' (the safest
+ * non-plan default — matches the pre-refactor "skip prompts" behaviour).
+ */
+function resolveCreateAgentPermissionMode(bodyValue, _projectPath, globalSettings) {
+    if (isAgentPermissionMode(bodyValue))
+        return bodyValue;
+    const global = globalSettings.defaultPermissionMode;
+    if (isAgentPermissionMode(global))
+        return global;
+    if (global === 'plan')
+        return 'plan';
+    return 'bypass';
+}
 app.get('/', (c) => {
     try {
         const workspaces = workspaceService.listWorkspaces();
@@ -172,8 +196,9 @@ app.post('/', migrationGuard, async (c) => {
             ...(useReusedWorktree ? { worktreePath: body.worktreePath, worktreeOwned: false } : {}),
             model: body.model,
             reasoningEffort: body.reasoningEffort,
-            permissionMode: body.permissionMode || globalSettings.defaultPermissionMode || 'plan',
+            agentPermissionMode: resolveCreateAgentPermissionMode(body.agentPermissionMode, body.projectPath, globalSettings),
             engine: body.engine,
+            ...(useReusedWorktree ? {} : { worktreesPath: globalSettings.worktreesPath }),
         });
         // Auto-tag the workspace based on its creation source — `notion` when
         // imported from a Notion page, `sentry` when bootstrapped from a Sentry
@@ -264,7 +289,7 @@ app.post('/', migrationGuard, async (c) => {
         }
         else {
             try {
-                worktreePath = worktreeService.createWorktree(body.projectPath, workingBranch, body.sourceBranch);
+                worktreePath = worktreeService.createWorktree(body.projectPath, workingBranch, body.sourceBranch, globalSettings.worktreesPath);
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -544,7 +569,7 @@ ${AUTO_LOOP_HARD_RULES}`;
                 brainstormPrompt += `\n\nThen brainstorm the implementation approach. Explore the codebase to understand the existing structure. Ask clarifying questions if needed. When you're done brainstorming and have a clear plan, create a plan file and proceed with implementation. Once you have completed the brainstorming phase, output [BRAINSTORM_COMPLETE] on its own line.`;
             }
             try {
-                const agent = agentManager.startAgent(workspace.id, worktreePath, brainstormPrompt, workspace.model, false, workspace.permissionMode, undefined, workspace.reasoningEffort);
+                const agent = agentManager.startAgent(workspace.id, worktreePath, brainstormPrompt, workspace.model, false, workspace.agentPermissionMode, undefined, workspace.reasoningEffort);
                 // Persist the initial prompt in the feed so it's visible in the chat,
                 // tagged with the freshly created session id so the strict session filter shows it.
                 wsService.emit(workspace.id, 'user:message', { content: brainstormPrompt, sender: 'system-prompt' }, agent.agentSessionId);
@@ -723,7 +748,8 @@ app.get('/:id/pending-wakeup', (c) => {
         return c.json({ error: message }, 500);
     }
 });
-// DELETE /api/workspaces/:id/pending-wakeup — user-initiated cancel ("×" button).
+// DELETE /api/workspaces/:id/pending-wakeup — user-initiated cancel ("×" button)
+// or agent-initiated cancel via the `kobo__cancel_wakeup` MCP tool.
 app.delete('/:id/pending-wakeup', (c) => {
     try {
         const id = c.req.param('id');
@@ -735,6 +761,41 @@ app.delete('/:id/pending-wakeup', (c) => {
         return c.json({ error: message }, 500);
     }
 });
+// POST /api/workspaces/:id/pending-wakeup — agent-initiated schedule via the
+// `kobo__schedule_wakeup` MCP tool. Replaces any existing pending wakeup.
+app.post('/:id/pending-wakeup', async (c) => {
+    try {
+        const id = c.req.param('id');
+        const body = (await c.req.json().catch(() => ({})));
+        const delaySeconds = body.delaySeconds;
+        const prompt = body.prompt;
+        const reason = body.reason;
+        if (typeof delaySeconds !== 'number' || !Number.isFinite(delaySeconds) || delaySeconds <= 0) {
+            return c.json({ error: 'delaySeconds must be a positive number' }, 400);
+        }
+        if (typeof prompt !== 'string' || prompt.trim().length === 0) {
+            return c.json({ error: 'prompt is required' }, 400);
+        }
+        if (reason !== undefined && typeof reason !== 'string') {
+            return c.json({ error: 'reason must be a string when provided' }, 400);
+        }
+        // Pin the wakeup to the session that scheduled it, so the resume targets
+        // that conversation instead of whichever session happens to be the latest
+        // at fire time. The MCP tool is invoked from inside an active session, so
+        // a missing controller signals misuse — reject explicitly.
+        const agentSessionId = agentManager.getActiveSessionId(id);
+        if (!agentSessionId) {
+            return c.json({ error: 'no active agent session for this workspace' }, 409);
+        }
+        wakeupService.schedule(id, delaySeconds, prompt, reason, agentSessionId);
+        const pending = wakeupService.getPending(id);
+        return c.json({ ok: true, pending });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
 // PATCH /api/workspaces/:id/sessions/:sessionId — rename a session
 app.patch('/:id/sessions/:sessionId', async (c) => {
     try {
@@ -759,6 +820,94 @@ app.patch('/:id/sessions/:sessionId', async (c) => {
         return c.json({ error: message }, 500);
     }
 });
+// POST /api/workspaces/:id/deferred-tool-use/answer — resume a deferred
+// AskUserQuestion call by feeding the user's answers back to the SDK.
+app.post('/:id/deferred-tool-use/answer', async (c) => {
+    try {
+        const id = c.req.param('id');
+        const body = await c.req
+            .json()
+            .catch(() => ({}));
+        if (!body?.answers || typeof body.answers !== 'object') {
+            return c.json({ error: 'answers payload required' }, 400);
+        }
+        await agentManager.answerPendingQuestion(id, body.answers, body.toolCallId);
+        return c.json({ ok: true });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'unknown';
+        // "No deferred tool use pending" is a benign race — the frontend
+        // self-heals on this string. Use 409 (Conflict) so dev tools don't
+        // surface it as a 400 validation failure.
+        const status = /no deferred tool use pending/i.test(message) ? 409 : 400;
+        return c.json({ error: message }, status);
+    }
+});
+// POST /api/workspaces/:id/deferred-tool-use/cancel — cancel a deferred
+// AskUserQuestion. The SDK callback resolves with deny + a message; the
+// agent sees an error tool_result and adapts. Does NOT abort the session.
+app.post('/:id/deferred-tool-use/cancel', async (c) => {
+    try {
+        const id = c.req.param('id');
+        const body = await c.req
+            .json()
+            .catch(() => ({}));
+        await agentManager.cancelPendingQuestion(id, body.reason, body.toolCallId);
+        return c.json({ ok: true });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'unknown';
+        const status = /no deferred tool use pending/i.test(message) ? 409 : 400;
+        return c.json({ error: message }, status);
+    }
+});
+// POST /api/workspaces/:id/deferred-permission/decision — resume a deferred
+// interactive permission request with the user's allow/deny decision.
+app.post('/:id/deferred-permission/decision', async (c) => {
+    try {
+        const id = c.req.param('id');
+        const body = await c.req
+            .json()
+            .catch(() => ({}));
+        if (!body?.toolCallId || typeof body.toolCallId !== 'string') {
+            return c.json({ error: 'toolCallId required' }, 400);
+        }
+        if (body.decision !== 'allow' && body.decision !== 'deny') {
+            return c.json({ error: "decision must be 'allow' or 'deny'" }, 400);
+        }
+        await agentManager.answerPendingPermission(id, {
+            toolCallId: body.toolCallId,
+            decision: body.decision,
+            reason: typeof body.reason === 'string' ? body.reason : undefined,
+        });
+        return c.json({ ok: true });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'unknown';
+        const status = /no deferred tool use pending/i.test(message) ? 409 : 400;
+        return c.json({ error: message }, status);
+    }
+});
+// DELETE /api/workspaces/:id/events/:eventId — permanently dismiss a single
+// persisted ws_events row (used today by the agent error banner so a closed
+// error doesn't replay on F5 / reconnect). Defensive: only deletes if the row
+// exists in this workspace; idempotent on missing row (returns 200).
+app.delete('/:id/events/:eventId', (c) => {
+    try {
+        const workspaceId = c.req.param('id');
+        const eventId = c.req.param('eventId');
+        if (!workspaceService.getWorkspace(workspaceId)) {
+            return c.json({ error: `Workspace '${workspaceId}' not found` }, 404);
+        }
+        const db = getDb();
+        db.prepare('DELETE FROM ws_events WHERE id = ? AND workspace_id = ?').run(eventId, workspaceId);
+        return c.json({ ok: true });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'unknown';
+        return c.json({ error: message }, 500);
+    }
+});
 // POST /api/workspaces/:id/tasks — create a new task
 app.post('/:id/tasks', async (c) => {
     try {
@@ -1065,7 +1214,7 @@ app.put('/:id/tags', async (c) => {
         return c.json({ error: msg }, status);
     }
 });
-// PATCH /api/workspaces/:id — update workspace fields (status, model, permissionMode, name)
+// PATCH /api/workspaces/:id — update workspace fields (status, model, agentPermissionMode, name)
 app.patch('/:id', migrationGuard, async (c) => {
     try {
         const id = c.req.param('id');
@@ -1081,18 +1230,11 @@ app.patch('/:id', migrationGuard, async (c) => {
         if (body.reasoningEffort !== undefined) {
             updated = workspaceService.updateWorkspaceReasoningEffort(id, body.reasoningEffort);
         }
-        if (body.permissionMode !== undefined) {
-            const validModes = ['auto-accept', 'plan'];
-            if (!validModes.includes(body.permissionMode)) {
-                return c.json({ error: `Invalid permission mode. Must be one of: ${validModes.join(', ')}` }, 400);
-            }
-            updated = workspaceService.updateWorkspacePermissionMode(id, body.permissionMode);
-        }
-        if (body.permissionProfile !== undefined) {
-            if (body.permissionProfile !== 'bypass' && body.permissionProfile !== 'strict') {
-                return c.json({ error: "Invalid permission profile. Must be 'bypass' or 'strict'." }, 400);
+        if (body.agentPermissionMode !== undefined) {
+            if (!isAgentPermissionMode(body.agentPermissionMode)) {
+                return c.json({ error: `Invalid agentPermissionMode. Must be one of: ${VALID_AGENT_PERMISSION_MODES.join(', ')}` }, 400);
             }
-            updated = workspaceService.setPermissionProfile(id, body.permissionProfile);
+            updated = workspaceService.updateAgentPermissionMode(id, body.agentPermissionMode);
         }
         if (body.status) {
             updated = workspaceService.updateWorkspaceStatus(id, body.status);
@@ -1103,10 +1245,9 @@ app.patch('/:id', migrationGuard, async (c) => {
         if (!body.status &&
             body.model === undefined &&
             body.reasoningEffort === undefined &&
-            body.permissionMode === undefined &&
-            body.permissionProfile === undefined &&
+            body.agentPermissionMode === undefined &&
             body.name === undefined) {
-            return c.json({ error: 'Missing field: status, model, reasoningEffort, permissionMode, permissionProfile, or name' }, 400);
+            return c.json({ error: 'Missing field: status, model, reasoningEffort, agentPermissionMode, or name' }, 400);
         }
         return c.json(updated);
     }
@@ -1394,7 +1535,7 @@ app.post('/:id/start', migrationGuard, async (c) => {
             // Agent may not be running — ignore
         }
         const worktreePath = workspace.worktreePath;
-        const agent = agentManager.startAgent(id, worktreePath, prompt, workspace.model, resume, workspace.permissionMode, agentSessionId, workspace.reasoningEffort);
+        const agent = agentManager.startAgent(id, worktreePath, prompt, workspace.model, resume, workspace.agentPermissionMode, agentSessionId, workspace.reasoningEffort);
         workspaceService.updateWorkspaceStatus(id, 'executing');
         // Persist the user prompt so it survives page refresh.
         // When agentSessionId is provided (idle-session flow), the prompt was typed
@@ -1586,11 +1727,7 @@ app.post('/:id/rename-branch', async (c) => {
         // Sibling rename: keep the same worktrees-root, swap the branch leaf.
         // Cannot use `path.dirname` directly because branches with slashes
         // (e.g. `feature/x`) make the dirname end one level too deep.
-        const oldSuffix = `/${workspace.workingBranch}`;
-        const worktreesRoot = oldWorktreePath.endsWith(oldSuffix)
-            ? oldWorktreePath.slice(0, -oldSuffix.length)
-            : path.join(workspace.projectPath, '.worktrees');
-        const newWorktreePath = path.join(worktreesRoot, newName);
+        const newWorktreePath = resolveSiblingWorkspaceWorktreePath(workspace.projectPath, oldWorktreePath, workspace.workingBranch, newName);
         // Reject early if the target name is already in use — either as a local
         // branch or on origin. Avoids git's generic "already exists" error and
         // protects against the same silent-fallback trap the create flow has.
@@ -1660,11 +1797,7 @@ app.post('/:id/resync-branch', (c) => {
         // if the move fails (dir already moved, lockfile, dirty tree), we still
         // update the DB so git ops stay aligned with the current ref name — the
         // user can repair the dir manually.
-        const oldSuffix = `/${workspace.workingBranch}`;
-        const worktreesRoot = worktreePath.endsWith(oldSuffix)
-            ? worktreePath.slice(0, -oldSuffix.length)
-            : path.join(workspace.projectPath, '.worktrees');
-        const newWorktreePath = path.join(worktreesRoot, actual);
+        const newWorktreePath = resolveSiblingWorkspaceWorktreePath(workspace.projectPath, worktreePath, workspace.workingBranch, actual);
         try {
             gitOps.moveWorktree(workspace.projectPath, worktreePath, newWorktreePath);
             workspaceService.updateWorktreePath(id, newWorktreePath);
@@ -1850,7 +1983,7 @@ Start now.`;
         }
         catch {
             try {
-                agentManager.startAgent(workspace.id, worktreePath, prompt, workspace.model, true, workspace.permissionMode, undefined, workspace.reasoningEffort);
+                agentManager.startAgent(workspace.id, worktreePath, prompt, workspace.model, true, workspace.agentPermissionMode, undefined, workspace.reasoningEffort);
                 workspaceService.updateWorkspaceStatus(workspace.id, 'executing');
                 messageSent = true;
             }
@@ -1989,7 +2122,7 @@ app.post('/:id/open-pr', async (c) => {
             // Agent not running — resume it with the PR prompt
             try {
                 const worktreePathForResume = workspace.worktreePath;
-                agentManager.startAgent(workspace.id, worktreePathForResume, rendered, workspace.model, true, workspace.permissionMode, undefined, workspace.reasoningEffort);
+                agentManager.startAgent(workspace.id, worktreePathForResume, rendered, workspace.model, true, workspace.agentPermissionMode, undefined, workspace.reasoningEffort);
                 workspaceService.updateWorkspaceStatus(workspace.id, 'executing');
                 messageSent = true;
             }

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

@@ -10,7 +10,7 @@ export const CLAUDE_CODE_CAPABILITIES = {
         { id: 'medium', label: 'Medium' },
         { id: 'high', label: 'High' },
     ],
-    permissionModes: ['auto-accept', 'plan'],
+    permissionModes: ['plan', 'bypass', 'strict', 'interactive'],
     supportsResume: true,
     supportsMcp: true,
     supportsSkills: true,