claude-code-kanban 7.19.0 → 7.20.0

package/lib/ask.js

@@ -0,0 +1,215 @@
+// The ask modal's server side: one open question per terminal, from the plugin's ask tool. The tool's
+// call waits on it, long-polling /wait until the board answers, the user skips, or the agent is
+// interrupted. Nothing is written to disk: a question outlives neither the board nor its terminal.
+
+const crypto = require('node:crypto');
+const path = require('node:path');
+const express = require('express');
+const { httpError } = require('./http-error');
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ASK_PATH = '/api/terminals/:terminalId/ask';
+// The answer of a playground card is its whole state.
+const BODY_LIMIT = '256kb';
+const MAX_LABEL = 200;
+const SIZES = ['md', 'lg', 'full'];
+// $.http.fetch gives up after 30 s, so a wait answers pending before that.
+const WAIT_MAX_MS = 25_000;
+// An answer that lands between two polls waits this long for the next one.
+const DONE_TTL_MS = 60_000;
+
+function parseAsk(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return 'body must be a JSON object';
+  const { sessionId, title, file, size = 'lg' } = body;
+  if (typeof sessionId !== 'string' || !UUID_RE.test(sessionId)) return 'invalid sessionId';
+  if (typeof title !== 'string' || !title.trim() || title.length > MAX_LABEL) {
+    return `title must be a non-empty string of at most ${MAX_LABEL} characters`;
+  }
+  if (typeof file !== 'string' || !path.isAbsolute(file)) return 'file must be an absolute path';
+  if (!SIZES.includes(size)) return `size must be one of ${SIZES.join(', ')}`;
+  return { sessionId, title, file, size };
+}
+
+// A string is a reason the body is refused.
+function parseAnswer(body) {
+  const { status, data } = body || {};
+  if (status === 'dismissed') return { status };
+  if (status !== 'answered') return 'status must be answered or dismissed';
+  if (data === undefined) return 'an answer needs data';
+  return { status, data };
+}
+
+/**
+ * @param {object} [o]
+ * @param {() => number} [o.now]
+ */
+function createAskStore(o = {}) {
+  const now = o.now || Date.now;
+  const open = new Map();
+  const done = new Map();
+  const waiters = new Map();
+
+  function sweep() {
+    const t = now();
+    for (const [id, d] of done) if (t - d.at > DONE_TTL_MS) done.delete(id);
+  }
+
+  function settle(ask, result) {
+    open.delete(ask.terminalId);
+    done.set(ask.id, { result, at: now() });
+    for (const w of waiters.get(ask.id) || []) w(result);
+    waiters.delete(ask.id);
+  }
+
+  // A new question ends the open one, so the board never holds two.
+  function ask(terminalId, { sessionId, title, file, size }) {
+    sweep();
+    const old = open.get(terminalId);
+    if (old) settle(old, { status: 'dismissed', reason: 'replaced' });
+    const entry = { id: crypto.randomUUID(), terminalId, sessionId, title, file, size, at: now() };
+    open.set(terminalId, entry);
+    return { entry, replaced: old?.id ?? null };
+  }
+
+  function current(terminalId) {
+    return open.get(terminalId) || null;
+  }
+
+  function end(terminalId, askId, result) {
+    const entry = open.get(terminalId);
+    if (!entry || entry.id !== askId) return false;
+    settle(entry, result);
+    return true;
+  }
+
+  // Resolves the result once, or pending after `ms`; an unknown id is gone.
+  function wait(askId, ms) {
+    const d = done.get(askId);
+    if (d) {
+      done.delete(askId);
+      return Promise.resolve(d.result);
+    }
+    if (![...open.values()].some((a) => a.id === askId)) return Promise.resolve({ status: 'gone' });
+    return new Promise((resolve) => {
+      const list = waiters.get(askId) || [];
+      const finish = (result) => {
+        clearTimeout(timer);
+        done.delete(askId);
+        resolve(result);
+      };
+      const timer = setTimeout(() => {
+        const left = (waiters.get(askId) || []).filter((w) => w !== finish);
+        if (left.length) waiters.set(askId, left);
+        else waiters.delete(askId);
+        resolve({ status: 'pending' });
+      }, ms);
+      timer.unref?.();
+      list.push(finish);
+      waiters.set(askId, list);
+    });
+  }
+
+  function prune(keep) {
+    for (const [tid, entry] of open) if (!keep(tid)) settle(entry, { status: 'dismissed', reason: 'terminal ended' });
+  }
+
+  return { ask, current, end, wait, prune };
+}
+
+function askBodyParser() {
+  return express.json({ limit: BODY_LIMIT });
+}
+
+/**
+ * @param {import('express').Express} app
+ * @param {object} o
+ * @param {ReturnType<typeof createAskStore>} o.store
+ * @param {(token: string|undefined) => boolean} o.authorized  the terminal token
+ * @param {(terminalId: string) => boolean} o.hasTerminal  a live terminal has this id
+ * @param {(absPath: string) => Promise<{content: string|null, kind: string|null}>} o.readPreviewFile
+ * @param {(event: object) => void} o.broadcast
+ */
+function mountAskRoutes(app, o) {
+  const { store } = o;
+
+  function guard(req, res) {
+    if (!o.authorized(req.get('x-terminal-token'))) return res.status(401).json({ error: 'invalid terminal token' });
+    if (!o.hasTerminal(req.params.terminalId)) return res.status(404).json({ error: 'no live terminal with that id' });
+    return null;
+  }
+
+  async function readCard(file) {
+    let read;
+    try {
+      read = await o.readPreviewFile(file);
+    } catch (e) {
+      if (e.status === 404) throw httpError(400, `file not found: ${file}`);
+      throw e;
+    }
+    if (read.kind !== 'html') throw httpError(400, 'file must be an HTML file');
+    return read.content;
+  }
+
+  const route = (fn) => (req, res) => fn(req, res).catch((e) => {
+    if (res.headersSent) return;
+    if (!e.status) console.error(`Error in ${req.method} ${req.path}:`, e);
+    res.status(e.status || 500).json({ error: e.status ? e.message : 'Internal error' });
+  });
+
+  const closed = (terminalId, id, status) => o.broadcast({ type: 'ask:closed', terminalId, id, status });
+
+  app.post(ASK_PATH, route(async (req, res) => {
+    if (guard(req, res)) return;
+    const p = parseAsk(req.body);
+    if (typeof p === 'string') return res.status(400).json({ error: p });
+    await readCard(p.file);
+    const { terminalId } = req.params;
+    const { entry, replaced } = store.ask(terminalId, p);
+    if (replaced) closed(terminalId, replaced, 'dismissed');
+    o.broadcast({ type: 'ask:opened', terminalId, id: entry.id, sessionId: entry.sessionId });
+    res.json({ id: entry.id });
+  }));
+
+  app.get(ASK_PATH, route(async (req, res) => {
+    res.setHeader('Cache-Control', 'no-store');
+    const entry = store.current(req.params.terminalId);
+    if (!entry) return res.json({ ask: null });
+    const { id, title, size, file, sessionId } = entry;
+    let content = null;
+    try {
+      content = await readCard(file);
+    } catch (e) {
+      if (!e.status) throw e;
+    }
+    res.json({ ask: { id, title, size, file, sessionId, content } });
+  }));
+
+  app.get(`${ASK_PATH}/:askId/wait`, route(async (req, res) => {
+    if (guard(req, res)) return;
+    const ms = Math.min(Math.max(Number(req.query.ms) || WAIT_MAX_MS, 0), WAIT_MAX_MS);
+    res.setHeader('Cache-Control', 'no-store');
+    res.json(await store.wait(req.params.askId, ms));
+  }));
+
+  // The board answers or skips.
+  app.post(`${ASK_PATH}/:askId`, route(async (req, res) => {
+    if (guard(req, res)) return;
+    const result = parseAnswer(req.body);
+    if (typeof result === 'string') return res.status(400).json({ error: result });
+    const { terminalId, askId } = req.params;
+    if (!store.end(terminalId, askId, result)) return res.status(404).json({ error: 'no such question' });
+    closed(terminalId, askId, result.status);
+    res.status(204).end();
+  }));
+
+  // The tool call was interrupted.
+  app.delete(`${ASK_PATH}/:askId`, route(async (req, res) => {
+    if (guard(req, res)) return;
+    const { terminalId, askId } = req.params;
+    if (!store.end(terminalId, askId, { status: 'cancelled' })) return res.status(404).json({ error: 'no such question' });
+    closed(terminalId, askId, 'cancelled');
+    res.status(204).end();
+  }));
+}
+
+module.exports = { createAskStore, mountAskRoutes, askBodyParser, parseAsk, parseAnswer, ASK_PATH, WAIT_MAX_MS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "7.19.0",
+  "version": "7.20.0",
   "description": "A web-based Kanban board for viewing Claude Code tasks with agent teams support",
   "main": "server.js",
   "type": "commonjs",

package/plugin/plugins/claude-code-kanban/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "claude-code-kanban",
-  "version": "3.7.14",
+  "version": "3.8.0",
   "description": "claude-code-kanban dashboard integration: agent activity tracking, context and cost tracking, board moves and reviews delivered to the session, and skills to drive the board from a session"
 }

package/plugin/plugins/claude-code-kanban/hooks/ask.ts

@@ -0,0 +1,163 @@
+import type { EngineInterface, Register } from 'claude-code'
+import { cckRoot } from './context'
+import { boardPort } from './show'
+
+export const TOOL = 'mcp__claude-code-kanban__ask'
+
+type AskInput = { title: string; file: string; size?: 'md' | 'lg' | 'full' }
+type Target = { url: string; terminalId: string }
+
+let cck: Promise<string> | undefined
+
+function cckDir($: EngineInterface) {
+  cck ??= Promise.all([$.env.get('CLAUDE_CONFIG_DIR'), $.env.get('HOME'), $.env.get('USERPROFILE')]).then(
+    ([configDir, home, userProfile]) => cckRoot(configDir, home, userProfile),
+  )
+  return cck
+}
+
+let target: Promise<Target | undefined> | undefined
+
+// Both vars come from ptyEnv, so only a session started in cck's embedded terminal has them.
+function terminal($: EngineInterface) {
+  target ??= Promise.all([$.env.get('CCK_URL'), $.env.get('CCK_TERMINAL_ID')]).then(([url, terminalId]) =>
+    url && terminalId ? { url: url.replace(/\/+$/, ''), terminalId } : undefined,
+  )
+  return target
+}
+
+// Read on every call: a restarted board writes a new token.
+async function terminalToken($: EngineInterface, url: string) {
+  const port = boardPort(url)
+  if (!port) return undefined
+  try {
+    const { token } = JSON.parse(await $.fs.read(`${await cckDir($)}/terminal-tokens/${port}.json`))
+    return typeof token === 'string' && token ? token : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function errorText(status: number, text: string) {
+  try {
+    const { error } = JSON.parse(text)
+    if (typeof error === 'string' && error) return error
+  } catch {}
+  return `cck answered HTTP ${status}`
+}
+
+async function send(
+  $: EngineInterface,
+  url: string,
+  path: string,
+  headers: Record<string, string>,
+  body: unknown,
+): Promise<{ text: string } | { deny: string }> {
+  try {
+    const res = await $.http.fetch(`${url}${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...headers },
+      body: JSON.stringify(body),
+    })
+    return res.ok ? { text: res.text } : { deny: errorText(res.status, res.text) }
+  } catch (err) {
+    return { deny: `Cannot reach cck at ${url}: ${err instanceof Error ? err.message : String(err)}` }
+  }
+}
+type Answer = { status: 'answered'; data: unknown } | { status: 'dismissed' | 'cancelled' | 'gone' | 'pending'; reason?: string }
+
+// Under $.http.fetch's 30 s limit; the board answers pending at this mark.
+export const WAIT_MS = 20_000
+
+export function answerText(title: string, a: Answer) {
+  if (a.status === 'answered') return `The user answered "${title}":\n${JSON.stringify(a.data, null, 2)}`
+  if (a.status === 'dismissed' && a.reason === 'replaced') return `"${title}" was replaced by a newer question.`
+  if (a.status === 'dismissed') return `The user skipped "${title}" without answering.`
+  return `"${title}" is no longer open on the board; the user did not answer it.`
+}
+
+const askPath = (t: Target, id = '') =>
+  `/api/terminals/${encodeURIComponent(t.terminalId)}/ask${id ? `/${encodeURIComponent(id)}` : ''}`
+
+async function poll($: EngineInterface, t: Target, id: string): Promise<Answer | { deny: string }> {
+  const token = await terminalToken($, t.url)
+  if (!token) return { deny: `No terminal token for the cck server at ${t.url}.` }
+  try {
+    const res = await $.http.fetch(`${t.url}${askPath(t, id)}/wait?ms=${WAIT_MS}`, {
+      headers: { 'x-terminal-token': token },
+    })
+    if (!res.ok) return { deny: errorText(res.status, res.text) }
+    return JSON.parse(res.text) as Answer
+  } catch (err) {
+    return { deny: `Lost the cck board at ${t.url}: ${err instanceof Error ? err.message : String(err)}` }
+  }
+}
+
+async function cancel($: EngineInterface, t: Target, id: string) {
+  const token = await terminalToken($, t.url)
+  if (!token) return
+  try {
+    await $.http.fetch(`${t.url}${askPath(t, id)}`, { method: 'DELETE', headers: { 'x-terminal-token': token } })
+  } catch {}
+}
+
+// The call waits until the user answers or skips. An interrupt aborts `signal`: the hook stops at once
+// and closes the modal, because the dispatch has gone on without it.
+async function ask($: EngineInterface, t: Target, input: AskInput, signal: AbortSignal) {
+  const token = await terminalToken($, t.url)
+  if (!token) return { deny: `No terminal token for the cck server at ${t.url}. It must run with the terminal enabled.` }
+  const { title, file, size } = input
+  const opened = await send($, t.url, askPath(t), { 'x-terminal-token': token }, {
+    sessionId: await $.session.id(),
+    title,
+    file,
+    size,
+  })
+  if ('deny' in opened) return opened
+  const { id } = JSON.parse(opened.text) as { id: string }
+  const aborted = new Promise<'aborted'>((resolve) => {
+    if (signal.aborted) resolve('aborted')
+    signal.addEventListener('abort', () => resolve('aborted'), { once: true })
+  })
+  for (;;) {
+    const got = await Promise.race([poll($, t, id), aborted])
+    if (got === 'aborted') {
+      await cancel($, t, id)
+      return { deny: 'Interrupted; the question was closed.' }
+    }
+    if ('deny' in got) return got
+    if (got.status !== 'pending') return { result: answerText(title, got) }
+  }
+}
+
+const ASK_TOOL = {
+  description:
+    'Ask the user through an HTML card in a modal over this terminal, and wait for the answer, which comes back as the tool result: the data the card sent, as JSON, or a line that says the user skipped. For fixed choices, use AskUserQuestion; use ask when the answer needs something to see or control: a preview, a diagram, sliders, a long form, a quiz sheet, a playground. Load the claude-code-kanban:ask skill first: it says how to write the card and how it sends the answer. Write the card to an HTML file in your scratchpad, then pass it as file.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      title: { type: 'string', description: 'The question, short: it titles the modal and the chip that reopens it' },
+      file: { type: 'string', description: 'Absolute path of the HTML card' },
+      size: {
+        type: 'string',
+        enum: ['md', 'lg', 'full'],
+        description: 'Modal size: md for a short form, lg (default) for most cards, full for a playground or a quiz sheet',
+      },
+    },
+    required: ['title', 'file'],
+  },
+}
+
+// Only a session in cck's terminal has a board to draw the modal; elsewhere AskUserQuestion serves.
+export const register: Register = (on) => {
+  on('session.start', { isInteractive: true }, async ($, e, next) => {
+    if (await terminal($)) await $.tool.register({ name: 'ask', ...ASK_TOOL })
+    return next(e)
+  })
+
+  on('tool.call', { tool: TOOL }, async ($, e, next) => {
+    const t = await terminal($)
+    if (!t) return { deny: 'No cck board here: use AskUserQuestion.' }
+    return ask($, t, e as unknown as AskInput, next.signal)
+  })
+}

package/plugin/plugins/claude-code-kanban/hooks/index.ts

@@ -1,5 +1,6 @@
 import type { Register } from 'claude-code'
 import { register as activity } from './activity'
+import { register as ask } from './ask'
 import { register as context } from './context'
 import { register as doorbell } from './doorbell'
 import { register as show } from './show'
@@ -9,4 +10,5 @@ export const register: Register = (on, options) => {
   activity(on, options)
   doorbell(on, options)
   show(on, options)
+  ask(on, options)
 }

package/plugin/plugins/claude-code-kanban/skills/ask/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ask
+description: Ask card guide for the cck ask modal, an HTML question the user answers over the terminal. Cards can be a form, quiz sheet, sliders over a preview, a diagram to pick from, or a playground.
+argument-hint: '[playground|quiz|form] [what to ask]'
+---
+
+# Ask cards
+
+The `mcp__claude-code-kanban__ask` tool exists only in a Claude Code session started in cck's terminal. Without it, ask with AskUserQuestion.
+
+An argument names what to ask. A first word of `playground`, `quiz` or `form` sets the card kind; for a playground, read [references/playground.md](references/playground.md) and build one. With no argument, ask the open question of this conversation.
+
+The tool opens the card as a modal over the terminal and waits. The user's answer comes back as the tool result.
+
+## HTML contract
+
+- Write a body fragment to an `.html` file in your scratchpad: no `<!doctype>`, `<html>`, `<head>` or `<body>`. The modal wraps it in a sandboxed document. `<style>` and `<script>` work; the script has no network and no access to the page around it.
+- Pick the size with `size`: `md` 560 px wide for a short form, `lg` 960 px (default) for most cards, `full` the whole terminal for a playground or a quiz sheet. `md` and `lg` take the content's height up to the terminal's, then scroll, so keep their content in normal flow, without `position: fixed` or `100vh`. A `full` card always fills the terminal.
+- Open the card with an `<h2>` that states the question. The modal title is the short form of it.
+- Open links with `<a href="https://...">`; they open in a new browser tab.
+- Take every color and font from these variables, so the card follows the user's light or dark theme:
+
+| Variable | Use |
+|---|---|
+| `--color-bg`, `--color-bg-subtle` | Page and panel background |
+| `--color-text`, `--color-text-muted` | Body text, secondary text |
+| `--color-border` | Lines, box outlines |
+| `--color-accent` | The one thing to look at |
+| `--color-info`, `--color-success`, `--color-warning`, `--color-danger` | Status |
+| `--color-series-1` … `--color-series-8` | Chart series, in order |
+| `--color-ramp-1` … `--color-ramp-5` | One-hue magnitude, least to most |
+| `--font-sans`, `--font-mono` | Fonts |
+
+## Sending the answer
+
+- From a script: `cck.send(data)`, any JSON value, called from a click or a key press. Use it when the answer is state the card holds, such as a playground's settings or a quiz's picks.
+- From markup: a form `<form data-cck-submit="name">` sends `{action, label, fields}` on submit, with each input's `name` as a field; `required` works. A button `<button data-cck-action="name">` sends its action and label. Action names use letters, digits, `.`, `_` and `-`.
+- Put only the Send button where the card sends: the user's picks are already on screen.
+- Send once, with everything you need: the first answer ends the question. Make each value self-explanatory, so the result reads without the card.
+- A skip comes back as a line that says so. Go on without the answer, and ask in chat only if you cannot.
+
+## Exhibits in the card
+
+A picture the user answers about follows the show skill's guides, read before you draw: [chart](../show/references/chart.md), [diagram](../show/references/diagram.md), [mockup](../show/references/mockup.md). Their widths are for the narrower show card; the `size` above sets this one.

package/plugin/plugins/claude-code-kanban/skills/ask/references/playground.md

@@ -0,0 +1,25 @@
+# Playground
+
+A playground is an ask card with controls on one side and a live preview on the other. The user moves the controls until the preview looks right, then sends. The answer is the settings and a sentence that says what they mean. Post it with `size: "full"`.
+
+## Layout
+
+- Two columns: controls on the left, about 280 px, and the preview filling the rest. Below 720 px the columns stack, preview first.
+- Group the controls by concern under small headings. Put the rarely used ones in a `<details>` that starts closed.
+- Presets sit above the controls as a row of buttons: 3 to 5 named combinations that look good. The first one is the default, so the card looks right on first load.
+- One Send button closes the controls column. The card has no foot: the preview takes all the height.
+
+## State
+
+- Keep every setting in one `state` object, with a frozen `DEFAULTS` beside it.
+- One `draw()` builds the preview from `state`. Every control only writes to `state` and calls `draw()`; there is no Apply button.
+- Declare presets in markup, `<button data-preset='{"radius":8,"shadow":"soft"}'>Soft</button>`, and read them in one place. A new preset is one line of HTML.
+- Keep the computation apart from the drawing, so the preview and the summary read the same numbers.
+- Read colors from the theme variables on each draw, in canvas and SVG too.
+
+## The answer
+
+Send calls `cck.send({ summary, state })`:
+
+- `summary` is one short sentence, built at send time, that an agent can act on without the card: the last preset picked and only the settings that differ from it, with words next to the numbers ("a soft 8 px shadow"). Keep that preset in `state`, so the summary compares against it, not against `DEFAULTS`.
+- `state` is the full settings object, for exact values.

package/plugin/plugins/claude-code-kanban/tests/ask.test.ts

@@ -0,0 +1,100 @@
+import type { On, ToolCallArgs } from 'claude-code'
+import { expect, mock, test } from 'claude-code/testing'
+import { answerText, TOOL, WAIT_MS } from '../hooks/ask'
+
+const CCK_URL = 'http://127.0.0.1:4100'
+const TERMINAL_ID = 'term-1'
+const TOKEN_FILE = 'C:/cfg/.cck/terminal-tokens/4100.json'
+const ASK = `${CCK_URL}/api/terminals/${TERMINAL_ID}/ask`
+
+type Reply = { status: number; body: unknown }
+type Request = { url: string; method?: string; headers?: Record<string, string>; body?: unknown }
+
+// `replies` answers the ask routes in order; the doorbell's polls never settle.
+function engine(on: On, env: Record<string, string>, replies: Reply[] = []) {
+  const registered: string[] = []
+  const requests: Request[] = []
+  mock.clock(on)
+  on('env.get', (_$, e) => ({ value: { CLAUDE_CONFIG_DIR: 'C:/cfg', ...env }[e.name] }))
+  on('fs.read', (_$, e) => {
+    if (e.path.replaceAll('\\', '/') === TOKEN_FILE) return { value: '{"token":"tok-abc"}' }
+    throw new Error(`ENOENT: ${e.path}`)
+  })
+  on('session.id', () => ({ value: 'sid-1' }))
+  on('session.start', (_$, e) => ({ cwd: e.cwd }))
+  on('tool.register', (_$, e) => {
+    registered.push(e.name)
+    return { value: { tool: `mcp__claude-code-kanban__${e.name}` } }
+  })
+  on('http.fetch', (_$, e) => {
+    if (!e.url.includes('/ask')) return new Promise(() => {})
+    const { method, headers, body } = (e.init ?? {}) as Omit<Request, 'url'>
+    requests.push({ url: e.url, method, headers, body: typeof body === 'string' ? JSON.parse(body) : body })
+    const reply = replies.shift()
+    if (!reply) throw new Error('no reply')
+    return { value: { status: reply.status, ok: reply.status < 300, headers: {}, text: JSON.stringify(reply.body) } }
+  })
+  return { registered, requests }
+}
+
+const GATE = { CCK_URL, CCK_TERMINAL_ID: TERMINAL_ID }
+const call = (input: Record<string, unknown>) => ({ tool: TOOL, ...input }) as ToolCallArgs
+const START = { cwd: 'C:/proj', surface: 'terminal', isInteractive: true } as const
+
+test('answer lines', async () => {
+  expect(answerText('Pick', { status: 'answered', data: { a: 1 } })).toBe('The user answered "Pick":\n{\n  "a": 1\n}')
+  expect(answerText('Pick', { status: 'dismissed' })).toBe('The user skipped "Pick" without answering.')
+  expect(answerText('Pick', { status: 'dismissed', reason: 'replaced' })).toBe('"Pick" was replaced by a newer question.')
+  expect(answerText('Pick', { status: 'gone' })).toContain('no longer open')
+})
+
+test('only a session in the terminal gets the tool', async ($, on) => {
+  const board = engine(on, { CCK_URL })
+  await $.session.start(START)
+  expect(board.registered).toEqual(['show'])
+})
+
+test('in the terminal: registers ask beside show', async ($, on) => {
+  const board = engine(on, GATE)
+  await $.session.start(START)
+  expect(board.registered).toEqual(['show', 'ask'])
+})
+
+test('opens the question, polls past pending, and answers with the data', async ($, on) => {
+  const board = engine(on, GATE, [
+    { status: 200, body: { id: 'q1' } },
+    { status: 200, body: { status: 'pending' } },
+    { status: 200, body: { status: 'answered', data: { theme: 'light' } } },
+  ])
+  await $.session.start(START)
+  const res = await $.tool.call(call({ title: 'Pick a theme', file: 'C:/s/ask.html', size: 'full' }))
+  expect(res.result).toBe(answerText('Pick a theme', { status: 'answered', data: { theme: 'light' } }))
+  const headers = { 'x-terminal-token': 'tok-abc' }
+  expect(board.requests).toEqual([
+    {
+      url: ASK,
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...headers },
+      body: { sessionId: 'sid-1', title: 'Pick a theme', file: 'C:/s/ask.html', size: 'full' },
+    },
+    { url: `${ASK}/q1/wait?ms=${WAIT_MS}`, method: undefined, headers, body: undefined },
+    { url: `${ASK}/q1/wait?ms=${WAIT_MS}`, method: undefined, headers, body: undefined },
+  ])
+})
+
+test('a skip answers that the user skipped', async ($, on) => {
+  engine(on, GATE, [
+    { status: 200, body: { id: 'q1' } },
+    { status: 200, body: { status: 'dismissed' } },
+  ])
+  await $.session.start(START)
+  const res = await $.tool.call(call({ title: 'Pick', file: 'C:/s/ask.html' }))
+  expect(res.result).toBe('The user skipped "Pick" without answering.')
+})
+
+test('a board refusal reaches the model with its text', async ($, on) => {
+  engine(on, GATE, [{ status: 400, body: { error: 'file must be an HTML file' } }])
+  await $.session.start(START)
+  const res = await $.tool.call(call({ title: 'Pick', file: 'C:/s/ask.md' }))
+  expect(res.deny).toBe('file must be an HTML file')
+})

package/plugin/plugins/claude-code-kanban/tests/show.test.ts

@@ -56,7 +56,7 @@ test('helpers: the port of CCK_URL, the answer lines', async () => {
 test('in the terminal: the overlay tool, file optional', async ($, on) => {
   const board = engine(on, GATE)
   await $.session.start({ cwd: 'C:/proj', surface: 'terminal', isInteractive: true })
-  expect(board.registered).toEqual([{ name: 'show', required: ['title'] }])
+  expect(board.registered[0]).toEqual({ name: 'show', required: ['title'] })
 })
 
 test('outside the terminal: the pane tool, file required', async ($, on) => {

package/public/app.js

@@ -2808,7 +2808,7 @@ function isAnyModalOpen() {
 
 // An open modal owns the zoom keys even when it has nothing to scale.
 function isZoomableOnScreen() {
-  return isAnyModalOpen() ? isZoomableModalOpen() : isPaneDocOnScreen() || isShowCardFocused();
+  return isAnyModalOpen() ? isZoomableModalOpen() : isAskOnScreen() || isPaneDocOnScreen() || isShowCardFocused();
 }
 
 const ZOOM_KEYS = { '+': 0.1, '=': 0.1, NumpadAdd: 0.1, '-': -0.1, _: -0.1, NumpadSubtract: -0.1, 0: 0, Numpad0: 0 };
@@ -9073,6 +9073,7 @@ function reviewOptsOfFrame(frame) {
 
 async function sendPreviewAction(frame, msg) {
   if (!navigator.userActivation?.isActive) return;
+  if (frame === askState.frame) return answerAsk({ action: msg.action, label: msg.label, fields: msg.data });
   const opts = reviewOptsOfFrame(frame);
   if (!opts?.sessionId) return;
   const key = `${msg.action}\n${JSON.stringify(msg.data)}`;
@@ -10250,6 +10251,8 @@ function setupEventSource() {
 
       if (data.type === 'show:cleared') onShowCleared(data);
       if (data.type === 'show:removed') onShowRemoved(data);
+      if (data.type === 'ask:opened') onAskOpened(data);
+      if (data.type === 'ask:closed') onAskClosed(data);
 
       if (data.type === 'agent-update') {
         if (!data.unreadOnly) pendingAgentSessionIds.add(data.sessionId);
@@ -15214,9 +15217,10 @@ function inPageField(e) {
 function terminalShortcut(e, probe = false) {
   const ctrlAlt = hubModDown(e);
   const ctrlShift = e.ctrlKey && e.shiftKey && !e.altKey && !e.metaKey;
-  // Ctrl+_ is Claude Code's undo, so the zoom keys leave it to the terminal.
+  // Ctrl+_ is Claude Code's undo, so the zoom keys leave it to the terminal. An open ask card,
+  // which sits in the terminal pane, takes them for its own text zoom.
   const zoom = e.key === '_' ? undefined : zoomDelta(e);
-  if (zoom !== undefined && termFrame.inited && (probe || terminalPaneFocused())) {
+  if (zoom !== undefined && termFrame.inited && (probe || (terminalPaneFocused() && !isAskOnScreen()))) {
     return () => adjustTerminalFontSize(Math.sign(zoom));
   }
   if (ctrlAlt && e.code === 'KeyS') return swapToPreviousSession;
@@ -16417,6 +16421,177 @@ window.addEventListener('message', (e) => {
 
 //#endregion
 
+//#region ASK
+// The question the session in the embedded terminal asks with the ask tool; the tool call waits for
+// the answer. Hiding keeps the frame, so a half-filled card comes back as it was. Only an answer, a
+// skip or the agent's interrupt ends the question.
+const ASK_MSG = 'cck-ask:';
+const askState = { terminalId: null, ask: null, frame: null, frameH: 0, hidden: false, busy: false, seq: 0 };
+
+// Runs inside the card as source text, ahead of the card's own scripts. The JSON round trip makes
+// the answer cloneable, and a value that is not JSON throws in the card.
+function askBridge() {
+  window.cck = {
+    send: (data) => parent.postMessage({ type: 'cck-ask:send', data: JSON.parse(JSON.stringify(data ?? null)) }, '*'),
+  };
+}
+
+const ASK_BRIDGE_TAG = `<script>(${askBridge})();</script>`;
+
+function askEl() {
+  return document.getElementById('ask-modal');
+}
+
+function isAskOnScreen() {
+  return !!askState.ask && !askEl().hidden;
+}
+
+function syncAsk(tid) {
+  if (tid === askState.terminalId) return;
+  askState.terminalId = tid;
+  setAsk(null);
+  if (tid) loadAsk(tid);
+}
+
+async function loadAsk(tid) {
+  const seq = ++askState.seq;
+  const data = await getJson(apiPath`/api/terminals/${tid}/ask`, null, { cache: 'no-store' });
+  if (seq !== askState.seq || tid !== askState.terminalId) return;
+  const a = data?.ask ?? null;
+  if (a?.id !== askState.ask?.id) setAsk(a);
+}
+
+function setAsk(a) {
+  const modal = askEl();
+  const body = modal.querySelector('.ask-body');
+  Object.assign(askState, { ask: a, frame: null, frameH: 0, hidden: false, busy: false });
+  body.replaceChildren();
+  if (a) {
+    modal.querySelector('.ask-title').textContent = a.title;
+    modal.querySelector('.ask-box').dataset.size = a.size;
+    if (a.content == null) {
+      body.innerHTML = '<p class="ask-missing">The card file is gone. Skip, so the agent stops waiting.</p>';
+    } else {
+      const frame = createPreviewFrame('ask-frame', showSrcdoc(a.content, 0, ASK_BRIDGE_TAG), SHOW_SANDBOX);
+      frame.addEventListener('load', () => {
+        if (askState.frame === frame && !askState.hidden) frame.focus();
+      });
+      askState.frame = frame;
+      body.append(frame);
+    }
+  }
+  renderAsk();
+}
+
+function renderAsk() {
+  const a = askState.ask;
+  askEl().hidden = !a || askState.hidden;
+  const chip = document.getElementById('ask-reopen');
+  chip.hidden = !a || !askState.hidden;
+  if (a) {
+    chip.querySelector('.ask-reopen-n').textContent = a.title;
+    chip.title = `Open the question: ${a.title}`;
+  }
+  layoutAsk();
+}
+
+// A full card fills the modal; a smaller one takes its content's height, up to the terminal's.
+function layoutAsk() {
+  const frame = askState.frame;
+  const box = askEl().querySelector('.ask-box');
+  if (!frame || askEl().hidden || box.dataset.size === 'full') return;
+  const host = document.getElementById('terminal-host');
+  const chrome = box.querySelector('.ask-head').offsetHeight + box.querySelector('.ask-foot').offsetHeight + 2;
+  frame.style.height = `${Math.max(SHOW_MIN_H, Math.min(askState.frameH || SHOW_MIN_H, host.clientHeight - 32 - chrome))}px`;
+}
+
+function hideAsk() {
+  askState.hidden = true;
+  renderAsk();
+  focusTerminalPane();
+}
+
+function reopenAsk() {
+  askState.hidden = false;
+  renderAsk();
+  askState.frame?.focus();
+}
+
+async function endAsk(body) {
+  const a = askState.ask;
+  const tid = askState.terminalId;
+  if (!a || !tid || askState.busy) return;
+  askState.busy = true;
+  try {
+    const res = await terminalFetch(apiPath`/api/terminals/${tid}/ask/${a.id}`, 'POST', body);
+    if (res.status === 404) showToast('The question is no longer open');
+    else if (!res.ok) {
+      const out = await res.json().catch(() => ({}));
+      return showToast(out.error || `Send failed (HTTP ${res.status})`, 'error');
+    }
+    if (askState.ask?.id !== a.id) return;
+    setAsk(null);
+    focusTerminalPane();
+  } catch {
+    showToast('Failed to send the answer', 'error');
+  } finally {
+    if (askState.ask?.id === a.id) askState.busy = false;
+  }
+}
+
+function answerAsk(data) {
+  return endAsk({ status: 'answered', data });
+}
+
+function onAskOpened(d) {
+  if (typeof d.terminalId !== 'string') return;
+  if (d.terminalId === askState.terminalId) return loadAsk(d.terminalId);
+  if (askState.terminalId || !wantsTerminal()) return;
+  if (!terminalIds.has(currentSessionId)) showState.lookup = null;
+  syncShowCard();
+}
+
+function onAskClosed(d) {
+  if (d.terminalId !== askState.terminalId || askState.ask?.id !== d.id) return;
+  if (d.status === 'cancelled') showToast('The agent stopped waiting for the answer');
+  setAsk(null);
+}
+
+// A script can send without a click, so a send needs transient user activation, as a card action does.
+window.addEventListener('message', (e) => {
+  const frame = askState.frame;
+  if (!frame || e.source !== frame.contentWindow || typeof e.data?.type !== 'string') return;
+  if (e.data.type === `${ASK_MSG}send`) {
+    if (navigator.userActivation?.isActive) answerAsk(e.data.data);
+  } else if (e.data.type === `${SHOW_MSG}height`) {
+    askState.frameH = Number(e.data.h) || askState.frameH;
+    layoutAsk();
+  }
+});
+
+function initAsk() {
+  const modal = askEl();
+  modal.addEventListener('click', (e) => {
+    const cmd = e.target === modal ? 'hide' : e.target.closest('[data-ask]')?.dataset.ask;
+    if (cmd === 'hide') hideAsk();
+    else if (cmd === 'skip') endAsk({ status: 'dismissed' });
+  });
+  document.getElementById('ask-reopen').addEventListener('click', reopenAsk);
+  // Capture, ahead of the board's own Escape. The card's frame hands Escape back as a key on the frame.
+  window.addEventListener(
+    'keydown',
+    (e) => {
+      if (e.key !== 'Escape' || modal.hidden || !modal.contains(e.target)) return;
+      e.preventDefault();
+      e.stopImmediatePropagation();
+      hideAsk();
+    },
+    true,
+  );
+  window.addEventListener('resize', layoutAsk);
+}
+//#endregion
+
 //#region SHOW
 // The card the session in the embedded terminal posts to with the show tool. It belongs to the
 // terminal, not the session: /clear and the --resume picker change the session id, the terminal id
@@ -16629,6 +16804,7 @@ function syncShowCard() {
     loadTerminals().catch(() => {});
   }
   const tid = pty ? (terminalIds.get(pty) ?? null) : null;
+  syncAsk(tid);
   if (tid === showState.terminalId) return;
   const view = (tid && showViews[tid]) || { collapsed: true };
   Object.assign(showState, { terminalId: tid, sessionId: null, idx: 0 });
@@ -16882,8 +17058,8 @@ function withHeadFirst(content, head) {
 const FRAME_SCROLLBAR_CSS = ':where(html){scrollbar-width:thin;scrollbar-color:rgba(128,128,128,.45) transparent}';
 
 // A whole document gets the tokens and base styles first in its head, so its own styles win.
-function showSrcdoc(content, restoreY) {
-  const head = `<meta http-equiv="Content-Security-Policy" content="${SHOW_CSP}"><style>:root{${showTokenCss()}}${SHOW_FRAME_BASE}${FRAME_SCROLLBAR_CSS}</style>`;
+function showSrcdoc(content, restoreY, extraHead = '') {
+  const head = `<meta http-equiv="Content-Security-Policy" content="${SHOW_CSP}"><style>:root{${showTokenCss()}}${SHOW_FRAME_BASE}${FRAME_SCROLLBAR_CSS}</style>${extraHead}`;
   const bridge = `<script>(${showBridge})(${Math.max(0, Math.round(restoreY) || 0)}, ${modalZoom});</script>${REVIEW_BRIDGE_TAG}`;
   if (!/^\s*(<!doctype|<html)/i.test(content)) {
     return `<!doctype html><html><head><meta charset="utf-8">${head}</head><body>${content}${bridge}</body></html>`;
@@ -16989,7 +17165,7 @@ new MutationObserver(() => {
 
 // Builds the message only when a frame is there, because showTokens forces a style recalc.
 function postToShowFrames(makeMsg) {
-  const frames = [showState.frame, ...document.querySelectorAll('.show-pane-frame, .themed-frame')].filter(
+  const frames = [showState.frame, ...document.querySelectorAll('.show-pane-frame, .themed-frame, .ask-frame')].filter(
     (f) => f?.contentWindow,
   );
   if (!frames.length) return;
@@ -17929,6 +18105,7 @@ initSessionGroupsDnd();
 initSessionPicker();
 initProjectPicker();
 initShowCard();
+initAsk();
 for (const k of readStoredList(ACTIVITY_FILTER_KEY)) activityFilter.add(k);
 initSidebarResize();
 applyModalZoom();

package/public/index.html

@@ -362,6 +362,10 @@
         <div id="terminal-pane" class="terminal-pane">
           <div class="terminal-bar">
             <span id="terminal-status" class="terminal-status"></span>
+            <button id="ask-reopen" class="show-reopen ask-reopen" type="button" hidden>
+              <span class="ask-dot" aria-hidden="true">?</span>
+              <span class="ask-reopen-n"></span>
+            </button>
             <button id="show-reopen" class="show-reopen" type="button" title="Show the overlay" hidden>
               <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="4" width="18" height="16" rx="2"/><path d="M13 4v7h8"/></svg>
               <span class="show-reopen-n">show</span>
@@ -375,6 +379,23 @@
           </div>
           <div id="terminal-host" class="terminal-host">
             <section id="show-card" class="show-card" aria-label="Show overlay"></section>
+            <div id="ask-modal" class="ask-modal" hidden>
+              <section class="ask-box" role="dialog" aria-modal="true" aria-labelledby="ask-title">
+                <header class="ask-head">
+                  <span class="ask-dot" aria-hidden="true">?</span>
+                  <span id="ask-title" class="ask-title"></span>
+                  <span class="ask-hint">Esc hides</span>
+                  <button type="button" class="ask-x" data-ask="hide" title="Hide. The question stays open." aria-label="Hide">
+                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M18 6L6 18M6 6l12 12"/></svg>
+                  </button>
+                </header>
+                <div class="ask-body"></div>
+                <footer class="ask-foot">
+                  <span>The agent waits for your answer.</span>
+                  <button type="button" data-ask="skip">Skip</button>
+                </footer>
+              </section>
+            </div>
           </div>
           <textarea id="terminal-key-proxy" class="terminal-key-proxy" tabindex="-1" aria-hidden="true"></textarea>
         </div>

package/public/style.css

@@ -4460,6 +4460,181 @@ body.show-resizing iframe {
 
 /* #endregion */
 
+/* #region ASK */
+.ask-modal {
+  position: absolute;
+  inset: 0;
+  z-index: 5;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: color-mix(in srgb, var(--bg-deep) 55%, transparent);
+}
+
+.ask-modal[hidden] {
+  display: none;
+}
+
+.ask-box {
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  width: min(560px, calc(100% - 32px));
+  max-height: calc(100% - 32px);
+  background: var(--bg-surface);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  box-shadow: 0 12px 32px -12px rgba(0, 0, 0, 0.45);
+  overflow: hidden;
+}
+
+.ask-box[data-size='lg'] {
+  width: min(960px, calc(100% - 32px));
+}
+
+.ask-box[data-size='full'] {
+  width: calc(100% - 32px);
+  height: calc(100% - 32px);
+}
+
+.ask-head,
+.ask-foot {
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 8px 6px 12px;
+  color: var(--text-tertiary);
+  font-size: 11px;
+}
+
+.ask-head {
+  border-bottom: 1px solid var(--border);
+}
+
+.ask-foot {
+  justify-content: space-between;
+  border-top: 1px solid var(--border);
+}
+
+.ask-dot {
+  display: inline-grid;
+  place-items: center;
+  flex: none;
+  width: 16px;
+  height: 16px;
+  border-radius: 50%;
+  background: var(--accent);
+  color: #fff;
+  font-size: 10px;
+  font-weight: 700;
+}
+
+.ask-title {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  color: var(--text-primary);
+  font-size: 12px;
+  font-weight: 600;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.ask-x {
+  display: inline-grid;
+  place-items: center;
+  width: 22px;
+  height: 22px;
+  padding: 0;
+  border: 0;
+  border-radius: 4px;
+  background: transparent;
+  color: var(--text-tertiary);
+  cursor: pointer;
+}
+
+.ask-x svg {
+  width: 14px;
+  height: 14px;
+}
+
+.ask-foot button {
+  padding: 3px 12px;
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  background: transparent;
+  color: var(--text-secondary);
+  font: inherit;
+  cursor: pointer;
+}
+
+.ask-x:hover,
+.ask-foot button:hover {
+  background: var(--bg-hover);
+  color: var(--text-primary);
+}
+
+.ask-body {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  min-height: 0;
+}
+
+.ask-frame {
+  display: block;
+  width: 100%;
+  border: 0;
+  background: var(--bg-surface);
+}
+
+.ask-box[data-size='full'] .ask-frame {
+  flex: 1;
+}
+
+.ask-missing {
+  margin: 0;
+  padding: 16px;
+  color: var(--text-tertiary);
+}
+
+.ask-reopen {
+  max-width: 240px;
+  border-color: color-mix(in srgb, var(--accent) 50%, var(--border));
+  color: var(--text-secondary);
+}
+
+.ask-reopen-n {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.ask-reopen .ask-dot {
+  width: 14px;
+  height: 14px;
+  font-size: 9px;
+  animation: ask-pulse 1.6s ease-out infinite;
+}
+
+@keyframes ask-pulse {
+  0% {
+    box-shadow: 0 0 0 0 color-mix(in srgb, var(--accent) 60%, transparent);
+  }
+  100% {
+    box-shadow: 0 0 0 6px transparent;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ask-reopen .ask-dot {
+    animation: none;
+  }
+}
+
+/* #endregion */
+
 /* #region PANES */
 .pane-strip {
   display: none;

package/server.js

@@ -51,6 +51,7 @@ const { createTerminalClient } = require('./lib/terminal-client');
 const { kanbotOn, kanbotModel, createKanbot, findCostCli, readCostServer } = require('./lib/kanbot');
 const { AGENT_ID_RE } = require('./cli');
 const { createShowStore, mountShowRoutes, showBodyParser, SHOW_PATH } = require('./lib/show');
+const { createAskStore, mountAskRoutes, askBodyParser, ASK_PATH } = require('./lib/ask');
 const { readLiveSessions, isPidAlive, noteReplacedSessions } = require('./lib/live-sessions');
 const { createProcStats } = require('./lib/proc-stats');
 const { createUserGroupStore } = require('./lib/user-groups');
@@ -666,6 +667,7 @@ app.param('name', (_req, res, next, val) => {
 });
 
 app.use(SHOW_PATH, showBodyParser());
+app.use(ASK_PATH, askBodyParser());
 // Parse JSON bodies. A review of 50 comments at the field caps is about 450 kB.
 app.use(express.json({ limit: '1mb' }));
 // #endregion
@@ -3326,6 +3328,7 @@ let savedTerminals = terminalsFile.load() || {};
 function saveTerminals() {
   const kept = new Set(Object.values(savedTerminals.terminalIds || {}));
   const showSessions = show.prune((id) => kept.has(id) || terminal.hasTerminal(id));
+  ask.prune((id) => terminal.hasTerminal(id));
   terminalsFile.save({ ...savedTerminals, showSessions });
 }
 
@@ -3460,6 +3463,14 @@ mountShowRoutes(app, {
   broadcast,
   onRemoved: (sessionId, paths) => panes.removeShow(sessionId, paths),
 });
+const ask = createAskStore();
+mountAskRoutes(app, {
+  store: ask,
+  authorized: (token) => terminal.authorized(token),
+  hasTerminal: (id) => terminal.hasTerminal(id),
+  readPreviewFile,
+  broadcast,
+});
 
 // Served from node_modules, never a CDN: any script on this page can use the token.
 const XTERM_FILES = {