typeclaw 0.20.0 → 0.22.0

package/src/bundled-plugins/github-cli-auth/index.ts

@@ -2,6 +2,7 @@ import { TYPECLAW_INTERNAL_BASH_ENV } from '@/agent/plugin-tools'
 import { definePlugin } from '@/plugin'
 
 import { analyzeGhCommand } from './gh-command'
+import { checkGraphqlAuthNudge } from './graphql-auth-nudge'
 import { classifyGhToken } from './token-class'
 
 export default definePlugin({
@@ -34,8 +35,14 @@ export default definePlugin({
           // --setenv by the bash wrapper) so the token never enters the command
           // string, where it could leak through logs or later hooks.
           event.args[TYPECLAW_INTERNAL_BASH_ENV] = { GH_TOKEN: result.token }
+          // graphql consumed `-R/--repo` as a mint hint; `gh api` rejects it, so
+          // run the command with the flag stripped (token still rides in env).
+          if (decision.rewrittenCommand !== undefined) event.args.command = decision.rewrittenCommand
           return
         },
+        'tool.after': async (event) => {
+          checkGraphqlAuthNudge({ tool: event.tool, result: event.result })
+        },
       },
     }
   },

package/src/bundled-plugins/memory/memory-logger.ts

@@ -81,9 +81,11 @@ Session transcripts are JSONL files where each line is an entry with an \`id\` f
 Typical flow with a watermark:
 
 1. \`find_entry(path=<transcript>, entryId=<watermark>)\` → returns \`line=N, totalLines=T, offset=N+1\`.
-2. \`read(path=<transcript>, offset=N+1)\` → returns the chunk starting AT the first unread entry. Repeat with the next offset until the read tool's continuation notice stops appearing.
+2. \`read(path=<transcript>, offset=N+1)\` → returns the chunk starting AT the first unread entry. Repeat with the next offset until you reach the end of the file. \`find_entry\` already told you \`totalLines=T\`: once a \`read\` has returned line T (or the read tool reports no continuation), you have reached the end of the transcript. Stop reading.
 3. As you read, track the most recent \`id\` you see. That is your new watermark value — pass it as \`latestEntryId\` on the final \`append\` call, or to the watermark-advance tool when there are zero fragments.
 
+**Reading is bounded — a finite transcript takes a finite number of reads.** \`find_entry\` gives you \`totalLines=T\` up front, so you always know the last line. Each \`read\` returns a slice and an offset to continue; advance the offset forward each time. Once you have read line T, or a \`read\` returns no new content (an empty chunk, or the same slice you already saw, or no continuation offset), you are at the end. Do NOT re-read the same offset, and do NOT keep calling \`read\` hoping more will appear — nothing more will. A read that returns nothing new is the end-of-file signal, not a transient error to retry. Re-reading past the end produces no new information and wastes the entire run; treat the first no-new-content read as "done reading" and move to your fragment decision.
+
 Never write the same watermark id you were given as input. If the transcript has no new entries past the watermark, evaluate the entries you can see, then advance the watermark to the latest \`id\` in the transcript (which is on line \`totalLines\` from \`find_entry\`'s reply). The whole point of the watermark is to move forward each run.
 
 # Capture philosophy: when in doubt, SKIP
@@ -202,7 +204,9 @@ When you evaluated the transcript but found nothing worth a fragment, call the w
 
 # Stopping
 
-When you're done, simply stop. There is no completion message to emit.`
+You are done the moment BOTH are true: (1) you have read to the end of the transcript (reached \`totalLines\` from \`find_entry\`, or a \`read\` returned no new content), and (2) you have either written your fragment(s) with the final \`latestEntryId\`, or advanced the watermark for the zero-fragment case. When both hold, simply stop. There is no completion message to emit.
+
+Do not loop. The hard stop is \`totalLines\`: a long transcript may legitimately need many \`read\` chunks to reach it, and that is fine as long as each \`read\` advances the offset toward \`totalLines\`. What is NOT fine is re-reading without progress. If a \`read\` returns no new content, returns the same slice you already saw, or your offset stops advancing, you are at the end — stop reading immediately and proceed to your fragment decision. A transcript has a fixed length; re-reading the same offset cannot surface content that is not there. The single most expensive failure mode for this subagent is re-reading the same file in a cycle instead of recognizing end-of-file and stopping.`
 
 function buildInitialPrompt(payload: MemoryLoggerPayload, streamFile: string, watermark: string | null): string {
   const lines: string[] = [

package/src/bundled-plugins/reviewer/skills/code-review.ts

@@ -64,6 +64,14 @@ Prioritize in this order:
 - **request-changes** — At least one blocker, OR a load-bearing concern that needs an answer before this lands.
 - **comment** — Mixed signal: useful observations without a clear approve/reject. Common on large refactors where you reviewed part of the change, or on early-draft PRs where the author asked for direction more than approval.
 
+### Re-reviews must re-decide, not observe
+
+When the payload tells you this is a **re-review** — you (or this agent) previously requested changes on this PR and the author has pushed fixes and asked again — your verdict's whole purpose is to **re-decide the blocking state**, so:
+
+- Return **approve** if the blockers that drove the prior \`request-changes\` are resolved (leftover nits do not block — \`approve\` with inline nits is correct).
+- Return **request-changes** if any blocker remains or a new one appeared.
+- **Do NOT return \`comment\` on a re-review.** \`comment\` is for ambiguous partial reviews with no accept/reject signal; a re-review is the opposite — it is precisely an accept/reject decision. A \`comment\` verdict here leaves the PR's \`REQUEST_CHANGES\` state stuck (a plain comment does not clear it on GitHub), which is the exact failure a re-review exists to resolve. The only escape hatch is the same one that always applies: if you genuinely cannot reach the diff or the prior context, return one \`blocker\` finding stating what you need and a \`comment\` verdict — but a reachable, reviewable re-review must end in \`approve\` or \`request-changes\`.
+
 ## Line-anchor every finding
 
 Code review is line-level work, and your findings are meant to land as **inline comments on the exact lines they describe**. The parent agent posts them that way — it reads the \`location\` on each \`<finding>\` and attaches your \`<issue>\`/\`<evidence>\`/\`<suggestion>\` to that line. A finding with no line anchor cannot be posted inline; the parent can only fold it into a top-level summary, which strips the one thing that made it actionable.

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

@@ -141,7 +141,13 @@ function splitInbound(event: DiscordGatewayMessageCreateEvent): SplitInbound {
   return { text, attachments }
 }
 
-function describeDiscordMedia(event: DiscordGatewayMessageCreateEvent): InboundAttachment[] {
+export type DiscordMediaCarrier = {
+  attachments?: DiscordFile[]
+  embeds?: DiscordGatewayEmbed[]
+  sticker_items?: DiscordGatewayStickerItem[]
+}
+
+export function describeDiscordMedia(event: DiscordMediaCarrier): InboundAttachment[] {
   return [
     ...(event.attachments ?? []).map(describeAttachment),
     ...(event.embeds ?? []).map(describeEmbed),
@@ -167,7 +173,7 @@ function describeSticker(sticker: DiscordGatewayStickerItem): Omit<InboundAttach
   return { kind: 'sticker', ref: '', filename: sticker.name }
 }
 
-function renderPlaceholder(attachment: InboundAttachment): string {
+export function renderPlaceholder(attachment: InboundAttachment): string {
   const parts: string[] = [`Discord attachment #${attachment.id}: ${attachment.kind}`]
   if (attachment.mimetype !== undefined) parts.push(attachment.mimetype)
   if (attachment.filename !== undefined) parts.push(`name=${attachment.filename}`)

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

@@ -1,8 +1,11 @@
 import { DiscordBotClient, DiscordBotListener } from 'agent-messenger/discordbot'
 import {
   DiscordIntent,
+  type DiscordFile,
+  type DiscordGatewayEmbed,
   type DiscordGatewayInteractionEvent,
   type DiscordGatewayMessageCreateEvent,
+  type DiscordGatewayStickerItem,
 } from 'agent-messenger/discordbot'
 
 import {
@@ -29,7 +32,12 @@ import type {
 } from '@/channels/types'
 
 import { createDiscordChannelResolver } from './discord-bot-channel-resolver'
-import { classifyInbound, type InboundDropReason } from './discord-bot-classify'
+import {
+  classifyInbound,
+  describeDiscordMedia,
+  type InboundDropReason,
+  renderPlaceholder,
+} from './discord-bot-classify'
 import {
   ackInteraction,
   parseInteractionAsCommand,
@@ -44,6 +52,8 @@ import {
 const SLASH_COMMANDS: readonly DiscordCommandDeclaration[] = [
   { name: 'help', description: 'List available commands' },
   { name: 'stop', description: 'Abort the current turn in this channel' },
+  { name: 'reload', description: 'Reload typeclaw config and subsystems from disk' },
+  { name: 'restart', description: 'Restart the typeclaw container' },
 ]
 const SLASH_COMMAND_NAMES: ReadonlySet<string> = new Set(SLASH_COMMANDS.map((c) => c.name))
 
@@ -487,6 +497,9 @@ type DiscordRawHistoryMessage = {
   content: string
   timestamp: string
   message_reference?: { message_id?: string }
+  attachments?: DiscordFile[]
+  embeds?: DiscordGatewayEmbed[]
+  sticker_items?: DiscordGatewayStickerItem[]
 }
 
 // Discord treats threads as separate channels with their own snowflake ids,
@@ -551,14 +564,28 @@ export function createDiscordHistoryCallback(deps: {
 function mapDiscordMessage(msg: DiscordRawHistoryMessage, botUserId: string | null): ChannelHistoryMessage {
   const isBot = msg.author.bot === true || (botUserId !== null && msg.author.id === botUserId)
   const ts = Date.parse(msg.timestamp)
+  // The REST history fetch bypasses the inbound classifier, so attachments,
+  // embeds, and stickers on already-posted messages (e.g. an image on a thread
+  // root the agent is later @-mentioned under) must be mapped here too —
+  // otherwise they are silently dropped and look_at_channel_attachment can
+  // never resolve them. Mirror the classifier's splitInbound: bake placeholders
+  // into text and carry the structured attachments so the router can resolve ids.
+  const attachments = describeDiscordMedia(msg)
+  const text =
+    attachments.length === 0
+      ? msg.content
+      : msg.content === ''
+        ? attachments.map(renderPlaceholder).join('\n')
+        : `${msg.content}\n${attachments.map(renderPlaceholder).join('\n')}`
   return {
     externalMessageId: msg.id,
     authorId: msg.author.id,
     authorName: msg.author.global_name ?? msg.author.username ?? msg.author.id,
-    text: msg.content,
+    text,
     ts: Number.isFinite(ts) ? ts : 0,
     isBot,
     replyToBotMessageId: msg.message_reference?.message_id ?? null,
+    ...(attachments.length > 0 ? { attachments } : {}),
   }
 }
 

package/src/channels/adapters/github/decoy-reviewer.ts

@@ -0,0 +1,43 @@
+import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+
+// `absent` separates "GitHub says the reviewer is already not requested"
+// (404/422 — never on the list, already removed, or invalid for the repo) from
+// `failed` ("couldn't reach GitHub"), so callers warn only on the latter.
+export type RemoveRequestedReviewerResult =
+  | { kind: 'removed'; status: number }
+  | { kind: 'absent'; status: number; message: string }
+  | { kind: 'failed'; status?: number; reason: string }
+
+export async function removeRequestedReviewer(params: {
+  fetchImpl: typeof fetch
+  token: string
+  owner: string
+  repo: string
+  pullNumber: number
+  reviewerLogin: string
+}): Promise<RemoveRequestedReviewerResult> {
+  const url = `${GITHUB_API_BASE}/repos/${params.owner}/${params.repo}/pulls/${params.pullNumber}/requested_reviewers`
+  try {
+    const response = await params.fetchImpl(url, {
+      method: 'DELETE',
+      headers: githubJsonHeaders(params.token),
+      body: JSON.stringify({ reviewers: [params.reviewerLogin] }),
+    })
+    if (response.ok) return { kind: 'removed', status: response.status }
+    const message = await response.text().catch(() => '')
+    // 404 (PR/reviewer not found) and 422 (reviewer not currently requested,
+    // or not a valid reviewer for this repo) mean there is nothing to remove —
+    // the desired end state already holds. Everything else (401/403 auth,
+    // 429 rate, 5xx) is a real failure worth surfacing.
+    if (response.status === 404 || response.status === 422) {
+      return { kind: 'absent', status: response.status, message }
+    }
+    return {
+      kind: 'failed',
+      status: response.status,
+      reason: `GitHub API ${response.status}${message !== '' ? `: ${message}` : ''}`,
+    }
+  } catch (err) {
+    return { kind: 'failed', reason: err instanceof Error ? err.message : String(err) }
+  }
+}

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

@@ -2,6 +2,8 @@ import { createHmac, timingSafeEqual } from 'node:crypto'
 
 import type { InboundMessage } from '@/channels/types'
 
+import type { GithubAuthContext } from './auth'
+import { removeRequestedReviewer } from './decoy-reviewer'
 import type { DeliveryDedup } from './dedup'
 import { isGithubEventAllowed } from './event-allowlist'
 import { encodeGithubReactionRef, type GithubReactionTarget } from './reactions'
@@ -17,12 +19,23 @@ export type GithubWebhookHandlerOptions = {
   // Defaults to 'pat' when omitted. In 'app' mode classifyReviewRequest also
   // matches the App's decoy reviewer login; see resolveDecoyReviewerLogin.
   authType?: () => 'pat' | 'app'
+  // Defaults to true when omitted. When it returns false, every inbound carries
+  // an appended operator-policy note telling the agent not to submit an APPROVE
+  // review; the github skill keys off that note to downgrade approve→COMMENT.
+  allowApprove?: () => boolean
   route: (message: InboundMessage) => void
   logger: GithubInboundLogger
   // Optional: resolves whether the bot is a member of the given team. When
   // omitted, team-reviewer requests are silently dropped (the v1 fallback
   // behavior). The adapter wires this in production; tests inject a fake.
   isBotInTeam?: (input: { org: string; slug: string; login: string }) => Promise<boolean>
+  // App-auth only: mints a repo-scoped token used to drop the decoy reviewer
+  // once the bot's own review lands. Omitted under PAT auth (no decoy exists).
+  authToken?: (context?: GithubAuthContext) => Promise<string>
+  // Schedules the decoy-drop off the webhook ACK path so the 200 stays fast.
+  // Defaults to fire-and-forget; tests inject a recorder to await the task.
+  scheduleBackgroundTask?: (task: () => Promise<void>) => void
+  fetchImpl?: typeof fetch
 }
 
 export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions): (req: Request) => Promise<Response> {
@@ -51,6 +64,7 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
     const selfLogin = options.selfLogin()
     const author = readAuthor(event, payload)
     if (author !== null && isSelfAuthor(author, selfId, selfLogin)) {
+      maybeScheduleDecoyReviewerDrop({ event, action, payload, selfLogin, options })
       options.logger.info(
         `[github] dropped self-authored ${event}${action !== null ? `.${action}` : ''} from @${author.login}`,
       )
@@ -65,11 +79,88 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
     if (classified === null) return ok()
 
     if (delivery !== '') options.dedup.add(delivery)
-    options.route(classified)
+    options.route(withApprovalPolicy(classified, options.allowApprove?.() ?? true))
     return ok()
   }
 }
 
+export const PR_APPROVAL_DISABLED_NOTE =
+  'Operator policy: PR approval is disabled for this agent ' +
+  '(`channels.github.review.approve: false`). If you review a PR and the ' +
+  'verdict is `approve`, submit a `COMMENT` review instead of `APPROVE` — post ' +
+  'the findings, but never formally approve.'
+
+// Gating PR approval lives here (inbound text), not at the bash layer: the
+// review is posted via `gh api --input <file>`, so the `event: APPROVE` value
+// sits in a temp file the gh-cli-auth command interceptor never inspects. The
+// note rides on every inbound (cheap: one line, only when an operator has
+// opted out) so it reaches the agent for both webhook review requests and
+// plain-language "@bot review this" asks, which arrive on arbitrary inbounds.
+function withApprovalPolicy(message: InboundMessage, allowApprove: boolean): InboundMessage {
+  if (allowApprove) return message
+  const text = message.text === '' ? PR_APPROVAL_DISABLED_NOTE : `${message.text}\n\n${PR_APPROVAL_DISABLED_NOTE}`
+  return { ...message, text }
+}
+
+// GitHub auto-records the App as a reviewer the moment its review posts, but
+// leaves the decoy user pinned as a perpetual "review requested". When the bot
+// drops its own review (the self-authored event we're about to discard), fire a
+// background DELETE to remove the decoy. The DELETE is authenticated as the App,
+// so the resulting review_request_removed webhook has the bot actor as sender
+// and is dropped by classifyReviewRequest's self-loop guard — no fresh session.
+function maybeScheduleDecoyReviewerDrop(input: {
+  event: string
+  action: string | null
+  payload: Record<string, unknown>
+  selfLogin: string | null
+  options: GithubWebhookHandlerOptions
+}): void {
+  const { event, action, payload, selfLogin, options } = input
+  if (event !== 'pull_request_review' || action !== 'submitted') return
+  if (selfLogin === null) return
+  const authToken = options.authToken
+  if (authToken === undefined) return
+  if ((options.authType?.() ?? 'pat') !== 'app') return
+  const decoyLogin = resolveDecoyReviewerLogin(selfLogin, 'app')
+  if (decoyLogin === null) return
+
+  const repository = readRepository(payload)
+  const pr = readRecord(payload.pull_request)
+  const pullNumber = readNumber(pr, 'number')
+  if (repository === null || pullNumber === null) return
+
+  const fetchImpl = options.fetchImpl ?? fetch
+  const schedule = options.scheduleBackgroundTask ?? defaultScheduleBackgroundTask
+  const target = `${repository.owner}/${repository.name}#${pullNumber}`
+  schedule(async () => {
+    // authToken can throw (installation lookup / token mint), and a thrown
+    // failure must still warn — the default scheduler swallows rejections, so
+    // catching here is the only place the failure is observable.
+    try {
+      const token = await authToken({ repoSlug: `${repository.owner}/${repository.name}` })
+      const result = await removeRequestedReviewer({
+        fetchImpl,
+        token,
+        owner: repository.owner,
+        repo: repository.name,
+        pullNumber,
+        reviewerLogin: decoyLogin,
+      })
+      if (result.kind === 'failed') {
+        options.logger.warn(`[github] failed to drop decoy reviewer @${decoyLogin} from ${target}: ${result.reason}`)
+      }
+    } catch (err) {
+      options.logger.warn(
+        `[github] failed to drop decoy reviewer @${decoyLogin} from ${target}: ${err instanceof Error ? err.message : String(err)}`,
+      )
+    }
+  })
+}
+
+function defaultScheduleBackgroundTask(task: () => Promise<void>): void {
+  void task().catch(() => {})
+}
+
 export async function verifySignature(body: string, secret: string, sigHeader: string): Promise<boolean> {
   const expected = `sha256=${createHmac('sha256', secret).update(body).digest('hex')}`
   const a = Buffer.from(expected)

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

@@ -19,7 +19,7 @@ import {
   buildPermissionGuidance,
   parseListHooksPermissionStatus,
 } from './permission-guidance'
-import { createGithubReactionCallback } from './reactions'
+import { createGithubReactionCallback, createGithubRemoveReactionCallback } from './reactions'
 import { createTeamMembershipChecker } from './team-membership'
 import { deregisterGithubWebhooks, registerGithubWebhooks, type WebhookRegistrationResult } from './webhook-register'
 
@@ -125,6 +125,11 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     authType: options.secrets.auth.type,
     fetchImpl,
   })
+  const removeReaction = createGithubRemoveReactionCallback({
+    token: authToken,
+    authType: options.secrets.auth.type,
+    fetchImpl,
+  })
   const history = createGithubHistoryCallback({
     token: authToken,
     fetchImpl,
@@ -144,7 +149,10 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     selfId: () => selfId,
     selfLogin: () => selfLogin,
     authType: () => options.secrets.auth.type,
+    allowApprove: () => options.configRef().review.approve,
     isBotInTeam,
+    authToken,
+    fetchImpl,
     logger,
     route: (message) => {
       rememberWorkspace(message.workspace, message.chat)
@@ -168,6 +176,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       // is fully wired before any webhook can arrive.
       options.router.registerOutbound('github', outbound)
       options.router.registerReaction('github', reaction)
+      options.router.registerRemoveReaction('github', removeReaction)
       options.router.registerTyping('github', typing)
       options.router.registerHistory('github', history)
       options.router.registerMembership('github', membership)
@@ -180,6 +189,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         // and the manager can report the failure cleanly.
         options.router.unregisterOutbound('github', outbound)
         options.router.unregisterReaction('github', reaction)
+        options.router.unregisterRemoveReaction('github', removeReaction)
         options.router.unregisterTyping('github', typing)
         options.router.unregisterHistory('github', history)
         options.router.unregisterMembership('github', membership)
@@ -301,6 +311,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       started = false
       options.router.unregisterOutbound('github', outbound)
       options.router.unregisterReaction('github', reaction)
+      options.router.unregisterRemoveReaction('github', removeReaction)
       options.router.unregisterTyping('github', typing)
       options.router.unregisterHistory('github', history)
       options.router.unregisterMembership('github', membership)

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

@@ -1,4 +1,10 @@
-import type { ReactionCallback, ReactionErrorCode, ReactionRef, ReactionResult } from '@/channels/types'
+import type {
+  RemoveReactionCallback,
+  ReactionCallback,
+  ReactionErrorCode,
+  ReactionRef,
+  ReactionResult,
+} from '@/channels/types'
 
 import type { GithubAuthContext } from './auth'
 import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
@@ -21,6 +27,11 @@ export type GithubReactionTarget =
   | { kind: 'issue-comment'; owner: string; repo: string; commentId: number }
   | { kind: 'pr-review-comment'; owner: string; repo: string; commentId: number }
 
+export type GithubReactionRemovalTarget =
+  | { kind: 'issue'; owner: string; repo: string; issueNumber: number; reactionId: number }
+  | { kind: 'issue-comment'; owner: string; repo: string; commentId: number; reactionId: number }
+  | { kind: 'pr-review-comment'; owner: string; repo: string; commentId: number; reactionId: number }
+
 export function encodeGithubReactionRef(target: GithubReactionTarget): ReactionRef {
   return { adapter: 'github', value: JSON.stringify(target) }
 }
@@ -35,6 +46,7 @@ export function decodeGithubReactionRef(ref: ReactionRef): GithubReactionTarget
   }
   if (typeof parsed !== 'object' || parsed === null) return null
   const t = parsed as Record<string, unknown>
+  if (t.op !== undefined) return null
   const owner = typeof t.owner === 'string' ? t.owner : null
   const repo = typeof t.repo === 'string' ? t.repo : null
   if (owner === null || repo === null) return null
@@ -47,6 +59,32 @@ export function decodeGithubReactionRef(ref: ReactionRef): GithubReactionTarget
   return null
 }
 
+export function encodeGithubRemovalRef(target: GithubReactionRemovalTarget): ReactionRef {
+  return { adapter: 'github', value: JSON.stringify({ op: 'remove', ...target }) }
+}
+
+export function decodeGithubRemovalRef(ref: ReactionRef): GithubReactionRemovalTarget | null {
+  if (ref.adapter !== 'github') return null
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(ref.value)
+  } catch {
+    return null
+  }
+  if (typeof parsed !== 'object' || parsed === null) return null
+  const t = parsed as Record<string, unknown>
+  const owner = typeof t.owner === 'string' ? t.owner : null
+  const repo = typeof t.repo === 'string' ? t.repo : null
+  if (t.op !== 'remove' || owner === null || repo === null || typeof t.reactionId !== 'number') return null
+  if (t.kind === 'issue' && typeof t.issueNumber === 'number') {
+    return { kind: 'issue', owner, repo, issueNumber: t.issueNumber, reactionId: t.reactionId }
+  }
+  if ((t.kind === 'issue-comment' || t.kind === 'pr-review-comment') && typeof t.commentId === 'number') {
+    return { kind: t.kind, owner, repo, commentId: t.commentId, reactionId: t.reactionId }
+  }
+  return null
+}
+
 // GitHub's Reactions API takes a fixed vocabulary of content strings. Map the
 // adapter-generic emoji name onto it; anything outside the set is reported as
 // `unsupported` so the model gets a clear signal rather than a silent 422.
@@ -82,8 +120,35 @@ export function createGithubReactionCallback(deps: {
     const endpoint = reactionEndpoint(target)
     const endpointKind: OutboundEndpointKind =
       target.kind === 'pr-review-comment' ? 'pr-review-comment-reaction' : 'issue-reaction'
-    return await postReaction(fetchImpl, await deps.token({ repoSlug: `${target.owner}/${target.repo}` }), endpoint, {
-      content,
+    return await postReaction(
+      fetchImpl,
+      await deps.token({ repoSlug: `${target.owner}/${target.repo}` }),
+      endpoint,
+      target,
+      {
+        content,
+        authType: deps.authType,
+        endpointKind,
+      },
+    )
+  }
+}
+
+export function createGithubRemoveReactionCallback(deps: {
+  token: (context?: GithubAuthContext) => Promise<string>
+  authType: GithubAuthType
+  fetchImpl?: typeof fetch
+}): RemoveReactionCallback {
+  const fetchImpl = deps.fetchImpl ?? fetch
+  return async (req): Promise<ReactionResult> => {
+    if (req.adapter !== 'github') return { ok: false, error: `unknown adapter: ${req.adapter}`, code: 'unsupported' }
+    const target = decodeGithubRemovalRef(req.reactionRef)
+    if (target === null) return { ok: false, error: 'unparseable github reaction removal ref', code: 'unsupported' }
+
+    const endpoint = removeReactionEndpoint(target)
+    const endpointKind: OutboundEndpointKind =
+      target.kind === 'pr-review-comment' ? 'pr-review-comment-reaction' : 'issue-reaction'
+    return await deleteReaction(fetchImpl, await deps.token({ repoSlug: `${target.owner}/${target.repo}` }), endpoint, {
       authType: deps.authType,
       endpointKind,
     })
@@ -102,10 +167,23 @@ function reactionEndpoint(target: GithubReactionTarget): string {
   }
 }
 
+function removeReactionEndpoint(target: GithubReactionRemovalTarget): string {
+  const base = `${GITHUB_API_BASE}/repos/${target.owner}/${target.repo}`
+  switch (target.kind) {
+    case 'issue':
+      return `${base}/issues/${target.issueNumber}/reactions/${target.reactionId}`
+    case 'issue-comment':
+      return `${base}/issues/comments/${target.commentId}/reactions/${target.reactionId}`
+    case 'pr-review-comment':
+      return `${base}/pulls/comments/${target.commentId}/reactions/${target.reactionId}`
+  }
+}
+
 async function postReaction(
   fetchImpl: typeof fetch,
   token: string,
   url: string,
+  target: GithubReactionTarget,
   options: { content: string; authType: GithubAuthType; endpointKind: OutboundEndpointKind },
 ): Promise<ReactionResult> {
   let response: Response
@@ -121,7 +199,11 @@ async function postReaction(
   // 201 = reaction created, 200 = the actor already left this same reaction.
   // Both are success: an :eyes: that's already there is the desired end state,
   // so a duplicate webhook delivery (or a retried engage) must not surface an error.
-  if (response.status === 200 || response.status === 201) return { ok: true }
+  if (response.status === 200 || response.status === 201) {
+    const reactionId = await readReactionId(response)
+    if (reactionId === null) return { ok: true }
+    return { ok: true, reactionRef: encodeGithubRemovalRef(removalTargetFor(target, reactionId)) }
+  }
   const text = await response.text().catch(() => '')
   const baseError = `GitHub API ${response.status}${text !== '' ? `: ${text}` : ''}`
   if (isOutboundPermissionDenial(response.status, text)) {
@@ -134,6 +216,58 @@ async function postReaction(
   return { ok: false, error: baseError, code: classifyStatus(response.status) }
 }
 
+async function deleteReaction(
+  fetchImpl: typeof fetch,
+  token: string,
+  url: string,
+  options: { authType: GithubAuthType; endpointKind: OutboundEndpointKind },
+): Promise<ReactionResult> {
+  let response: Response
+  try {
+    response = await fetchImpl(url, {
+      method: 'DELETE',
+      headers: githubJsonHeaders(token),
+    })
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err), code: 'transient' }
+  }
+  if (response.status === 204) return { ok: true }
+  const text = await response.text().catch(() => '')
+  const baseError = `GitHub API ${response.status}${text !== '' ? `: ${text}` : ''}`
+  if (isOutboundPermissionDenial(response.status, text)) {
+    return {
+      ok: false,
+      error: `${baseError}${buildOutboundPermissionGuidance({ authType: options.authType, endpointKind: options.endpointKind })}`,
+      code: 'permission-denied',
+    }
+  }
+  return { ok: false, error: baseError, code: classifyStatus(response.status) }
+}
+
+function removalTargetFor(target: GithubReactionTarget, reactionId: number): GithubReactionRemovalTarget {
+  switch (target.kind) {
+    case 'issue':
+      return { kind: 'issue', owner: target.owner, repo: target.repo, issueNumber: target.issueNumber, reactionId }
+    case 'issue-comment':
+      return { kind: 'issue-comment', owner: target.owner, repo: target.repo, commentId: target.commentId, reactionId }
+    case 'pr-review-comment':
+      return {
+        kind: 'pr-review-comment',
+        owner: target.owner,
+        repo: target.repo,
+        commentId: target.commentId,
+        reactionId,
+      }
+  }
+}
+
+async function readReactionId(response: Response): Promise<number | null> {
+  const body = await response.json().catch(() => null)
+  if (typeof body !== 'object' || body === null) return null
+  const id = (body as Record<string, unknown>).id
+  return typeof id === 'number' ? id : null
+}
+
 function classifyStatus(status: number): ReactionErrorCode {
   if (status === 403) return 'permission-denied'
   if (status === 404) return 'not-found'

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

@@ -182,7 +182,7 @@ function describeSlackMedia(event: SlackInboundMessageEvent): InboundAttachment[
   return (event.files ?? []).map((file, index) => describeSlackFile(file, index + 1))
 }
 
-function describeSlackFile(file: SlackFile, id: number): InboundAttachment {
+export function describeSlackFile(file: SlackFile, id: number): InboundAttachment {
   return {
     id,
     kind: 'file',
@@ -192,7 +192,7 @@ function describeSlackFile(file: SlackFile, id: number): InboundAttachment {
   }
 }
 
-function renderPlaceholder(attachment: InboundAttachment): string {
+export function renderPlaceholder(attachment: InboundAttachment): string {
   const parts: string[] = [`Slack attachment #${attachment.id}: ${attachment.kind}`]
   if (attachment.mimetype !== undefined) parts.push(attachment.mimetype)
   if (attachment.filename !== undefined) parts.push(`name=${attachment.filename}`)