typeclaw 0.15.2 → 0.17.0

package/src/agent/tools/grant-role.ts

@@ -0,0 +1,214 @@
+import { Type } from '@mariozechner/pi-ai'
+import { defineTool } from '@mariozechner/pi-coding-agent'
+
+import {
+  grantRole,
+  grantRolePermission,
+  isDmChannelOrigin,
+  parseMatchRule,
+  type PermissionService,
+  type RolesConfig,
+} from '@/permissions'
+
+import type { SessionOrigin } from '../session-origin'
+
+export type GrantRoleToolDetails =
+  | { ok: true; mode: 'match' | 'permission'; role: string; value: string; added: boolean; restartRequired: boolean }
+  | { ok: false; error: string }
+
+export type CreateGrantRoleToolOptions = {
+  agentDir: string
+  getOrigin: () => SessionOrigin | undefined
+  permissions: PermissionService
+  // Re-reads roles FROM DISK and returns the fresh set, for hot-reloading a
+  // match-grant after grantRole writes typeclaw.json. Must NOT read an
+  // in-memory config snapshot: grantRole writes the file directly, so a
+  // snapshot taken before the live config pointer is reloaded would be stale
+  // and replaceRoles would reapply the pre-grant table. Production wires this
+  // to reloadConfig(agentDir) + getConfig().roles, matching the config
+  // reloadable. A permission-grant is restart-required, so the reload has no
+  // runtime effect for it, but we reload anyway to keep a same-session
+  // subsequent match-grant reading a consistent table.
+  reloadRoles: () => RolesConfig | undefined
+}
+
+// Roles this tool may target, lowest to highest. `guest` is a valid target
+// (an operator opening guest channel.respond) but never a granter — the gate
+// below requires the caller to resolve to owner/trusted.
+const TIER_ORDER = ['guest', 'member', 'trusted', 'owner'] as const
+type TierRole = (typeof TIER_ORDER)[number]
+
+function tierOf(role: string): number {
+  return TIER_ORDER.indexOf(role as TierRole)
+}
+
+function isTierRole(role: string): role is TierRole {
+  return (TIER_ORDER as readonly string[]).includes(role)
+}
+
+// A single-principal turn carries only the principal's own first-party words:
+// the TUI (a human typing directly) or a 1:1 DM (principal + bot, no
+// third-party messages buffered in). A group/open channel turn always mixes in
+// other authors' messages, which is the confused-deputy surface that lets a
+// guest prompt-inject a trusted turn into rewriting the access-control table.
+// Role grants are confined to single-principal turns so that surface does not
+// exist.
+function isSinglePrincipalOrigin(origin: SessionOrigin | undefined): boolean {
+  if (origin === undefined) return false
+  if (origin.kind === 'tui') return true
+  if (origin.kind === 'channel') return isDmChannelOrigin(origin)
+  return false
+}
+
+export function createGrantRoleTool(options: CreateGrantRoleToolOptions) {
+  const { agentDir, getOrigin, permissions, reloadRoles } = options
+
+  return defineTool({
+    name: 'grant_role',
+    label: 'Grant Role',
+    description:
+      'Assign an author to a role (match grant) or give a role a capability (permission grant), by editing typeclaw.json#roles. ' +
+      'Use this to onboard a teammate ("respond to author U_X" → grant them member) or to open the agent to a wider audience ' +
+      '("let anyone in this channel message you" → grant guest channel.respond). ' +
+      'Only callable from the TUI or a 1:1 DM by an owner or trusted user — group-channel turns cannot use it. ' +
+      'Permission grants are restart-required: they land in typeclaw.json but take effect on the next `typeclaw restart`.',
+    parameters: Type.Object({
+      role: Type.Union(
+        [Type.Literal('owner'), Type.Literal('trusted'), Type.Literal('member'), Type.Literal('guest')],
+        {
+          description: 'The role to grant TO.',
+        },
+      ),
+      match: Type.Optional(
+        Type.String({
+          description:
+            'A match rule assigning an author/scope to the role, e.g. "slack:T0123 author:U_WIFE". ' +
+            'Provide exactly one of match or permission.',
+        }),
+      ),
+      permission: Type.Optional(
+        Type.String({
+          description:
+            'A capability to add to the role, e.g. "channel.respond". Provide exactly one of match or permission. ' +
+            'security.bypass.* permissions cannot be granted through this tool.',
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params): Promise<ToolReturn> {
+      const origin = getOrigin()
+
+      if (!isSinglePrincipalOrigin(origin)) {
+        return err(
+          'grant_role is only available from the TUI or a 1:1 DM. A group-channel turn cannot change roles, ' +
+            'because it mixes in other participants\u2019 messages (prompt-injection surface).',
+        )
+      }
+
+      const callerRole = permissions.resolveRole(origin)
+      if (callerRole !== 'owner' && callerRole !== 'trusted') {
+        return err(`grant_role denied: caller resolves to '${callerRole}'; only owner or trusted may grant roles.`)
+      }
+
+      const hasMatch = typeof params.match === 'string' && params.match.length > 0
+      const hasPermission = typeof params.permission === 'string' && params.permission.length > 0
+      if (hasMatch === hasPermission) {
+        return err('Provide exactly one of `match` or `permission`.')
+      }
+
+      if (!isTierRole(params.role)) {
+        return err(`Unknown target role '${params.role}'.`)
+      }
+
+      // Tier ceiling: a granter may not assign or empower a role ABOVE its own.
+      // owner(3) ≥ trusted(2) ≥ member(1) ≥ guest(0).
+      if (tierOf(params.role) > tierOf(callerRole)) {
+        return err(`grant_role denied: a ${callerRole} caller cannot grant the higher '${params.role}' role.`)
+      }
+
+      return hasMatch
+        ? grantMatch(params.role, params.match as string)
+        : grantPermission(callerRole, params.role, params.permission as string)
+    },
+  })
+
+  function grantMatch(role: string, matchRule: string): ToolReturn {
+    const parsed = parseMatchRule(matchRule)
+    if (!parsed.ok) {
+      return err(`Invalid match rule '${matchRule}': ${parsed.error}`)
+    }
+
+    const result = grantRole({ cwd: agentDir, roleName: role, matchRule })
+    if (!result.ok) return err(result.reason)
+
+    reload()
+    return ok('match', role, matchRule, result.added, false)
+  }
+
+  function grantPermission(callerRole: string, role: string, permission: string): ToolReturn {
+    // security.bypass.* defeats guards rather than enabling a feature; never
+    // grantable through an agent tool. It stays a deliberate hand-edit gated by
+    // the rolePromotion guard + an explicit ack.
+    if (permission.startsWith('security.bypass.')) {
+      return err(
+        `grant_role refuses to grant '${permission}': security.bypass.* permissions disable security guards and ` +
+          'must be set by hand-editing typeclaw.json (gated by the rolePromotion guard), not via this tool.',
+      )
+    }
+
+    // "Grant only what you hold": the caller cannot confer a capability it does
+    // not itself possess. Owner's resolved set is the expanded wildcard, so an
+    // owner can grant any non-bypass core permission; trusted is capped at its
+    // literal set.
+    const callerPerms = permissions.describe(getOrigin()).permissions
+    if (!callerPerms.includes(permission)) {
+      return err(
+        `grant_role denied: a ${callerRole} caller cannot grant '${permission}' because it does not hold that permission.`,
+      )
+    }
+
+    const result = grantRolePermission({ cwd: agentDir, roleName: role, permission })
+    if (!result.ok) return err(result.reason)
+
+    reload()
+    return ok('permission', role, permission, result.added, true)
+  }
+
+  function reload(): void {
+    try {
+      permissions.replaceRoles(reloadRoles())
+    } catch {
+      // Best-effort hot-reload of match-grants. A failure here does not undo
+      // the on-disk write; the next config reload / restart picks it up.
+    }
+  }
+}
+
+function ok(
+  mode: 'match' | 'permission',
+  role: string,
+  value: string,
+  added: boolean,
+  restartRequired: boolean,
+): ToolReturn {
+  const details: GrantRoleToolDetails = { ok: true, mode, role, value, added, restartRequired }
+  const note = added ? '' : ' (already on file)'
+  const restart = restartRequired
+    ? ' This permission grant is restart-required; run `typeclaw restart` for it to take effect.'
+    : ''
+  const text =
+    mode === 'match'
+      ? `Granted role '${role}' the match rule '${value}'${note}.${restart}`
+      : `Granted role '${role}' the permission '${value}'${note}.${restart}`
+  return { content: [{ type: 'text', text }], details }
+}
+
+function err(message: string): ToolReturn {
+  const details: GrantRoleToolDetails = { ok: false, error: message }
+  return { content: [{ type: 'text', text: message }], details }
+}
+
+type ToolReturn = {
+  content: { type: 'text'; text: string }[]
+  details: GrantRoleToolDetails
+}

package/src/bundled-plugins/guard/policies/non-workspace-write.ts

@@ -20,12 +20,14 @@ const AGENT_ROOT_WRITE_ALLOWLIST = new Set([
   'typeclaw.json',
 ])
 
-// `packages/` is a bun workspace root scaffolded at init (see
-// src/init/index.ts#DIRECTORIES). Reusable systems and custom typeclaw
-// plugins live there as standalone packages, so the agent must be able to
-// write into `packages/<name>/...` without acknowledging the guard — same
-// as `workspace/`, but for code intended to be reused rather than discarded.
-const AGENT_ROOT_DIRECTORY_ALLOWLIST = new Set(['mounts', 'packages'])
+// All scaffolded write zones outside `workspace/` (see
+// src/init/index.ts#DIRECTORIES) that the agent may write into without
+// acknowledging the guard. `packages/` holds reusable systems and custom
+// typeclaw plugins as standalone packages; `public/` is the guest-visible
+// zone for anything intended to be shared out. Both are deliberate write
+// targets, same as `workspace/`, so an unacknowledged write is expected, not
+// suspicious.
+const AGENT_ROOT_DIRECTORY_ALLOWLIST = new Set(['mounts', 'packages', 'public'])
 
 export async function checkNonWorkspaceWriteGuard(options: {
   tool: string

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

@@ -6,7 +6,7 @@ import { CronExpressionParser } from 'cron-parser'
 import { z } from 'zod'
 
 import type { SessionOrigin } from '@/agent/session-origin'
-import { definePlugin } from '@/plugin'
+import { definePlugin, type SpawnSubagentOptions } from '@/plugin'
 import { formatLocalDate } from '@/shared'
 
 import { createDreamingSubagent, type DreamingPayload } from './dreaming'
@@ -205,9 +205,20 @@ export default definePlugin({
         ...(last.origin !== undefined ? { origin: last.origin } : {}),
         ...(streamLineCursor !== undefined ? { streamLineCursor } : {}),
       }
-      const spawnOptions = {
+      // Execution authority is `system` (resolves to owner), NOT the
+      // triggering turn's role: memory-logging is TypeClaw infrastructure over
+      // operator-owned sessions//memory/, so a guest channel turn that triggers
+      // it must not demote the logger to guest and get its transcript read
+      // blocked by privateSurfaceRead. The triggering origin is preserved two
+      // ways: `triggeredBy` for audit provenance, and `payload.origin` for
+      // content provenance (memory extraction/retrieval channel-safety).
+      const spawnOptions: SpawnSubagentOptions = {
         parentSessionId: sessionId,
-        ...(last.origin !== undefined ? { spawnedByOrigin: last.origin } : {}),
+        spawnedByOrigin: {
+          kind: 'system',
+          component: 'memory-logger',
+          ...(last.origin !== undefined ? { triggeredBy: last.origin } : {}),
+        },
       }
       const next = spawnChain
         .catch(() => undefined)
@@ -280,10 +291,18 @@ export default definePlugin({
         cacheFilePath,
         ...(event.origin !== undefined ? { origin: event.origin } : {}),
       }
-      await ctx.spawnSubagent('memory-retrieval', payload, {
+      // System authority, not the triggering turn's role — see the
+      // memory-logger spawn above. memory-retrieval writes
+      // memory/.retrieval-cache/, which a guest-demoted role cannot.
+      const retrievalSpawnOptions: SpawnSubagentOptions = {
         parentSessionId: event.sessionId,
-        ...(event.origin !== undefined ? { spawnedByOrigin: event.origin } : {}),
-      })
+        spawnedByOrigin: {
+          kind: 'system',
+          component: 'memory-retrieval',
+          ...(event.origin !== undefined ? { triggeredBy: event.origin } : {}),
+        },
+      }
+      await ctx.spawnSubagent('memory-retrieval', payload, retrievalSpawnOptions)
     }
 
     // Subagents are constructed at boot here (rather than imported as constants)

package/src/bundled-plugins/security/index.ts

@@ -1,4 +1,5 @@
 import { definePlugin } from '@/plugin'
+import { resolveHiddenPaths } from '@/sandbox'
 
 import { HIGH_TIER_PER_GUARD_PERMISSIONS, SECURITY_PERMISSIONS, SEVERITY_PERMISSION } from './permissions'
 import type { SecurityPermission, SecuritySeverity } from './permissions'
@@ -11,6 +12,7 @@ import {
   recordGitRemoteTaintIfAny,
 } from './policies/git-exfil'
 import { GUARD_OUTBOUND_SECRET_SEVERITY, checkOutboundSecretGuard } from './policies/outbound-secret-scan'
+import { checkPrivateSurfaceReadGuard } from './policies/private-surface-read'
 import { applyPromptInjectionDefense } from './policies/prompt-injection'
 import { clearSessionTaints } from './policies/remote-taint-state'
 import { GUARD_ROLE_PROMOTION_SEVERITY, checkRolePromotionGuard } from './policies/role-promotion'
@@ -161,6 +163,16 @@ export default definePlugin({
                 SECURITY_PERMISSIONS.bypassSecretExfilRead,
                 GUARD_SECRET_EXFIL_READ_SEVERITY,
               ),
+          // Role-derived, not severity-bypassed: resolveHiddenPaths already
+          // returns an empty deny-list for roles that may see the surface, so
+          // there is no canBypass wrapper. Mirrors the bash sandbox masks onto
+          // the non-bash read/grep/find/ls/edit/write builtins.
+          checkPrivateSurfaceReadGuard({
+            tool: event.tool,
+            args: event.args,
+            agentDir: ctx.agentDir,
+            hidden: resolveHiddenPaths(ctx.permissions, event.origin, ctx.agentDir),
+          }),
           canBypass(GUARD_SSRF_SEVERITY, SECURITY_PERMISSIONS.bypassSsrf)
             ? undefined
             : withPermissionHint(

package/src/bundled-plugins/security/policies/private-surface-read.ts

@@ -0,0 +1,215 @@
+import { realpathSync } from 'node:fs'
+import path from 'node:path'
+
+import type { HiddenPaths } from '@/sandbox'
+
+import type { SecurityBlock } from '../policy'
+
+export const GUARD_PRIVATE_SURFACE_READ = 'privateSurfaceRead'
+
+// bash is excluded: its access to hidden paths is contained by the bwrap
+// sandbox (applyBashSandbox), not by blocking the call. Every OTHER tool is
+// scanned, so a new file-reading tool — bundled or third-party — is covered
+// the day it ships without a whitelist edit. websearch/webfetch take URLs, not
+// local paths, and the path-plausibility filter keeps their args from matching.
+const UNSCANNED_TOOLS = new Set(['bash'])
+
+// The bash sandbox hides the role's private surface — the working DIRECTORIES
+// (workspace/, memory/, sessions/) and the secret FILES (.env, secrets.json) —
+// via bwrap masks, but every non-bash tool runs in the main process, outside
+// any sandbox. find_entry, look_at, and the channel attachment tools all read
+// files by a caller-supplied path, so without a guard a restricted role could
+// read back through them exactly what bash masking denies. This guard mirrors
+// the WHOLE deny-list (dirs + files) onto all of them, honouring the PR's
+// "two enforcement points, one deny-list" invariant.
+//
+// It covers the full deny-list rather than delegating secret files to the
+// secretExfilRead guard: that guard only inspects read/grep/find/ls (not
+// edit/write/look_at/channel_send) and is acknowledgement-bypassable, so
+// delegating would leave .env/secrets.json reachable through the uncovered
+// tools — exactly the gap the bash masks close. secretExfilRead remains as
+// independent defense in depth for the four tools it does cover.
+//
+// Posture is FAIL-CLOSED for restricted roles: it does not whitelist a known
+// set of tools (that fails open the moment a new reader is added). It scans
+// every arg of every non-bash tool — recursively, since paths hide in nested
+// shapes like look_at's images[].path and channel_send's attachments[].path —
+// and blocks any string that resolves to (a secret file) or under (a hidden
+// directory) the deny-list.
+export function checkPrivateSurfaceReadGuard(options: {
+  tool: string
+  args: Record<string, unknown>
+  agentDir: string
+  hidden: HiddenPaths
+}): SecurityBlock | undefined {
+  const { tool, args, agentDir, hidden } = options
+  if (UNSCANNED_TOOLS.has(tool)) return undefined
+  const deniedDirs = hidden.dirs
+  const deniedFiles = hidden.files
+  if (deniedDirs.length === 0 && deniedFiles.length === 0) return undefined
+
+  for (const candidate of collectPathCandidates(args, tool)) {
+    const hit = matchHidden(candidate, agentDir, deniedDirs, deniedFiles)
+    if (hit !== undefined) {
+      return {
+        block: true,
+        reason: [
+          `Guard \`${GUARD_PRIVATE_SURFACE_READ}\` blocked ${tool}: argument \`${candidate}\` resolves to ${hit}, which is hidden from the current role.`,
+          'The bash sandbox masks the same path; reaching it through another tool is the same disclosure.',
+        ].join(' '),
+      }
+    }
+  }
+  return undefined
+}
+
+// Field names whose values are ALWAYS free text (prose/queries/ids), NEVER a
+// filesystem path, for EVERY tool. Scanning them caused false positives: a
+// guest's `channel_reply({ text: "the memory leak" })` or `websearch({ query:
+// "workspace setup" })` resolve to a bare hidden-dir name and were wrongly
+// blocked. This is a DENYLIST OF KEY NAMES, not a tool whitelist: an unknown
+// field on an unknown tool is still scanned (fail-closed for new path-bearing
+// readers); we only skip values whose KEY is universally free text. `command`
+// is here because bash (its only user) is already exempt via UNSCANNED_TOOLS.
+//
+// `glob` and `pattern` are deliberately ABSENT — they are tool-dependent (a
+// glob/path-filter in grep/find, a regex only in grep) and handled by
+// FREE_TEXT_KEYS_BY_TOOL below.
+const NON_PATH_KEYS = new Set([
+  'text',
+  'query',
+  'prompt',
+  'selector',
+  'url',
+  'message',
+  'body',
+  'content',
+  'command',
+  'reason',
+  'subject',
+  'description',
+  'title',
+  'name',
+  // edit tool: replacement text is free-form and may quote a hidden path.
+  'oldText',
+  'newText',
+  // memory append tool: fragment topic is free text.
+  'topic',
+  // channel_send/channel_reply attachments[].filename and
+  // channel_fetch_attachment.filename: display-only metadata (defaults to the
+  // basename of the real `path`), never the file location the guard cares
+  // about — `attachments[].path` carries that and is NOT exempted.
+  'filename',
+])
+
+// Keys that are free text in SPECIFIC tools but path-bearing in others, so a
+// global denylist would either over-block or open a bypass. Scoped per tool:
+//   - grep.pattern  : a regex/search string (e.g. "sessions"), NOT a path.
+// Notably NOT listed (and therefore SCANNED):
+//   - grep.glob / find.pattern : both are glob path-filters resolved RELATIVE
+//     to the search root, so `grep({ path: '.', glob: 'workspace/**' })` and
+//     `find({ path: '.', pattern: 'workspace/**' })` reach a hidden subtree.
+//     Exempting them let the only hidden-identifying arg through (the bypass a
+//     review caught). They have no false-positive risk: path.resolve treats
+//     glob metacharacters as literal, so `*.ts` -> `/agent/*.ts` (passes) while
+//     `workspace/**` -> `/agent/workspace/**` (correctly blocked).
+// Fail-closed: only the listed tool's listed key is exempted; an unknown tool
+// (or grep gaining a new key) scans everything.
+const FREE_TEXT_KEYS_BY_TOOL: Record<string, ReadonlySet<string>> = {
+  grep: new Set(['pattern']),
+}
+
+// Recursively collects strings that could be paths, skipping values under a
+// universally-free-text key or a tool-scoped free-text key. matchHidden then
+// realpath-resolves each candidate and fires only on one landing inside a
+// hidden directory. Fail-closed by design: a bare path-bearing value equal to a
+// hidden dir name (e.g. `path: "memory"`) is still blocked. `underExempt`
+// propagates so nested values under an exempt key (e.g. a structured pattern)
+// stay exempt; top-level strings and array elements carry no key and are always
+// scanned (so attachments[].path is collected).
+function collectPathCandidates(value: unknown, tool: string): string[] {
+  const out: string[] = []
+  walk(value, out, tool, false)
+  return out
+}
+
+function walk(value: unknown, out: string[], tool: string, underExempt: boolean): void {
+  if (typeof value === 'string') {
+    if (underExempt) return
+    out.push(value)
+    return
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) walk(item, out, tool, underExempt)
+    return
+  }
+  if (value !== null && typeof value === 'object') {
+    const toolFreeText = FREE_TEXT_KEYS_BY_TOOL[tool]
+    for (const [key, item] of Object.entries(value)) {
+      const keyIsExempt = NON_PATH_KEYS.has(key) || (toolFreeText?.has(key) ?? false)
+      walk(item, out, tool, underExempt || keyIsExempt)
+    }
+  }
+}
+
+// Resolving both sides against agentDir defeats traversal (workspace/../workspace/x),
+// relative forms (./workspace), and absolute restatements. Secret files match on
+// exact equality; hidden directories match the dir itself or anything under it,
+// using a trailing slash so `workspace` does not also match a sibling
+// `workspace-notes`.
+//
+// Symlink defense: lexical path.resolve is NOT enough. A restricted role can
+// plant `public/leak -> ../.env` (or `-> ../memory`) via sandboxed bash, then
+// read it back through a non-bash tool whose path lexically lands in the
+// guest-visible `public/`. So we resolve the candidate's REAL path
+// (realpathRealIntendedPath follows symlinks on every existing path component)
+// before matching. Both sides are realpath'd because agentDir itself may sit
+// under a symlink (e.g. /tmp -> /private/tmp on macOS); comparing a real
+// candidate against a lexical deny-list would never match.
+function matchHidden(
+  candidate: string,
+  agentDir: string,
+  deniedDirs: string[],
+  deniedFiles: string[],
+): string | undefined {
+  const resolved = realpathRealIntendedPath(path.resolve(agentDir, candidate))
+  for (const file of deniedFiles) {
+    if (resolved === realpathRealIntendedPath(file)) return file
+  }
+  for (const dir of deniedDirs) {
+    const realDir = realpathRealIntendedPath(dir)
+    if (resolved === realDir || resolved.startsWith(`${realDir}/`)) return dir
+  }
+  return undefined
+}
+
+// Resolves symlinks on the longest existing prefix of an absolute path, then
+// re-appends the non-existent tail. A bare realpathSync throws on a path that
+// does not exist yet (a write target, or a read of a not-yet-created file), so
+// we walk up to the nearest existing ancestor, realpath THAT (collapsing any
+// symlinked component including a planted symlink), and rejoin the remainder.
+// This catches `public/leak/x` where `public/leak` is a symlink into a hidden
+// dir even though `public/leak/x` itself does not exist. Sync (realpathSync)
+// keeps the guard synchronous so the security tool.before check array stays
+// non-async; the cost is one syscall per existing component, negligible at the
+// tool-call boundary. Sync mirror of resolveRealIntendedPath in the guard
+// plugin's non-workspace-write policy.
+function realpathRealIntendedPath(absolutePath: string): string {
+  const pending: string[] = []
+  let current = absolutePath
+  while (true) {
+    try {
+      return path.join(realpathSync.native(current), ...pending.reverse())
+    } catch (err) {
+      if (!isNotFoundError(err)) throw err
+    }
+    const parent = path.dirname(current)
+    if (parent === current) return absolutePath
+    pending.push(path.basename(current))
+    current = parent
+  }
+}
+
+function isNotFoundError(err: unknown): boolean {
+  return err instanceof Error && 'code' in err && err.code === 'ENOENT'
+}

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

@@ -13,6 +13,9 @@ export type GithubWebhookHandlerOptions = {
   allowlist: () => readonly string[]
   selfId: () => string | null
   selfLogin: () => string | null
+  // Defaults to 'pat' when omitted. Only 'app' promotes an opened PR to a
+  // review request; see classifyOpenedAsReview for why.
+  authType?: () => 'pat' | 'app'
   route: (message: InboundMessage) => void
   logger: GithubInboundLogger
   // Optional: resolves whether the bot is a member of the given team. When
@@ -56,6 +59,7 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
     const teamIsBotMember = await resolveTeamMembership(event, payload, options)
     const classified = classifyGithubInbound(event, payload, selfLogin, {
       teamIsBotMember,
+      authType: options.authType?.() ?? 'pat',
     })
     if (classified === null) return ok()
 
@@ -77,7 +81,7 @@ export function classifyGithubInbound(
   event: string,
   payload: Record<string, unknown>,
   selfLogin: string | null,
-  options?: { teamIsBotMember?: boolean },
+  options?: { teamIsBotMember?: boolean; authType?: 'pat' | 'app' },
 ): InboundMessage | null {
   const repository = readRepository(payload)
   if (repository === null) return null
@@ -177,6 +181,14 @@ export function classifyGithubInbound(
         teamIsBotMember: options?.teamIsBotMember,
       })
     }
+    // A GitHub App cannot be added to a PR's requested_reviewers, so it never
+    // receives a review_requested event targeting itself. The opened event is
+    // the only signal it can act on, so in App mode an opened PR is promoted to
+    // a review request. A PAT-backed bot is a real user that can be requested,
+    // so it waits for the explicit request instead of reviewing every PR.
+    if (action === 'opened' && options?.authType === 'app') {
+      return classifyOpenedAsReview({ payload, pr, number, base, selfLogin })
+    }
     return buildInbound(
       { ...base, chat: `pr:${number}`, thread: null },
       pr.body,
@@ -291,6 +303,47 @@ function classifyReviewRequest(input: ReviewRequestInput): InboundMessage | null
   }
 }
 
+type OpenedAsReviewInput = {
+  payload: Record<string, unknown>
+  pr: Record<string, unknown>
+  number: number
+  base: Pick<InboundMessage, 'adapter' | 'workspace' | 'isDm' | 'mentionsOthers' | 'replyToOtherMessageId'>
+  selfLogin: string | null
+}
+
+function classifyOpenedAsReview(input: OpenedAsReviewInput): InboundMessage | null {
+  const { payload, pr, number, base, selfLogin } = input
+  if (selfLogin === null) return null
+  const sender = readUser(payload.sender)
+  if (sender === null) return null
+  if (sender.login === selfLogin) return null
+
+  const title = readString(pr, 'title') ?? `#${number}`
+  const head = readString(readRecord(pr.head), 'ref')
+  const baseRef = readString(readRecord(pr.base), 'ref')
+  const branchSegment = head !== null && baseRef !== null ? ` Branch: ${head} → ${baseRef}.` : ''
+  const text =
+    `@${sender.login} requested your review on PR #${number}: "${title}".${branchSegment}` +
+    ' Please review the changes line-by-line and post your feedback.'
+
+  const updatedAt = readString(pr, 'updated_at') ?? ''
+  const prId = readNumber(pr, 'id') ?? number
+
+  return {
+    ...base,
+    chat: `pr:${number}`,
+    thread: null,
+    text,
+    externalMessageId: `pr-${prId}-opened-${updatedAt}`,
+    authorId: String(sender.id),
+    authorName: sender.login,
+    authorIsBot: sender.type === 'Bot',
+    isBotMention: true,
+    replyToBotMessageId: null,
+    ts: updatedAt !== '' ? Date.parse(updatedAt) || 0 : 0,
+  }
+}
+
 export type GithubReviewerTeam = { slug: string; id: number; org: string | null }
 
 export function readReviewerTeam(value: unknown): GithubReviewerTeam | null {

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

@@ -128,6 +128,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     allowlist: () => options.configRef().eventAllowlist,
     selfId: () => selfId,
     selfLogin: () => selfLogin,
+    authType: () => options.secrets.auth.type,
     isBotInTeam,
     logger,
     route: (message) => {