typeclaw 0.19.0 → 0.20.0

package/src/channels/router.ts

@@ -54,6 +54,10 @@ import type {
   OutboundCallback,
   OutboundMessage,
   QuoteAnchorSource,
+  ReactionCallback,
+  ReactionRef,
+  ReactionRequest,
+  ReactionResult,
   ResolvedChannelNames,
   SendErrorCode,
   SendResult,
@@ -108,6 +112,7 @@ export const SESSION_GC_INTERVAL_MS = 60 * 1000
 // Enforced inside router.send for `source: 'tool'` callers; system
 // recovery paths (`source: 'system'`) bypass.
 export const MAX_CHANNEL_SENDS_PER_TURN = 10
+export const ENGAGE_REACTION_EMOJI = 'eyes'
 // Ceiling on tool-source channel sends that a same-turn router policy DENIED
 // without delivering — `skip-locked`, `turn-cap`, or `duplicate`. Such denials
 // return a soft error and do NOT increment `consecutiveSends`, so a model that
@@ -276,6 +281,7 @@ type QueuedInbound = {
   authorName: string
   authorIsBot: boolean
   externalMessageId: string
+  reactionRef?: ReactionRef
   isBotMention: boolean
   replyToBotMessageId: string | null
   isDm: boolean
@@ -324,6 +330,14 @@ type LiveSession = {
   originRef: { current: SessionOrigin | undefined }
   promptQueue: QueuedInbound[]
   contextBuffer: ObservedInbound[]
+  // Attachments of the messages composing the in-flight turn. drain()
+  // splices promptQueue/contextBuffer empty BEFORE calling prompt(), but
+  // the model only requests an attachment (look_at_channel_attachment /
+  // channel_fetch_attachment) DURING prompt() — by which point both queues
+  // are empty. This turn-scoped snapshot, populated right after the splice
+  // and cleared when the turn ends, is what the lookup reads so a freshly-
+  // arrived attachment stays resolvable for the whole turn it belongs to.
+  currentTurnAttachments: readonly InboundAttachment[]
   draining: boolean
   debounceTimer: ReturnType<typeof setTimeout> | null
   typingTimer: ReturnType<typeof setInterval> | null
@@ -334,6 +348,11 @@ type LiveSession = {
   firstUnprocessedAt: number
   currentTurnAuthorId: string | null
   currentTurnAuthorIds: Set<string>
+  // Reaction target of the inbound that triggered THIS turn (the last item in
+  // the drained batch, mirroring `currentTurnAuthorId`). Surfaced on the live
+  // origin so `channel_react` reacts to the triggering message, not whichever
+  // inbound happens to be latest in the queue. Null on reminder-only turns.
+  currentTurnReactionRef: ReactionRef | null
   lastTurnAuthorIds: Set<string>
   // Mirror of currentTurnAuthorId at end-of-turn (the LAST speaker of the
   // prior batch), preserved across the drain finally-block which resets
@@ -511,6 +530,14 @@ export type ChannelRouter = {
   }) => { count: number; windowMs: number }
   registerOutbound: (adapter: ChannelKey['adapter'], cb: OutboundCallback) => void
   unregisterOutbound: (adapter: ChannelKey['adapter'], cb: OutboundCallback) => void
+  // Reaction support is opt-in per adapter: an adapter that never calls
+  // registerReaction makes `react` resolve to `code: 'unsupported'`, and
+  // auto-react-on-engage becomes a silent no-op for it. Kept separate from
+  // the outbound path on purpose — reactions are best-effort side effects, not
+  // messages, so they must not flow through send()'s flood/cap/dup/sticky guards.
+  registerReaction: (adapter: ChannelKey['adapter'], cb: ReactionCallback) => void
+  unregisterReaction: (adapter: ChannelKey['adapter'], cb: ReactionCallback) => void
+  react: (req: ReactionRequest) => Promise<ReactionResult>
   registerTyping: (adapter: ChannelKey['adapter'], cb: TypingCallback) => void
   unregisterTyping: (adapter: ChannelKey['adapter'], cb: TypingCallback) => void
   registerChannelNameResolver: (adapter: ChannelKey['adapter'], resolver: ChannelNameResolver) => void
@@ -703,6 +730,7 @@ export type ClaimHandler = (input: ClaimHandlerInput) => Promise<ClaimHandlerOut
 const GRANT_ALL_PERMISSIONS: PermissionService = {
   has: () => true,
   resolveRole: () => 'owner',
+  compareRoleSeverity: () => 1,
   describe: () => ({ role: 'owner', permissions: [CORE_PERMISSIONS.channelRespond] }),
   replaceRoles: () => {},
 }
@@ -728,6 +756,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   // teardown was meant to clear.
   let liveGeneration = 0
   const outboundCallbacks = new Map<ChannelKey['adapter'], Set<OutboundCallback>>()
+  const reactionCallbacks = new Map<ChannelKey['adapter'], Set<ReactionCallback>>()
   const typingCallbacks = new Map<ChannelKey['adapter'], Set<TypingCallback>>()
   const channelNameResolvers = new Map<ChannelKey['adapter'], Set<ChannelNameResolver>>()
   const membershipResolvers = new Map<ChannelKey['adapter'], Set<MembershipResolver>>()
@@ -1081,6 +1110,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         promptQueue: [],
         pendingSystemReminders: [],
         contextBuffer: [],
+        currentTurnAttachments: [],
         draining: false,
         debounceTimer: null,
         typingTimer: null,
@@ -1091,6 +1121,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         firstUnprocessedAt: 0,
         currentTurnAuthorId: null,
         currentTurnAuthorIds: new Set(),
+        currentTurnReactionRef: null,
         // `lastTurnAuthorId` (string, used for `lastInboundAuthorId` in
         // origin) and `lastTurnAuthorIds` (Set, used by
         // `grantStickyForReplyTargets` as the fallback when
@@ -1451,6 +1482,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       ...(live.resolvedNames.chatName !== undefined ? { chatName: live.resolvedNames.chatName } : {}),
       thread: live.key.thread,
       ...(live.currentTurnAuthorId !== null ? { lastInboundAuthorId: live.currentTurnAuthorId } : {}),
+      ...(live.currentTurnReactionRef !== null ? { reactionRef: live.currentTurnReactionRef } : {}),
       participants: live.participants,
       ...(membership !== null ? { membership } : {}),
     }
@@ -1494,10 +1526,12 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         const batch = live.promptQueue.splice(0, live.promptQueue.length)
         const observed = live.contextBuffer.splice(0, live.contextBuffer.length)
         const reminders = live.pendingSystemReminders.splice(0, live.pendingSystemReminders.length)
+        live.currentTurnAttachments = collectTurnAttachments(observed, batch)
 
         if (batch.length > 0) {
           live.currentTurnAuthorId = batch[batch.length - 1]!.authorId
           live.currentTurnAuthorIds = new Set(batch.map((m) => m.authorId))
+          live.currentTurnReactionRef = batch[batch.length - 1]!.reactionRef ?? null
           live.consecutiveSends.clear()
           live.lastSentText.clear()
           live.pendingQuoteCandidate = captureQuoteCandidate(live.key.adapter, batch, observed)
@@ -1568,6 +1602,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       live.draining = false
       live.currentTurnAuthorId = null
       live.currentTurnAuthorIds = new Set()
+      live.currentTurnReactionRef = null
+      live.currentTurnAttachments = []
       await stopTypingHeartbeat(live)
     }
   }
@@ -1816,6 +1852,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 
     publishInbound(event, 'engage', live.sessionId)
 
+    autoReactOnEngage(event)
+
     updateLoopGuard(live, event)
 
     enqueue(live, event)
@@ -1908,6 +1946,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       authorName: event.authorName,
       authorIsBot: event.authorIsBot,
       externalMessageId: event.externalMessageId,
+      ...(event.reactionRef !== undefined ? { reactionRef: event.reactionRef } : {}),
       isBotMention: event.isBotMention,
       replyToBotMessageId: event.replyToBotMessageId,
       isDm: event.isDm,
@@ -1925,6 +1964,69 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     set.add(cb)
   }
 
+  const registerReaction = (adapter: ChannelKey['adapter'], cb: ReactionCallback): void => {
+    let set = reactionCallbacks.get(adapter)
+    if (!set) {
+      set = new Set()
+      reactionCallbacks.set(adapter, set)
+    }
+    set.add(cb)
+  }
+
+  const unregisterReaction = (adapter: ChannelKey['adapter'], cb: ReactionCallback): void => {
+    reactionCallbacks.get(adapter)?.delete(cb)
+  }
+
+  const react = async (req: ReactionRequest): Promise<ReactionResult> => {
+    if (req.reactionRef.adapter !== req.adapter) {
+      return { ok: false, error: 'reaction ref adapter mismatch', code: 'unsupported' }
+    }
+    const callbacks = reactionCallbacks.get(req.adapter)
+    if (!callbacks || callbacks.size === 0) {
+      return { ok: false, error: `adapter "${req.adapter}" does not support reactions`, code: 'unsupported' }
+    }
+    let lastError: ReactionResult | undefined
+    for (const cb of Array.from(callbacks)) {
+      // A ReactionCallback that throws must not reject this promise: react() is
+      // called both fire-and-forget (autoReactOnEngage) and awaited by the
+      // channel_react tool, and neither should have to wrap it in try/catch. A
+      // throw is converted to a transient failure result so every caller gets a
+      // uniform { ok: false } instead of an exception.
+      const result = await cb(req).catch(
+        (err): ReactionResult => ({ ok: false, error: describe(err), code: 'transient' }),
+      )
+      if (result.ok) return result
+      lastError = result
+    }
+    return lastError ?? { ok: false, error: 'no reaction callback handled request', code: 'unsupported' }
+  }
+
+  // Best-effort acknowledgment: drop an :eyes: on the triggering inbound the
+  // moment we decide to engage, replacing the old "On it" ack comment on
+  // GitHub. Fire-and-forget so a reaction failure (missing permission, the
+  // adapter not supporting reactions, a transient API error) can NEVER block
+  // engagement, enqueueing, or the agent's actual reply. No reactionRef =
+  // nothing reactable (synthetic inbounds, reaction-less adapters) = silent skip.
+  const autoReactOnEngage = (event: InboundMessage): void => {
+    if (event.reactionRef === undefined) return
+    void react({
+      adapter: event.adapter,
+      workspace: event.workspace,
+      chat: event.chat,
+      thread: event.thread,
+      reactionRef: event.reactionRef,
+      emoji: ENGAGE_REACTION_EMOJI,
+    })
+      .then((result) => {
+        if (!result.ok && result.code !== 'unsupported') {
+          logger.info(`[channels] engage-react failed adapter=${event.adapter} chat=${event.chat}: ${result.error}`)
+        }
+      })
+      .catch((err) => {
+        logger.info(`[channels] engage-react threw adapter=${event.adapter} chat=${event.chat}: ${describe(err)}`)
+      })
+  }
+
   const unregisterOutbound = (adapter: ChannelKey['adapter'], cb: OutboundCallback): void => {
     outboundCallbacks.get(adapter)?.delete(cb)
   }
@@ -2058,9 +2160,14 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     // Walk newest → oldest so that when an id collides across messages
     // (e.g. two photos in the same session each labelled `#1`) the agent's
     // `attachment_id: 1` always resolves to the CURRENT inbound's
-    // attachment. promptQueue holds the about-to-be-delivered turn and
-    // is therefore the freshest; within each list, append-order maps to
-    // wall-clock order, so iterating in reverse gives recency.
+    // attachment. currentTurnAttachments holds the in-flight turn — the
+    // only place the about-to-be-viewed attachment lives once drain() has
+    // spliced promptQueue empty — and is therefore the freshest; promptQueue
+    // then holds any inbound that arrived mid-turn. Within each list,
+    // append-order maps to wall-clock order, so iterating in reverse gives
+    // recency.
+    const found = findAttachmentById(live.currentTurnAttachments, args.id)
+    if (found !== null) return found
     const haystacks: ReadonlyArray<ReadonlyArray<{ attachments?: readonly InboundAttachment[] }>> = [
       live.promptQueue,
       live.contextBuffer,
@@ -2068,8 +2175,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     for (const haystack of haystacks) {
       for (let i = haystack.length - 1; i >= 0; i--) {
         const item = haystack[i]
-        const found = item?.attachments?.find((attachment) => attachment.id === args.id)
-        if (found !== undefined) return found
+        const hit = item?.attachments?.find((attachment) => attachment.id === args.id)
+        if (hit !== undefined) return hit
       }
     }
     return null
@@ -2079,6 +2186,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     const live = liveSessions.get(channelKeyId(args))
     if (live === undefined) return []
     const ids = new Set<number>()
+    for (const attachment of live.currentTurnAttachments) ids.add(attachment.id)
     for (const item of [...live.promptQueue, ...live.contextBuffer]) {
       for (const attachment of item.attachments ?? []) ids.add(attachment.id)
     }
@@ -2617,6 +2725,9 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     getSendRate,
     registerOutbound,
     unregisterOutbound,
+    registerReaction,
+    unregisterReaction,
+    react,
     registerTyping,
     unregisterTyping,
     registerChannelNameResolver,
@@ -2701,6 +2812,24 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   }
 }
 
+function collectTurnAttachments(
+  observed: readonly ObservedInbound[],
+  batch: readonly QueuedInbound[],
+): readonly InboundAttachment[] {
+  const out: InboundAttachment[] = []
+  for (const item of observed) out.push(...(item.attachments ?? []))
+  for (const item of batch) out.push(...(item.attachments ?? []))
+  return out
+}
+
+function findAttachmentById(attachments: readonly InboundAttachment[], id: number): InboundAttachment | null {
+  for (let i = attachments.length - 1; i >= 0; i--) {
+    const attachment = attachments[i]
+    if (attachment?.id === id) return attachment
+  }
+  return null
+}
+
 function composeTurnPrompt(
   observed: readonly ObservedInbound[],
   batch: readonly QueuedInbound[],
@@ -2782,13 +2911,14 @@ function composeTurnPrompt(
     )
   }
   // Group-chat nudge: same SYSTEM MESSAGE convention as the loop guard. We
-  // engaged this turn (explicit mention/reply/alias, or a fresh trigger),
-  // but the room has multiple humans, so the default "answer everything"
-  // posture is wrong. The engagement gate already stopped sticky credit
-  // from waking us on every follow-up; this tells the model to be
-  // selective on the turns it IS woken for. Cache-neutral (user-turn
-  // suffix), and skipped when the loop guard already fired to avoid
-  // stacking two silence notices in one turn.
+  // engaged this turn — possibly via sticky credit, which now wakes us on
+  // every follow-up in a group too (the engagement gate is content-blind by
+  // design). In a multi-human room the default "answer everything" posture is
+  // wrong, so this nudge is the ONLY thing that makes the bot selective: it
+  // tells the model to answer genuine follow-ups and stay silent on chatter.
+  // The gate gets us into the turn; the model decides whether to speak.
+  // Cache-neutral (user-turn suffix), and skipped when the loop guard already
+  // fired to avoid stacking two silence notices in one turn.
   if (state.groupChatNudge === true && !state.loopGuardActive) {
     parts.push(
       '---',
@@ -2798,10 +2928,15 @@ function composeTurnPrompt(
       'signal from the channel router, not a message from anyone in the chat.',
       '**Do not acknowledge or reply to this notice.**',
       '',
-      'Guidance:',
-      '- Reply only if the current message is addressed to you or clearly needs your input.',
-      '- For chatter between others, side-conversation, or messages that do not need you,',
-      '  reply with `NO_REPLY` (or call `skip_response`) to stay silent and just keep watching.',
+      'You are woken on every message from someone you recently talked with, so',
+      'most turns you should stay quiet. Reply ONLY when:',
+      '- the current message is addressed to you (by name, @-mention, or reply), or',
+      '- it directly continues your own last exchange and clearly wants an answer',
+      '  (e.g. a follow-up question about what you just said).',
+      '',
+      'Otherwise — chatter between others, side-conversation, banter, or anything',
+      'not actually waiting on you — reply with `NO_REPLY` (or call `skip_response`)',
+      'to stay silent and keep watching. When unsure, prefer silence.',
       '',
       '---',
       '',

package/src/channels/types.ts

@@ -94,8 +94,50 @@ export type InboundMessage = {
   // means "unknown" — the formatter renders such lines without a
   // timestamp prefix instead of stamping them with the wrong clock.
   ts: number
+  // Opaque, adapter-owned handle for the entity an emoji reaction would
+  // attach to. The classifier stamps it because only there is the platform-
+  // side target type still known (GitHub: issue body vs issue-comment vs
+  // pr-review-comment — all collapse to the same `chat`/`externalMessageId`
+  // pair downstream). Mirrors the `InboundAttachment.ref` opaque-handle
+  // pattern: ONLY the originating adapter's ReactionCallback knows how to
+  // parse `value`; the router and tools treat it as a pass-through token and
+  // never inspect it. Omitted when the inbound has no reactable target (e.g.
+  // synthetic review-request inbounds, or adapters without reaction support).
+  reactionRef?: ReactionRef
 }
 
+// Opaque reaction target handle. `adapter` lets the router refuse a ref to
+// the wrong adapter's callback; `value` is an adapter-private encoding (for
+// GitHub, a JSON blob distinguishing issue / issue-comment / pr-review-comment
+// / discussion plus the numeric id). Never rendered into prompt context.
+export type ReactionRef = {
+  adapter: AdapterId
+  value: string
+}
+
+// A request to add an emoji reaction to a previously-seen inbound. Distinct
+// from OutboundMessage on purpose: reactions are best-effort side effects, not
+// messages, so they bypass `send()`'s flood guard, per-turn send cap, exact-
+// duplicate guard, sticky-credit grants, and typing heartbeat — all of which
+// are message semantics that would misbehave on a reaction.
+export type ReactionRequest = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  thread?: string | null
+  reactionRef: ReactionRef
+  // Bare emoji name, no surrounding colons (e.g. 'eyes', '+1'). Each adapter
+  // maps this to its platform's reaction vocabulary and rejects unsupported
+  // names via `code: 'unsupported'`.
+  emoji: string
+}
+
+export type ReactionErrorCode = 'permission-denied' | 'not-found' | 'unsupported' | 'rate-limited' | 'transient'
+
+export type ReactionResult = { ok: true } | { ok: false; error: string; code?: ReactionErrorCode }
+
+export type ReactionCallback = (req: ReactionRequest) => Promise<ReactionResult>
+
 // File on disk that the agent wants to attach to an outbound message. The
 // agent runs inside a container with /agent bind-mounted from the host;
 // `path` should be an absolute path the container can `readFile`. The

package/src/cli/inspect.ts

@@ -75,6 +75,9 @@ export const inspectCommand = defineCommand({
           if (escListener === null) return new AbortController().signal
           return escListener.armForStream()
         },
+        afterEscStream: () => {
+          escListener?.pause()
+        },
         ...(liveHint !== undefined ? { liveHint } : {}),
         stdout: (line) => process.stdout.write(`${line}\n`),
         stderr: (line) => process.stderr.write(`${line}\n`),

package/src/inspect/loop.ts

@@ -2,6 +2,12 @@ import { runInspect, type RunInspectOptions, type RunInspectResult } from './ind
 
 export type RunInspectLoopOptions = Omit<RunInspectOptions, 'escSignal'> & {
   newEscSignal: () => AbortSignal
+  // Runs after every runInspect attempt settles. The caller disarms the raw-mode
+  // ESC listener here so the live tail releases stdin before clack re-opens the
+  // picker: an ESC-aborted tail leaves the listener armed (raw mode on, 'data'
+  // handler attached), and handing clack that flowing stream freezes the picker
+  // on SSH/Bun pseudo-TTYs.
+  afterEscStream?: () => void
 }
 
 export async function runInspectLoop(opts: RunInspectLoopOptions): Promise<RunInspectResult> {
@@ -23,7 +29,12 @@ export async function runInspectLoop(opts: RunInspectLoopOptions): Promise<RunIn
     if (sessionArg !== undefined) callOpts.sessionIdOrPrefix = sessionArg
     else delete (callOpts as { sessionIdOrPrefix?: string }).sessionIdOrPrefix
 
-    const result = await runInspect(callOpts)
+    let result: RunInspectResult
+    try {
+      result = await runInspect(callOpts)
+    } finally {
+      opts.afterEscStream?.()
+    }
     if (!result.ok) return result
     if (result.escToPicker !== true) return result
     sessionArg = undefined

package/src/permissions/permissions.ts

@@ -9,6 +9,12 @@ export type PermissionService = {
   has(origin: SessionOrigin | undefined, permission: string): boolean
   resolveRole(origin: SessionOrigin | undefined): string
   describe(origin: SessionOrigin | undefined): { role: string; permissions: readonly string[] }
+  // Orders two role names on the severity tower so callers can cap an
+  // action to the requester's role (a guest turn must not read the output
+  // of a member-spawned subagent). `undefined` means an unknown role on
+  // either side and MUST be treated as deny, never allow — mistreating it
+  // as allow reopens the privilege-escalation hole this gate closes.
+  compareRoleSeverity(a: string, b: string): -1 | 0 | 1 | undefined
   // Rebuilds the resolved role table from the given roles config, preserving
   // the same plugin-permission set captured at construction time. Used by
   // the config reloadable so role match-rule edits (typeclaw role claim,
@@ -25,6 +31,7 @@ export type UnknownPermissionWarning = {
 export const noopPermissionService: PermissionService = {
   has: () => false,
   resolveRole: () => 'guest',
+  compareRoleSeverity: () => undefined,
   describe: () => ({ role: 'guest', permissions: [] }),
   replaceRoles: () => {},
 }
@@ -139,6 +146,15 @@ export function createPermissionService(opts: CreatePermissionServiceOptions = {
     return 'guest'
   }
 
+  function roleSeverity(name: string): number | undefined {
+    if (name === 'owner') return 4
+    if (name === 'trusted') return 3
+    if (name === 'member') return 1
+    if (name === 'guest') return 0
+    if (byName.has(name)) return 2
+    return undefined
+  }
+
   return {
     has(origin, permission) {
       // Fail-safe floor: an undefined origin holds nothing, regardless of
@@ -156,6 +172,14 @@ export function createPermissionService(opts: CreatePermissionServiceOptions = {
       return role.permissions.includes(permission)
     },
     resolveRole,
+    compareRoleSeverity(a, b) {
+      const aRank = roleSeverity(a)
+      const bRank = roleSeverity(b)
+      if (aRank === undefined || bRank === undefined) return undefined
+      if (aRank < bRank) return -1
+      if (aRank > bRank) return 1
+      return 0
+    },
     describe(origin) {
       const name = resolveRole(origin)
       const role = byName.get(name)

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

@@ -50,7 +50,7 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
 
 2. **Spawn the `reviewer` subagent with the PR target.** Use `run_in_background: true` so you stay responsive while the deep model works. Pass the PR URL (or `owner/repo#N`) plus any context the requester gave you (focus areas, specific files, etc.). The reviewer fetches the diff itself (`gh pr diff`, `gh api /repos/.../pulls/<n>`), loads the `code-review` skill, and returns a `<review>` block whose code findings carry `location="path:line"`.
 
-   If you post an "on it" acknowledgement before spawning the reviewer, it **must** be `channel_reply({ text: "…", continue: true })` — a bare reply ends the turn and the review never starts (see "Mid-turn status replies need `continue: true`" above).
+   Do **not** post an "on it" acknowledgement comment before spawning the reviewer — the runtime already adds an :eyes: reaction to the PR the moment it engages, so a "looking into this" comment is redundant noise. Just spawn the reviewer with `run_in_background: true` and keep working; the formal review is your reply. If you want to acknowledge explicitly, use `channel_react({ emoji: "eyes" })`, which reacts without posting a comment.
 
 3. **Wait for the completion `<system-reminder>`,** then call `subagent_output({ task_id })` to read the reviewer's final assistant message. The structured payload looks like:
 
@@ -118,7 +118,15 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
 
    The returned `id`/`state` is your proof the formal review posted. If the call errored or the review is absent, do **not** fall back to a top-level `channel_reply` that _claims_ a review was posted — fix the payload (most often a `line` that isn't part of the diff; re-anchor it or move that finding to the top-level `body`) and resubmit. A trace reply that says "Posted review" when no review exists is worse than silence.
 
-6. **End the turn with `skip_response`, not a trace reply.** The formal review from step 4 already landed _in this PR_ — it carries the summary, the verdict, and the inline comments. A `channel_reply` here does **not** go to a separate operator channel; on GitHub it posts another public comment on the same PR. A one-line "Posted review on PR #N: …" narrated into the PR thread is meta-commentary addressed to a phantom operator, and it reads absurdly next to the review it claims to point at. So once step 5 confirms the review exists, call `skip_response({ reason: "review posted via gh api" })` to close the turn silently. Only fall back to `channel_reply` when there was **no** formal review to post — the zero-actionable-findings branch below uses `channel_reply`/issue comments _as_ the substantive reply.
+6. **Drop the decoy reviewer — App auth only, request-path only.** When this review was triggered by an explicit review-request inbound (path A) **and** you are running under **GitHub App** auth, remove the decoy reviewer from the PR's requested-reviewers list once the review has landed (after step 5 confirms it). Why: GitHub auto-adds **you** (the App account) to the PR's reviewers the moment your formal review posts, so the "reviewed" state is already recorded under the App identity — but the **decoy** account stays pinned in the requested-reviewers list as a perpetual "review requested", as if the review never happened. Removing it is the natural "I'm done, drop me" cleanup a human reviewer gets for free. The decoy login is the App slug — `selfLogin` with the trailing `[bot]` removed (`my-app[bot]` → `my-app`); see [GitHub decoy reviewer](/docs/internals/github-decoy-reviewer).
+
+   ```sh
+   gh api -X DELETE /repos/owner/repo/pulls/<N>/requested_reviewers -f 'reviewers[]=<decoy-login>'
+   ```
+
+   **Skip this entirely** when (a) you are under **PAT** auth — there is no decoy; the bot is a real user GitHub keeps listed as a reviewer, and removing yourself there is not wanted — or (b) the review came from a **plain-language** ask (path B) or a **team** request, where no decoy user was ever placed on the requested-reviewers list and the DELETE would be a no-op/404. The removal is safe under the adapter's self-loop guard: you make the `DELETE` authenticated as the App, so the `review_request_removed` webhook GitHub emits has your bot actor (`slug[bot]`) as `sender`, which the classifier drops, so it never wakes a fresh session (see "Self-loop safety" below). Treat a failure here as non-fatal — the review already landed; do not retry in a loop or surface it to the PR thread.
+
+7. **End the turn with `skip_response`, not a trace reply.** The formal review from step 4 already landed _in this PR_ — it carries the summary, the verdict, and the inline comments. A `channel_reply` here does **not** go to a separate operator channel; on GitHub it posts another public comment on the same PR. A one-line "Posted review on PR #N: …" narrated into the PR thread is meta-commentary addressed to a phantom operator, and it reads absurdly next to the review it claims to point at. So once step 5 confirms the review exists (and step 6 has dropped the decoy, if applicable), call `skip_response({ reason: "review posted via gh api" })` to close the turn silently. Only fall back to `channel_reply` when there was **no** formal review to post — the zero-actionable-findings branch below uses `channel_reply`/issue comments _as_ the substantive reply.
 
 ### Zero actionable findings
 
@@ -147,3 +155,5 @@ For App auth, `GH_TOKEN` is an installation access token that refreshes automati
 ## Self-loop safety
 
 The adapter will **not** wake you when you assign yourself as a reviewer (e.g., via `gh pr edit --add-reviewer`). It will only wake you when someone else requests your review.
+
+The same guard covers **removing** a reviewer: when you drop the decoy after a review (step 6 of the PR review flow), you act as the App, so the `review_request_removed` webhook GitHub emits carries your bot actor (`slug[bot]`) as its `sender`, which the classifier drops. So the cleanup never echoes back as a fresh wake. Both directions — add and remove — are matched on `sender.login` (against either the bot actor or its decoy), so any reviewer-list mutation you make yourself stays silent.