typeclaw 0.24.0 → 0.26.0

package/src/bundled-plugins/security/policies/ssrf.ts

@@ -100,7 +100,7 @@ export function classifyUrl(rawUrl: string): SsrfClassification {
 
 export function checkSsrfGuard(options: { tool: string; args: Record<string, unknown> }): SecurityBlock | undefined {
   const { tool, args } = options
-  if (tool !== 'webfetch') return undefined
+  if (tool !== 'web_fetch') return undefined
   const url = args.url
   if (typeof url !== 'string') return undefined
   if (isGuardAcknowledged(args, GUARD_SSRF)) return undefined
@@ -111,9 +111,9 @@ export function checkSsrfGuard(options: { tool: string; args: Record<string, unk
   return {
     block: true,
     reason: [
-      `Guard \`${GUARD_SSRF}\` blocked webfetch to a non-public destination (${result.category ?? 'unknown'}): ${result.reason ?? 'classified as internal'}.`,
+      `Guard \`${GUARD_SSRF}\` blocked web_fetch to a non-public destination (${result.category ?? 'unknown'}): ${result.reason ?? 'classified as internal'}.`,
       'This protects against SSRF, cloud metadata exfiltration, and accidental fetches against internal services.',
-      `If this is genuinely intentional and you trust the URL, retry with \`${ACKNOWLEDGE_GUARDS}.${GUARD_SSRF}: true\` in the webfetch arguments.`,
+      `If this is genuinely intentional and you trust the URL, retry with \`${ACKNOWLEDGE_GUARDS}.${GUARD_SSRF}: true\` in the web_fetch arguments.`,
     ].join(' '),
   }
 }

package/src/bundled-plugins/tool-result-cap/README.md

@@ -9,7 +9,7 @@ This plugin is **auto-loaded** by every TypeClaw agent. There is no `plugins[]`
 `pi-coding-agent`'s built-in tools occasionally return very large payloads that the model only needed once. Two empirically observed cases:
 
 1. **`read` on an image file** returns the base64-encoded image inline (e.g. `{type:"image", data:"<3.2MB of base64>"}`). The model uses it on the turn it was asked for, then sees the same 3.2MB of base64 as conversation context on every subsequent prompt — until compaction fires (which is token-driven, not byte-driven, so a single fat blob may sit in context for many turns before compaction is triggered).
-2. **`webfetch` on a binary URL** (PNG, ZIP, etc.) receives the raw response body, treats it as text, and stores raw binary as a JSON-encoded string. Same effect: 100KB+ of mojibake sits in the transcript permanently.
+2. **`web_fetch` on a binary URL** (PNG, ZIP, etc.) receives the raw response body, treats it as text, and stores raw binary as a JSON-encoded string. Same effect: 100KB+ of mojibake sits in the transcript permanently.
 
 The result is a session JSONL file that's tens of megabytes on disk but mostly one or two giant tool results, plus 3-minute first-prompt latencies after container restart because the full transcript gets re-shipped to the LLM as context.
 

package/src/channels/adapters/discord-bot-classify.ts

@@ -8,6 +8,8 @@ import type {
 import type { ChannelAdapterConfig } from '@/channels/schema'
 import type { InboundAttachment, InboundMessage } from '@/channels/types'
 
+import { encodeDiscordReactionRef } from './discord-bot-reactions'
+
 export type InboundDropReason =
   | 'self_author' // event.author.id === botUserId; we never route our own messages back to ourselves
   | 'empty_content' // SDK delivered content: '' — usually missing MessageContent intent
@@ -87,6 +89,7 @@ export function classifyInbound(
       text,
       ...(attachments.length > 0 ? { attachments } : {}),
       externalMessageId: event.id,
+      reactionRef: encodeDiscordReactionRef({ channel: event.channel_id, message: event.id }),
       authorId: event.author.id,
       // Discord's post-2023 username system allows pure-numeric handles (e.g.
       // "1411531"); the human-facing display name lives on `global_name`. The

package/src/channels/adapters/discord-bot-reactions.ts

@@ -0,0 +1,164 @@
+import type { DiscordBotClient } from 'agent-messenger/discordbot'
+
+import type {
+  ReactionCallback,
+  ReactionErrorCode,
+  ReactionRef,
+  ReactionResult,
+  RemoveReactionCallback,
+} from '@/channels/types'
+
+// The reactable target on Discord: a message is addressed by its channel id
+// plus the message id. The classifier stamps this because both values are on
+// the gateway event but `chat`/`externalMessageId` are the only ones that
+// survive into the routed payload — keeping them paired in an opaque ref means
+// the router/tool never have to reassemble Discord's addressing.
+export type DiscordReactionTarget = { channel: string; message: string }
+
+// `RemoveReactionRequest` carries no emoji (the router only round-trips the
+// success ref), so removal needs the resolved unicode folded into the ref:
+// Discord's DELETE is keyed by (channel, message, emoji). Mirrors Slack's
+// removal-ref pattern; GitHub instead carries a per-reaction id.
+export type DiscordReactionRemovalTarget = { channel: string; message: string; emoji: string }
+
+export function encodeDiscordReactionRef(target: DiscordReactionTarget): ReactionRef {
+  return { adapter: 'discord-bot', value: JSON.stringify(target) }
+}
+
+export function decodeDiscordReactionRef(ref: ReactionRef): DiscordReactionTarget | null {
+  if (ref.adapter !== 'discord-bot') return null
+  const parsed = parseRecord(ref.value)
+  if (parsed === null || parsed.op !== undefined) return null
+  const channel = typeof parsed.channel === 'string' ? parsed.channel : null
+  const message = typeof parsed.message === 'string' ? parsed.message : null
+  if (channel === null || message === null) return null
+  return { channel, message }
+}
+
+export function encodeDiscordRemovalRef(target: DiscordReactionRemovalTarget): ReactionRef {
+  return { adapter: 'discord-bot', value: JSON.stringify({ op: 'remove', ...target }) }
+}
+
+export function decodeDiscordRemovalRef(ref: ReactionRef): DiscordReactionRemovalTarget | null {
+  if (ref.adapter !== 'discord-bot') return null
+  const parsed = parseRecord(ref.value)
+  if (parsed === null || parsed.op !== 'remove') return null
+  const channel = typeof parsed.channel === 'string' ? parsed.channel : null
+  const message = typeof parsed.message === 'string' ? parsed.message : null
+  const emoji = typeof parsed.emoji === 'string' ? parsed.emoji : null
+  if (channel === null || message === null || emoji === null) return null
+  return { channel, message, emoji }
+}
+
+// Discord's reaction endpoint takes the literal unicode emoji (URL-encoded by
+// the SDK), NOT a `:name:` shortcode — the agent passes adapter-generic bare
+// names (`+1`, `rocket`), so we translate here. The set mirrors GitHub's fixed
+// reaction vocabulary so the same `channel_react({ emoji })` call works on both
+// platforms, plus a few extra chat-native acks. An unmapped name is reported as
+// `unsupported` rather than forwarded, so a typo gets a clear signal instead of
+// Discord's opaque `10014 Unknown Emoji`.
+const EMOJI_UNICODE: Record<string, string> = {
+  eyes: '👀',
+  '+1': '👍',
+  thumbsup: '👍',
+  '-1': '👎',
+  thumbsdown: '👎',
+  laugh: '😄',
+  hooray: '🎉',
+  tada: '🎉',
+  confused: '😕',
+  heart: '❤️',
+  rocket: '🚀',
+  white_check_mark: '✅',
+  'white-check-mark': '✅',
+  check: '✅',
+  fire: '🔥',
+  eye: '👁️',
+  raised_hands: '🙌',
+}
+
+function resolveEmoji(emoji: string): string | null {
+  const name = emoji.replace(/^:|:$/g, '')
+  return EMOJI_UNICODE[name] ?? null
+}
+
+export function createDiscordReactionCallback(deps: {
+  client: Pick<DiscordBotClient, 'addReaction'>
+}): ReactionCallback {
+  return async (req): Promise<ReactionResult> => {
+    if (req.adapter !== 'discord-bot') {
+      return { ok: false, error: `unknown adapter: ${req.adapter}`, code: 'unsupported' }
+    }
+    const unicode = resolveEmoji(req.emoji)
+    if (unicode === null) {
+      return { ok: false, error: `discord does not support reaction "${req.emoji}"`, code: 'unsupported' }
+    }
+    const target = decodeDiscordReactionRef(req.reactionRef)
+    if (target === null) return { ok: false, error: 'unparseable discord reaction ref', code: 'unsupported' }
+    try {
+      await deps.client.addReaction(target.channel, target.message, unicode)
+    } catch (err) {
+      return { ok: false, error: describe(err), code: classifyDiscordError(err) }
+    }
+    return { ok: true, reactionRef: encodeDiscordRemovalRef({ ...target, emoji: unicode }) }
+  }
+}
+
+export function createDiscordRemoveReactionCallback(deps: {
+  client: Pick<DiscordBotClient, 'removeReaction'>
+}): RemoveReactionCallback {
+  return async (req): Promise<ReactionResult> => {
+    if (req.adapter !== 'discord-bot') {
+      return { ok: false, error: `unknown adapter: ${req.adapter}`, code: 'unsupported' }
+    }
+    const target = decodeDiscordRemovalRef(req.reactionRef)
+    if (target === null) return { ok: false, error: 'unparseable discord reaction removal ref', code: 'unsupported' }
+    try {
+      await deps.client.removeReaction(target.channel, target.message, target.emoji)
+    } catch (err) {
+      return { ok: false, error: describe(err), code: classifyDiscordError(err) }
+    }
+    return { ok: true }
+  }
+}
+
+// DiscordBotError exposes the Discord error code on `.code` as a string. We
+// read it structurally so a wrapped/re-thrown error still classifies. The
+// numeric codes are Discord's documented JSON error codes; `http_4xx` is the
+// SDK's fallback when no JSON code is present.
+function classifyDiscordError(err: unknown): ReactionErrorCode {
+  const code = typeof err === 'object' && err !== null && 'code' in err ? String((err as { code: unknown }).code) : ''
+  switch (code) {
+    case '10003': // Unknown Channel
+    case '10008': // Unknown Message
+    case 'http_404':
+      return 'not-found'
+    case '50001': // Missing Access
+    case '50013': // Missing Permissions
+    case 'http_403':
+    case 'http_401':
+      return 'permission-denied'
+    case '10014': // Unknown Emoji
+      return 'unsupported'
+    case 'http_429':
+      return 'rate-limited'
+    default:
+      return 'transient'
+  }
+}
+
+function parseRecord(value: string): Record<string, unknown> | null {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(value)
+  } catch {
+    return null
+  }
+  return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+    ? (parsed as Record<string, unknown>)
+    : null
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}

package/src/channels/adapters/discord-bot.ts

@@ -39,6 +39,7 @@ import {
   type InboundDropReason,
   renderPlaceholder,
 } from './discord-bot-classify'
+import { createDiscordReactionCallback, createDiscordRemoveReactionCallback } from './discord-bot-reactions'
 import { enrichDiscordMessageReferences } from './discord-bot-reference'
 import {
   ackInteraction,
@@ -863,6 +864,9 @@ export function createDiscordBotAdapter(options: DiscordBotAdapterOptions): Disc
 
   const fetchAttachmentCallback = createFetchAttachmentCallback({ token: options.token, logger })
 
+  const reactionCallback = createDiscordReactionCallback({ client })
+  const removeReactionCallback = createDiscordRemoveReactionCallback({ client })
+
   const interactionHandler = createInteractionHandler({
     router: options.router,
     knownCommandNames: SLASH_COMMAND_NAMES,
@@ -999,6 +1003,8 @@ export function createDiscordBotAdapter(options: DiscordBotAdapterOptions): Disc
       })
 
       options.router.registerOutbound('discord-bot', outboundCallback)
+      options.router.registerReaction('discord-bot', reactionCallback)
+      options.router.registerRemoveReaction('discord-bot', removeReactionCallback)
       options.router.registerTyping('discord-bot', typingCallback)
       options.router.registerChannelNameResolver('discord-bot', channelResolver)
       options.router.registerSelfIdentity('discord-bot', selfIdentityResolver)
@@ -1009,6 +1015,21 @@ export function createDiscordBotAdapter(options: DiscordBotAdapterOptions): Disc
       try {
         await listener.start()
       } catch (err) {
+        // Listener failed after registration — roll back every callback so a
+        // failed start leaves no router state behind (stop() returns early on
+        // !started and would otherwise skip cleanup), mirroring the github
+        // adapter's rollback path.
+        options.router.unregisterOutbound('discord-bot', outboundCallback)
+        options.router.unregisterReaction('discord-bot', reactionCallback)
+        options.router.unregisterRemoveReaction('discord-bot', removeReactionCallback)
+        options.router.unregisterTyping('discord-bot', typingCallback)
+        options.router.unregisterChannelNameResolver('discord-bot', channelResolver)
+        options.router.unregisterSelfIdentity('discord-bot', selfIdentityResolver)
+        options.router.unregisterHistory('discord-bot', historyCallback)
+        options.router.unregisterFetchAttachment('discord-bot', fetchAttachmentCallback)
+        options.router.unregisterMembership('discord-bot', membershipResolver)
+        listener = null
+        botUserId = null
         started = false
         logger.error(`[discord-bot] listener start failed: ${describe(err)}`)
         throw err
@@ -1019,6 +1040,8 @@ export function createDiscordBotAdapter(options: DiscordBotAdapterOptions): Disc
       if (!started) return
       started = false
       options.router.unregisterOutbound('discord-bot', outboundCallback)
+      options.router.unregisterReaction('discord-bot', reactionCallback)
+      options.router.unregisterRemoveReaction('discord-bot', removeReactionCallback)
       options.router.unregisterTyping('discord-bot', typingCallback)
       options.router.unregisterChannelNameResolver('discord-bot', channelResolver)
       options.router.unregisterSelfIdentity('discord-bot', selfIdentityResolver)

package/src/channels/adapters/github/inbound.ts

@@ -301,7 +301,12 @@ export function classifyGithubInbound(
         teamIsBotMember: options?.teamIsBotMember,
       })
     }
-    if (action === 'opened' && reviewOn === 'opened') {
+    // `ready_for_review` (draft→ready) is a fresh review opportunity, so it
+    // reuses the `opened` paths: same review trigger, same title-only awareness
+    // text. The draft skip in classifyOpenedReviewTrigger is a no-op here since
+    // the PR is non-draft once ready — preserving "review when no longer draft".
+    const isOpenLike = action === 'opened' || action === 'ready_for_review'
+    if (isOpenLike && reviewOn === 'opened') {
       const trigger = classifyOpenedReviewTrigger({
         payload,
         pr,
@@ -314,8 +319,7 @@ export function classifyGithubInbound(
     }
     const opener = readUser(pr.user)
     const hasBody = readString(pr, 'body')?.trim() ? true : false
-    const prText =
-      action === 'opened' ? bodyOrOpenedTitle(pr.body, opener, 'PR', number, readString(pr, 'title')) : pr.body
+    const prText = isOpenLike ? bodyOrOpenedTitle(pr.body, opener, 'PR', number, readString(pr, 'title')) : pr.body
     return buildInbound(
       { ...base, chat: `pr:${number}`, thread: null },
       prText,
@@ -324,7 +328,7 @@ export function classifyGithubInbound(
       selfLogin,
       pr.created_at,
       { kind: 'issue', owner: repository.owner, repo: repository.name, issueNumber: number },
-      action === 'opened' && !hasBody,
+      isOpenLike && !hasBody,
     )
   }
 
@@ -494,6 +498,12 @@ function classifyOpenedReviewTrigger(input: OpenedReviewTriggerInput): InboundMe
   const decoyLogin = resolveDecoyReviewerLogin(selfLogin, authType)
   if (sender.login === selfLogin || (decoyLogin !== null && sender.login === decoyLogin)) return null
 
+  // A draft PR is work-in-progress, so the automatic `opened` path skips it: null
+  // here drops to awareness-only context (like a non-`opened` reviewOn) instead of
+  // waking a review. An explicit `review_requested` still triggers on a draft via
+  // classifyReviewRequest, preserving "skip until explicitly requested".
+  if (readBoolean(pr, 'draft') === true) return null
+
   const title = readString(pr, 'title') ?? `#${number}`
   const head = readString(readRecord(pr.head), 'ref')
   const baseRef = readString(readRecord(pr.base), 'ref')
@@ -738,6 +748,11 @@ function readNumber(obj: Record<string, unknown> | null, key: string): number |
   return typeof value === 'number' && Number.isFinite(value) ? value : null
 }
 
+function readBoolean(obj: Record<string, unknown> | null, key: string): boolean | null {
+  const value = obj?.[key]
+  return typeof value === 'boolean' ? value : null
+}
+
 function ok(): Response {
   return new Response('ok', { status: 200 })
 }

package/src/channels/adapters/github/webhook-register.ts

@@ -54,17 +54,25 @@ export async function registerGithubWebhooks(
   options: RegisterGithubWebhooksOptions,
 ): Promise<WebhookRegistrationResult> {
   const fetchImpl = options.fetchImpl ?? fetch
-  const repos: WebhookRepoResult[] = []
-  for (const repo of options.repos) {
-    let token: string
-    try {
-      token = await options.token(repo)
-    } catch (err) {
-      repos.push({ repo, action: 'failed', error: describe(err) })
-      continue
-    }
-    repos.push(await registerOne(fetchImpl, token, repo, options))
-  }
+  // Dedupe before fanning out: the serial loop self-corrected on a repeated
+  // repo (the second pass saw the first pass's hook and updated it), but
+  // concurrent passes would both list an empty set and each POST a hook,
+  // creating a duplicate. Collapsing to distinct slugs restores convergence.
+  const distinctRepos = [...new Set(options.repos)]
+  // Repos are independent (own installation token, own hooks), so register them
+  // concurrently. Every task resolves to a result (failures are caught into a
+  // `failed` entry, never thrown), so the batch never rejects and order is kept.
+  const repos = await Promise.all(
+    distinctRepos.map(async (repo): Promise<WebhookRepoResult> => {
+      let token: string
+      try {
+        token = await options.token(repo)
+      } catch (err) {
+        return { repo, action: 'failed', error: describe(err) }
+      }
+      return registerOne(fetchImpl, token, repo, options)
+    }),
+  )
   return { repos }
 }
 
@@ -82,17 +90,17 @@ export async function deregisterGithubWebhooks(
   options: DeregisterGithubWebhooksOptions,
 ): Promise<WebhookDeregistrationResult> {
   const fetchImpl = options.fetchImpl ?? fetch
-  const hooks: WebhookDeregistrationResult['hooks'] = []
-  for (const hook of options.hooks) {
-    let token: string
-    try {
-      token = await options.token(hook.repo)
-    } catch (err) {
-      hooks.push({ ...hook, action: 'failed', error: describe(err) })
-      continue
-    }
-    hooks.push(await deleteOne(fetchImpl, token, hook))
-  }
+  const hooks = await Promise.all(
+    options.hooks.map(async (hook): Promise<WebhookDeregistrationResult['hooks'][number]> => {
+      let token: string
+      try {
+        token = await options.token(hook.repo)
+      } catch (err) {
+        return { ...hook, action: 'failed', error: describe(err) }
+      }
+      return deleteOne(fetchImpl, token, hook)
+    }),
+  )
   return { hooks }
 }
 
@@ -125,11 +133,8 @@ async function registerOne(
     // inspecting the repo's webhook list.
     const [keep, ...stale] = owned.slice().sort((a, b) => a - b)
     await updateHook(fetchImpl, token, parsed, keep!, options)
-    let stalePruned = 0
-    for (const id of stale) {
-      const ok = await tryDeleteHook(fetchImpl, token, parsed, id)
-      if (ok) stalePruned++
-    }
+    const pruned = await Promise.all(stale.map((id) => tryDeleteHook(fetchImpl, token, parsed, id)))
+    const stalePruned = pruned.filter(Boolean).length
     return { repo, action: 'updated', hookId: keep!, stalePruned }
   } catch (err) {
     return { repo, action: 'failed', error: describe(err) }

package/src/channels/adapters/slack-bot-classify.ts

@@ -4,6 +4,7 @@ import { matchesAnyAlias } from '@/channels/engagement'
 import type { ChannelAdapterConfig } from '@/channels/schema'
 import type { InboundAttachment, InboundMessage } from '@/channels/types'
 
+import { encodeSlackReactionRef } from './slack-bot-reactions'
 import { hasSlackMessageShareAttachments } from './slack-bot-reference'
 import { slackTsToMillis } from './slack-bot-time'
 
@@ -141,6 +142,7 @@ export function classifyInbound(
       text,
       ...(attachments.length > 0 ? { attachments } : {}),
       externalMessageId: event.ts,
+      reactionRef: encodeSlackReactionRef({ channel: event.channel, ts: event.ts }),
       authorId: event.user,
       authorName: event.user,
       authorIsBot,

package/src/channels/adapters/slack-bot-reactions.ts

@@ -0,0 +1,167 @@
+import type { SlackBotClient } from 'agent-messenger/slackbot'
+
+import type {
+  ReactionCallback,
+  ReactionErrorCode,
+  ReactionRef,
+  ReactionResult,
+  RemoveReactionCallback,
+} from '@/channels/types'
+
+// The reactable target on Slack: a message is addressed by its channel id plus
+// the message `ts`. The classifier stamps this because `ts` is the inbound's
+// own message timestamp — the same value that becomes `externalMessageId`
+// downstream, but kept in an opaque ref so the router/tool never have to know
+// Slack's addressing. Mirrors the GitHub `GithubReactionTarget` precedent.
+export type SlackReactionTarget = { channel: string; ts: string }
+
+// Removal needs the emoji name too: Slack's `reactions.remove` is keyed by
+// (channel, ts, name), unlike GitHub's per-reaction id. We fold the emoji that
+// was added into the removal ref so `RemoveReactionCallback` can reconstruct
+// the exact call without the caller tracking it.
+export type SlackReactionRemovalTarget = { channel: string; ts: string; emoji: string }
+
+export function encodeSlackReactionRef(target: SlackReactionTarget): ReactionRef {
+  return { adapter: 'slack-bot', value: JSON.stringify(target) }
+}
+
+export function decodeSlackReactionRef(ref: ReactionRef): SlackReactionTarget | null {
+  if (ref.adapter !== 'slack-bot') return null
+  const parsed = parseRecord(ref.value)
+  if (parsed === null) return null
+  if (parsed.op !== undefined) return null
+  const channel = typeof parsed.channel === 'string' ? parsed.channel : null
+  const ts = typeof parsed.ts === 'string' ? parsed.ts : null
+  if (channel === null || ts === null) return null
+  return { channel, ts }
+}
+
+export function encodeSlackRemovalRef(target: SlackReactionRemovalTarget): ReactionRef {
+  return { adapter: 'slack-bot', value: JSON.stringify({ op: 'remove', ...target }) }
+}
+
+export function decodeSlackRemovalRef(ref: ReactionRef): SlackReactionRemovalTarget | null {
+  if (ref.adapter !== 'slack-bot') return null
+  const parsed = parseRecord(ref.value)
+  if (parsed === null || parsed.op !== 'remove') return null
+  const channel = typeof parsed.channel === 'string' ? parsed.channel : null
+  const ts = typeof parsed.ts === 'string' ? parsed.ts : null
+  const emoji = typeof parsed.emoji === 'string' ? parsed.emoji : null
+  if (channel === null || ts === null || emoji === null) return null
+  return { channel, ts, emoji }
+}
+
+// Slack accepts any custom-emoji name the workspace has, so unlike GitHub there
+// is no fixed allow-list to validate against up front — an unknown name comes
+// back as `invalid_name` from the API, which we map to `unsupported`. We only
+// strip surrounding colons here; the SDK does the same, but normalizing first
+// keeps the removal ref's stored name canonical.
+function normalizeEmoji(emoji: string): string {
+  return emoji.replace(/^:|:$/g, '')
+}
+
+export function createSlackReactionCallback(deps: { client: Pick<SlackBotClient, 'addReaction'> }): ReactionCallback {
+  return async (req): Promise<ReactionResult> => {
+    if (req.adapter !== 'slack-bot') {
+      return { ok: false, error: `unknown adapter: ${req.adapter}`, code: 'unsupported' }
+    }
+    const target = decodeSlackReactionRef(req.reactionRef)
+    if (target === null) return { ok: false, error: 'unparseable slack reaction ref', code: 'unsupported' }
+    const emoji = normalizeEmoji(req.emoji)
+    try {
+      await deps.client.addReaction(target.channel, target.ts, emoji)
+    } catch (err) {
+      // `already_reacted` is the desired end state, not a failure: a duplicate
+      // engage (or a retried tool call) that re-adds the same emoji must read
+      // as success so the model/runtime don't surface a spurious error.
+      const code = slackErrorCode(err)
+      if (code === 'already_reacted') {
+        return { ok: true, reactionRef: encodeSlackRemovalRef({ ...target, emoji }) }
+      }
+      return { ok: false, error: withScopeHint(code, describe(err)), code: classifySlackError(code) }
+    }
+    return { ok: true, reactionRef: encodeSlackRemovalRef({ ...target, emoji }) }
+  }
+}
+
+export function createSlackRemoveReactionCallback(deps: {
+  client: Pick<SlackBotClient, 'removeReaction'>
+}): RemoveReactionCallback {
+  return async (req): Promise<ReactionResult> => {
+    if (req.adapter !== 'slack-bot') {
+      return { ok: false, error: `unknown adapter: ${req.adapter}`, code: 'unsupported' }
+    }
+    const target = decodeSlackRemovalRef(req.reactionRef)
+    if (target === null) return { ok: false, error: 'unparseable slack reaction removal ref', code: 'unsupported' }
+    try {
+      await deps.client.removeReaction(target.channel, target.ts, target.emoji)
+    } catch (err) {
+      // `no_reaction` means the reaction is already gone — the desired end
+      // state for a removal, so treat it as success (idempotent), mirroring the
+      // `already_reacted` handling on the add path.
+      const code = slackErrorCode(err)
+      if (code === 'no_reaction') return { ok: true }
+      return { ok: false, error: describe(err), code: classifySlackError(code) }
+    }
+    return { ok: true }
+  }
+}
+
+// SlackBotError carries the raw Slack API error string on `.code`. We read it
+// structurally (not by instanceof) so a re-thrown or wrapped error still maps
+// correctly, falling back to the message when no code is present.
+function slackErrorCode(err: unknown): string | null {
+  if (typeof err === 'object' && err !== null && 'code' in err) {
+    const code = (err as { code: unknown }).code
+    if (typeof code === 'string') return code
+  }
+  return null
+}
+
+// `reactions:write` is the scope the bot token needs for both add and remove.
+// On `missing_scope` the bare Slack error is uninformative, so append the
+// concrete operator fix — mirroring GitHub's permission-guidance precedent —
+// since autoReactOnEngage surfaces this to host logs on every engaged inbound
+// until the scope is granted.
+function withScopeHint(code: string | null, error: string): string {
+  if (code !== 'missing_scope') return error
+  return `${error} (Slack bot token needs the \`reactions:write\` scope; reinstall/reauthorize the app with that scope.)`
+}
+
+function classifySlackError(code: string | null): ReactionErrorCode {
+  switch (code) {
+    case 'invalid_name':
+    case 'no_item_specified':
+      return 'unsupported'
+    case 'missing_scope':
+    case 'not_in_channel':
+    case 'is_archived':
+    case 'not_authed':
+    case 'invalid_auth':
+      return 'permission-denied'
+    case 'message_not_found':
+    case 'channel_not_found':
+      return 'not-found'
+    case 'ratelimited':
+    case 'rate_limited':
+      return 'rate-limited'
+    default:
+      return 'transient'
+  }
+}
+
+function parseRecord(value: string): Record<string, unknown> | null {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(value)
+  } catch {
+    return null
+  }
+  return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+    ? (parsed as Record<string, unknown>)
+    : null
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}

package/src/channels/adapters/slack-bot.ts

@@ -43,6 +43,7 @@ import {
   type SlackInboundMessageEvent,
 } from './slack-bot-classify'
 import { createSlackDedupe } from './slack-bot-dedupe'
+import { createSlackReactionCallback, createSlackRemoveReactionCallback } from './slack-bot-reactions'
 import { enrichSlackReferenceContext } from './slack-bot-reference'
 import {
   buildSlashAckPayload,
@@ -997,6 +998,9 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
 
   const fetchAttachmentCallback = createFetchAttachmentCallback({ client, logger })
 
+  const reactionCallback = createSlackReactionCallback({ client })
+  const removeReactionCallback = createSlackRemoveReactionCallback({ client })
+
   const dedupe = createSlackDedupe()
 
   const handleSlashCommand = createSlashCommandHandler({
@@ -1206,6 +1210,8 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
       })
 
       options.router.registerOutbound('slack-bot', outboundCallback)
+      options.router.registerReaction('slack-bot', reactionCallback)
+      options.router.registerRemoveReaction('slack-bot', removeReactionCallback)
       options.router.registerTyping('slack-bot', typingCallback)
       options.router.registerChannelNameResolver('slack-bot', channelResolver)
       options.router.registerSelfIdentity('slack-bot', selfIdentityResolver)
@@ -1216,6 +1222,22 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
       try {
         await listener.start()
       } catch (err) {
+        // Listener failed after registration — roll back every callback so a
+        // failed start leaves no router state behind (stop() returns early on
+        // !started and would otherwise skip cleanup), mirroring the github
+        // adapter's rollback path.
+        options.router.unregisterOutbound('slack-bot', outboundCallback)
+        options.router.unregisterReaction('slack-bot', reactionCallback)
+        options.router.unregisterRemoveReaction('slack-bot', removeReactionCallback)
+        options.router.unregisterTyping('slack-bot', typingCallback)
+        options.router.unregisterChannelNameResolver('slack-bot', channelResolver)
+        options.router.unregisterSelfIdentity('slack-bot', selfIdentityResolver)
+        options.router.unregisterHistory('slack-bot', historyCallback)
+        options.router.unregisterFetchAttachment('slack-bot', fetchAttachmentCallback)
+        options.router.unregisterMembership('slack-bot', membershipResolver)
+        listener = null
+        botUserId = null
+        teamId = null
         started = false
         logger.error(`[slack-bot] listener start failed: ${describe(err)}`)
         throw err
@@ -1226,6 +1248,8 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
       if (!started) return
       started = false
       options.router.unregisterOutbound('slack-bot', outboundCallback)
+      options.router.unregisterReaction('slack-bot', reactionCallback)
+      options.router.unregisterRemoveReaction('slack-bot', removeReactionCallback)
       options.router.unregisterTyping('slack-bot', typingCallback)
       options.router.unregisterChannelNameResolver('slack-bot', channelResolver)
       options.router.unregisterSelfIdentity('slack-bot', selfIdentityResolver)