typeclaw 0.25.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/src/agent/session-origin.ts

@@ -123,14 +123,20 @@ export const PARTICIPANTS_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
 type PlatformInfo = {
   displayName: string
   mentionMode: 'angle-id' | 'at-username' | 'alias'
+  // Whether this adapter registers a ReactionCallback, i.e. whether
+  // `channel_react` actually does anything here. Gates the proactive-reaction
+  // prompt guidance so we never tell a KakaoTalk/Telegram agent to react when
+  // the call would no-op. Keep in sync with the adapters that call
+  // `router.registerReaction` (github, slack-bot, discord-bot today).
+  supportsReactions: boolean
 }
 
 const PLATFORM_INFO: Record<AdapterId, PlatformInfo> = {
-  'slack-bot': { displayName: 'Slack', mentionMode: 'angle-id' },
-  'discord-bot': { displayName: 'Discord', mentionMode: 'angle-id' },
-  github: { displayName: 'GitHub', mentionMode: 'at-username' },
-  'telegram-bot': { displayName: 'Telegram', mentionMode: 'at-username' },
-  kakaotalk: { displayName: 'KakaoTalk', mentionMode: 'alias' },
+  'slack-bot': { displayName: 'Slack', mentionMode: 'angle-id', supportsReactions: true },
+  'discord-bot': { displayName: 'Discord', mentionMode: 'angle-id', supportsReactions: true },
+  github: { displayName: 'GitHub', mentionMode: 'at-username', supportsReactions: true },
+  'telegram-bot': { displayName: 'Telegram', mentionMode: 'at-username', supportsReactions: false },
+  kakaotalk: { displayName: 'KakaoTalk', mentionMode: 'alias', supportsReactions: false },
 }
 
 function getPlatformInfo(adapter: AdapterId): PlatformInfo {
@@ -348,6 +354,23 @@ function renderChannelOrigin(
   const conversationLine = renderConversationLine(origin)
   if (conversationLine !== null) lines.push('', conversationLine)
 
+  if (platformInfo.supportsReactions) {
+    lines.push(
+      '',
+      '**React like a teammate would.** You can drop an emoji on the message that',
+      'triggered this turn with `channel_react({ emoji })` — it posts no comment,',
+      'just a reaction. Read the message and pick what genuinely fits its tone:',
+      '`+1` to agree or approve, `rocket` for something shipping or exciting,',
+      '`tada` to celebrate, `heart` to show appreciation, `laugh` for something',
+      'funny, `eyes` to signal you are looking. Reach for it when a reaction adds',
+      'real warmth or signal — not on every message, and not just because you can.',
+      'A reaction does NOT satisfy the reply obligation below: when the message',
+      'needs a substantive answer, still send it via `channel_reply`. Think of',
+      'reactions as the lightweight, human layer on top of your words, not a',
+      'replacement for them.',
+    )
+  }
+
   lines.push(
     '',
     '**For every user message in this session, you MUST call `channel_reply`',

package/src/agent/subagent-completion-reminder.ts

@@ -16,6 +16,7 @@ export type CompletionReminderArgs = {
   durationMs: number
   error?: string
   channel?: boolean
+  adapter?: string
 }
 
 const CHANNEL_REPLY_NUDGE =
@@ -28,9 +29,23 @@ const CHANNEL_REPLY_NUDGE =
   'can see why the post-completion turn was silent. `NO_REPLY` is the legacy fallback only when ' +
   '`skip_response` is unavailable.'
 
+// Conditional carve-out for github channel sessions. The base nudge above
+// steers EVERY completion to `channel_reply`, which on github is a plain PR
+// comment — fine for most subagents, but wrong for a finished `reviewer`:
+// a verdict delivered as a comment leaves the PR "awaiting review" with no
+// formal approval. This reminder cannot tell a review turn from any other
+// completion, so the carve-out is phrased conditionally ("if this was a PR
+// review") to redirect only the review case without misleading the rest.
+const GITHUB_REVIEW_NUDGE =
+  'If this was a PR review, the verdict is a formal review, not a `channel_reply`: ' +
+  'post it via `gh api -X POST /repos/owner/repo/pulls/<N>/reviews` (APPROVE/REQUEST_CHANGES/COMMENT) ' +
+  'and end the turn with `skip_response`. A `channel_reply` that merely says "Approved" posts a ' +
+  'comment and leaves the PR awaiting review.'
+
 export function renderSubagentCompletionReminder(args: CompletionReminderArgs): string {
   const durationStr = formatReminderDuration(args.durationMs)
-  const channelTail = args.channel === true ? ` ${CHANNEL_REPLY_NUDGE}` : ''
+  const githubTail = args.channel === true && args.adapter === 'github' ? ` ${GITHUB_REVIEW_NUDGE}` : ''
+  const channelTail = args.channel === true ? ` ${CHANNEL_REPLY_NUDGE}${githubTail}` : ''
   if (args.ok) {
     return (
       `<system-reminder>\n` +

package/src/agent/tools/channel-react.ts

@@ -31,12 +31,19 @@ export function createChannelReactTool({
     name: 'channel_react',
     label: 'Channel React',
     description:
-      'Add an emoji reaction to the message that triggered this turn — a lightweight acknowledgment that does not post a comment. ' +
-      'On GitHub this reacts to the triggering issue/PR/comment (e.g. :eyes: to signal "I am looking at this"). ' +
-      'Use this instead of a textual "on it" reply when a reaction is enough. Pass the bare emoji name, no colons.',
+      'React to the message that triggered this turn with an emoji that fits its content or tone — a lightweight, ' +
+      'human touch that posts no comment. Works on GitHub (issue/PR/comment), Slack, and Discord. ' +
+      'Pick the reaction a thoughtful teammate would leave: :+1: to agree or approve, :rocket: for something ' +
+      'shipping or exciting, :tada: to celebrate, :heart: to show appreciation, :eyes: to signal "I am looking at this", ' +
+      ':laugh: for something funny. Use it when a reaction adds genuine social signal — not on every message. ' +
+      'A reaction does NOT replace `channel_reply`: when the message needs a substantive answer, still send one. ' +
+      'If a reaction alone is the whole response, call `skip_response` afterward so the turn ends cleanly. ' +
+      'Pass the bare emoji name, no colons.',
     parameters: Type.Object({
       emoji: Type.String({
-        description: 'Bare emoji name, no surrounding colons. e.g. "eyes", "+1", "rocket", "heart".',
+        description:
+          'Bare emoji name, no surrounding colons. Choose one that matches the message: ' +
+          'e.g. "+1", "rocket", "tada", "heart", "eyes", "laugh".',
         minLength: 1,
       }),
     }),

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,
     )
   }
 

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)

package/src/channels/router.ts

@@ -3233,6 +3233,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       error?: string
     },
   ): { kind: 'delivered'; keyId: string } => {
+    const adapter = live.keyId.split(':', 1)[0] ?? ''
     const text = renderSubagentCompletionReminder({
       subagent: args.subagent,
       taskId: args.taskId,
@@ -3240,6 +3241,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       durationMs: args.durationMs,
       ...(args.error !== undefined ? { error: args.error } : {}),
       channel: true,
+      adapter,
     })
     live.pendingSystemReminders.push(text)
     // The reminder tells the agent to fetch this result now; clear the

package/src/channels/schema.ts

@@ -125,12 +125,53 @@ export const DEFAULT_GITHUB_EVENT_ALLOWLIST = [
   'discussion_comment.created',
   'issues.opened',
   'pull_request.opened',
+  'pull_request.ready_for_review',
   'pull_request.review_requested',
   'pull_request.review_request_removed',
   'discussion.created',
   'pull_request_review.submitted',
 ] as const
 
+// Prior values of DEFAULT_GITHUB_EVENT_ALLOWLIST that shipped in releases and
+// were seeded verbatim into typeclaw.json. Kept as historical record so the
+// migration can recognize and unfreeze configs created by those versions.
+// NEVER edit these in place — they are snapshots of what was on disk.
+//   - v1: 7-event default, shipped 0.5.1–0.10.0 (commit fe4f3a8)
+const GITHUB_EVENT_ALLOWLIST_V1 = [
+  'issue_comment.created',
+  'pull_request_review_comment.created',
+  'discussion_comment.created',
+  'issues.opened',
+  'pull_request.opened',
+  'discussion.created',
+  'pull_request_review.submitted',
+] as const
+//   - v2: added review_requested + review_request_removed, shipped 0.11.0+ (commit 4f365ce)
+const GITHUB_EVENT_ALLOWLIST_V2 = [
+  'issue_comment.created',
+  'pull_request_review_comment.created',
+  'discussion_comment.created',
+  'issues.opened',
+  'pull_request.opened',
+  'pull_request.review_requested',
+  'pull_request.review_request_removed',
+  'discussion.created',
+  'pull_request_review.submitted',
+] as const
+
+// Every event-allowlist that `channel add` / `init` has ever seeded verbatim
+// into typeclaw.json, oldest first, current default last. The legacy-shape
+// migration uses this to tell a seeded default (safe to strip so the config
+// re-tracks the shipped default) from a user's deliberate customization (must
+// be preserved). Append the prior array here — never edit in place — whenever
+// DEFAULT_GITHUB_EVENT_ALLOWLIST changes, or configs from the old version stay
+// frozen and the migration starts eating user edits.
+export const SEEDED_GITHUB_EVENT_ALLOWLISTS: readonly (readonly string[])[] = [
+  GITHUB_EVENT_ALLOWLIST_V1,
+  GITHUB_EVENT_ALLOWLIST_V2,
+  DEFAULT_GITHUB_EVENT_ALLOWLIST,
+]
+
 // Which pull_request webhook action triggers an agent code review. The two
 // event values are GitHub's bare PR action names (the `pull_request.` event
 // prefix is implied by this field living under the review config); `off` is the

package/src/config/config.ts

@@ -5,7 +5,7 @@ import { isAbsolute, join, resolve } from 'node:path'
 import type { Model } from '@mariozechner/pi-ai'
 import { z } from 'zod'
 
-import { channelsSchema } from '@/channels/schema'
+import { channelsSchema, SEEDED_GITHUB_EVENT_ALLOWLISTS } from '@/channels/schema'
 import { commitSystemFileSync } from '@/git/system-commit'
 import { rolesConfigSchema } from '@/permissions/schema'
 import { secretFieldSchema } from '@/secrets/resolve'
@@ -810,6 +810,7 @@ export type MigrationStep =
   | { kind: 'strip-permissions-gate-channel-respond' }
   | { kind: 'model-to-models'; ref: string }
   | { kind: 'drop-stale-model'; ref: string }
+  | { kind: 'drop-github-seeded-event-allowlist' }
 
 export type MigrationResult = { json: unknown; changed: boolean; applied: MigrationStep[] }
 
@@ -830,13 +831,15 @@ export function migrateLegacyConfigShape(json: unknown): MigrationResult {
   // silently — same precedence rule as the dockerfile/gitignore migrations.
   const hasLegacyModel = 'model' in obj && !('models' in obj) && typeof obj.model === 'string'
   const hasStaleModelAlongsideModels = 'model' in obj && 'models' in obj
+  const hasSeededGithubEventAllowlist = isSeededGithubEventAllowlist(obj)
   if (
     !hasLegacyDockerfile &&
     !hasLegacyGitignore &&
     !channelsAllowMigration.found &&
     !hasLegacyGateChannelRespond &&
     !hasLegacyModel &&
-    !hasStaleModelAlongsideModels
+    !hasStaleModelAlongsideModels &&
+    !hasSeededGithubEventAllowlist
   ) {
     return { json, changed: false, applied: [] }
   }
@@ -897,9 +900,43 @@ export function migrateLegacyConfigShape(json: unknown): MigrationResult {
     delete next.model
     applied.push({ kind: 'drop-stale-model', ref })
   }
+  if (hasSeededGithubEventAllowlist) {
+    dropSeededGithubEventAllowlist(next)
+    applied.push({ kind: 'drop-github-seeded-event-allowlist' })
+  }
   return { json: next, changed: true, applied }
 }
 
+// True when channels.github.eventAllowlist deep-equals an allowlist that
+// `channel add` / `init` has previously seeded verbatim. Such a value is
+// indistinguishable from "the default at that time", so stripping it lets the
+// config re-track the shipped default. A user who hand-edited to any other set
+// (added/removed/reordered an event) fails this check and is preserved.
+function isSeededGithubEventAllowlist(obj: Record<string, unknown>): boolean {
+  const github = isPlainObject(obj.channels) ? obj.channels.github : undefined
+  if (!isPlainObject(github)) return false
+  const list = github.eventAllowlist
+  if (!Array.isArray(list)) return false
+  return SEEDED_GITHUB_EVENT_ALLOWLISTS.some((seeded) => arraysEqual(list, seeded))
+}
+
+function dropSeededGithubEventAllowlist(next: Record<string, unknown>): void {
+  const channels = next.channels
+  if (!isPlainObject(channels)) return
+  const github = channels.github
+  if (!isPlainObject(github)) return
+  const { eventAllowlist: _dropped, ...rest } = github
+  next.channels = { ...channels, github: rest }
+}
+
+function arraysEqual(a: readonly unknown[], b: readonly unknown[]): boolean {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false
+  }
+  return true
+}
+
 // Builds a meaningful one-line git commit subject for a typeclaw.json
 // migration. Single-step migrations get a specific subject; multi-step ones
 // fall back to a stable summary subject with the count. The body (after the
@@ -949,6 +986,8 @@ function shortStepLabel(step: MigrationStep): string {
       return 'lift model → models.default'
     case 'drop-stale-model':
       return 'drop stale legacy model alongside models'
+    case 'drop-github-seeded-event-allowlist':
+      return 'drop seeded channels.github.eventAllowlist'
   }
 }
 
@@ -972,6 +1011,8 @@ function describeStep(step: MigrationStep): string {
       return step.ref !== ''
         ? `drop stale top-level model (${step.ref}) — models block takes precedence`
         : 'drop stale top-level model — models block takes precedence'
+    case 'drop-github-seeded-event-allowlist':
+      return 'drop seeded channels.github.eventAllowlist so it re-tracks the shipped default'
   }
 }
 

package/src/init/index.ts

@@ -3,7 +3,6 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { basename, dirname, join, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { DEFAULT_GITHUB_EVENT_ALLOWLIST } from '@/channels/schema'
 import { config, configSchema, migrateLegacyConfigShape, type Config } from '@/config'
 import {
   DEFAULT_MODEL_REF,
@@ -1167,10 +1166,12 @@ async function mergeChannelIntoConfig(cwd: string, options: AddChannelOptions):
 }
 
 function buildGithubChannelConfig(options: Extract<AddChannelOptions, { channel: 'github' }>): Record<string, unknown> {
+  // Do NOT write eventAllowlist: the schema defaults it at parse time, so
+  // omitting it lets the user's config track the shipped default across
+  // releases instead of freezing the list captured at `channel add` time.
   return {
     ...(options.webhookUrl !== undefined ? { webhookUrl: options.webhookUrl } : {}),
     webhookPort: options.webhookPort ?? 8975,
-    eventAllowlist: [...DEFAULT_GITHUB_EVENT_ALLOWLIST],
     repos: options.repos,
   }
 }
@@ -1246,7 +1247,6 @@ async function writeGithubChannelForInit(cwd: string, credentials: GithubInitCre
   existingChannels.github = {
     ...(credentials.webhookUrl !== undefined ? { webhookUrl: credentials.webhookUrl } : {}),
     webhookPort: credentials.webhookPort ?? 8975,
-    eventAllowlist: [...DEFAULT_GITHUB_EVENT_ALLOWLIST],
     repos: credentials.repos,
   }
   parsed.channels = existingChannels

package/src/skills/typeclaw-channel-github/SKILL.md

@@ -189,7 +189,7 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
 
 A finding is "actionable" if its severity is `blocker`, `concern`, or `nit`. The inline-review post in step 4 applies whenever the actionable count is **at least one**. When the reviewer returns **exactly zero** actionable findings (only `praise`, or none), there is nothing to anchor inline — handle by verdict:
 
-- `approve` → post a plain `APPROVE` with the `<summary>` as the review body (no `comments[]` array). **If the operator approval policy above disabled approval, submit a `COMMENT` review instead — same `<summary>` as the review body, `event: "COMMENT"`, no `comments[]` array. Keep it a formal review, not a top-level issue comment, so the review metadata and flow are preserved.** (Re-review caveat: a `COMMENT` review does **not** clear a sticky `CHANGES_REQUESTED` block. If this is a re-review under approval-disabled policy, follow the step-4 re-review branch — dismiss your prior review — instead of relying on this `COMMENT`.)
+- `approve` → post a plain `APPROVE` with the `<summary>` as the review body (no `comments[]` array). **This is still a formal review via `POST /pulls/<N>/reviews`, NOT a `channel_reply`.** A zero-findings approval is the single most common place this goes wrong: with nothing to anchor inline, the model is tempted to just `channel_reply({ text: "Approved …" })` and end the turn. That posts a plain PR comment and leaves the PR **"awaiting review"** with no approval — the verdict never reaches GitHub's review API. Never start a top-level `channel_reply` on a `pr:N` with "Approved" / "LGTM" / "Request changes": those are verdicts, and verdicts are always formal reviews. Submit the `APPROVE` via `gh api`, confirm it landed (step 5), then `skip_response`. **If the operator approval policy above disabled approval, submit a `COMMENT` review instead — same `<summary>` as the review body, `event: "COMMENT"`, no `comments[]` array. Keep it a formal review, not a top-level issue comment, so the review metadata and flow are preserved.** (Re-review caveat: a `COMMENT` review does **not** clear a sticky `CHANGES_REQUESTED` block. If this is a re-review under approval-disabled policy, follow the step-4 re-review branch — dismiss your prior review — instead of relying on this `COMMENT`.)
 - `comment` → post the summary as a top-level PR comment via `gh api -X POST /repos/.../issues/<N>/comments` instead of submitting an empty review. **Exception — re-reviews:** if this is a re-review (you have an unresolved blocking obligation — a formal `CHANGES_REQUESTED` **or** an unretracted flat-comment blocker), a top-level comment discharges neither. Do not use this branch; resolve it via the step-4 re-review branch (`APPROVE` if resolved and approval is enabled, the dismissal endpoint if a formal block is resolved but approval is disabled, `REQUEST_CHANGES` if not resolved).
 - `request-changes` → submit `REQUEST_CHANGES` with the `<summary>` as the review body and no `comments[]` array. This combination is rare (the reviewer's contract says `request-changes` requires at least one blocker or load-bearing concern); if it happens, faithfully encode the verdict and trust the reviewer's reasoning is in the summary.
 

package/typeclaw.schema.json

@@ -529,6 +529,7 @@
                 "discussion_comment.created",
                 "issues.opened",
                 "pull_request.opened",
+                "pull_request.ready_for_review",
                 "pull_request.review_requested",
                 "pull_request.review_request_removed",
                 "discussion.created",