@loicngr/kobo 1.6.2 → 1.6.4

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

@@ -183,3 +183,148 @@ export function listWorkspaceImagesHandler(worktreePath) {
         };
     });
 }
+// ── Documents ────────────────────────────────────────────────────────────────
+/** Directories (relative to the worktree root) scanned for AI-generated docs. */
+export const DOCUMENT_DIRS = ['docs/plans', 'docs/superpowers', '.ai/thoughts'];
+/** Depth cap to keep recursion bounded even on pathological symlink loops. */
+const DOC_MAX_DEPTH = 8;
+function walkMarkdownFiles(rootAbs, rootRel, out, depth = 0) {
+    if (depth > DOC_MAX_DEPTH)
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(rootAbs);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.startsWith('.') && entry !== '.ai')
+            continue;
+        const absEntry = path.join(rootAbs, entry);
+        const relEntry = `${rootRel}/${entry}`;
+        let stat;
+        try {
+            stat = fs.statSync(absEntry);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            walkMarkdownFiles(absEntry, relEntry, out, depth + 1);
+        }
+        else if (stat.isFile() && entry.endsWith('.md')) {
+            out.push({ path: relEntry, name: entry, modifiedAt: stat.mtime.toISOString() });
+        }
+    }
+}
+/**
+ * Recursively list every `.md` file under `docs/plans/`, `docs/superpowers/`,
+ * and `.ai/thoughts/` inside the given worktree. Sorted by modifiedAt desc.
+ */
+export function listDocumentsHandler(worktreePath) {
+    const documents = [];
+    for (const dir of DOCUMENT_DIRS) {
+        const absDir = path.join(worktreePath, dir);
+        if (!fs.existsSync(absDir))
+            continue;
+        walkMarkdownFiles(absDir, dir, documents);
+    }
+    documents.sort((a, b) => new Date(b.modifiedAt).getTime() - new Date(a.modifiedAt).getTime());
+    return documents;
+}
+/**
+ * Read a single document. The caller-supplied path must be relative to the
+ * worktree root and live under one of the allowed DOCUMENT_DIRS; `.md` only;
+ * traversal (`..`) is rejected.
+ */
+export function readDocumentHandler(worktreePath, relPath) {
+    if (!relPath)
+        throw new Error('path is required');
+    const normalized = path.normalize(relPath);
+    if (normalized.includes('..') ||
+        !DOCUMENT_DIRS.some((dir) => normalized.startsWith(`${dir}/`) || normalized === dir)) {
+        throw new Error(`Invalid path: must be under ${DOCUMENT_DIRS.map((d) => `${d}/`).join(', ')}`);
+    }
+    if (!normalized.endsWith('.md')) {
+        throw new Error('Only .md files can be read');
+    }
+    const abs = path.join(worktreePath, normalized);
+    if (!fs.existsSync(abs)) {
+        throw new Error(`Document not found: ${normalized}`);
+    }
+    return { path: normalized, content: fs.readFileSync(abs, 'utf-8') };
+}
+/**
+ * Append a thought / decision / note to `.ai/thoughts/<YYYY-MM-DD>-<slug>.md`.
+ * Creates the directory if missing. Returns the path (worktree-relative) of
+ * the file actually written — useful for the agent to reference it in chat.
+ */
+export function logThoughtHandler(worktreePath, data) {
+    const title = data.title?.trim();
+    if (!title)
+        throw new Error('title is required');
+    const content = data.content?.trim();
+    if (!content)
+        throw new Error('content is required');
+    const thoughtsDir = path.join(worktreePath, '.ai', 'thoughts');
+    fs.mkdirSync(thoughtsDir, { recursive: true });
+    const date = new Date().toISOString().slice(0, 10);
+    const slug = title
+        .toLowerCase()
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60) || 'note';
+    const tagSuffix = data.tag ? `-${data.tag.replace(/[^a-z0-9]+/gi, '-').toLowerCase()}` : '';
+    const filename = `${date}-${slug}${tagSuffix}.md`;
+    const abs = path.join(thoughtsDir, filename);
+    const relPath = `.ai/thoughts/${filename}`;
+    const header = `# ${title}\n\n_${new Date().toISOString()}_${data.tag ? ` · tag: \`${data.tag}\`` : ''}\n\n`;
+    fs.writeFileSync(abs, header + content + (content.endsWith('\n') ? '' : '\n'), 'utf-8');
+    return { path: relPath };
+}
+/**
+ * Aggregate `usage` events from `ws_events` to report how many tokens and
+ * dollars the workspace has consumed — both in total and for the currently
+ * running agent_session (if any). Silently skips rows whose payload is not
+ * valid JSON or not a usage event.
+ */
+export function getSessionUsageHandler(db, workspaceId) {
+    const runningSession = db
+        .prepare("SELECT id FROM agent_sessions WHERE workspace_id = ? AND status = 'running' ORDER BY started_at DESC LIMIT 1")
+        .get(workspaceId);
+    const currentSessionId = runningSession?.id ?? null;
+    const rows = db
+        .prepare("SELECT payload, session_id FROM ws_events WHERE workspace_id = ? AND type = 'agent:event'")
+        .all(workspaceId);
+    const totals = { inputTokens: 0, outputTokens: 0, costUsd: 0 };
+    const current = { inputTokens: 0, outputTokens: 0, costUsd: 0 };
+    for (const row of rows) {
+        let parsed;
+        try {
+            parsed = JSON.parse(row.payload);
+        }
+        catch {
+            continue;
+        }
+        if (parsed.kind !== 'usage')
+            continue;
+        const input = typeof parsed.inputTokens === 'number' ? parsed.inputTokens : 0;
+        const output = typeof parsed.outputTokens === 'number' ? parsed.outputTokens : 0;
+        const cost = typeof parsed.costUsd === 'number' ? parsed.costUsd : 0;
+        totals.inputTokens += input;
+        totals.outputTokens += output;
+        totals.costUsd += cost;
+        if (currentSessionId && row.session_id === currentSessionId) {
+            current.inputTokens += input;
+            current.outputTokens += output;
+            current.costUsd += cost;
+        }
+    }
+    return {
+        workspaceTotals: totals,
+        currentSession: { sessionId: currentSessionId, ...current },
+    };
+}

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

@@ -5,7 +5,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import Database from 'better-sqlite3';
-import { createTaskHandler, deleteTaskHandler, getDevServerStatusHandler, getSettingsHandler, getWorkspaceInfoHandler, listTasksHandler, listWorkspaceImagesHandler, markTaskDoneHandler, updateTaskHandler, } from './kobo-tasks-handlers.js';
+import { createTaskHandler, deleteTaskHandler, getDevServerStatusHandler, getSessionUsageHandler, getSettingsHandler, getWorkspaceInfoHandler, listDocumentsHandler, listTasksHandler, listWorkspaceImagesHandler, logThoughtHandler, markTaskDoneHandler, readDocumentHandler, updateTaskHandler, } from './kobo-tasks-handlers.js';
 const workspaceId = process.env.KOBO_WORKSPACE_ID;
 const dbPath = process.env.KOBO_DB_PATH;
 const settingsPath = process.env.KOBO_SETTINGS_PATH;
@@ -73,37 +73,30 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {
             name: 'list_tasks',
-            description: 'List all tasks and acceptance criteria for the current workspace with their IDs and current status. Call this first to discover task IDs before calling mark_task_done / update_task / delete_task.',
-            inputSchema: {
-                type: 'object',
-                properties: {},
-                required: [],
-            },
+            description: 'CALL FIRST on any non-trivial turn to know what the user wants done and what is already completed. Returns every task and acceptance criterion for the current workspace with its id and status. Re-call periodically (before marking something done, or after the user asks for a status) to stay in sync with user-added or external updates.',
+            inputSchema: { type: 'object', properties: {}, required: [] },
         },
         {
             name: 'mark_task_done',
-            description: 'Mark a task or acceptance criterion as done. Use this when you have completed the work for a criterion and validated it.',
+            description: 'CALL AS SOON AS a task or acceptance criterion is finished AND verified (tests pass, feature works, diff committed). Do not wait for the end of the turn — the user watches progress live and marking each item as it completes is the primary signal Kōbō uses to track you.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    task_id: {
-                        type: 'string',
-                        description: 'The ID of the task to mark as done (obtained from list_tasks)',
-                    },
+                    task_id: { type: 'string', description: 'Task id from list_tasks.' },
                 },
                 required: ['task_id'],
             },
         },
         {
             name: 'create_task',
-            description: 'Create a new task or acceptance criterion for the current workspace. Appended at the end of the list.',
+            description: 'CALL WHEN you discover follow-up work that was not in the original list and needs to stick around (e.g. "refactor this helper later", "add a test for edge case"). Appends at the end of the list. Do not use it for ephemeral internal notes — prefer log_thought for those.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    title: { type: 'string', description: 'Task title' },
+                    title: { type: 'string', description: 'Short, imperative title (e.g. "Add retry to fetchUser").' },
                     is_acceptance_criterion: {
                         type: 'boolean',
-                        description: 'Whether this is an acceptance criterion (default: false)',
+                        description: 'Mark as acceptance criterion rather than a task (default: false).',
                     },
                 },
                 required: ['title'],
@@ -111,20 +104,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: 'update_task',
-            description: 'Update an existing task — change title, status, or is_acceptance_criterion flag. At least one field is required.',
+            description: 'CALL WHEN you need to refine a task — rewording for clarity, flipping status to `in_progress` as you start it, or promoting a task to acceptance criterion. At least one mutable field is required.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    task_id: { type: 'string', description: 'The ID of the task to update' },
-                    title: { type: 'string', description: 'New title (optional)' },
+                    task_id: { type: 'string', description: 'Task id from list_tasks.' },
+                    title: { type: 'string', description: 'New title (optional).' },
                     status: {
                         type: 'string',
                         enum: ['pending', 'in_progress', 'done'],
-                        description: 'New status (optional)',
+                        description: 'New status (optional).',
                     },
                     is_acceptance_criterion: {
                         type: 'boolean',
-                        description: 'Toggle acceptance criterion flag (optional)',
+                        description: 'Toggle acceptance criterion flag (optional).',
                     },
                 },
                 required: ['task_id'],
@@ -132,95 +125,150 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: 'delete_task',
-            description: 'Delete a task from the current workspace permanently.',
+            description: 'CALL ONLY when a task was created in error or became truly irrelevant (scope change validated by user). Prefer marking done or in_progress over deleting.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    task_id: { type: 'string', description: 'The ID of the task to delete' },
+                    task_id: { type: 'string', description: 'Task id from list_tasks.' },
                 },
                 required: ['task_id'],
             },
         },
         {
-            name: 'get_settings',
-            description: 'Read Kōbō settings (global + projects). Optionally filter to a specific project by path to get both global and that project override.',
+            name: 'get_workspace_info',
+            description: 'CALL EARLY in a session to confirm project path, working/source branch, worktree path, model, and notion link. Cheap read — useful when the user refers to "this workspace" or when you need the worktree path to locate files.',
+            inputSchema: { type: 'object', properties: {}, required: [] },
+        },
+        {
+            name: 'get_git_info',
+            description: 'CALL BEFORE creating a PR, committing in batches, or reporting progress to the user. Returns commit count ahead of source, files changed, insertions/deletions, and existing PR URL if any.',
+            inputSchema: { type: 'object', properties: {}, required: [] },
+        },
+        {
+            name: 'set_workspace_status',
+            description: 'CALL WHEN you believe the mission is done (`completed`), blocked beyond recovery (`error`), or explicitly idle awaiting user input (`idle`). Transitions are validated by the backend — invalid ones are rejected.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    project_path: {
+                    status: {
                         type: 'string',
-                        description: 'Optional project path to resolve a specific project entry',
+                        enum: ['idle', 'completed', 'error'],
+                        description: 'Target status.',
                     },
                 },
-                required: [],
+                required: ['status'],
             },
         },
         {
-            name: 'get_dev_server_status',
-            description: 'Get the live dev server status for the current workspace. Returns status (running/stopped/starting/error/unknown), URL, HTTP port, instance name, project name, and running container names.',
-            inputSchema: {
-                type: 'object',
-                properties: {},
-                required: [],
-            },
+            name: 'get_notion_ticket',
+            description: 'CALL when the user references "the ticket", "the Notion page", or when you need the source-of-truth text for the mission. Returns the Notion URL + locally-extracted ticket content from .ai/thoughts/.',
+            inputSchema: { type: 'object', properties: {}, required: [] },
         },
         {
-            name: 'get_workspace_info',
-            description: 'Get all metadata about the current workspace (name, project path, branches, model, notion URL, worktree path, status).',
+            name: 'get_dev_server_status',
+            description: 'CALL BEFORE asking the user whether the app is running, or when your change is dev-server-sensitive. Returns running/stopped/starting/error + URL, port, container names.',
             inputSchema: { type: 'object', properties: {}, required: [] },
         },
         {
             name: 'start_dev_server',
-            description: 'Start the dev server configured for the current workspace.',
+            description: 'CALL WHEN the user asks you to test the running app and the dev server is stopped.',
             inputSchema: { type: 'object', properties: {}, required: [] },
         },
         {
             name: 'stop_dev_server',
-            description: 'Stop the dev server of the current workspace.',
+            description: 'CALL WHEN the user explicitly asks to stop the dev server, or before destructive operations that require a clean boot.',
             inputSchema: { type: 'object', properties: {}, required: [] },
         },
         {
             name: 'get_dev_server_logs',
-            description: 'Fetch the last N lines of the dev server logs for the current workspace.',
+            description: 'CALL WHEN debugging a runtime issue the user describes as happening in the running app. Returns the last N lines of logs (default 200). Cheaper than asking the user to paste them.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    tail: {
-                        type: 'number',
-                        description: 'Number of lines to fetch from the end (default: 200)',
-                    },
+                    tail: { type: 'number', description: 'Number of lines from the end (default: 200).' },
                 },
                 required: [],
             },
         },
         {
             name: 'list_workspace_images',
-            description: 'List all images uploaded to the current workspace (from .ai/images/index.json). Returns uid, originalName, relativePath and createdAt for each image.',
+            description: 'CALL WHEN the user mentions "the screenshot", "the attached image", or when you need to reference a previously-uploaded image. Returns uid, originalName, relativePath, createdAt for every image in .ai/images/.',
             inputSchema: { type: 'object', properties: {}, required: [] },
         },
         {
-            name: 'get_git_info',
-            description: 'Get git stats for the current workspace (commit count, files changed, insertions, deletions, PR URL if any).',
+            name: 'get_settings',
+            description: 'CALL WHEN you need to confirm configured models, PR prompt templates, git conventions, or dev-server commands before acting on them. Pass project_path to merge global + project-specific entries.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_path: {
+                        type: 'string',
+                        description: 'Project path to resolve a specific project entry (optional).',
+                    },
+                },
+                required: [],
+            },
+        },
+        // ── Knowledge / context tools ─────────────────────────────────────────────
+        {
+            name: 'list_documents',
+            description: 'CALL EARLY on a new session to discover plans, specs, and thoughts previously written for this workspace. Recursively lists every .md under docs/plans/, docs/superpowers/, and .ai/thoughts/. Before writing a new plan, check if one already exists.',
             inputSchema: { type: 'object', properties: {}, required: [] },
         },
         {
-            name: 'set_workspace_status',
-            description: 'Update the current workspace status. Valid values: idle, completed, error. Transitions are validated by the backend.',
+            name: 'read_document',
+            description: 'CALL AFTER list_documents when a file title looks relevant to the current task. Returns the full markdown content. Scoped to docs/plans/, docs/superpowers/, .ai/thoughts/ — reject anything else.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    status: {
+                    path: {
                         type: 'string',
-                        enum: ['idle', 'completed', 'error'],
-                        description: 'New status (e.g. idle, completed)',
+                        description: 'Worktree-relative path from list_documents (e.g. "docs/superpowers/plans/2026-04-17-foo.md").',
                     },
                 },
-                required: ['status'],
+                required: ['path'],
             },
         },
         {
-            name: 'get_notion_ticket',
-            description: 'Get the Notion ticket info for the current workspace. Returns the Notion URL and the extracted ticket content (from .ai/thoughts/) if available.',
+            name: 'log_thought',
+            description: 'CALL WHEN you make a decision worth remembering — architecture choice, trade-off taken, dead-end avoided, pattern discovered. Appends a dated markdown file to .ai/thoughts/. Keep entries short and focused; one decision per call. Use create_task for actionable follow-ups instead.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    title: { type: 'string', description: 'Short, descriptive title (becomes the filename slug and the # H1).' },
+                    content: { type: 'string', description: 'Markdown body explaining the decision and its reasoning.' },
+                    tag: {
+                        type: 'string',
+                        description: 'Optional short tag appended to filename (e.g. "arch", "bug", "perf").',
+                    },
+                },
+                required: ['title', 'content'],
+            },
+        },
+        {
+            name: 'search_codebase',
+            description: 'CALL WHEN you need to recall prior chat history across workspaces — past decisions, prior user requests, an agent message you remember but can’t locate. Full-text search over user messages + agent outputs persisted in Kōbō. Use the local Grep tool for searching source code; this tool searches CONVERSATIONS.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Search phrase. Plain text; no regex.' },
+                    include_archived: {
+                        type: 'boolean',
+                        description: 'Include archived workspaces in the search (default: false).',
+                    },
+                    scope: {
+                        type: 'string',
+                        enum: ['workspace', 'all'],
+                        description: 'Restrict to this workspace only (default) or search across every workspace.',
+                    },
+                    limit: { type: 'number', description: 'Max results to return (default 30, max 100).' },
+                },
+                required: ['query'],
+            },
+        },
+        {
+            name: 'get_session_usage',
+            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: [] },
         },
     ],
@@ -339,6 +387,48 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const result = await backendRequest('PATCH', `/api/workspaces/${workspaceId}`, { status });
             return ok(result);
         }
+        if (name === 'list_documents') {
+            const info = getWorkspaceInfoHandler(db, workspaceId);
+            return ok(listDocumentsHandler(info.worktreePath));
+        }
+        if (name === 'read_document') {
+            const docPath = a.path;
+            if (!docPath)
+                return fail('path parameter is required');
+            const info = getWorkspaceInfoHandler(db, workspaceId);
+            return ok(readDocumentHandler(info.worktreePath, docPath));
+        }
+        if (name === 'log_thought') {
+            const title = a.title;
+            const content = a.content;
+            if (!title)
+                return fail('title parameter is required');
+            if (!content)
+                return fail('content parameter is required');
+            const info = getWorkspaceInfoHandler(db, workspaceId);
+            return ok(logThoughtHandler(info.worktreePath, {
+                title,
+                content,
+                tag: a.tag,
+            }));
+        }
+        if (name === 'get_session_usage') {
+            return ok(getSessionUsageHandler(db, workspaceId));
+        }
+        if (name === 'search_codebase') {
+            const query = a.query;
+            if (!query)
+                return fail('query parameter is required');
+            const scope = a.scope ?? 'workspace';
+            const includeArchived = a.include_archived === true;
+            const limit = Math.min(Math.max(1, a.limit ?? 30), 100);
+            const qs = new URLSearchParams({ q: query, limit: String(limit) });
+            if (includeArchived)
+                qs.set('includeArchived', 'true');
+            const raw = (await backendRequest('GET', `/api/search?${qs.toString()}`));
+            const results = scope === 'all' ? raw : raw.filter((r) => r.workspaceId === workspaceId);
+            return ok({ query, scope, total: results.length, results });
+        }
         return fail(`Unknown tool: ${name}`);
     }
     catch (err) {

package/dist/server/routes/workspaces.js

@@ -76,6 +76,27 @@ app.post('/', migrationGuard, async (c) => {
         });
         let notionContent = null;
         let sentryContent = null;
+        // Auto-tag the workspace based on its creation source — `notion` when
+        // imported from a Notion page, `sentry` when bootstrapped from a Sentry
+        // issue URL. Pre-seeded in the global tag catalogue via migration v9.
+        // Skip any tag the user has removed from the catalogue so we respect
+        // their choice (they may have pruned "notion"/"sentry" on purpose).
+        const catalogTags = new Set(globalSettings.tags ?? []);
+        const autoTags = [];
+        if (body.notionUrl && catalogTags.has('notion'))
+            autoTags.push('notion');
+        if (body.sentryUrl && catalogTags.has('sentry'))
+            autoTags.push('sentry');
+        if (autoTags.length > 0) {
+            try {
+                const tagged = workspaceService.setWorkspaceTags(workspace.id, autoTags);
+                if (tagged)
+                    workspace = tagged;
+            }
+            catch (err) {
+                console.error('[workspaces] Failed to apply auto tags:', err);
+            }
+        }
         // Extract Notion page content if a URL was provided
         if (body.notionUrl) {
             workspaceService.updateWorkspaceStatus(workspace.id, 'extracting');
@@ -1143,18 +1164,27 @@ app.get('/:id/git-stats', async (c) => {
         return c.json({ error: message }, 500);
     }
 });
-// GET /api/workspaces/:id/diff — list changed files
+// GET /api/workspaces/:id/diff?mode=branch|unpushed — list changed files
+// - `branch` (default): committed + working tree changes vs sourceBranch,
+//   i.e. what the PR will contain.
+// - `unpushed`: committed-only changes vs `origin/<workingBranch>`,
+//   i.e. what the next `git push` will send.
 app.get('/:id/diff', (c) => {
     try {
         const id = c.req.param('id');
+        const mode = c.req.query('mode') === 'unpushed' ? 'unpushed' : 'branch';
         const workspace = workspaceService.getWorkspace(id);
         if (!workspace) {
             return c.json({ error: `Workspace '${id}' not found` }, 404);
         }
         const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
-        const files = gitOps.getChangedFiles(worktreePath, workspace.sourceBranch);
+        const files = mode === 'unpushed'
+            ? gitOps.getUnpushedChangedFiles(worktreePath, workspace.workingBranch)
+            : gitOps.getChangedFiles(worktreePath, workspace.sourceBranch);
+        c.header('Cache-Control', 'no-store');
         return c.json({
             files,
+            mode,
             sourceBranch: workspace.sourceBranch,
             workingBranch: workspace.workingBranch,
         });
@@ -1164,11 +1194,16 @@ app.get('/:id/diff', (c) => {
         return c.json({ error: message }, 500);
     }
 });
-// GET /api/workspaces/:id/diff/:filePath — get original and modified content for a file
+// GET /api/workspaces/:id/diff-file?path=...&mode=branch|unpushed
+// Resolves `original` at the appropriate base ref:
+//  - `branch`   → sourceBranch
+//  - `unpushed` → origin/<workingBranch>
+// `modified` is always the current worktree content.
 app.get('/:id/diff-file', (c) => {
     try {
         const id = c.req.param('id');
         const filePath = c.req.query('path');
+        const mode = c.req.query('mode') === 'unpushed' ? 'unpushed' : 'branch';
         if (!filePath) {
             return c.json({ error: 'Missing path query parameter' }, 400);
         }
@@ -1177,9 +1212,32 @@ app.get('/:id/diff-file', (c) => {
             return c.json({ error: `Workspace '${id}' not found` }, 404);
         }
         const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
-        const original = gitOps.getFileAtRef(worktreePath, workspace.sourceBranch, filePath);
+        const baseRef = mode === 'unpushed' ? `origin/${workspace.workingBranch}` : workspace.sourceBranch;
+        const original = gitOps.getFileAtRef(worktreePath, baseRef, filePath);
         const modified = gitOps.getFileContent(worktreePath, filePath);
-        return c.json({ original: original ?? '', modified: modified ?? '', filePath });
+        c.header('Cache-Control', 'no-store');
+        return c.json({ original: original ?? '', modified: modified ?? '', filePath, mode });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+// GET /api/workspaces/:id/commits?limit=50 — list commits between sourceBranch
+// and HEAD, each tagged with whether it's already pushed to origin/<branch>.
+app.get('/:id/commits', (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 limitRaw = c.req.query('limit');
+        const limit = Math.min(Math.max(1, parseInt(limitRaw ?? '50', 10) || 50), 200);
+        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        const commits = gitOps.listBranchCommits(worktreePath, workspace.sourceBranch, workspace.workingBranch, limit);
+        c.header('Cache-Control', 'no-store');
+        return c.json({ commits, sourceBranch: workspace.sourceBranch, workingBranch: workspace.workingBranch });
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);

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

@@ -1,10 +1,37 @@
+/**
+ * Short brief injected at the top of the first prompt of a *new* session so
+ * the agent discovers the Kōbō MCP toolbox without having to be asked.
+ * Skipped on `--resume` because the brief is already in conversation history.
+ */
+const KOBO_MCP_BRIEF = [
+    '[Kōbō MCP] This workspace exposes a dedicated MCP server with tools prefixed `kobo__`.',
+    'Conventions — read these BEFORE starting work, not as a fallback:',
+    '• `kobo__list_tasks` first on any non-trivial turn, then `kobo__mark_task_done` as each item completes.',
+    '• `kobo__list_documents` / `kobo__read_document` to discover existing plans and specs under docs/ and .ai/thoughts/ before writing new ones.',
+    '• `kobo__log_thought` to persist notable decisions to `.ai/thoughts/<date>-<slug>.md`.',
+    '• `kobo__search_codebase` to recall prior chat history (conversations, not source — use Grep for source).',
+    '• `kobo__get_workspace_info` / `kobo__get_git_info` / `kobo__get_notion_ticket` for context.',
+    '• `kobo__set_workspace_status` when the mission is done / blocked / idle.',
+    'Each tool carries its own "WHEN to use" guidance in its description — follow it.',
+].join('\n');
 export function buildClaudeArgs(input) {
     const args = ['--output-format', 'stream-json', '--verbose'];
-    if (input.skipPermissions)
+    // `plan` mode is handled by Claude Code natively via `--permission-mode plan`.
+    // Under plan mode, Claude restricts itself to read-only tools and surfaces an
+    // `ExitPlanMode` tool call when the plan is ready for the user to approve.
+    // `--dangerously-skip-permissions` is incompatible with plan mode (it would
+    // bypass the very restriction plan mode enforces), so we skip it here.
+    if (input.permissionMode === 'plan') {
+        args.push('--permission-mode', 'plan');
+    }
+    else if (input.skipPermissions) {
         args.push('--dangerously-skip-permissions');
+    }
     let prompt = input.prompt;
-    if (input.permissionMode === 'plan') {
-        prompt = `[PLAN MODE] You are in PLAN/READ-ONLY mode. You MUST NOT create, edit, write, or delete any files. Only use read-only tools (Read, Grep, Glob, LS, Bash for read-only commands). Analyze the codebase, plan your approach, and present your findings — but do NOT execute any changes.\n\n${prompt}`;
+    // Only prepend the MCP brief on a fresh session — on --resume, the previous
+    // turn's context already contains it, and re-prepending would spam.
+    if (!input.resumeFromEngineSessionId) {
+        prompt = `${KOBO_MCP_BRIEF}\n\n${prompt}`;
     }
     if (input.model && input.model !== 'auto')
         args.push('--model', input.model);