typeclaw 0.27.0 → 0.28.1

package/package.json

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

package/scripts/generate-schema.ts

@@ -14,12 +14,10 @@ import { secretsFileSchema } from '../src/secrets/schema'
 const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
 
 // auth.schema.json is the permanent compatibility alias for secrets.schema.json.
-// Pre-rename `auth.json` files (or migrated `secrets.json` files that still
-// carry the legacy `$schema` URL — `mergeLlmIntoEnvelope` preserves an
-// existing `$schema`, so the legacy pointer survives the file rename) need
-// it to resolve in editors. The alias is tiny and re-emitting it has no
-// maintenance cost, so we keep it indefinitely rather than coordinating a
-// content-rewrite migration for every old agent folder.
+// Old agent folders may still carry an `auth.json`, or a `secrets.json` whose
+// `$schema` still points at the pre-rename URL; the alias lets those resolve in
+// editors. It is tiny and re-emitting it has no maintenance cost, so we keep it
+// indefinitely rather than rewriting `$schema` in every old agent folder.
 const targets: Array<{ path: string; schema: z.ZodType }> = [
   { path: join(repoRoot, 'typeclaw.schema.json'), schema: buildConfigSchemaWithBundledPlugins(coreConfigSchema) },
   { path: join(repoRoot, 'cron.schema.json'), schema: cronFileSchema },

package/src/agent/index.ts

@@ -13,6 +13,7 @@ import type { AgentSession, ToolDefinition } from '@mariozechner/pi-coding-agent
 
 import { loadMemory } from '@/bundled-plugins/memory/load-memory'
 import type { ChannelRouter } from '@/channels/router'
+import type { ReactionRef } from '@/channels/types'
 import { getConfig, resolveModel, resolveProfile } from '@/config'
 import { defaultThinkingLevelForRef, providerForModelRef, type KnownModelRef } from '@/config/providers'
 import { renderMcpCatalog } from '@/mcp/catalog'
@@ -359,7 +360,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
             ...(options.mcpManager ? buildMcpDispatcherToolDefinitions(options.mcpManager) : []),
             ...(options.reloadRegistry ? [createReloadTool({ registry: options.reloadRegistry })] : []),
             ...(options.stream ? [createStreamSnapshotTool({ stream: options.stream })] : []),
-            ...buildChannelTools(options.channelRouter, options.origin, sessionManager.getSessionId()),
+            ...buildChannelTools(options.channelRouter, options.origin, sessionManager.getSessionId(), getOrigin),
             ...(options.containerName
               ? [
                   createRestartTool({
@@ -620,6 +621,7 @@ export function buildChannelTools(
   channelRouter: ChannelRouter | undefined,
   origin: SessionOrigin | undefined,
   sessionId?: string,
+  getOrigin?: () => SessionOrigin | undefined,
 ): ToolDefinition[] {
   if (!channelRouter) return []
   const tools: ToolDefinition[] = []
@@ -630,13 +632,33 @@ export function buildChannelTools(
       chat: origin.chat,
       thread: origin.thread,
     }
-    tools.push(createChannelReplyTool({ router: channelRouter, origin: channelOrigin }))
+    tools.push(
+      createChannelReplyTool({
+        router: channelRouter,
+        origin: channelOrigin,
+        ...(sessionId !== undefined ? { sessionId } : {}),
+      }),
+    )
     tools.push(createChannelHistoryTool({ router: channelRouter, origin: channelOrigin }))
-    tools.push(createChannelSendTool({ router: channelRouter, origin: channelOrigin }))
+    tools.push(
+      createChannelSendTool({
+        router: channelRouter,
+        origin: channelOrigin,
+        ...(sessionId !== undefined ? { sessionId } : {}),
+      }),
+    )
+    // Read the live turn origin, falling back to the static snapshot when no
+    // getter is wired (composition tests). `reactionRef` is per-turn, so the
+    // getter is what makes reactions work outside tests.
+    const resolveReactionRef = (): ReactionRef | undefined => {
+      const live = getOrigin?.() ?? origin
+      return live.kind === 'channel' ? live.reactionRef : undefined
+    }
     tools.push(
       createChannelReactTool({
         router: channelRouter,
-        origin: { ...channelOrigin, ...(origin.reactionRef !== undefined ? { reactionRef: origin.reactionRef } : {}) },
+        origin: channelOrigin,
+        getReactionRef: resolveReactionRef,
       }),
     )
     tools.push(

package/src/agent/multimodal/look-at.ts

@@ -3,7 +3,6 @@ import type { ImageContent } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
 import { createSessionWithDispose, type SessionOrigin } from '@/agent'
-import { normalizeRef } from '@/agent/tools/normalize-ref'
 import type { ChannelRouter } from '@/channels/router'
 import type { AdapterId } from '@/channels/schema'
 
@@ -121,7 +120,7 @@ export function createChannelLookAtTool(router: ChannelRouter, origin: ChannelLo
         )
       }
       const result = await router.fetchAttachment(origin.adapter, {
-        ref: normalizeRef(found.ref),
+        ref: found.ref,
         ...(found.filename !== undefined ? { filename: found.filename } : {}),
       })
       if (!result.ok) return errorResult(result.error, { count: 0, prompt: params.prompt })

package/src/agent/provider-error.ts

@@ -13,7 +13,39 @@ import type { AgentSession } from './index'
 // not by this helper.
 
 export type DetectedProviderError = {
+  // Raw provider text. Safe for logs and operator-only surfaces (TUI,
+  // `typeclaw logs`), but NOT for channels — see `safeMessage`.
   message: string
+  // Redacted, user-facing variant for public/multi-user channels. Known-safe
+  // operational classes (rate/usage limit, billing/quota) map to a canonical
+  // sentence; everything else (malformed-response SDK dumps, unknown failures)
+  // collapses to a generic notice so provider response bodies, URLs, or tokens
+  // can never leak to a channel.
+  safeMessage: string
+}
+
+const GENERIC_SAFE_NOTICE = 'The upstream LLM provider failed. Operators can check `typeclaw logs` for details.'
+
+// Each entry pairs a narrow matcher against the raw provider text with the
+// canonical, leak-free sentence shown in channels. Matchers are intentionally
+// specific: a miss falls through to GENERIC_SAFE_NOTICE rather than echoing raw
+// text, so adding a new class is opt-in and never widens what we expose.
+const SAFE_CLASSES: ReadonlyArray<{ match: RegExp; safe: string }> = [
+  {
+    match: /\b(usage limit|rate limit|rate.?limited|too many requests|429)\b/i,
+    safe: 'The upstream LLM provider is rate-limited (usage limit reached). Try again shortly.',
+  },
+  {
+    match: /\b(billing|quota|insufficient.*(credit|fund|balance)|payment|account is not active)\b/i,
+    safe: 'The upstream LLM provider rejected the request for a billing/quota reason. Operators can check `typeclaw logs` for details.',
+  },
+]
+
+function toSafeMessage(raw: string): string {
+  for (const { match, safe } of SAFE_CLASSES) {
+    if (match.test(raw)) return safe
+  }
+  return GENERIC_SAFE_NOTICE
 }
 
 export function detectProviderError(message: unknown): DetectedProviderError | null {
@@ -25,7 +57,7 @@ export function detectProviderError(message: unknown): DetectedProviderError | n
   // ignore aborts (no surface to render them on).
   if (m.stopReason !== 'error') return null
   const text = typeof m.errorMessage === 'string' && m.errorMessage.length > 0 ? m.errorMessage : 'LLM call failed'
-  return { message: text }
+  return { message: text, safeMessage: toSafeMessage(text) }
 }
 
 export type ProviderErrorListener = (error: DetectedProviderError) => void

package/src/agent/tools/channel-fetch-attachment.ts

@@ -8,7 +8,6 @@ import type { ChannelRouter } from '@/channels/router'
 import type { AdapterId } from '@/channels/schema'
 
 import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
-import { normalizeRef } from './normalize-ref'
 
 export type ChannelFetchAttachmentOrigin = {
   adapter: AdapterId
@@ -87,7 +86,7 @@ export function createChannelFetchAttachmentTool({
           `attachment #${params.attachment_id} (${found.kind}) has no fetchable ref — likely a sticker or an upstream payload without a public URL. Acknowledge the user but do not promise to view it.`,
         )
       }
-      const ref = normalizeRef(found.ref)
+      const ref = found.ref
       const filename = params.filename ?? found.filename
       const result = await router.fetchAttachment(adapter, {
         ref,

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

@@ -13,18 +13,23 @@ export type ChannelReactOrigin = {
   workspace: string
   chat: string
   thread: string | null
-  reactionRef?: ReactionRef
 }
 
 export type CreateChannelReactToolOptions = {
   router: ChannelRouter
   origin: ChannelReactOrigin
+  // Resolved at execute time, not captured: the target is the message that
+  // triggered THIS turn. The tool is built once at session creation, whose
+  // origin snapshot carries no reactionRef, so a static capture would deny
+  // every call.
+  getReactionRef: () => ReactionRef | undefined
   logger?: ChannelToolLogger
 }
 
 export function createChannelReactTool({
   router,
   origin,
+  getReactionRef,
   logger = consoleChannelLogger,
 }: CreateChannelReactToolOptions) {
   return defineTool({
@@ -58,14 +63,15 @@ export function createChannelReactTool({
         }
       }
 
-      if (origin.reactionRef === undefined) return deny('this conversation has no message to react to')
+      const reactionRef = getReactionRef()
+      if (reactionRef === undefined) return deny('this conversation has no message to react to')
 
       const result = await router.react({
         adapter: origin.adapter,
         workspace: origin.workspace,
         chat: origin.chat,
         thread: origin.thread,
-        reactionRef: origin.reactionRef,
+        reactionRef,
         emoji: params.emoji,
       })
 

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

@@ -1,6 +1,8 @@
 import { Type } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
+import { checkFalseReceipt } from '@/channels/github-false-receipt'
+import { evaluateRereviewGuard } from '@/channels/github-rereview-guard'
 import {
   containsKimiToolDelimiter,
   isNoReplySignal,
@@ -22,6 +24,10 @@ export type ChannelReplyOrigin = {
 export type CreateChannelReplyToolOptions = {
   router: ChannelRouter
   origin: ChannelReplyOrigin
+  // Scopes the per-turn false-receipt ledger. Defaults to '' when a caller (e.g.
+  // a focused test) has no session; the guard then simply finds no recorded
+  // action and falls back to its safe default.
+  sessionId?: string
   logger?: ChannelToolLogger
 }
 
@@ -37,6 +43,7 @@ export type CreateChannelReplyToolOptions = {
 export function createChannelReplyTool({
   router,
   origin,
+  sessionId = '',
   logger = consoleChannelLogger,
 }: CreateChannelReplyToolOptions) {
   return defineTool({
@@ -131,6 +138,49 @@ export function createChannelReplyTool({
         }
       }
 
+      // False-receipt guard: deny a terminal reply that CLAIMS a PR verdict /
+      // thread close-out the agent never actually performed this turn. Warn-tier
+      // claims fall through and have their notice appended on success below.
+      const falseReceipt = checkFalseReceipt({
+        sessionId,
+        adapter: origin.adapter,
+        workspace: origin.workspace,
+        chat: origin.chat,
+        thread: origin.thread,
+        text,
+        isContinue: keepTurnAlive,
+        resolveReviewThread: params.resolve_review_thread === true,
+      })
+      if (falseReceipt.kind === 'block') {
+        logger.warn(formatChannelToolFailure('channel_reply', falseReceipt.reason))
+        return {
+          content: [{ type: 'text' as const, text: `channel_reply denied: ${falseReceipt.reason}` }],
+          details: { ok: false, error: falseReceipt.reason },
+        }
+      }
+      const falseReceiptNotice = falseReceipt.kind === 'warn' ? falseReceipt.notice : null
+
+      // Re-review stranding guard: block a thread close-out / verdict ack while
+      // the bot still holds its own CHANGES_REQUESTED on this PR, so it can't
+      // silently leave the PR blocked (PR #644). Runs before the resolve so a
+      // blocked close-out never mutates the thread.
+      const rereview = await evaluateRereviewGuard({
+        adapter: origin.adapter,
+        workspace: origin.workspace,
+        chat: origin.chat,
+        thread: origin.thread,
+        text,
+        wantsResolve: params.resolve_review_thread === true,
+        getReviewState: (req) => router.getReviewState(req),
+      })
+      if (rereview.block) {
+        logger.warn(formatChannelToolFailure('channel_reply', rereview.reason))
+        return {
+          content: [{ type: 'text' as const, text: `channel_reply denied: ${rereview.reason}` }],
+          details: { ok: false, error: rereview.reason },
+        }
+      }
+
       // Resolve BEFORE posting: a successful channel_reply ends the turn, so a
       // resolve attempted "after" the ack would never run (the exact bug this
       // flag fixes). Resolve-failure blocks the reply so the agent never posts
@@ -203,8 +253,9 @@ export function createChannelReplyTool({
         // TOOL_RESULT_PREFIX to match the denial branch below. The prefix is
         // intentionally weaker and is safe ONLY because denials carry no echoed
         // prose; the success result does, and the weak prefix let Kimi loop.
+        const warnNote = falseReceiptNotice !== null ? fenceRuntimeNotice(falseReceiptNotice) : ''
         return {
-          content: [{ type: 'text' as const, text: `${fenceToolResult(receipt)}${hint}` }],
+          content: [{ type: 'text' as const, text: `${fenceToolResult(receipt)}${hint}${warnNote}` }],
           details,
         }
       }

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

@@ -1,6 +1,9 @@
 import { Type } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
+import { checkFalseReceipt } from '@/channels/github-false-receipt'
+import { evaluateRereviewGuard } from '@/channels/github-rereview-guard'
+import { recordResolvedThread } from '@/channels/github-review-turn-ledger'
 import {
   containsKimiToolDelimiter,
   isNoReplySignal,
@@ -28,10 +31,19 @@ export type CreateChannelSendToolOptions = {
   // the model can self-correct on its next turn. Absent for sessions whose
   // origin isn't a channel (e.g. cron prompts that send to channels).
   origin?: ChannelSendOrigin
+  // Scopes the per-turn false-receipt ledger for github resolve close-outs.
+  // Defaults to '' when absent (cron / non-channel sessions); the guard then
+  // finds no recorded action and falls back to its safe default.
+  sessionId?: string
   logger?: ChannelToolLogger
 }
 
-export function createChannelSendTool({ router, origin, logger = consoleChannelLogger }: CreateChannelSendToolOptions) {
+export function createChannelSendTool({
+  router,
+  origin,
+  sessionId = '',
+  logger = consoleChannelLogger,
+}: CreateChannelSendToolOptions) {
   return defineTool({
     name: 'channel_send',
     label: 'Channel Send',
@@ -93,6 +105,15 @@ export function createChannelSendTool({ router, origin, logger = consoleChannelL
           },
         ),
       ),
+      resolve_review_thread: Type.Optional(
+        Type.Boolean({
+          description:
+            'GitHub review threads ONLY — ignored on every other adapter and on a github send that has no `thread`. ' +
+            'Set `true` to close out a review thread you authored once you have confirmed the new commits address your concern: pass the thread\'s root comment id as `thread`, an acknowledgement (e.g. "addressed in <sha> — resolving") as `text`, and this flag. ' +
+            'This is the post-push close-out path: a `pull_request.synchronize` recheck lists your unresolved threads, and you call this once per addressed thread. ' +
+            "Safe by default — the runtime resolves BEFORE posting and ONLY if the thread's root comment is yours, refusing (and blocking the send) on a human reviewer's thread. Leave it unset to keep the thread open (not addressed, partial fix, disagreement).",
+        }),
+      ),
     }),
 
     async execute(_toolCallId, params) {
@@ -136,6 +157,67 @@ export function createChannelSendTool({ router, origin, logger = consoleChannelL
         }
       }
 
+      const wantsResolve = params.resolve_review_thread === true
+      const falseReceipt = checkFalseReceipt({
+        sessionId,
+        adapter,
+        workspace: params.workspace,
+        chat: params.chat,
+        thread: params.thread ?? null,
+        text: bodyText,
+        isContinue: false,
+        resolveReviewThread: wantsResolve,
+      })
+      if (falseReceipt.kind === 'block') {
+        logger.warn(formatChannelToolFailure('channel_send', falseReceipt.reason))
+        return {
+          content: [{ type: 'text' as const, text: `channel_send denied: ${falseReceipt.reason}` }],
+          details: { ok: false, error: falseReceipt.reason },
+        }
+      }
+      const falseReceiptNotice = falseReceipt.kind === 'warn' ? falseReceipt.notice : null
+
+      // Re-review stranding guard (mirrors channel_reply): block a thread
+      // close-out / verdict ack while the bot still holds its own
+      // CHANGES_REQUESTED on this PR, before the resolve mutates the thread.
+      const rereview = await evaluateRereviewGuard({
+        adapter,
+        workspace: params.workspace,
+        chat: params.chat,
+        thread: params.thread ?? null,
+        text: bodyText,
+        wantsResolve,
+        getReviewState: (req) => router.getReviewState(req),
+      })
+      if (rereview.block) {
+        logger.warn(formatChannelToolFailure('channel_send', rereview.reason))
+        return {
+          content: [{ type: 'text' as const, text: `channel_send denied: ${rereview.reason}` }],
+          details: { ok: false, error: rereview.reason },
+        }
+      }
+
+      // Resolve BEFORE posting (mirrors channel_reply): a failed resolve must
+      // block the acknowledgement so the bot never posts "addressed — resolving"
+      // next to a still-open thread. The router enforces that only the bot's own
+      // threads can be resolved.
+      if (wantsResolve) {
+        const resolveError = await resolveReviewThreadBeforeSend(router, {
+          adapter,
+          workspace: params.workspace,
+          chat: params.chat,
+          thread: params.thread ?? null,
+        })
+        if (resolveError !== null) {
+          logger.warn(formatChannelToolFailure('channel_send', resolveError))
+          return {
+            content: [{ type: 'text' as const, text: `channel_send denied: ${resolveError}` }],
+            details: { ok: false, error: resolveError },
+          }
+        }
+        recordResolvedThreadFromSend(sessionId, params.workspace, params.chat, params.thread ?? null)
+      }
+
       const result = await router.send({
         adapter,
         workspace: params.workspace,
@@ -179,6 +261,8 @@ export function createChannelSendTool({ router, origin, logger = consoleChannelL
         })
         if (threadMismatch) hints.push(threadMismatch)
 
+        if (falseReceiptNotice !== null) hints.push(fenceRuntimeNotice(falseReceiptNotice))
+
         return {
           content: [{ type: 'text' as const, text: `${fenceToolResult(receipt)}${hints.join('')}` }],
           details,
@@ -192,6 +276,36 @@ export function createChannelSendTool({ router, origin, logger = consoleChannelL
   })
 }
 
+async function resolveReviewThreadBeforeSend(
+  router: ChannelRouter,
+  target: { adapter: AdapterId; workspace: string; chat: string; thread: string | null },
+): Promise<string | null> {
+  if (target.adapter !== 'github') {
+    return 'resolve_review_thread is only supported on github sends.'
+  }
+  if (target.thread === null) {
+    return 'resolve_review_thread requires a `thread` (the review thread root comment id).'
+  }
+  const result = await router.resolveReviewThread({
+    adapter: target.adapter,
+    workspace: target.workspace,
+    chat: target.chat,
+    rootCommentId: target.thread,
+  })
+  if (result.ok) return null
+  if (result.code === 'no-match') return null
+  return `could not resolve review thread: ${result.error}`
+}
+
+function recordResolvedThreadFromSend(sessionId: string, workspace: string, chat: string, thread: string | null): void {
+  if (thread === null) return
+  const m = /^pr:(\d+)$/.exec(chat)
+  if (m === null) return
+  const prNumber = Number(m[1])
+  if (!Number.isSafeInteger(prNumber) || prNumber <= 0) return
+  recordResolvedThread({ sessionId, workspace, prNumber, rootCommentId: thread })
+}
+
 // Returns a behavioral hint when the model posted to the SAME conversation
 // as the session's origin (same adapter+workspace+chat) but DROPPED the
 // thread. This catches the "model forgot to copy thread verbatim" failure

package/src/bundled-plugins/github-cli-auth/gh-review-detect.ts

@@ -0,0 +1,175 @@
+import type { ReviewVerdict } from '@/channels/github-review-turn-ledger'
+
+// Extracts the formal-review verdict a successful `gh` command landed, so the
+// false-receipt ledger can credit it. Covers the three vectors the agent uses to
+// post a review: REST create-review via `--input <file>`, REST create-review via
+// inline `-f/-F event=...`, and the `gh pr review` porcelain. Returns null when
+// the command is not a verdict-bearing review submission (incl. COMMENT reviews,
+// which carry no false-receipt risk and are not tracked).
+
+// `source` drives success detection downstream: the REST endpoints echo the
+// created review JSON, while the `gh pr review` porcelain prints a plain
+// confirmation line — so each needs its own success markers (see review-recorder).
+export type DetectedReview = {
+  workspace: string
+  prNumber: number
+  verdict: ReviewVerdict
+  source: 'api' | 'pr-review'
+}
+
+export type GhReviewDetectInput = {
+  command: string
+  // Contents of the file named by `--input <file>`, when the caller resolved it.
+  // Kept as an injected value so this module does no I/O and stays sync+pure.
+  inputFileContents?: string | null
+}
+
+const REVIEWS_ENDPOINT = /\/repos\/([^/\s]+)\/([^/\s]+)\/pulls\/(\d+)\/reviews\b/
+
+export function detectReviewSubmission(input: GhReviewDetectInput): DetectedReview | null {
+  const args = splitArgs(input.command)
+  if (args[0] !== 'gh') return null
+  const sub = args[1]
+  if (sub === 'api') return detectApiReview(args, input.inputFileContents ?? null)
+  if (sub === 'pr' && args[2] === 'review') return detectPrReview(args)
+  return null
+}
+
+function detectApiReview(args: readonly string[], fileContents: string | null): DetectedReview | null {
+  const endpoint = args.find((a) => REVIEWS_ENDPOINT.test(a))
+  if (endpoint === undefined) return null
+  const m = REVIEWS_ENDPOINT.exec(endpoint)
+  if (m === null) return null
+  const workspace = `${m[1]}/${m[2]}`
+  const prNumber = Number(m[3])
+  if (!Number.isSafeInteger(prNumber)) return null
+
+  const verdict = verdictFromInlineFields(args) ?? verdictFromFile(fileContents)
+  if (verdict === null) return null
+  return { workspace, prNumber, verdict, source: 'api' }
+}
+
+// Inline `-f event=APPROVE` / `--field event=REQUEST_CHANGES` (and `-F` raw).
+// gh accepts both `flag value` and `flag=value` shapes; cover both.
+function verdictFromInlineFields(args: readonly string[]): ReviewVerdict | null {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === undefined) continue
+    if (a === '-f' || a === '-F' || a === '--field' || a === '--raw-field') {
+      const v = parseEventAssignment(args[i + 1])
+      if (v !== null) return v
+    }
+    if (a.startsWith('-f=') || a.startsWith('-F=') || a.startsWith('--field=') || a.startsWith('--raw-field=')) {
+      const v = parseEventAssignment(a.slice(a.indexOf('=') + 1))
+      if (v !== null) return v
+    }
+  }
+  return null
+}
+
+function parseEventAssignment(token: string | undefined): ReviewVerdict | null {
+  if (token === undefined) return null
+  const eq = token.indexOf('=')
+  if (eq === -1) return null
+  if (token.slice(0, eq).trim().toLowerCase() !== 'event') return null
+  return normalizeVerdict(token.slice(eq + 1))
+}
+
+function verdictFromFile(contents: string | null): ReviewVerdict | null {
+  if (contents === null || contents === '') return null
+  try {
+    const parsed = JSON.parse(contents) as unknown
+    if (typeof parsed !== 'object' || parsed === null) return null
+    const event = (parsed as Record<string, unknown>).event
+    return typeof event === 'string' ? normalizeVerdict(event) : null
+  } catch {
+    return null
+  }
+}
+
+function detectPrReview(args: readonly string[]): DetectedReview | null {
+  const verdict =
+    args.includes('--approve') || args.includes('-a')
+      ? 'APPROVE'
+      : args.includes('--request-changes') || args.includes('-r')
+        ? 'REQUEST_CHANGES'
+        : null
+  if (verdict === null) return null
+  const workspace = repoFromFlag(args)
+  const prNumber = prNumberArg(args)
+  if (workspace === null || prNumber === null) return null
+  return { workspace, prNumber, verdict, source: 'pr-review' }
+}
+
+function repoFromFlag(args: readonly string[]): string | null {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === undefined) continue
+    if ((a === '-R' || a === '--repo') && isRepoSlug(args[i + 1])) return args[i + 1] as string
+    if (a.startsWith('--repo=') && isRepoSlug(a.slice('--repo='.length))) return a.slice('--repo='.length)
+    if (a.startsWith('-R=') && isRepoSlug(a.slice('-R='.length))) return a.slice('-R='.length)
+  }
+  return null
+}
+
+function prNumberArg(args: readonly string[]): number | null {
+  const start = args.indexOf('review') + 1
+  for (let i = start; i < args.length; i++) {
+    const a = args[i]
+    if (a === undefined) continue
+    if (a.startsWith('-')) continue
+    if (/^\d+$/.test(a)) {
+      const n = Number(a)
+      return Number.isSafeInteger(n) ? n : null
+    }
+  }
+  return null
+}
+
+function normalizeVerdict(value: string): ReviewVerdict | null {
+  const v = value.trim().toUpperCase()
+  if (v === 'APPROVE') return 'APPROVE'
+  if (v === 'REQUEST_CHANGES') return 'REQUEST_CHANGES'
+  return null
+}
+
+function isRepoSlug(value: string | undefined): boolean {
+  if (value === undefined) return false
+  const [owner, name, ...rest] = value.split('/')
+  return owner !== undefined && owner !== '' && name !== undefined && name !== '' && rest.length === 0
+}
+
+// Quote-aware whitespace split. The interceptor guarantees a single bare `gh`
+// command before we record (no pipes/substitution), so this only needs to honor
+// quotes, not full shell grammar.
+function splitArgs(command: string): string[] {
+  const out: string[] = []
+  let cur = ''
+  let quote: '"' | "'" | null = null
+  let has = false
+  for (const ch of command) {
+    if (quote !== null) {
+      if (ch === quote) quote = null
+      else cur += ch
+      has = true
+      continue
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch
+      has = true
+      continue
+    }
+    if (ch === ' ' || ch === '\t' || ch === '\n') {
+      if (has) {
+        out.push(cur)
+        cur = ''
+        has = false
+      }
+      continue
+    }
+    cur += ch
+    has = true
+  }
+  if (has) out.push(cur)
+  return out
+}

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

@@ -3,6 +3,7 @@ import { definePlugin } from '@/plugin'
 
 import { analyzeGhCommand } from './gh-command'
 import { checkGraphqlAuthNudge } from './graphql-auth-nudge'
+import { commitReviewIfSucceeded, noteReviewCommand } from './review-recorder'
 import { classifyGhToken } from './token-class'
 
 export default definePlugin({
@@ -15,6 +16,8 @@ export default definePlugin({
           const command = event.args.command
           if (typeof command !== 'string' || !command.includes('gh')) return
 
+          await noteReviewCommand({ callId: event.callId, command })
+
           const decision = analyzeGhCommand(command)
           if (decision.kind === 'pass-through') return
 
@@ -42,6 +45,7 @@ export default definePlugin({
         },
         'tool.after': async (event) => {
           checkGraphqlAuthNudge({ tool: event.tool, result: event.result })
+          commitReviewIfSucceeded({ sessionId: event.sessionId, callId: event.callId, result: event.result })
         },
       },
     }