claude-code-kanban 4.19.0 → 4.21.0

package/README.md

@@ -30,7 +30,15 @@ npx claude-code-kanban --open
 
 ### 3. Use Claude Code as usual
 
-Tasks, agents, and messages appear on the board automatically — Claude Code writes task files and conversation logs to `~/.claude`, the dashboard watches them and streams updates to the browser via SSE. It never directs Claude's work.
+Tasks, agents, and messages appear on the board automatically — Claude Code writes task files and conversation logs to `~/.claude`, the dashboard watches them and streams updates to the browser via SSE. Moving a card is the one thing that flows the other way: the board notifies the owning session with the card subject and description, so the agent can act on it.
+
+> **Empty board?** Claude Code ships the task tools off by default on some models — currently Opus 5, Fable 5 — so nothing writes task files and the board stays empty. Turn them on in `~/.claude/settings.json`:
+>
+> ```json
+> { "env": { "CLAUDE_CODE_ENABLE_TODO_TOOLS": "true" } }
+> ```
+>
+> Then restart Claude Code. You can also add a task by hand from the board's Pending column.
 
 ## Features
 
@@ -41,6 +49,7 @@ Tasks, agents, and messages appear on the board automatically — Claude Code wr
 - **Follow & pin** — Follow the latest message live (`Shift+M`), pin the messages that matter
 - **Tool stats & impact** — Per-session tool usage breakdown and file impact
 - **Waiting-for-user indicators** — Amber highlight on sessions needing permission or input
+- **UI approvals (opt-in)** — Allow/deny permission asks and answer questions from the board — [docs](docs/ui-approvals.md)
 - **Agent teams** — Color-coded team members, owner filtering, member count badges
 - **17 color themes** — Dracula, Nord, Catppuccin, Gruvbox, Tokyo Night, and more — each in light and dark
 - **Storage manager** — Inspect disk usage and clean up stale sessions and tasks

package/lib/approvals.js

@@ -0,0 +1,82 @@
+// UI-driven approvals (_plans/cck-ui-approvals/): approval-gate.sh writes the
+// _waiting.json marker with a request id (D8) and polls for _decision-<id>.json.
+// buildDecision validates a board response against the live marker and shapes
+// the decision file; the route writes it. The hook deletes marker + decision on
+// consumption; orphans from a terminal deny (D13) are left for the sweep.
+
+// Ids are hook-minted (uuidgen or a time-pid-random compound) — anything outside
+// this alphabet is either corruption or a path-traversal attempt (3.5).
+function sanitizeRequestId(raw) {
+  return typeof raw === 'string' && /^[a-zA-Z0-9-]{1,64}$/.test(raw) ? raw : null;
+}
+
+// A decision whose shape doesn't match the ask's kind produces hook output
+// Claude Code rejects, surfacing as an opaque stall — reject at the API
+// boundary instead (D7). Returns { error, status } or { decision }.
+function buildDecision(marker, body) {
+  if (!marker || marker.status !== 'waiting') {
+    return { error: 'No pending ask', status: 410 };
+  }
+  const id = sanitizeRequestId(body && body.id);
+  if (!id) return { error: 'Invalid or missing request id', status: 400 };
+  if (marker.id !== id) return { error: 'Ask superseded by a newer one', status: 409 };
+
+  if (marker.kind === 'question') {
+    if (!body.answers || typeof body.answers !== 'object') {
+      return { error: 'A question ask needs answers', status: 422 };
+    }
+    // Partial answers are allowed — Claude reads the answered keys and treats
+    // the rest as skipped. Only a completely empty object is a no-op ask.
+    // multiSelect answers arrive as arrays of labels — Claude Code validates
+    // that shape natively.
+    const usable = (v) =>
+      (typeof v === 'string' && v) ||
+      (Array.isArray(v) && v.length > 0 && v.every((x) => typeof x === 'string' && x));
+    const given = Object.entries(body.answers).filter(([, v]) => usable(v));
+    if (!given.length) {
+      return { error: 'A question ask needs at least one answer', status: 422 };
+    }
+    return { decision: { answers: Object.fromEntries(given) } };
+  }
+
+  if (body.behavior !== 'allow' && body.behavior !== 'deny') {
+    return { error: 'A permission ask needs behavior "allow" or "deny"', status: 422 };
+  }
+  const decision = { behavior: body.behavior };
+  if (typeof body.message === 'string' && body.message) decision.message = body.message;
+  if (body.updatedInput && typeof body.updatedInput === 'object') decision.updatedInput = body.updatedInput;
+  if (Array.isArray(body.updatedPermissions)) decision.updatedPermissions = body.updatedPermissions;
+  return { decision };
+}
+
+function decisionFileName(id) {
+  return `_decision-${id}.json`;
+}
+
+// Keep in sync with decisionFileName — the cleanup sweep matches by shape
+function isDecisionFile(name) {
+  return name.startsWith('_decision-') && name.endsWith('.json');
+}
+
+// approval-gate.sh only polls for a decision for waitSeconds — after that the
+// ask belongs to the terminal. Default and clamp mirror the gate's own parse
+// (PERMISSION_TTL_MS hides the card at 30 min, so waiting longer than the UI
+// can show the ask is strictly worse — D11); keep them in sync with
+// approval-gate.sh.
+const WAIT_SECONDS_DEFAULT = 30;
+const WAIT_SECONDS_MAX = 1800;
+// Small grace over the gate's own deadline so a race never 410s a live hook
+const LAPSE_GRACE_MS = 5000;
+
+function waitSecondsFrom(cfg) {
+  const raw = cfg && cfg.waitSeconds;
+  if (Number.isInteger(raw) && raw >= 0) return Math.min(raw, WAIT_SECONDS_MAX);
+  return WAIT_SECONDS_DEFAULT;
+}
+
+function isLapsed(timestamp, waitMs, now = Date.now()) {
+  if (!timestamp) return true;
+  return now - new Date(timestamp).getTime() > waitMs + LAPSE_GRACE_MS;
+}
+
+module.exports = { sanitizeRequestId, buildDecision, decisionFileName, isDecisionFile, waitSecondsFrom, isLapsed };

package/lib/session-events.js

@@ -0,0 +1,99 @@
+// Session event doorbell: tells a live session that the board moved one of its tasks.
+// Its own module so the behaviour is unit-testable without booting the server -- the
+// bucket-map invariants here are the difference between a bounded queue and a map that
+// grows one permanent entry per session id ever named in a request path.
+
+// Tells a live session that the board moved one of its tasks. The postman monitor
+// (plugin/plugins/claude-code-kanban/scripts/postman.js) drains this queue and prints
+// each line, which Claude Code delivers into that session as a task notification.
+//
+// Deliberately in-memory and lossy. The task file is the durable command -- a dropped
+// event only means the agent notices on its next turn instead of immediately -- so a
+// disk queue would buy nothing. Reading consumes, so a restarted postman never replays
+// a backlog and acts on the same move twice.
+//
+// A bucket exists only while it holds something: an undelivered line or a waiting
+// poller. Without that, the map would grow one permanent entry per session id ever
+// asked for -- and the id comes straight off the request path.
+const sessionEventBuckets = new Map();
+
+// The line reaches the model verbatim at hook trust level. The task id is caller-supplied
+// and the subject and description are board-authored, so the length cap and the
+// control-character scrub are what hold the one-line-per-event contract: a newline inside
+// a description becomes a space rather than a second forged event.
+//
+// One cap for the whole line rather than one per field, because the description comes
+// last: truncation eats its tail first and leaves the machine-readable head intact.
+function sanitizeEventLine(line) {
+  return line.replace(/[\x00-\x1f\x7f]/g, ' ').trim().slice(0, 1500);
+}
+
+// Everything after `description=` is the description verbatim to end of line, so no amount
+// of board text can pose as a further field. That leaves the subject as the only value
+// that needs delimiting.
+function formatTaskMoved(taskId, prevStatus, task) {
+  const subject = String(task.subject || '').replace(/(["\\])/g, '\\$1');
+  const head = `cck:1 task.moved ${taskId} ${prevStatus || 'none'}>${task.status} subject="${subject}"`;
+  return task.description ? `${head} description=${task.description}` : head;
+}
+
+function enqueueSessionEvent(sessionId, line) {
+  const text = sanitizeEventLine(line);
+  if (!sessionId || !text) return;
+  let bucket = sessionEventBuckets.get(sessionId);
+  if (!bucket) {
+    bucket = { queue: [], waiters: new Set() };
+    sessionEventBuckets.set(sessionId, bucket);
+  }
+  bucket.queue.push(text);
+  // A session with no postman attached must not grow without bound.
+  if (bucket.queue.length > 50) bucket.queue.splice(0, bucket.queue.length - 50);
+  for (const wake of [...bucket.waiters]) wake();
+}
+
+// Long-poll drained by the postman monitor. Routing stays in server.js; this is the handler.
+function handleSessionEvents(req, res) {
+  const { sessionId } = req.params;
+  const bucket = sessionEventBuckets.get(sessionId);
+  const wait = Math.min(Math.max(Number(req.query.wait) || 0, 0), 120);
+
+  // A postman is armed by a skill invocation, so it can attach long after the board moved
+  // something. Those lines are read as instructions, and an hours-old instruction is worse
+  // than no instruction, so the grant starts the session's history rather than inheriting
+  // it: `first=1` drops the whole backlog. drain() (not a bare truncate) so an emptied
+  // bucket is still evicted from the map.
+  if (bucket && req.query.first === '1') drain(sessionId, bucket);
+
+  if (bucket && bucket.queue.length) return res.json({ events: drain(sessionId, bucket) });
+  if (!wait) return res.json({ events: [] });
+
+  const pending = bucket || { queue: [], waiters: new Set() };
+  sessionEventBuckets.set(sessionId, pending);
+
+  const send = () => {
+    // Set.delete is the whole idempotency story: whichever of enqueue, timeout, or
+    // client disconnect gets here first is the one that answers.
+    if (!pending.waiters.delete(send)) return;
+    clearTimeout(timer);
+    req.removeListener('close', send);
+    const events = drain(sessionId, pending);
+    if (!res.writableEnded) res.json({ events });
+  };
+  const timer = setTimeout(send, wait * 1000);
+  pending.waiters.add(send);
+  req.on('close', send);
+}
+
+function drain(sessionId, bucket) {
+  const events = bucket.queue.splice(0);
+  if (!bucket.queue.length && !bucket.waiters.size) sessionEventBuckets.delete(sessionId);
+  return events;
+}
+
+module.exports = {
+  sessionEventBuckets,
+  sanitizeEventLine,
+  formatTaskMoved,
+  enqueueSessionEvent,
+  handleSessionEvents,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "4.19.0",
+  "version": "4.21.0",
   "description": "A web-based Kanban board for viewing Claude Code tasks with agent teams support",
   "main": "server.js",
   "bin": {
@@ -10,7 +10,7 @@
     "start": "node server.js",
     "dev": "node --watch server.js",
     "test": "node --test test/*.test.js",
-    "test:hooks": "bash tests/test-agent-spy.sh",
+    "test:hooks": "bash tests/test-agent-spy.sh && bash tests/test-approval-gate.sh",
     "validate:schemas": "node test/validate-live-schemas.js",
     "prepare": "husky"
   },

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

@@ -1,5 +1,8 @@
 {
   "name": "claude-code-kanban",
-  "version": "2.3.3",
-  "description": "claude-code-kanban dashboard integration: agent activity tracking, context statusline, and a skill to drive the board from a session"
+  "version": "2.10.0",
+  "description": "claude-code-kanban dashboard integration: agent activity tracking, context statusline, skills to drive the board from a session and to follow it",
+  "experimental": {
+    "monitors": "./monitors.json"
+  }
 }

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

@@ -54,30 +54,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh",
-            "timeout": 5
-          }
-        ]
-      }
-    ],
-    "PreToolUse": [
-      {
-        "matcher": "AskUserQuestion",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh",
-            "timeout": 5
-          }
-        ]
-      },
-      {
-        "matcher": "ExitPlanMode",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh",
-            "timeout": 5
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/approval-gate.sh",
+            "timeout": 86400
           }
         ]
       }

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

@@ -0,0 +1,8 @@
+[
+  {
+    "name": "kanban-doorbell",
+    "description": "Notifies this session when its tasks are moved on the kanban board.",
+    "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/postman.js\"",
+    "when": "on-skill-invoke:claude-code-kanban:kanban-follow"
+  }
+]

package/plugin/plugins/claude-code-kanban/scripts/agent-spy.sh

@@ -47,6 +47,15 @@ fi
 # EnterPlanMode has no waiting semantics — skip
 [ "$TOOL_NAME" = "EnterPlanMode" ] && exit 0
 
+# Legacy-config shim: shipped hooks.json routes PermissionRequest to
+# approval-gate.sh (which owns the id-bearing marker) and registers no
+# PreToolUse, so the suppression and writer below only run for configs that
+# still route those events here. Suppressing question/plan PermissionRequest
+# keeps such a config from overwriting the gate's marker with an id-less one.
+if [ "$EVENT" = "PermissionRequest" ] && { [ "$TOOL_NAME" = "AskUserQuestion" ] || [ "$TOOL_NAME" = "ExitPlanMode" ]; }; then
+  exit 0
+fi
+
 # Waiting-for-user events → write _waiting.json marker
 if [ "$EVENT" = "PermissionRequest" ] || { [ "$EVENT" = "PreToolUse" ] && { [ "$TOOL_NAME" = "AskUserQuestion" ] || [ "$TOOL_NAME" = "ExitPlanMode" ]; }; }; then
   DIR="$CCK_ACTIVITY/$SESSION_ID"
@@ -103,12 +112,17 @@ if [ "$EVENT" = "SubagentStart" ]; then
   fi
 
 elif [ "$EVENT" = "SubagentStop" ]; then
+  # Omit empty type: the server folds lines last-key-wins, so an empty type
+  # here would clobber the type recorded by the start line
   echo "$INPUT" | jq -c \
     --arg id "$AGENT_ID" --arg type "$AGENT_TYPE_RAW" --arg ts "$TS" \
-    '{agentId: $id, type: $type, event: "stop", status: "stopped",
-      lastMessage: (.last_assistant_message // ""), stoppedAt: $ts, updatedAt: $ts}' \
+    '{agentId: $id, event: "stop", status: "stopped",
+      lastMessage: (.last_assistant_message // ""), stoppedAt: $ts, updatedAt: $ts}
+     + (if $type == "" then {} else {type: $type} end)' \
     >> "$FILE"
 
 elif [ "$EVENT" = "TeammateIdle" ]; then
-  echo "{\"agentId\":\"$AGENT_ID\",\"type\":\"$AGENT_TYPE_RAW\",\"event\":\"idle\",\"status\":\"idle\",\"updatedAt\":\"$TS\"}" >> "$FILE"
+  TYPE_FIELD=""
+  [ -n "$AGENT_TYPE_RAW" ] && TYPE_FIELD="\"type\":\"$AGENT_TYPE_RAW\","
+  echo "{\"agentId\":\"$AGENT_ID\",${TYPE_FIELD}\"event\":\"idle\",\"status\":\"idle\",\"updatedAt\":\"$TS\"}" >> "$FILE"
 fi

package/plugin/plugins/claude-code-kanban/scripts/approval-gate.sh

@@ -0,0 +1,141 @@
+#!/bin/bash
+# Blocking approval gate: lets the cck board answer a permission ask or an
+# AskUserQuestion. Always writes the _waiting.json marker first (badge behavior
+# is unchanged when the feature is off), then — only when explicitly enabled and
+# the board's server is alive — waits for a decision file written by the server.
+#
+# Contract (_plans/cck-ui-approvals/decisions.md):
+#   marker    ~/.claude/.cck/agent-activity/<sid>/_waiting.json            (D8: + id, cwd, permissionSuggestions)
+#   decision  ~/.claude/.cck/agent-activity/<sid>/_decision-<id>.json      (server writes it, Phase 3)
+#   config    ~/.claude/.cck/approvals.json {enabled, mode, waitSeconds}   (D2: fail-open when absent)
+#   liveness  ~/.claude/.cck/server.json {port, pid}                       (D1: a dead board costs nothing)
+#
+# First writer wins (D5): a terminal answer deletes the marker via PostToolUse
+# and this gate exits silently; a decision arriving after the tool already ran
+# is discarded by Claude Code, so a losing write on either side is harmless.
+
+INPUT=$(cat)
+
+eval "$(echo "$INPUT" | jq -r '
+  @sh "SESSION_ID=\(.session_id // "")",
+  @sh "EVENT=\(.hook_event_name // "")",
+  @sh "TOOL_NAME=\(.tool_name // "")"
+')"
+
+[ -z "$SESSION_ID" ] && exit 0
+
+# AskUserQuestion and ExitPlanMode gate on PermissionRequest, not PreToolUse:
+# the TUI question and plan dialogs render ~10 s in while a PermissionRequest
+# hook blocks (first writer wins, like permissions), but stay frozen for the
+# whole wait during a PreToolUse hook — measured live (#42, #40). Suppress the
+# PreToolUse double-fire in case a stale hooks.json still registers it.
+if [ "$EVENT" = "PreToolUse" ]; then
+  exit 0
+fi
+
+KIND="permission"
+[ "$TOOL_NAME" = "AskUserQuestion" ] && KIND="question"
+[ "$TOOL_NAME" = "ExitPlanMode" ] && KIND="plan"
+
+CCK_DIR="$HOME/.claude/.cck"
+DIR="$CCK_DIR/agent-activity/$SESSION_ID"
+MARKER="$DIR/_waiting.json"
+mkdir -p "$DIR"
+
+# uuidgen is missing on some Git Bash installs; uniqueness only has to hold
+# across the asks of one session, so a timestamp compound is enough
+REQ_ID=$(uuidgen 2>/dev/null) || REQ_ID="$(date +%s%N)-$$-$RANDOM"
+
+TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+echo "$INPUT" | jq -c --arg kind "$KIND" --arg ts "$TS" --arg id "$REQ_ID" '{
+  status: "waiting",
+  kind: $kind,
+  id: $id,
+  toolName: (.tool_name // "unknown"),
+  toolInput: ((.tool_input | tostring) // ""),
+  cwd: (.cwd // ""),
+  permissionSuggestions: (.permission_suggestions // []),
+  timestamp: $ts
+}' > "$MARKER"
+
+# Every exit below leaves the marker in place for the badge; agent-spy.sh's
+# PostToolUse (or the server's TTL) retires it, exactly as before this feature.
+
+CONFIG="$CCK_DIR/approvals.json"
+[ -f "$CONFIG" ] || exit 0
+ENABLED=""
+eval "$(jq -r '
+  @sh "ENABLED=\(.enabled // false)",
+  @sh "MODE=\(.mode // "permission")",
+  @sh "WAIT_SECONDS=\(.waitSeconds // 30)"
+' < "$CONFIG" 2>/dev/null)"
+[ "$ENABLED" = "true" ] || exit 0
+
+if [ "$KIND" = "question" ] && [ "$MODE" != "permission+question" ]; then
+  exit 0
+fi
+
+case "$WAIT_SECONDS" in *[!0-9]* | "") WAIT_SECONDS=30 ;; esac
+# PERMISSION_TTL_MS hides the card at 30 min — waiting longer than the UI can
+# show the ask is strictly worse than giving up (D11)
+[ "$WAIT_SECONDS" -gt 1800 ] && WAIT_SECONDS=1800
+
+SERVER_INFO="$CCK_DIR/server.json"
+[ -f "$SERVER_INFO" ] || exit 0
+SERVER_PORT=$(jq -r '.port // empty' < "$SERVER_INFO" 2>/dev/null)
+[ -n "$SERVER_PORT" ] || exit 0
+# A TCP connect beats a pid probe: it proves the board is actually serving, and
+# it works in the stripped environment Claude Code spawns hooks into, where
+# kill -0 cannot see native Windows pids and ps may be missing from PATH
+(: < "/dev/tcp/127.0.0.1/$SERVER_PORT") 2>/dev/null || exit 0
+
+DECISION="$DIR/_decision-$REQ_ID.json"
+# EPOCHSECONDS (bash 5) keeps the poll loop free of `date` spawns
+DEADLINE=$((EPOCHSECONDS + WAIT_SECONDS))
+
+while :; do
+  if [ -f "$DECISION" ]; then
+    PAYLOAD=$(cat "$DECISION" 2>/dev/null)
+    rm -f "$DECISION" "$MARKER"
+    [ -n "$PAYLOAD" ] || exit 0
+    if [ "$KIND" = "plan" ] && [ "$(echo "$PAYLOAD" | jq -r '.behavior // "deny"' 2>/dev/null)" = "allow" ]; then
+      # A plan allow must echo tool_input as updatedInput — Claude Code
+      # >= 2.1.199 silently drops an ExitPlanMode allow without it and falls
+      # back to the built-in dialog (measured; plannotator does the same).
+      echo "$INPUT" | jq -c --argjson p "$PAYLOAD" \
+        '{hookSpecificOutput: {hookEventName: "PermissionRequest",
+          decision: ({behavior: "allow", updatedInput: (.tool_input // {})}
+          + (if $p.updatedPermissions then {updatedPermissions: $p.updatedPermissions} else {} end))}}' 2>/dev/null
+    elif [ "$KIND" != "question" ]; then
+      # Permission asks and plan denies share this shaping — the server sends
+      # only behavior+message for a plan deny. PermissionRequest decisions must
+      # ride hookSpecificOutput — a top-level {decision} is the approve/block
+      # string channel and an object there throws
+      echo "$PAYLOAD" | jq -c '{hookSpecificOutput: {hookEventName: "PermissionRequest",
+        decision: ({behavior: (.behavior // "deny")}
+        + (if .message then {message: .message} else {} end)
+        + (if .updatedInput then {updatedInput: .updatedInput} else {} end)
+        + (if .updatedPermissions then {updatedPermissions: .updatedPermissions} else {} end))}}' 2>/dev/null
+    else
+      # updatedInput replaces the whole input object, so echo every field and
+      # add the answers Claude never fills in itself (D6). Questions ride the
+      # PermissionRequest channel now (#42) — allow with the answers filled in.
+      ANSWERS=$(echo "$PAYLOAD" | jq -c '.answers // empty' 2>/dev/null)
+      [ -n "$ANSWERS" ] || exit 0
+      echo "$INPUT" | jq -c --argjson answers "$ANSWERS" \
+        '{hookSpecificOutput: {hookEventName: "PermissionRequest",
+          decision: {behavior: "allow", updatedInput: ((.tool_input // {}) + {answers: $answers})}}}' 2>/dev/null
+    fi
+    exit 0
+  fi
+
+  # Marker gone = answered in the terminal (PostToolUse fires ~23 ms after — D5);
+  # id changed = displaced by a newer ask (D8). Either way this gate is over.
+  # Builtin read + substring match instead of jq: a spawn costs ~280 ms on
+  # Windows (O2), and the marker is single-line jq -c output with a known id.
+  IFS= read -r CUR_MARKER < "$MARKER" 2>/dev/null || exit 0
+  case "$CUR_MARKER" in *"\"id\":\"$REQ_ID\""*) ;; *) exit 0 ;; esac
+
+  [ "$EPOCHSECONDS" -ge "$DEADLINE" ] && exit 0
+  sleep 0.5
+done

package/plugin/plugins/claude-code-kanban/scripts/postman.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// Kanban -> session doorbell.
+//
+// Claude Code delivers every line a monitor prints to the owning session as a task
+// notification, so this process is the only way board activity can reach a session that
+// is sitting idle. It long-polls the kanban server for events addressed to this session
+// and prints them one per line.
+//
+// Pairing is free: CLAUDE_CODE_SESSION_ID is inherited from the session that spawned us,
+// so the id we poll with is the same id the hooks report. No cwd or pid guessing.
+//
+// The lines we print carry board text (the card subject and description), which the
+// session is told to read as the user's own brief. That is only safe because we are armed
+// by an explicit `kanban-follow` invocation: the user asked to follow the board before anything the
+// board says can reach the model.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SESSION_ID = process.env.CLAUDE_CODE_SESSION_ID;
+const SERVER_INFO = path.join(os.homedir(), '.claude', '.cck', 'server.json');
+// The server caps its own wait at 120s. Sitting at the ceiling halves every recurring
+// cost -- handshake, route walk, timer, empty response -- and costs no event latency,
+// because an enqueue wakes the poll immediately.
+const WAIT_SEC = 120;
+const RETRY_MS = 15000;
+
+if (!SESSION_ID) process.exit(0);
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// Re-read every cycle rather than caching: it is how we follow the board across a
+// restart onto a different port. A file left behind by a crashed server names a port
+// something else may now hold, so trust it only while its pid is alive.
+function serverUrl() {
+  const { port, pid } = JSON.parse(fs.readFileSync(SERVER_INFO, 'utf8'));
+  if (pid) process.kill(pid, 0);
+  return `http://127.0.0.1:${port}`;
+}
+
+// Once per process, not once per poll: the grant means "follow the board from here on", so
+// the first attach throws away whatever queued up before it. A later reconnect must not
+// discard again -- by then the queue holds events the user is owed.
+let firstAttach = true;
+
+async function poll(base) {
+  const first = firstAttach ? '&first=1' : '';
+  const url = `${base}/api/sessions/${encodeURIComponent(SESSION_ID)}/events?wait=${WAIT_SEC}${first}`;
+  const res = await fetch(url, { signal: AbortSignal.timeout((WAIT_SEC + 15) * 1000) });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  firstAttach = false;
+  const { events } = await res.json();
+  return Array.isArray(events) ? events : [];
+}
+
+(async () => {
+  for (;;) {
+    try {
+      for (const line of await poll(serverUrl())) console.log(line);
+    } catch (_) {
+      // No board yet, or it went away. It may come back later in the session, so keep
+      // waiting quietly -- a missing server is the normal case, not an error.
+      await sleep(RETRY_MS);
+    }
+  }
+})();

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

@@ -1,60 +1,53 @@
 ---
 name: kanban
-description: Drive the claude-code-kanban dashboard from this session — focus the current session in the browser, pin/unpin it in the sidebar, preview a markdown or HTML file, link a document to the session, or inspect session stats and messages. Use when the user mentions kanban or cck.
+description: Drive the kanban board — open, pin, preview, link, inspect.
 argument-hint: '[open|pin|unpin|preview|link] [target]'
+disable-model-invocation: true
 ---
 
 # Kanban Skill
 
-The current Claude session id is `${CLAUDE_SESSION_ID}` (substituted when this skill loads), so the user never needs to look it up.
+This session id is `${CLAUDE_SESSION_ID}`, substituted when the skill loads.
 
-When the user passes arguments, map them to the matching command below (`open` → `session open`, `pin`/`unpin`/`pins` → `session pin`/`--unpin`/`session pins`, `preview` → `preview-doc`, `link` → `link-doc`, `list`/`view`/`peek` → the read-only verbs); with no arguments, open the current session.
+An argument names the section below that handles it; with no argument, open the current session. Prefer the bare `claude-code-kanban` binary, falling back to `npx claude-code-kanban` when it is off PATH or the user asks for npx.
 
-Prefer the bare `claude-code-kanban` binary; fall back to `npx claude-code-kanban` when it is not on PATH, or when the user asks for npx explicitly.
+To be driven *by* the board instead — card moves arriving as instructions — the user types `/claude-code-kanban:kanban-follow`.
 
-## Open the current session in kanban
+## `open` — the current session
 
-Primary use case. Pins the active session in the sidebar and switches to the Active tab.
+Pins the session and switches the board to the Active tab.
 
 ```bash
 claude-code-kanban session open ${CLAUDE_SESSION_ID}
 ```
 
-## Pin the current session
-
-Pins the session so it stays visible regardless of filters. Three states: `pinned` (default), `sticky` (always at the top), or cleared with `--unpin`.
+## `pin` — keep the session visible
 
 ```bash
 claude-code-kanban session pin ${CLAUDE_SESSION_ID}            # pin
-claude-code-kanban session pin ${CLAUDE_SESSION_ID} --sticky   # sticky at top
+claude-code-kanban session pin ${CLAUDE_SESSION_ID} --sticky   # always at the top
 claude-code-kanban session pin ${CLAUDE_SESSION_ID} --unpin    # clear
+claude-code-kanban session pins                                # list pinned; --sticky narrows
 ```
 
-## List pinned sessions
-
-```bash
-claude-code-kanban session pins              # all pinned/sticky
-claude-code-kanban session pins --sticky     # sticky only
-```
-
-## Preview a file in kanban
+## `preview` — open a file in the modal
 
-Opens a markdown or standalone HTML file in the preview modal (HTML renders live in a sandboxed iframe, so sibling assets like `./style.css` do not load). Relative paths are fine — the server resolves to absolute.
+Markdown or standalone HTML. HTML renders in a sandboxed iframe, so sibling assets like `./style.css` do not load. Relative paths are fine — the server resolves them.
 
 ```bash
-claude-code-kanban preview-doc <path-to-file.md|.html> --session ${CLAUDE_SESSION_ID}
+claude-code-kanban preview-doc <file.md|.html> --session ${CLAUDE_SESSION_ID}
 ```
 
-## Link a document to the session (no modal)
+## `link` — attach a doc without the modal
 
-Same idea as `preview-doc`, but it only attaches the file to the session's linked docs in the sidebar — nothing pops up, so it is the safe choice while the user is working. Any extension is linkable.
+Adds the file to the session's linked docs in the sidebar. Any extension, and nothing pops up, so it is the safe choice while the user is working.
 
 ```bash
-claude-code-kanban link-doc <path-to-file> --session ${CLAUDE_SESSION_ID}            # link
-claude-code-kanban link-doc <path-to-file> --session ${CLAUDE_SESSION_ID} --unlink   # remove
+claude-code-kanban link-doc <path> --session ${CLAUDE_SESSION_ID}            # link
+claude-code-kanban link-doc <path> --session ${CLAUDE_SESSION_ID} --unlink   # remove
 ```
 
-## Inspect sessions (read-only)
+## `list` / `view` / `peek` — read-only
 
 ```bash
 claude-code-kanban session list --active                            # recent active sessions
@@ -64,12 +57,10 @@ claude-code-kanban session view ${CLAUDE_SESSION_ID}                # full stats
 claude-code-kanban session peek ${CLAUDE_SESSION_ID} --limit 20     # last 20 messages (server caps at 50)
 ```
 
-`session list` shows 10 rows by default and always includes pinned sessions, sticky first — `--no-pins` disables both.
-
-Add `--json` to any list-style verb for machine-readable output.
+`session list` shows 10 rows and always includes pinned sessions, sticky first (`--no-pins` disables both). `--json` works on any list-style verb.
 
 ## Troubleshooting
 
-`claude-code-kanban help <command>` prints the authoritative flags for any command — read it instead of guessing.
+`claude-code-kanban help <command>` prints the authoritative flags — read it instead of guessing.
 
 - **"Cannot reach cck server…"** → the error names the port it tried. Ask the user to start the server with `claude-code-kanban`. If they run it elsewhere, set `PORT=<n>` when invoking the CLI.