claude-slack-channel-bots 0.7.1 → 0.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-slack-channel-bots",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Multi-session Slack-to-Claude bridge — run multiple Claude Code bots across Slack channels via Socket Mode",
   "type": "module",
   "bin": {

package/src/permission-click-handler.ts

@@ -23,12 +23,26 @@ import type { WebClient } from '@slack/web-api'
 import { decideWithToken } from './agent-director-client.ts'
 import { parsePermissionActionId, type PermissionDecision } from './permission-action-id.ts'
 import { getLivePermission, markHandled } from './permission-poller.ts'
+import { emitTrail as defaultEmitTrail } from './permission-trail.ts'
+import type {
+  AdDecideResponseClass,
+  ClosureVerdictTag,
+  ParseFailureReason,
+  TrailEventBase,
+} from './permission-trail.ts'
 
 export interface ClickDeps {
   /** Returns an AD Client whose `decide` method this handler will invoke. */
   getClient: () => Pick<Client, 'decide'>
   web: Pick<WebClient, 'chat'>
   log?: (...args: unknown[]) => void
+  /**
+   * Trail emitter hook (SR-V). Defaults to `emitTrail` from
+   * `permission-trail.ts`. Tests override with a capture stub.
+   */
+  emitTrail?: (
+    partial: Omit<TrailEventBase, 'ts'> & { [extra: string]: unknown },
+  ) => void
 }
 
 function logDeps(deps: ClickDeps, ...args: unknown[]): void {
@@ -36,6 +50,34 @@ function logDeps(deps: ClickDeps, ...args: unknown[]): void {
   else console.error(...args)
 }
 
+/**
+ * SR-V-2.7 call-side classification of an agent-director `decide` error.
+ * Mirrors the existing branches in `handlePermissionClick`'s catch so the
+ * trail's `result_class` is identical to the operational discriminator.
+ */
+function classifyAdDecideError(err: unknown): AdDecideResponseClass {
+  if (err instanceof ErrAlreadyDecided) return 'ErrAlreadyDecided'
+  if (err instanceof AgentDirectorError && err.errName === 'ErrInvalidFlags') return 'ErrInvalidFlags'
+  if (err instanceof AgentDirectorError && err.errName === 'ErrAmbiguousRequest') return 'ErrAmbiguousRequest'
+  return 'other'
+}
+
+/** SR-V-2.5 Slack error class string (mirrors permission-poller.ts). */
+function classifySlackError(err: unknown): string {
+  if (err !== null && typeof err === 'object') {
+    const data = (err as { data?: unknown }).data
+    if (data !== null && typeof data === 'object') {
+      const e = (data as { error?: unknown }).error
+      if (typeof e === 'string' && e.length > 0) return e
+    }
+  }
+  if (err instanceof Error) {
+    if (err.name === 'AbortError') return 'aborted'
+    return 'network_error'
+  }
+  return 'unknown_error'
+}
+
 // Match the poller's SR-2.4 terminal verdict text exactly so the click-handler
 // render and the next-tick reconciliation render are byte-identical — no
 // visible flicker.
@@ -51,6 +93,22 @@ function buildDecisionBlocks(decision: PermissionDecision): unknown[] {
   ]
 }
 
+/**
+ * Inbound context captured from the Socket Mode interactive payload. Used by
+ * the SR-V-2.6 `cscb.click_handler.invoked` event so investigations can
+ * pivot by clicking user or by the Slack message being clicked against.
+ * Optional so unit-test call sites can omit it; the trail event records the
+ * fields as undefined/missing when not supplied (open envelope per SR-V-1).
+ */
+export interface ClickInteractionContext {
+  /** Inbound Slack channel id from the interactive payload. */
+  channel?: string
+  /** The clicked-message ts from the interactive payload. */
+  messageTs?: string
+  /** Clicking user's Slack id from the interactive payload. */
+  user?: string
+}
+
 /**
  * Handle a permission Block Kit click. Returns true when the action_id was a
  * valid permission decision (the caller has already ack'd); false when the
@@ -59,23 +117,66 @@ function buildDecisionBlocks(decision: PermissionDecision): unknown[] {
 export async function handlePermissionClick(
   actionId: string,
   deps: ClickDeps,
+  context: ClickInteractionContext = {},
 ): Promise<boolean> {
   const parsed = parsePermissionActionId(actionId)
   if (parsed === null) return false
 
   const { decision, claudeInstanceId, requestToken } = parsed
+  const emit = deps.emitTrail ?? defaultEmitTrail
+  // SR-V-2.6: live_pending captures the click-time state. Read the entry
+  // here so the trail event records the value at handler entry, before any
+  // markHandled / drop later in this function (or in the next tick) mutates
+  // the map.
+  const earlyEntry = getLivePermission(claudeInstanceId, requestToken)
+  emit({
+    event: 'cscb.click_handler.invoked',
+    claude_instance_id: claudeInstanceId,
+    request_token: requestToken,
+    channel: context.channel ?? earlyEntry?.channelId,
+    message_ts: context.messageTs ?? earlyEntry?.messageTs,
+    user: context.user,
+    raw_action_id: actionId,
+    decision,
+    live_pending: earlyEntry !== undefined,
+  })
 
   // SR-4.1, SR-4.2, SR-7.2: AD is the source of truth. Always call decide
   // with the decoded request_token — including for stale clicks whose
   // composite key is no longer in the pending map. This is the click's ONLY
   // AD interaction (SR-4.3 retires the pre-decide get).
+  const decideEnvelope = {
+    event: 'cscb.ad_decide.attempted',
+    claude_instance_id: claudeInstanceId,
+    request_token: requestToken,
+    decision,
+  }
   try {
     await decideWithToken(deps.getClient(), {
       claude_instance_id: claudeInstanceId,
       decision,
       request_token: requestToken,
     })
+    // SR-V-2.7 call-side success emission.
+    emit({ ...decideEnvelope, result_class: 'ok' satisfies AdDecideResponseClass })
   } catch (err) {
+    // SR-V-2.7 call-side failure emission. Classify against the same AD
+    // error names the existing branches discriminate on so the trail's
+    // result_class stays consistent with src/agent-director-errors.ts. The
+    // existing logDeps operational logging is preserved alongside the
+    // canonical trail event — the two serve different purposes (live
+    // stderr vs after-the-fact debugging).
+    const result_class: AdDecideResponseClass = classifyAdDecideError(err)
+    const emission: Omit<TrailEventBase, 'ts'> & { [extra: string]: unknown } = {
+      ...decideEnvelope,
+      result_class,
+    }
+    if (result_class === 'other') {
+      const raw = err instanceof Error ? err.message : String(err)
+      emission['raw_error_message'] = raw
+    }
+    emit(emission)
+
     // SR-4.4: ErrAlreadyDecided is silently swallowed — the next poller tick
     // reconciles the operator-visible Slack rendering via SR-2.4 / SR-5.
     if (err instanceof ErrAlreadyDecided) return true
@@ -104,16 +205,99 @@ export async function handlePermissionClick(
   const text = decision === 'allow'
     ? '*Permission* — Allowed'
     : '*Permission* — Denied by operator'
+  const blocks = buildDecisionBlocks(decision)
+  const verdictTag: ClosureVerdictTag = decision === 'allow'
+    ? 'click_handler_allow'
+    : 'click_handler_deny'
+  const envelope = {
+    event: 'cscb.chat_update.attempted',
+    claude_instance_id: claudeInstanceId,
+    request_token: requestToken,
+    channel: entry.channelId,
+    message_ts: entry.messageTs,
+    text,
+    blocks,
+    verdict_tag: verdictTag,
+    triggered_by: 'click_handler' as const,
+  }
   try {
     await deps.web.chat.update({
       channel: entry.channelId,
       ts: entry.messageTs,
       text,
-      blocks: buildDecisionBlocks(decision) as never,
+      blocks: blocks as never,
     })
     markHandled(claudeInstanceId, requestToken)
+    emit({ ...envelope, ok: true })
   } catch (err) {
+    // b.emk: failures land in BOTH server.log and the trail JSONL.
     logDeps(deps, `[slack] permission-click: decision chat.update failed for ${claudeInstanceId}:`, err)
+    emit({ ...envelope, ok: false, error: classifySlackError(err) })
   }
   return true
 }
+
+// ---------------------------------------------------------------------------
+// SR-V-2.9 inbound block_actions emission
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify a `block_actions` action_id for the SR-V-2.9 trail event without
+ * mutating state. Exported so `src/server.ts`'s `socket.on('interactive')`
+ * handler stays a thin wiring layer and so this branch can be unit-tested
+ * in isolation (server.ts has module-load side effects and is not directly
+ * importable from tests).
+ *
+ * The decision split is intentional: a `perm_(allow|deny)_*` prefix
+ * indicates a CSCB permission button whose body failed to parse
+ * (`malformed_token`); anything else is foreign (`foreign_action_id`). Note
+ * that `stale_prompt` is NOT a parse-failure reason here — a stale click
+ * decodes fine and shows up as `cscb.click_handler.invoked{live_pending:false}`.
+ */
+const PERMISSION_BUTTON_PREFIX_RE = /^perm_(allow|deny)_/
+
+export interface BlockActionTrailContext {
+  /** Inbound Slack channel id from the interactive payload. */
+  channel?: string
+  /** Clicked message ts from the interactive payload. */
+  messageTs?: string
+  /** Clicking user's Slack id. */
+  user?: string
+}
+
+/**
+ * Emit one `cscb.block_action.received` event for an inbound `block_actions`
+ * action_id. Called once per action in the payload's `actions` array,
+ * regardless of whether the action_id decodes (SR-V-2.9 — the
+ * decode-failure case is the diagnostically critical surface for
+ * "I clicked Allow and nothing happened").
+ */
+export function emitBlockActionReceived(
+  actionId: string,
+  context: BlockActionTrailContext,
+  emit: (
+    partial: Omit<TrailEventBase, 'ts'> & { [extra: string]: unknown },
+  ) => void = defaultEmitTrail,
+): void {
+  const parsed = parsePermissionActionId(actionId)
+  const base = {
+    event: 'cscb.block_action.received',
+    channel: context.channel,
+    message_ts: context.messageTs,
+    user: context.user,
+    raw_action_id: actionId,
+  }
+  if (parsed !== null) {
+    emit({
+      ...base,
+      claude_instance_id: parsed.claudeInstanceId,
+      request_token: parsed.requestToken,
+      decision: parsed.decision,
+    })
+    return
+  }
+  const reason: ParseFailureReason = PERMISSION_BUTTON_PREFIX_RE.test(actionId)
+    ? 'malformed_token'
+    : 'foreign_action_id'
+  emit({ ...base, parse_failure_reason: reason })
+}

package/src/permission-poller.ts

@@ -51,6 +51,12 @@ import type {
   GetPermissionResult,
 } from './agent-director-client.ts'
 import { encodePermissionActionId } from './permission-action-id.ts'
+import { emitTrail as defaultEmitTrail } from './permission-trail.ts'
+import type {
+  ClosureVerdictTag,
+  RowDecisionAction,
+  TrailEventBase,
+} from './permission-trail.ts'
 
 // ---------------------------------------------------------------------------
 // Wire-shape types (local — mirrors the `^0.6.0` wire)
@@ -136,6 +142,14 @@ export interface PollerDeps {
   /** Hook factories so tests can stub timer scheduling. */
   setInterval?: (cb: () => void, ms: number) => ReturnType<typeof setInterval>
   clearInterval?: (handle: ReturnType<typeof setInterval>) => void
+  /**
+   * Trail emitter hook (SR-V). Defaults to `emitTrail` from
+   * `permission-trail.ts`. Tests override with a capture stub to assert
+   * emission shape without touching the on-disk JSONL.
+   */
+  emitTrail?: (
+    partial: Omit<TrailEventBase, 'ts'> & { [extra: string]: unknown },
+  ) => void
 }
 
 // ---------------------------------------------------------------------------
@@ -245,6 +259,47 @@ function logViaDeps(deps: PollerDeps, ...args: unknown[]): void {
   else console.error(...args)
 }
 
+/**
+ * SR-V-2.3 row-decision emitter. Builds a `cscb.poller.row_decision` event
+ * with the canonical envelope fields and the action identifier. `request_token`
+ * is omitted (not empty) when absent per SR-V-1.1.
+ */
+function emitRowDecision(
+  deps: PollerDeps,
+  action: RowDecisionAction,
+  claudeInstanceId: string,
+  requestToken: string | undefined,
+): void {
+  const emit = deps.emitTrail ?? defaultEmitTrail
+  const event: Omit<TrailEventBase, 'ts'> & { [extra: string]: unknown } = {
+    event: 'cscb.poller.row_decision',
+    claude_instance_id: claudeInstanceId,
+    action,
+  }
+  if (requestToken !== undefined) event.request_token = requestToken
+  emit(event)
+}
+
+/**
+ * Map an unknown Slack error to a stable error-class string per SR-V-2.4.
+ * Slack platform errors expose `data.error` (e.g. `channel_not_found`); other
+ * errors collapse to short class labels.
+ */
+function classifySlackError(err: unknown): string {
+  if (err !== null && typeof err === 'object') {
+    const data = (err as { data?: unknown }).data
+    if (data !== null && typeof data === 'object') {
+      const e = (data as { error?: unknown }).error
+      if (typeof e === 'string' && e.length > 0) return e
+    }
+  }
+  if (err instanceof Error) {
+    if (err.name === 'AbortError') return 'aborted'
+    return 'network_error'
+  }
+  return 'unknown_error'
+}
+
 async function runTick(deps: PollerDeps): Promise<void> {
   if (tickInFlight) {
     skippedTicks++
@@ -284,13 +339,19 @@ async function runTick(deps: PollerDeps): Promise<void> {
       if (got.permission_requests === null || got.permission_requests === undefined) {
         logViaDeps(deps, `[slack] permission-poller: non-conforming open-rows response for ${row.claude_instance_id} — skipping`)
         nonConformingInstanceIds.add(row.claude_instance_id)
+        // SR-V-2.3: request_token omitted (no row was readable) per SR-V-1.1.
+        emitRowDecision(deps, 'non_conforming_skipped', row.claude_instance_id, undefined)
         continue
       }
 
       for (const perm of got.permission_requests) {
         const key = makeCompositeKey(row.claude_instance_id, perm.request_token)
         seenComposite.add(key)
-        if (livePermissions.has(key)) continue
+        if (livePermissions.has(key)) {
+          emitRowDecision(deps, 'already_tracked', row.claude_instance_id, perm.request_token)
+          continue
+        }
+        emitRowDecision(deps, 'post_attempted', row.claude_instance_id, perm.request_token)
         await postPermissionPrompt(deps, row, perm)
       }
     }
@@ -311,6 +372,7 @@ async function runTick(deps: PollerDeps): Promise<void> {
       } catch (err) {
         if (isErrPermissionRequestNotFound(err)) {
           logViaDeps(deps, `[slack] permission-poller: get-permission not-found for ${entry.claudeInstanceId} token=${entry.requestToken} — generic deny + drop`)
+          emitRowDecision(deps, 'not_found_generic_deny', entry.claudeInstanceId, entry.requestToken)
           await renderClosureUpdate(deps, entry, 'not_found')
           dropPermission(entry.claudeInstanceId, entry.requestToken)
           continue
@@ -318,6 +380,7 @@ async function runTick(deps: PollerDeps): Promise<void> {
         const e = err instanceof AgentDirectorError ? err : null
         logViaDeps(deps, `[slack] permission-poller: get-permission failed for ${entry.claudeInstanceId} token=${entry.requestToken}: ${e?.errName ?? String(err)}`)
         // SR-2.4 transient retry: leave entry alive; next tick will retry.
+        emitRowDecision(deps, 'transient_retry', entry.claudeInstanceId, entry.requestToken)
         continue
       }
 
@@ -325,6 +388,7 @@ async function runTick(deps: PollerDeps): Promise<void> {
       if (verdict === 'unknown') {
         logViaDeps(deps, `[slack] permission-poller: unknown verdict for ${entry.claudeInstanceId} token=${entry.requestToken} decision=${info.decision} decision_reason=${String(info.decision_reason)} — fail-closed generic deny`)
       }
+      emitRowDecision(deps, 'reconciled_closed', entry.claudeInstanceId, entry.requestToken)
       await renderClosureUpdate(deps, entry, verdict)
       dropPermission(entry.claudeInstanceId, entry.requestToken)
     }
@@ -364,13 +428,27 @@ async function postPermissionPrompt(
     permission.request_token,
   )
 
+  const text = `🤖🛠️ permission request: ${permission.tool_name}`
+  const emit = deps.emitTrail ?? defaultEmitTrail
   try {
     const response = await deps.web.chat.postMessage({
       channel: channelId,
-      text: `🤖🛠️ permission request: ${permission.tool_name}`,
+      text,
       blocks: blocks as never,
     })
     const messageTs = (response as { ts?: string }).ts
+    // SR-V-2.4: emit on success (and on the no-ts edge case below) with the
+    // Slack-returned ts. Full text + blocks pass through verbatim (SR-V-3.1).
+    emit({
+      event: 'cscb.chat_post.attempted',
+      claude_instance_id: row.claude_instance_id,
+      request_token: permission.request_token,
+      channel: channelId,
+      text,
+      blocks,
+      ok: true,
+      slack_ts: messageTs,
+    })
     if (!messageTs) {
       logViaDeps(deps, `[slack] permission-poller: chat.postMessage returned no ts for ${row.claude_instance_id}`)
       return
@@ -384,7 +462,20 @@ async function postPermissionPrompt(
       handled: false,
     })
   } catch (err) {
+    // b.emk: failures land in BOTH server.log (real-time visibility) AND the
+    // trail JSONL (after-the-fact debugging). Success paths stay trail-only,
+    // preserving the SR-V-2.4 asymmetric-behavior fix.
     logViaDeps(deps, `[slack] permission-poller: chat.postMessage failed for ${row.claude_instance_id}:`, err)
+    emit({
+      event: 'cscb.chat_post.attempted',
+      claude_instance_id: row.claude_instance_id,
+      request_token: permission.request_token,
+      channel: channelId,
+      text,
+      blocks,
+      ok: false,
+      error: classifySlackError(err),
+    })
   }
 }
 
@@ -472,6 +563,18 @@ async function renderClosureUpdate(
   tag: VerdictTag,
 ): Promise<void> {
   const { text, blocks } = buildVerdictRendering(tag)
+  const emit = deps.emitTrail ?? defaultEmitTrail
+  const envelope = {
+    event: 'cscb.chat_update.attempted',
+    claude_instance_id: entry.claudeInstanceId,
+    request_token: entry.requestToken,
+    channel: entry.channelId,
+    message_ts: entry.messageTs,
+    text,
+    blocks,
+    verdict_tag: tag as ClosureVerdictTag,
+    triggered_by: 'poller' as const,
+  }
   try {
     await deps.web.chat.update({
       channel: entry.channelId,
@@ -479,8 +582,11 @@ async function renderClosureUpdate(
       text,
       blocks: blocks as never,
     })
+    emit({ ...envelope, ok: true })
   } catch (err) {
+    // b.emk: failures land in BOTH server.log and the trail JSONL.
     logViaDeps(deps, `[slack] permission-poller: closure chat.update failed for ${entry.claudeInstanceId} token=${entry.requestToken} (verdict=${tag}):`, err)
+    emit({ ...envelope, ok: false, error: classifySlackError(err) })
   }
 }
 

package/src/permission-trail.ts

@@ -0,0 +1,234 @@
+/**
+ * permission-trail.ts — Append-only JSONL event store for the CSCB-side
+ * visibility trail of the AD↔CSCB tool-permission relay (SRD t1.cdb.4g).
+ *
+ * One JSON object per newline-terminated line in
+ *   <SLACK_STATE_DIR>/permission-trail.jsonl
+ * (default: ~/.claude/channels/slack/permission-trail.jsonl).
+ *
+ * Public API:
+ *   - TrailEvent                  — enforced line schema
+ *   - emitTrail(partial)          — auto-stamps `ts`, recommended call site API
+ *   - emitTrailEvent(event)       — raw, accepts caller-supplied `ts`
+ *   - _resetTrailFdForTests()     — test-only fd reset
+ *
+ * The emitter is the single enforcement point for SR-V-1 (correlation
+ * envelope), SR-V-3 (no truncation in the canonical store), and SR-V-4.5
+ * (RFC 3339 sub-second `ts`, stable hierarchical `event` identifier).
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+import { mkdirSync, openSync, writeSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+
+// ---------------------------------------------------------------------------
+// Line schema
+// ---------------------------------------------------------------------------
+
+/**
+ * Required envelope fields enforced by the type system on every emitted line.
+ * `event` is a stable hierarchical identifier in the `cscb.*` namespace
+ * (SR-V-4.5). `ts` is RFC 3339 with at least millisecond precision
+ * (SR-V-4.3, SR-V-4.5).
+ */
+export interface TrailEventBase {
+  ts: string
+  event: string
+  /** SR-V-1.1: AD-minted UUID, absent for events before token assignment (SR-V-1.2). */
+  request_token?: string
+  /** SR-V-1.2: present whenever known. */
+  claude_instance_id?: string
+  /** SR-V-1.3: Slack channel id for events that touch Slack. */
+  channel?: string
+  /** SR-V-1.3: Slack message ts for events that touch Slack. */
+  message_ts?: string
+}
+
+/**
+ * One emitted JSONL line. Extends the required envelope with an open index
+ * signature so per-event-class fields pass through verbatim (no truncation
+ * per SR-V-3.1) without a cast at the call site.
+ */
+export type TrailEvent = TrailEventBase & { [extra: string]: unknown }
+
+// ---------------------------------------------------------------------------
+// Per-event-class field types
+// ---------------------------------------------------------------------------
+
+/**
+ * The six canonical row-decision identifiers used as the `action` field on
+ * `cscb.poller.row_decision` events (SR-V-2.3). Exported for type-narrowing
+ * at the emission site.
+ *
+ * The set is open to extension per SR-V-2.3: the `(string & {})` widening
+ * keeps existing literals discoverable in editor completions while still
+ * accepting new identifiers without a type change.
+ */
+export const ROW_DECISION_ACTIONS = [
+  'post_attempted',
+  'already_tracked',
+  'reconciled_closed',
+  'not_found_generic_deny',
+  'non_conforming_skipped',
+  'transient_retry',
+] as const
+
+export type CanonicalRowDecisionAction = (typeof ROW_DECISION_ACTIONS)[number]
+
+/** Open string-literal union per SR-V-2.3 — canonical values plus any new identifier. */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type RowDecisionAction = CanonicalRowDecisionAction | (string & {})
+
+/**
+ * The 8 canonical verdict tags carried on `cscb.chat_update.attempted` events
+ * (SR-V-2.5). 6 are emitted by the poller's `renderClosureUpdate`; 2 are
+ * emitted by the click handler's verdict-render path. Open to extension.
+ */
+export const CLOSURE_VERDICT_TAGS = [
+  'operator_allow',
+  'operator_deny',
+  'timeout',
+  'find_missing',
+  'unknown',
+  'not_found',
+  'click_handler_allow',
+  'click_handler_deny',
+] as const
+
+export type CanonicalClosureVerdictTag = (typeof CLOSURE_VERDICT_TAGS)[number]
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type ClosureVerdictTag = CanonicalClosureVerdictTag | (string & {})
+
+/** Which surface triggered a closure `chat.update` (SR-V-2.5). Open to extension. */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type TriggeredBy = 'poller' | 'click_handler' | (string & {})
+
+/**
+ * Stable reasons a `cscb.block_action.received` event records when the
+ * inbound `action_id` failed `parsePermissionActionId` (SR-V-2.9). Open to
+ * extension. `stale_prompt` is intentionally NOT in this set — stale clicks
+ * decode fine and show up as `cscb.click_handler.invoked{live_pending:false}`.
+ */
+export const PARSE_FAILURE_REASONS = [
+  'foreign_action_id',
+  'malformed_token',
+] as const
+
+export type CanonicalParseFailureReason = (typeof PARSE_FAILURE_REASONS)[number]
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type ParseFailureReason = CanonicalParseFailureReason | (string & {})
+
+/** Decoded permission decision carried on inbound click events (SR-V-2.6 / SR-V-2.9). */
+export type ClickDecision = 'allow' | 'deny'
+
+/**
+ * Classification of an agent-director `decide` response on the CSCB call
+ * side (SR-V-2.7). The four named error classes match the AD error
+ * identifiers in `src/agent-director-errors.ts`. `"other"` is the catch-all
+ * for any other thrown value; the emit additionally carries a
+ * `raw_error_message` string in that case. Open extension allowed.
+ */
+export const AD_DECIDE_RESPONSE_CLASSES = [
+  'ok',
+  'ErrAlreadyDecided',
+  'ErrInvalidFlags',
+  'ErrAmbiguousRequest',
+  'other',
+] as const
+
+export type CanonicalAdDecideResponseClass = (typeof AD_DECIDE_RESPONSE_CLASSES)[number]
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type AdDecideResponseClass = CanonicalAdDecideResponseClass | (string & {})
+
+// ---------------------------------------------------------------------------
+// State-dir + path resolution
+// ---------------------------------------------------------------------------
+
+const TRAIL_FILENAME = 'permission-trail.jsonl'
+
+function resolveStateDir(): string {
+  const fromEnv = process.env['SLACK_STATE_DIR']
+  return fromEnv ? resolve(fromEnv) : join(homedir(), '.claude', 'channels', 'slack')
+}
+
+function resolveTrailPath(): string {
+  return join(resolveStateDir(), TRAIL_FILENAME)
+}
+
+// ---------------------------------------------------------------------------
+// Lazy-open module-scoped fd (mirrors src/logging.ts)
+// ---------------------------------------------------------------------------
+
+let fd: number | null = null
+
+/**
+ * Test-only: reset the module-scoped fd so a subsequent emit reopens the file
+ * (typically against a fresh `SLACK_STATE_DIR` temp directory). Mirrors the
+ * `resetClientForTests` pattern in `src/agent-director-client.ts`.
+ *
+ * @internal
+ */
+export function _resetTrailFdForTests(): void {
+  fd = null
+}
+
+// ---------------------------------------------------------------------------
+// Emission
+// ---------------------------------------------------------------------------
+
+const ISO_TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3,}Z$/
+
+function isValidTs(ts: unknown): ts is string {
+  return typeof ts === 'string' && ts.trim() !== '' && ISO_TIMESTAMP_RE.test(ts)
+}
+
+/**
+ * Append one fully-formed `TrailEvent` to the trail file. Use this when the
+ * caller supplies its own `ts` (e.g. test fixtures replaying historical
+ * events). Most production call sites should prefer `emitTrail`.
+ *
+ * Defensive guard: if `ts` is missing, empty, or not RFC 3339 with ms
+ * precision, substitute `new Date().toISOString()` and log a `[slack]`
+ * warning. Silently corrupting a trail line is worse than logging.
+ *
+ * Never throws. Write failures are caught and logged to stderr with the
+ * `[slack]` prefix per engineering-guide convention.
+ */
+export function emitTrailEvent(event: TrailEvent): void {
+  let toWrite: TrailEvent = event
+  if (!isValidTs(event.ts)) {
+    const stamped = new Date().toISOString()
+    console.error(
+      `[slack] permission-trail: missing/invalid ts on event=${String(event.event)} — substituting ${stamped}`,
+    )
+    toWrite = { ...event, ts: stamped }
+  }
+
+  try {
+    if (fd === null) {
+      const path = resolveTrailPath()
+      mkdirSync(dirname(path), { recursive: true })
+      fd = openSync(path, 'a')
+    }
+    const line = JSON.stringify(toWrite) + '\n'
+    writeSync(fd, line)
+  } catch (err) {
+    console.error('[slack] permission-trail: write failed', err)
+  }
+}
+
+/**
+ * Recommended call-site API for Epics 2–5: stamps `ts` from
+ * `new Date().toISOString()` (RFC 3339 with ms precision) and delegates to
+ * `emitTrailEvent`. Callers pass everything except `ts`.
+ */
+export function emitTrail(
+  partial: Omit<TrailEventBase, 'ts'> & { [extra: string]: unknown },
+): void {
+  emitTrailEvent({ ...partial, ts: new Date().toISOString() })
+}

package/src/server.ts

@@ -55,7 +55,10 @@ import {
 import { cleanSession, getCozempicAvailable } from './cozempic.ts'
 import { ErrSpawnNotFound } from 'agent-director'
 import { getClient, closeClient } from './agent-director-client.ts'
-import { handlePermissionClick } from './permission-click-handler.ts'
+import {
+  emitBlockActionReceived,
+  handlePermissionClick,
+} from './permission-click-handler.ts'
 import { trustBootstrap } from './trust-bootstrap.ts'
 import { startPermissionPoller, stopPermissionPoller } from './permission-poller.ts'
 import {
@@ -734,12 +737,28 @@ socket.on('interactive', async (evt) => {
   const { ack } = evt as { ack: () => Promise<void> }
   const p = ((evt as any).body ?? (evt as any).payload ?? evt) as Record<string, unknown>
   const actions = (Array.isArray(p['actions']) ? p['actions'] : []) as Array<{ action_id: string }>
+  // SR-V-2.6 / SR-V-2.9 envelope: pull the inbound channel / message ts /
+  // clicking user once per payload — all actions in this payload share them.
+  const channelId = ((p['channel'] as { id?: string } | undefined)?.id) ?? undefined
+  const messageTs = ((p['message'] as { ts?: string } | undefined)?.ts) ?? undefined
+  const userId = ((p['user'] as { id?: string } | undefined)?.id) ?? undefined
+
   for (const action of actions) {
     const actionId = action.action_id
-    const handled = await handlePermissionClick(actionId, {
-      getClient,
-      web,
+    // SR-V-2.9: emit cscb.block_action.received for every action regardless
+    // of whether handlePermissionClick decides to engage. Decode-failure
+    // cases are diagnostically critical for "I clicked and nothing happened".
+    emitBlockActionReceived(actionId, {
+      channel: channelId,
+      messageTs,
+      user: userId,
     })
+
+    const handled = await handlePermissionClick(
+      actionId,
+      { getClient, web },
+      { channel: channelId, messageTs, user: userId },
+    )
     if (handled) {
       await ack()
       return