claude-code-kanban 5.3.0 → 5.4.0

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

@@ -0,0 +1,266 @@
+import type { EngineInterface, Register, ToolCallArgs } from 'claude-code'
+import { cckRoot } from './context'
+
+// Mods cannot delete files. The server reads any status but "waiting" as no ask.
+export const CLEARED = JSON.stringify({ status: 'cleared' })
+
+export const BOARD_ALLOWED = 'Approved from the board — running'
+
+const POLL_MS = 500
+
+type Kind = 'permission' | 'question' | 'plan'
+type Ask = { id: string; kind: Kind; dir: string; waitMs?: number }
+type Decision = {
+  behavior?: 'allow' | 'deny'
+  message?: string
+  updatedInput?: Record<string, unknown>
+  answers?: Record<string, unknown>
+}
+
+// tool.check carries the call's id on a real call only, so a call without one is found by its input.
+const pending = new Set<{ id?: string; tool: string; args: Record<string, unknown>; asked: (ask: Ask) => void }>()
+// The board's allow runs the tool again through $.tool.call, and its tool.check must not ask twice.
+const allowOnce = new Set<string>()
+const callKey = (tool: string, input: unknown) => `${tool}\0${JSON.stringify(input)}`
+
+let cck: Promise<string> | undefined
+
+// The engine does not follow $ into an imported function, so only the path rule is shared.
+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
+}
+
+async function readText($: EngineInterface, path: string) {
+  try {
+    return await $.fs.read(path)
+  } catch {
+    return undefined
+  }
+}
+
+async function readJson<T>($: EngineInterface, path: string): Promise<T | undefined> {
+  try {
+    return JSON.parse((await readText($, path)) ?? '')
+  } catch {
+    return undefined
+  }
+}
+
+// The server folds an agent's lines last-key-wins, so a line leaves out a field it does not know.
+async function appendLine($: EngineInterface, path: string, record: object, { onlyIfExists = false } = {}) {
+  const text = await readText($, path)
+  if (text === undefined && onlyIfExists) return
+  await $.fs.write(path, `${text ?? ''}${JSON.stringify(record)}\n`)
+}
+
+async function sessionDir($: EngineInterface) {
+  const [dir, id] = await Promise.all([cckDir($), $.session.id()])
+  return `${dir}/agent-activity/${id}`
+}
+
+const kindOf = (tool: string): Kind =>
+  tool === 'AskUserQuestion' ? 'question' : tool === 'ExitPlanMode' ? 'plan' : 'permission'
+
+// Mirrors approvalsFrom and isKindGated in lib/approvals.js: the gate is on unless config.json
+// says enabled: false, and a missing or broken file means the defaults.
+async function boardWaitMs($: EngineInterface, kind: Kind) {
+  type Approvals = { enabled?: unknown; mode?: unknown; waitSeconds?: unknown }
+  const a = (await readJson<{ approvals?: Approvals }>($, `${await cckDir($)}/config.json`))?.approvals ?? {}
+  if (a.enabled === false) return undefined
+  if (kind === 'question' && a.mode === 'permission') return undefined
+  const seconds = Number.isInteger(a.waitSeconds) && (a.waitSeconds as number) >= 0 ? (a.waitSeconds as number) : 1800
+  return Math.min(seconds, 1800) * 1000
+}
+
+// The marker shows the ask on the board whether or not the board may answer it.
+async function openAsk($: EngineInterface, tool: string, input: unknown, rule?: string): Promise<Ask> {
+  const kind = kindOf(tool)
+  const id = crypto.randomUUID()
+  const [dir, cwd, waitMs] = await Promise.all([sessionDir($), $.session.cwd(), boardWaitMs($, kind)])
+  await $.fs.write(
+    `${dir}/_waiting.json`,
+    JSON.stringify({
+      status: 'waiting',
+      kind,
+      id,
+      toolName: tool,
+      toolInput: JSON.stringify(input),
+      cwd,
+      rule,
+      timestamp: new Date().toISOString(),
+    }),
+  )
+  return { id, kind, dir, waitMs }
+}
+
+// A newer ask (a parallel call) may own the marker by now.
+async function closeAsk($: EngineInterface, ask: Ask) {
+  const marker = `${ask.dir}/_waiting.json`
+  if ((await readJson<{ id?: string }>($, marker))?.id === ask.id) await $.fs.write(marker, CLEARED)
+}
+
+async function boardDecision($: EngineInterface, ask: Ask, signal: AbortSignal) {
+  const file = `${ask.dir}/_decision-${ask.id}.json`
+  for (let waited = 0; waited < (ask.waitMs ?? 0); waited += POLL_MS) {
+    try {
+      await $.clock.sleep(POLL_MS, { signal })
+    } catch {
+      return undefined
+    }
+    const d = await readJson<Decision>($, file)
+    if (d) return d
+  }
+  return undefined
+}
+
+// Only returning ends the terminal prompt, so an allow runs the tool again from here. A terminal
+// "Yes" in the moment before the hook returns runs it twice (docs/ui-approvals.md).
+async function answerFromBoard($: EngineInterface, tool: string, args: Record<string, unknown>, ask: Ask, d: Decision) {
+  if (ask.kind === 'question') {
+    return d.answers ? { result: { questions: args.questions, answers: d.answers } } : undefined
+  }
+  if (d.behavior !== 'allow') return { deny: d.message ?? 'Denied from the board' }
+  $.ui.status(BOARD_ALLOWED)
+  const input = { ...args, ...d.updatedInput }
+  const key = callKey(tool, input)
+  allowOnce.add(key)
+  try {
+    return await $.tool.call({ ...input, tool } as ToolCallArgs)
+  } finally {
+    allowOnce.delete(key)
+    $.ui.status(undefined)
+  }
+}
+
+async function mapTaskList($: EngineInterface, cwd: string) {
+  const taskListId = await $.env.get('CLAUDE_CODE_TASK_LIST_ID')
+  if (!taskListId) return
+  const path = `${await cckDir($)}/agent-activity/_task-maps/${taskListId}.json`
+  const maps = (await readJson<Record<string, unknown>>($, path)) ?? {}
+  maps[await $.session.id()] = { project: cwd, updatedAt: new Date().toISOString() }
+  await $.fs.write(path, JSON.stringify(maps))
+}
+
+async function markStopped($: EngineInterface) {
+  await $.fs.write(`${await sessionDir($)}/_stop.json`, '')
+}
+
+// The name map lets TeammateIdle, which names the teammate, find its agent id.
+async function agentStarted($: EngineInterface, agentId: string, type: string, name?: string) {
+  const dir = await sessionDir($)
+  const ts = new Date().toISOString()
+  await Promise.all([
+    appendLine($, `${dir}/${agentId}.jsonl`, {
+      agentId,
+      type,
+      event: 'start',
+      status: 'active',
+      startedAt: ts,
+      updatedAt: ts,
+    }),
+    $.fs.write(`${dir}/_name-${name ?? type}.id`, agentId),
+  ])
+}
+
+// turn.complete also ends loops agent.spawn never started (internal agents): those have no file.
+async function agentStopped($: EngineInterface, agentId: string, lastMessage: string) {
+  const ts = new Date().toISOString()
+  await appendLine(
+    $,
+    `${await sessionDir($)}/${agentId}.jsonl`,
+    {
+      agentId,
+      event: 'stop',
+      status: 'stopped',
+      ...(lastMessage && { lastMessage }),
+      stoppedAt: ts,
+      updatedAt: ts,
+    },
+    { onlyIfExists: true },
+  )
+}
+
+// TeammateIdle names the teammate but carries no agent_id outside the teammate's own loop.
+async function teammateIdle($: EngineInterface, name: string, agentId?: string, agentType?: string) {
+  const dir = await sessionDir($)
+  const id = agentId || (await readText($, `${dir}/_name-${name}.id`))
+  if (!id) return
+  const type = agentId ? agentType : name
+  await appendLine(
+    $,
+    `${dir}/${id}.jsonl`,
+    {
+      agentId: id,
+      ...(type && { type }),
+      event: 'idle',
+      status: 'idle',
+      updatedAt: new Date().toISOString(),
+    },
+    { onlyIfExists: !type },
+  )
+}
+
+export const register: Register = on => {
+  on('tool.check', async ($, e, next) => {
+    if (allowOnce.delete(callKey(e.tool, e.input))) return { decision: 'allow' }
+    const result = await next(e)
+    if (result.decision !== 'ask') return result
+    const input = e.tool_use_id ? undefined : JSON.stringify(e.input)
+    const call = [...pending].find(p =>
+      e.tool_use_id ? p.id === e.tool_use_id : p.tool === e.tool && JSON.stringify(p.args) === input,
+    )
+    call?.asked(await openAsk($, e.tool, e.input, result.rule))
+    return result
+  })
+  on('tool.call', async ($, e, next) => {
+    const { tool, tool_use_id, agentId: _agentId, consent: _consent, ...args } = e as typeof e & { consent?: unknown }
+    let asked: (ask: Ask) => void = () => {}
+    const ask = new Promise<Ask>(resolve => {
+      asked = resolve
+    })
+    const call = { id: tool_use_id, tool, args, asked }
+    pending.add(call)
+    const run = next(e)
+    const settled = new AbortController()
+    const done = run.then(() => undefined).finally(() => settled.abort())
+    try {
+      const opened = await Promise.race([done, ask])
+      if (!opened) return await run
+      try {
+        const d = await Promise.race([
+          done,
+          boardDecision($, opened, AbortSignal.any([next.signal, settled.signal])),
+        ])
+        return (d && (await answerFromBoard($, tool, args, opened, d))) ?? (await run)
+      } finally {
+        await closeAsk($, opened)
+      }
+    } finally {
+      pending.delete(call)
+    }
+  })
+  on('session.start', async ($, e, next) => {
+    await mapTaskList($, e.cwd)
+    return next(e)
+  })
+  on('agent.spawn', async ($, e, next) => {
+    const result = await next(e)
+    if (result.agentId) await agentStarted($, result.agentId, e.subagentType, e.name)
+    return result
+  })
+  // An interrupted turn fires no Stop hook, so it does not mark the session unread either.
+  on('turn.complete', async ($, e, next) => {
+    if (e.agentId) await agentStopped($, e.agentId, e.answer)
+    else if (!e.isAborted) await markStopped($)
+    return next(e)
+  })
+  // Managed settings bypass user-tier mods on classic.* (cc-plugin-sec-default), so this one
+  // has no effect there; there is no native teammate-idle event to use instead.
+  on('classic.TeammateIdle', async ($, e, next) => {
+    await teammateIdle($, e.teammate_name, e.agent_id, e.agent_type)
+    return next(e)
+  })
+}

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

@@ -0,0 +1,77 @@
+import type { EngineInterface, ModelUsage, Register, SessionMeasureInput } from 'claude-code'
+
+type Measure = Pick<SessionMeasureInput, 'context' | 'rateLimits' | 'cost'>
+
+export function displayName(model: string) {
+  const m = /^claude-([a-z]+)-(\d+)(?:-(\d{1,2})(?!\d))?/.exec(model)
+  if (!m?.[1]) return model
+  const family = m[1][0]!.toUpperCase() + m[1].slice(1)
+  return `${family} ${m[3] ? `${m[2]}.${m[3]}` : m[2]}`
+}
+
+const toEpochSeconds = (iso?: string) => (iso ? Math.floor(Date.parse(iso) / 1000) : undefined)
+
+// The board reads the statusLine's JSON shape, so the file keeps its field names.
+export function toStatus(model: string, m: Measure, usage: ModelUsage | undefined) {
+  const { context } = m
+  return {
+    model: { id: model, display_name: displayName(model) },
+    cost: { total_cost_usd: m.cost?.usd ?? 0 },
+    context_window: {
+      total_input_tokens: context.tokens ?? 0,
+      context_window_size: context.window,
+      current_usage: usage ?? null,
+      used_percentage: context.percent ?? null,
+    },
+    rate_limits: Object.fromEntries(
+      m.rateLimits.map(r => [r.kind, { used_percentage: r.percentUsed, resets_at: toEpochSeconds(r.resetsAt) }]),
+    ),
+  }
+}
+
+export const cckRoot = (configDir?: string, home?: string, userProfile?: string) =>
+  configDir ? `${configDir}/.cck` : `${home ?? userProfile}/.claude/.cck`
+
+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 lastUsage: ModelUsage | undefined
+let lastModel: string | undefined
+const lastWritten = new Map<string, string>()
+
+async function write($: EngineInterface, m: Measure) {
+  const [sessionId, model, dir] = await Promise.all([
+    $.session.id(),
+    lastModel ?? $.session.model(),
+    cckDir($),
+  ])
+  const text = JSON.stringify(toStatus(model, m, lastUsage))
+  const file = `${dir}/context-status/${sessionId}.json`
+  if (lastWritten.get(file) === text) return
+  await $.fs.write(file, text)
+  lastWritten.set(file, text)
+}
+
+export const register: Register = on => {
+  on('turn.step', async function* ($, e, next) {
+    const result = yield* next(e)
+    if (e.agentId === undefined && result.usage) {
+      const { model, ...usage } = result.usage
+      lastUsage = usage
+      lastModel = model
+      await write($, await $.session.usage())
+    }
+    return result
+  })
+
+  on('session.measure', async ($, e, next) => {
+    await write($, e)
+    return next(e)
+  })
+}

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

@@ -1,95 +1,3 @@
 {
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh\"",
-            "shell": "bash",
-            "timeout": 5
-          }
-        ]
-      }
-    ],
-    "SubagentStart": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh\"",
-            "shell": "bash",
-            "timeout": 5
-          }
-        ]
-      }
-    ],
-    "SubagentStop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh\"",
-            "shell": "bash",
-            "timeout": 30
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh\"",
-            "shell": "bash",
-            "timeout": 5
-          }
-        ]
-      }
-    ],
-    "TeammateIdle": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh\"",
-            "shell": "bash",
-            "timeout": 5
-          }
-        ]
-      }
-    ],
-    "PermissionRequest": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/approval-gate.sh\"",
-            "shell": "bash",
-            "timeout": 86400
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/agent-spy.sh\"",
-            "shell": "bash",
-            "timeout": 5
-          }
-        ]
-      }
-    ]
-  }
+  "modules": ["./index.ts"]
 }

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

@@ -0,0 +1,8 @@
+import type { Register } from 'claude-code'
+import { register as activity } from './activity'
+import { register as context } from './context'
+
+export const register: Register = (on, options) => {
+  context(on, options)
+  activity(on, options)
+}

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

@@ -26,8 +26,8 @@ const SERVER_INFO = path.join(CLAUDE_DIR, '.cck', 'server.json');
 // because an enqueue wakes the poll immediately.
 const WAIT_SEC = 120;
 const RETRY_MS = 15000;
-// Windows sometimes fails a loopback connect with ETIMEDOUT while the board is up, so that
-// error gets a few short waits before the normal one.
+// Windows sometimes fails a loopback connect with ETIMEDOUT, or resets it once open, while the
+// board is up, so those errors get a few short waits before the normal one.
 const CONNECT_RETRY_MS = [250, 500, 1000, 2000];
 // `--topic dispatch` is the dispatch inbox: reports from sessions this one started.
 const TOPIC = process.argv.includes('--topic') ? process.argv[process.argv.indexOf('--topic') + 1] : null;
@@ -75,8 +75,8 @@ async function poll(base) {
     } catch (e) {
       // 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.
-      const timedOut = e.cause?.code === 'ETIMEDOUT' && e.cause?.syscall === 'connect';
-      if (timedOut && connectRetries < CONNECT_RETRY_MS.length) {
+      const blip = (e.cause?.code === 'ETIMEDOUT' && e.cause?.syscall === 'connect') || e.cause?.code === 'ECONNRESET';
+      if (blip && connectRetries < CONNECT_RETRY_MS.length) {
         await sleep(CONNECT_RETRY_MS[connectRetries++]);
       } else {
         connectRetries = 0;