claude-code-kanban 4.20.0 → 4.22.0

package/README.md

@@ -49,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/file-url.js

@@ -0,0 +1,36 @@
+'use strict';
+
+// Some tools hand out a `file://` URL where a path is expected — Explorer's
+// "copy as path" on a network share, a PDF viewer's location bar, a chat client
+// that linkifies attachments. Windows apps also emit the non-standard backslash
+// spelling `file:\\\C:\dir\a.md`. Both are normalized to a plain OS path so the
+// user does not have to hand-edit what their clipboard produced.
+
+const { fileURLToPath } = require('url');
+
+// Matches any number of leading slashes before a drive letter, so it re-spells both
+// the well-formed `file:///C:/dir` and `file://C:/dir`, where the parser reads C: as
+// a host and rejects the URL outright. Anything else — POSIX paths, UNC shares — is
+// left for the parser.
+const DRIVE_URL = /^file:\/*([a-zA-Z]:.*)$/;
+
+/**
+ * Convert a `file://` URL to an OS path. Any other string is returned unchanged,
+ * as is a URL too malformed to parse — the caller reports "not found" on the
+ * literal text, which is more useful than a parser error.
+ * @param {string} value
+ */
+function fileUrlToPath(value) {
+  if (typeof value !== 'string' || !/^file:/i.test(value)) return value;
+  // Backslashes are not legal in a URL, so this cannot corrupt a well-formed one.
+  let url = value.replace(/\\/g, '/');
+  const drive = DRIVE_URL.exec(url);
+  if (drive) url = `file:///${drive[1]}`;
+  try {
+    return fileURLToPath(url);
+  } catch {
+    return value;
+  }
+}
+
+module.exports = { fileUrlToPath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "4.20.0",
+  "version": "4.22.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,6 +1,6 @@
 {
   "name": "claude-code-kanban",
-  "version": "2.7.1",
+  "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/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