claude-code-kanban 5.2.0 → 5.4.0

package/skill-guides/dispatch.md

@@ -2,7 +2,7 @@
 
 A dispatch is one Claude Code session that cck starts for a task, in its embedded terminal. It is an ordinary session, not a child: it shows in the sidebar like any other, and the user can open its terminal at any time.
 
-A dispatch is **fire-and-forget** by default: you hand the task off, and the user watches it in the sidebar. Add `--report` only when you need the outcome back: the user asked you to collect it, or your next step depends on it.
+A dispatch **reports back** by default: start it with `--report` and `--peer`, then collect and verify the outcome (With `--report`, below). When the user's request says `--no-report`, it is **fire-and-forget**: start it with neither flag (Fire-and-forget, below). `--no-report` lives only in the user's request; `dispatch start` has no such flag.
 
 ## Write the spec
 
@@ -19,12 +19,12 @@ Dispatch when the task can run on its own. Do the work yourself when it is small
 ## Start
 
 ```bash
-claude-code-kanban dispatch start --cwd <dir> --spec-file <spec.md> --name <name> --group <group> --peer <your-peer> [--report] --json
+claude-code-kanban dispatch start --cwd <dir> --spec-file <spec.md> --name <name> --group <group> --peer <your-peer> --report --json
 ```
 
 `claude-code-kanban help dispatch start` lists every flag (model, worktree, and the rest). `project list` shows the folders `--cwd` accepts. How to choose the values:
 
-- `--peer` is your own peer name: the first line of `ListAgents` ("This session is `<name>`"). Pass it whenever you have the `ListAgents` tool. cck then tells the started session to ask you with `SendMessage` instead of failing on a question. See [Peer](#peer).
+- `--peer` is your own peer name: the first line of `ListAgents` ("This session is `<name>`"). Pass it when you have the `ListAgents` tool. cck then tells the started session to ask you with `SendMessage` instead of failing on a question. See [Peer](#peer).
 - `--spec-file` over `--spec` for anything longer than a line: no shell quoting.
 - `--name` is what the user sees in the sidebar. Kebab-case, saying what the session does: `fix-login-redirect`, not `task-1`.
 - `--group` names the effort, in kebab-case (`auth-refactor`), and shows the new session under that sidebar group. This session stays where it is. Pass it on your first dispatch; later dispatches join the same group without it. A group goes away when its sessions end, unless the user pins a member or keeps the group.
@@ -32,7 +32,7 @@ claude-code-kanban dispatch start --cwd <dir> --spec-file <spec.md> --name <name
 
 ## Fire-and-forget
 
-Tell the user the session name, its group, and the dispatch id, then carry on with your own work or end your turn. The user follows the dispatch in the sidebar. With `--peer`, its questions still reach you as new turns.
+The started session gets the task alone and does not know your session exists. Tell the user the session name, its group, and the dispatch id. Your part ends with that message: the user follows the dispatch in the sidebar, and asks you when they want it checked.
 
 ## With `--report`
 

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

@@ -1,135 +0,0 @@
-#!/bin/bash
-# Tracks subagent lifecycle: one append-only JSONL file per agent, grouped by session
-# Layout: <CLAUDE_CONFIG_DIR or ~/.claude>/.cck/agent-activity/{sessionId}/{agentId}.jsonl
-# Each line is a lifecycle event (start | idle | stop). Server folds last-line-wins.
-
-INPUT=$(cat)
-
-# Single jq call to extract all routing fields
-eval "$(echo "$INPUT" | jq -r '
-  @sh "SESSION_ID=\(.session_id // "")",
-  @sh "AGENT_ID=\(.agent_id // "")",
-  @sh "EVENT=\(.hook_event_name // "")",
-  @sh "TOOL_NAME=\(.tool_name // "")",
-  @sh "AGENT_TYPE_RAW=\(.agent_type // "")",
-  @sh "TEAMMATE_NAME=\(.teammate_name // "")"
-')"
-
-[ -z "$SESSION_ID" ] && exit 0
-
-CCK_ACTIVITY="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.cck/agent-activity"
-
-# Map session to custom task list on session start
-if [ "$EVENT" = "SessionStart" ]; then
-  TASK_LIST_ID="${CLAUDE_CODE_TASK_LIST_ID:-}"
-  if [ -n "$TASK_LIST_ID" ]; then
-    CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
-    MAPS_DIR="$CCK_ACTIVITY/_task-maps"
-    mkdir -p "$MAPS_DIR"
-    MAP_FILE="$MAPS_DIR/$TASK_LIST_ID.json"
-    TMP_FILE="$MAP_FILE.$$"
-    TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-    EXISTING="{}"
-    [ -f "$MAP_FILE" ] && EXISTING=$(cat "$MAP_FILE")
-    echo "$EXISTING" | jq -c --arg sid "$SESSION_ID" --arg cwd "$CWD" --arg ts "$TS" \
-      '.[$sid] = {project: $cwd, updatedAt: $ts}' > "$TMP_FILE" && mv "$TMP_FILE" "$MAP_FILE"
-  fi
-  exit 0
-fi
-
-# Stop: the session finished its turn. The marker means unread; the board deletes it on open.
-if [ "$EVENT" = "Stop" ]; then
-  DIR="$CCK_ACTIVITY/$SESSION_ID"
-  [ -d "$DIR" ] || mkdir -p "$DIR"
-  : > "$DIR/_stop.json"
-  exit 0
-fi
-
-# PostToolUse / non-waiting PreToolUse: clear waiting state, and unread since the session is working again
-if [ "$EVENT" = "PostToolUse" ] || { [ "$EVENT" = "PreToolUse" ] && [ "$TOOL_NAME" != "AskUserQuestion" ] && [ "$TOOL_NAME" != "ExitPlanMode" ]; }; then
-  rm -f "$CCK_ACTIVITY/$SESSION_ID/_waiting.json" "$CCK_ACTIVITY/$SESSION_ID/_stop.json"
-  [ "$EVENT" = "PostToolUse" ] && exit 0
-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"
-  mkdir -p "$DIR"
-  KIND="permission"
-  [ "$EVENT" = "PreToolUse" ] && KIND="question"
-  TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-  echo "$INPUT" | jq -c --arg kind "$KIND" --arg ts "$TS" '{
-    status: "waiting",
-    kind: $kind,
-    toolName: (.tool_name // "unknown"),
-    toolInput: ((.tool_input | tostring) // ""),
-    timestamp: $ts
-  }' > "$DIR/_waiting.json"
-  exit 0
-fi
-
-# TeammateIdle has no agent_id — resolve via name→id mapping file
-if [ "$EVENT" = "TeammateIdle" ] && [ -z "$AGENT_ID" ] && [ -n "$TEAMMATE_NAME" ]; then
-  DIR="$CCK_ACTIVITY/$SESSION_ID"
-  MAP_FILE="$DIR/_name-${TEAMMATE_NAME}.id"
-  [ ! -f "$MAP_FILE" ] && exit 0
-  AGENT_ID=$(cat "$MAP_FILE")
-  [ -z "$AGENT_ID" ] && exit 0
-  FILE="$DIR/$AGENT_ID.jsonl"
-  TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-  echo "{\"agentId\":\"$AGENT_ID\",\"type\":\"$TEAMMATE_NAME\",\"event\":\"idle\",\"status\":\"idle\",\"updatedAt\":\"$TS\"}" >> "$FILE"
-  exit 0
-fi
-
-[ -z "$AGENT_ID" ] && exit 0
-
-DIR="$CCK_ACTIVITY/$SESSION_ID"
-FILE="$DIR/$AGENT_ID.jsonl"
-
-# On Start: skip if no type (internal agents like AskUserQuestion)
-# On Stop/Idle: only skip if no existing file (never tracked)
-if [ -z "$AGENT_TYPE_RAW" ]; then
-  if [ "$EVENT" = "SubagentStart" ]; then
-    exit 0
-  elif [ ! -f "$FILE" ]; then
-    exit 0
-  fi
-fi
-
-mkdir -p "$DIR"
-TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-
-if [ "$EVENT" = "SubagentStart" ]; then
-  echo "{\"agentId\":\"$AGENT_ID\",\"type\":\"$AGENT_TYPE_RAW\",\"event\":\"start\",\"status\":\"active\",\"startedAt\":\"$TS\",\"updatedAt\":\"$TS\"}" >> "$FILE"
-  # Mapping always points at latest agent of this type (used by TeammateIdle resolution).
-  if [ -n "$AGENT_TYPE_RAW" ]; then
-    echo -n "$AGENT_ID" > "$DIR/_name-${AGENT_TYPE_RAW}.id"
-  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, event: "stop", status: "stopped",
-      lastMessage: (.last_assistant_message // ""), stoppedAt: $ts, updatedAt: $ts}
-     + (if $type == "" then {} else {type: $type} end)' \
-    >> "$FILE"
-
-elif [ "$EVENT" = "TeammateIdle" ]; then
-  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

@@ -1,208 +0,0 @@
-#!/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 — unless config.json opts out, and
-# only while the board's server is alive — waits for a decision file written by the server.
-#
-# Contract (_plans/cck-ui-approvals/decisions.md), rooted at <CLAUDE_CONFIG_DIR or ~/.claude>/.cck:
-#   marker    agent-activity/<sid>/_waiting.json            (D8: + id, cwd, permissionSuggestions)
-#   decision  agent-activity/<sid>/_decision-<id>.json      (server writes it, Phase 3)
-#   config    config.json {approvals: {enabled, mode, waitSeconds}}  (on by default; absent = defaults)
-#   liveness  server.json {port, pid}                       (D1: a dead board costs nothing)
-#
-# First writer wins (D5): a terminal answer deletes the marker (this gate, via
-# the session registry, or 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="${CLAUDE_CONFIG_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.
-
-# Defaults mirror lib/approvals.js — keep in sync. A missing or unparseable
-# config.json means defaults, i.e. the gate is on.
-ENABLED="true"
-MODE="permission+question"
-WAIT_SECONDS=""
-CONFIG="$CCK_DIR/config.json"
-if [ -f "$CONFIG" ]; then
-  eval "$(jq -r '
-    @sh "ENABLED=\(if .approvals.enabled == false then "false" else "true" end)",
-    @sh "MODE=\(.approvals.mode // "permission+question")",
-    @sh "WAIT_SECONDS=\(.approvals.waitSeconds // "")"
-  ' < "$CONFIG" 2>/dev/null)"
-fi
-[ "$ENABLED" = "false" ] && exit 0
-
-if [ "$KIND" = "question" ] && [ "$MODE" != "permission+question" ]; then
-  exit 0
-fi
-
-case "$WAIT_SECONDS" in *[!0-9]* | "") WAIT_SECONDS=1800 ;; 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"
-
-# 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. The
-# port is re-read on every probe, not cached: under the hub every sub-app binds
-# an ephemeral port, so a board that restarts mid-wait comes back on a new one.
-# $(<file) and =~ keep the probe free of jq and cat spawns (~280 ms each here).
-board_alive() {
-  local raw port
-  raw=$(<"$SERVER_INFO") 2>/dev/null || return 1
-  [[ $raw =~ \"port\"[[:space:]]*:[[:space:]]*([0-9]+) ]] || return 1
-  port=${BASH_REMATCH[1]}
-  (: < "/dev/tcp/127.0.0.1/$port") 2>/dev/null
-}
-
-DECISION="$DIR/_decision-$REQ_ID.json"
-# EPOCHSECONDS (bash 5) keeps the poll loop free of `date` spawns
-DEADLINE=$((EPOCHSECONDS + WAIT_SECONDS))
-# Probing once up front made one unreachable moment disarm the whole ask, so a
-# board restarting on a new port (every hub-spawned sub-app binds an ephemeral
-# one) took the ask with it. Probe on a cadence instead and only give up once
-# the board has been gone for the whole grace. The terminal prompt stays live
-# throughout either way.
-BOARD_PROBE_SECONDS=5
-BOARD_GRACE_SECONDS=15
-NEXT_PROBE=0
-UNREACHABLE_SINCE=0
-
-# Claude Code's live-session registry flips from "waiting" the moment the
-# terminal prompt is answered, while PostToolUse waits for the tool to finish
-# and never fires on a deny. Undocumented, so a missing file or field leaves
-# PostToolUse in charge, as before.
-SESSIONS_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/sessions"
-REGISTRY=""
-SEEN_WAITING=0
-find_registry() {
-  local f raw
-  for f in "$SESSIONS_DIR"/*.json; do
-    [ -f "$f" ] || continue
-    raw=""
-    IFS= read -r raw 2>/dev/null < "$f"
-    case "$raw" in *"\"sessionId\":\"$SESSION_ID\""*) REGISTRY=$f; return 0 ;; esac
-  done
-  return 1
-}
-
-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
-
-  if [ -n "$REGISTRY" ]; then
-    REG_RAW=""
-    IFS= read -r REG_RAW 2>/dev/null < "$REGISTRY"
-    if [[ $REG_RAW =~ \"status\":\"([a-z]+)\" ]]; then
-      if [ "${BASH_REMATCH[1]}" = "waiting" ]; then
-        SEEN_WAITING=1
-      elif [ "$SEEN_WAITING" -eq 1 ]; then
-        rm -f "$MARKER"
-        exit 0
-      fi
-    fi
-  fi
-
-  if [ "$EPOCHSECONDS" -ge "$NEXT_PROBE" ]; then
-    NEXT_PROBE=$((EPOCHSECONDS + BOARD_PROBE_SECONDS))
-    [ -n "$REGISTRY" ] || find_registry
-    # No beacon at all = no board on this config dir, now or a moment ago: give
-    # up at once, exactly as before. A beacon whose port is closed is the
-    # restart window instead, so that one gets the grace.
-    [ -f "$SERVER_INFO" ] || exit 0
-    if board_alive; then
-      UNREACHABLE_SINCE=0
-    else
-      [ "$UNREACHABLE_SINCE" -eq 0 ] && UNREACHABLE_SINCE=$EPOCHSECONDS
-      [ $((EPOCHSECONDS - UNREACHABLE_SINCE)) -ge "$BOARD_GRACE_SECONDS" ] && exit 0
-    fi
-  fi
-
-  [ "$EPOCHSECONDS" -ge "$DEADLINE" ] && exit 0
-  sleep 0.5
-done

package/plugin/plugins/claude-code-kanban/scripts/context-status.sh

@@ -1,18 +0,0 @@
-#!/bin/bash
-# Statusline spy: writes raw context data for kanban dashboard, passes input through
-# Layout: <CLAUDE_CONFIG_DIR or ~/.claude>/.cck/context-status/{sessionId}.json
-#
-# Usage: pipe before your statusline command:
-#   "command": "~/.claude/hooks/context-status.sh | npx -y ccstatusline@latest"
-
-INPUT=$(cat)
-
-SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // ""')
-if [ -n "$SESSION_ID" ]; then
-  DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.cck/context-status"
-  mkdir -p "$DIR"
-  echo "$INPUT" > "$DIR/$SESSION_ID.json"
-fi
-
-# Pass through original input for downstream statusline
-echo "$INPUT"