typeclaw 0.17.0 → 0.19.0

package/src/channels/router.ts

@@ -7,13 +7,21 @@ import { createSession, renderTurnRoleAnchor, renderTurnTimeAnchor, type AgentSe
 import { subscribeProviderErrors } from '@/agent/provider-error'
 import type { ChannelParticipant, SessionOrigin } from '@/agent/session-origin'
 import { renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
-import { createCommandRegistry } from '@/commands'
+import { type Command, type CommandResult, createCommandRegistry } from '@/commands'
 import { CORE_PERMISSIONS, type PermissionService } from '@/permissions'
 import type { HookBus } from '@/plugin'
 import { extractClaimCode } from '@/role-claim'
 import type { Stream } from '@/stream'
 
-import { decideEngagement, grantStickyForReplyTargets, StickyLedger, type EngagementDecision } from './engagement'
+import { formatChannelCommandHelp } from './commands'
+import {
+  countEffectiveHumans,
+  decideEngagement,
+  grantStickyForReplyTargets,
+  isMultiHumanGroup,
+  StickyLedger,
+  type EngagementDecision,
+} from './engagement'
 import {
   MEMBERSHIP_COLD_FETCH_TIMEOUT_MS,
   type MembershipCount,
@@ -429,6 +437,10 @@ type LiveSession = {
   recentEngagedPeerBotTurns: { authorId: string; ts: number }[]
   consecutiveEngagedPeerBotTurns: number
   loopGuardActive: boolean
+  // Set in route() from the same membership+participants the engagement
+  // decision used, so the prompt nudge and sticky suppression agree on
+  // "is this a multi-human group". Read by composeTurnPrompt().
+  multiHumanGroup: boolean
   membershipFetch: Promise<MembershipCount | null> | null
   destroyed: boolean
   unsubProviderErrors: (() => void) | null
@@ -439,14 +451,16 @@ type LiveSession = {
 // pipeline (e.g. Discord native slash commands fired from listener.on
 // ('interaction_create')). Handlers that need a real inbound — for some
 // future hypothetical command like `/quote` — must guard on event !== null
-// instead of assuming it.
+// instead of assuming it. `live` is null for session-less commands
+// (requiresLiveSession:false, e.g. /help); session-control handlers run only
+// after the dispatch layer has resolved a live session, so they may assert it.
 type ChannelCommandContext = {
-  live: LiveSession
+  live: LiveSession | null
   event: InboundMessage | null
 }
 
 export type ExecuteCommandResult =
-  | { kind: 'handled'; name: string }
+  | { kind: 'handled'; name: string; reply?: string }
   | { kind: 'unknown-command'; name: string }
   | { kind: 'no-live-session' }
   | { kind: 'permission-denied' }
@@ -721,14 +735,31 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const historyCallbacks = new Map<ChannelKey['adapter'], Set<HistoryCallback>>()
   const fetchAttachmentCallbacks = new Map<ChannelKey['adapter'], Set<FetchAttachmentCallback>>()
   const stickyLedger = new StickyLedger()
-  const commands = createCommandRegistry<ChannelCommandContext>([
+  // The /help handler reads the live registry to enumerate commands, so it
+  // forward-references `commands`. Safe at runtime — the handler only runs on
+  // invocation, long after the assignment below completes.
+  const channelCommands: readonly Command<ChannelCommandContext>[] = [
+    {
+      name: 'help',
+      description: 'List available commands.',
+      permission: 'none',
+      requiresLiveSession: false,
+      handler: () => ({ reply: formatChannelCommandHelp(commands.list()) }),
+    },
     {
       name: 'stop',
+      description: 'Stop the current agent turn in this channel.',
+      permission: 'session.control',
+      requiresLiveSession: true,
       handler: async ({ live }) => {
-        await stopCurrentChannelTurn(live)
+        // requiresLiveSession:true guarantees the dispatch layer resolved a
+        // session before running this handler, so `live` is non-null here.
+        await stopCurrentChannelTurn(live!)
+        return { reply: 'Stopped the current turn.' }
       },
     },
-  ])
+  ]
+  const commands = createCommandRegistry<ChannelCommandContext>(channelCommands)
 
   // Implicit dir-name alias: agent folder basename matches Docker
   // container name (per AGENTS.md), the typical Discord/Slack bot
@@ -1086,6 +1117,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         recentEngagedPeerBotTurns: [],
         consecutiveEngagedPeerBotTurns: 0,
         loopGuardActive: false,
+        multiHumanGroup: false,
         membershipFetch,
         destroyed: false,
         unsubProviderErrors: null,
@@ -1499,6 +1531,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         const text = composeTurnPrompt(observed, batch, {
           adapter: live.key.adapter,
           loopGuardActive: live.loopGuardActive,
+          groupChatNudge: live.multiHumanGroup,
           systemReminders: reminders,
           role: liveRole,
         })
@@ -1603,6 +1636,28 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
   }
 
+  // Executes a parsed channel command and posts its reply (if any) back to the
+  // originating channel. Shared by the pre-gate public-command fast path and the
+  // post-gate command block so the execute→reply shape can't drift between them.
+  // Gating (channel.respond / session.control) and live-session resolution stay
+  // at the call sites — this helper only runs the handler and delivers the reply.
+  const runChannelCommand = async (event: InboundMessage, live: LiveSession | null): Promise<CommandResult> => {
+    const result = await commands.execute(event.text, { live, event })
+    if (result.kind === 'handled' && result.reply !== undefined) {
+      await send(
+        {
+          adapter: event.adapter,
+          workspace: event.workspace,
+          chat: event.chat,
+          thread: event.thread,
+          text: result.reply,
+        },
+        { source: 'system' },
+      )
+    }
+    return result
+  }
+
   const route = async (event: InboundMessage): Promise<void> => {
     const adapterConfig = options.configForAdapter(event.adapter)
     if (!adapterConfig) return
@@ -1650,6 +1705,25 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       }
     }
 
+    // Parse once, here, so the public-command fast path (below) and the
+    // post-gate command block share one parse and lookup.
+    const parsedCommand = commands.parse(event.text)
+    const commandInfo = parsedCommand === null ? undefined : commands.get(parsedCommand.name)
+
+    // Public-command fast path: a known command that is both ungated
+    // (permission:'none') AND informational (requiresLiveSession:false) runs
+    // BEFORE the channel.respond gate, mirroring the native-slash path where
+    // such commands skip permissions entirely. Both conditions are required so
+    // a future "public but live-session-aware" command can't silently bypass
+    // the gate. It only reveals already-public command names — it never creates
+    // a session or prompts the agent — so it is not a channel.respond bypass in
+    // any meaningful sense. Unknown commands, /stop, //escaped text, and plain
+    // messages all fall through to the gate unchanged.
+    if (parsedCommand !== null && commandInfo?.permission === 'none' && !commandInfo.requiresLiveSession) {
+      await runChannelCommand(event, null)
+      return
+    }
+
     if (isChannelRespondDenied(event)) {
       publishInbound(event, 'denied')
       logger.info(
@@ -1658,27 +1732,31 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       return
     }
 
-    const parsedCommand = commands.parse(event.text)
     if (parsedCommand !== null) {
       // Commands are control traffic, not engaged inbounds; if the session is stale,
       // the next engaged inbound will perform the rollover before prompting.
       const keyId = channelKeyId(key)
-      if (!commands.has(parsedCommand.name)) {
+      if (commandInfo === undefined) {
         logger.info(`[channels] ${keyId}: ignoring unknown command /${parsedCommand.name}`)
         return
       }
-      if (isSessionControlDenied(event)) {
+      if (commandInfo.permission === 'session.control' && isSessionControlDenied(event)) {
         logger.info(
           `[channels] ${keyId}: denied command /${parsedCommand.name} by permissions (session.control) author=${event.authorId}`,
         )
         return
       }
-      const existingLive = liveSessions.get(keyId)
-      if (!existingLive || existingLive.destroyed) {
-        logger.info(`[channels] ${keyId}: ignoring command /${parsedCommand.name} with no live session`)
-        return
+      // Session-less commands (e.g. /help) are informational and run without a
+      // live session; their handler reply is posted straight back to the channel.
+      let existingLive: LiveSession | null = null
+      if (commandInfo.requiresLiveSession) {
+        existingLive = liveSessions.get(keyId) ?? null
+        if (existingLive === null || existingLive.destroyed) {
+          logger.info(`[channels] ${keyId}: ignoring command /${parsedCommand.name} with no live session`)
+          return
+        }
       }
-      const commandResult = await commands.execute(event.text, { live: existingLive, event })
+      const commandResult = await runChannelCommand(event, existingLive)
       if (commandResult.kind !== 'not-command') return
     }
 
@@ -1712,6 +1790,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 
     const membership = await membershipForEngagement(live)
 
+    live.multiHumanGroup = isMultiHumanGroup(event.isDm, countEffectiveHumans(live.participants, membership, now()))
+
     const decision: EngagementDecision = decideEngagement({
       message: event,
       config: adapterConfig.engagement,
@@ -2416,38 +2496,49 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     options: ExecuteCommandOptions,
   ): Promise<ExecuteCommandResult> => {
     const lowered = name.toLowerCase()
-    if (!commands.has(lowered)) {
+    const commandInfo = commands.get(lowered)
+    if (commandInfo === undefined) {
       return { kind: 'unknown-command', name: lowered }
     }
     // Gates on session.control (not channel.respond) so a respond-capable
     // guest cannot abort another speaker's turn. Runs BEFORE the live-session
     // lookup so an unauthorized invoker gets 'permission-denied' regardless of
     // session state, rather than leaking session presence via the
-    // 'no-live-session' vs 'permission-denied' distinction.
-    const partial: SessionOrigin = {
-      kind: 'channel',
-      adapter: key.adapter,
-      workspace: key.workspace,
-      chat: key.chat,
-      thread: key.thread,
-      lastInboundAuthorId: options.invokerId,
-    }
-    if (!permissions.has(partial, CORE_PERMISSIONS.sessionControl)) {
-      return { kind: 'permission-denied' }
-    }
-    const resolved = resolveLiveSessionForCommand(liveSessions, key)
-    if (resolved.kind === 'none') {
-      return { kind: 'no-live-session' }
+    // 'no-live-session' vs 'permission-denied' distinction. Session-less
+    // informational commands (e.g. /help) declare permission:'none' and skip
+    // both the gate and the lookup so they work in channels with no live turn.
+    if (commandInfo.permission === 'session.control') {
+      const partial: SessionOrigin = {
+        kind: 'channel',
+        adapter: key.adapter,
+        workspace: key.workspace,
+        chat: key.chat,
+        thread: key.thread,
+        lastInboundAuthorId: options.invokerId,
+      }
+      if (!permissions.has(partial, CORE_PERMISSIONS.sessionControl)) {
+        return { kind: 'permission-denied' }
+      }
     }
-    if (resolved.kind === 'ambiguous') {
-      return { kind: 'ambiguous', matchCount: resolved.count }
+    let live: LiveSession | null = null
+    if (commandInfo.requiresLiveSession) {
+      const resolved = resolveLiveSessionForCommand(liveSessions, key)
+      if (resolved.kind === 'none') {
+        return { kind: 'no-live-session' }
+      }
+      if (resolved.kind === 'ambiguous') {
+        return { kind: 'ambiguous', matchCount: resolved.count }
+      }
+      live = resolved.session
     }
-    const result = await commands.execute(`/${lowered}`, { live: resolved.session, event: null })
+    const result = await commands.execute(`/${lowered}`, { live, event: null })
     if (result.kind === 'handled') {
-      return { kind: 'handled', name: result.name }
+      return result.reply !== undefined
+        ? { kind: 'handled', name: result.name, reply: result.reply }
+        : { kind: 'handled', name: result.name }
     }
     // commands.execute can only return not-command (impossible — we pass a
-    // leading slash), unknown-command (impossible — we just checked has()),
+    // leading slash), unknown-command (impossible — we just checked get()),
     // or handled. Any other outcome is a bug.
     return { kind: 'unknown-command', name: lowered }
   }
@@ -2616,6 +2707,7 @@ function composeTurnPrompt(
   state: {
     adapter?: AdapterId
     loopGuardActive: boolean
+    groupChatNudge?: boolean
     systemReminders?: readonly string[]
     now?: Date
     role?: string
@@ -2689,6 +2781,32 @@ 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.
+  if (state.groupChatNudge === true && !state.loopGuardActive) {
+    parts.push(
+      '---',
+      '**[SYSTEM MESSAGE — not from a human]**',
+      '',
+      'You are in a group chat with multiple people. This is an automated',
+      '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.',
+      '',
+      '---',
+      '',
+    )
+  }
   if (observed.length > 0) {
     parts.push('## Recent context (not addressed to you, for awareness only)')
     for (const o of observed) {

package/src/cli/channel.ts

@@ -842,7 +842,6 @@ async function promptGithubAppAuth(): Promise<{
   type: 'app'
   appId: number
   privateKey: string
-  installationId?: number
 }> {
   const appId = await text({
     message: 'GitHub App ID',
@@ -857,21 +856,10 @@ async function promptGithubAppAuth(): Promise<{
     cancel('Aborted.')
     process.exit(0)
   }
-  const installationId = await text({
-    message: 'Installation ID (optional; leave blank to auto-discover)',
-    validate: (value) =>
-      value === undefined || value === '' ? undefined : validatePositiveInteger(value, 'Installation ID is required'),
-  })
-  if (isCancel(installationId)) {
-    cancel('Aborted.')
-    process.exit(0)
-  }
-  const parsedInstallationId = installationId === '' ? undefined : Number(installationId)
   return {
     type: 'app',
     appId: Number(appId),
     privateKey,
-    ...(parsedInstallationId !== undefined ? { installationId: parsedInstallationId } : {}),
   }
 }
 

package/src/cli/init.ts

@@ -1293,7 +1293,6 @@ async function promptGithubAppAuth(): Promise<{
   type: 'app'
   appId: number
   privateKey: string
-  installationId?: number
 } | null> {
   const appId = await text({
     message: 'GitHub App ID',
@@ -1302,18 +1301,10 @@ async function promptGithubAppAuth(): Promise<{
   if (isCancel(appId)) return null
   const privateKey = await promptPrivateKeyPem('GitHub App private key PEM, escaped PEM, or path to .pem file')
   if (privateKey === CANCEL_SYMBOL) return null
-  const installationId = await text({
-    message: 'Installation ID (optional; leave blank to auto-discover)',
-    validate: (v) =>
-      v === undefined || v === '' ? undefined : validatePositiveInteger(v, 'Installation ID is required'),
-  })
-  if (isCancel(installationId)) return null
-  const parsedInstallationId = installationId === '' ? undefined : Number(installationId)
   return {
     type: 'app',
     appId: Number(appId),
     privateKey,
-    ...(parsedInstallationId !== undefined ? { installationId: parsedInstallationId } : {}),
   }
 }
 

package/src/cli/ui.ts

@@ -152,6 +152,12 @@ export const SLACK_APP_MANIFEST = {
     // so a misconfigured (non-Socket-Mode) deployment fails fast rather
     // than silently routing real slash invocations to a third-party URL.
     slash_commands: [
+      {
+        command: '/help',
+        description: 'List available commands',
+        url: 'https://example.invalid/typeclaw-uses-socket-mode',
+        should_escape: false,
+      },
       {
         command: '/stop',
         description: 'Abort the current turn in this channel',

package/src/commands/index.ts

@@ -1,8 +1,27 @@
-export type CommandHandler<Context> = (context: Context, command: ParsedCommand) => Promise<void> | void
+// Returning nothing keeps the void contract — the dispatch layer then falls
+// back to its static per-result-kind reply. A `reply` lets dynamic commands
+// (/help) surface text the dispatcher could not have known statically.
+export type CommandHandlerResult = void | { reply?: string }
+
+export type CommandHandler<Context> = (
+  context: Context,
+  command: ParsedCommand,
+) => Promise<CommandHandlerResult> | CommandHandlerResult
+
+// `permission` and `requiresLiveSession` are command-level policy the dispatch
+// layer (the channel router) enforces. They live on the command, not the
+// dispatcher, so a new command declares its own requirements in one place:
+// 'session.control' + requiresLiveSession:true is the control-command default
+// (/stop); 'none' + requiresLiveSession:false is the informational default
+// (/help). Both are optional so plain registries (tests, TUI) need not care.
+export type CommandPermission = 'none' | 'session.control'
 
 export type Command<Context> = {
   name: string
   aliases?: readonly string[]
+  description: string
+  permission?: CommandPermission
+  requiresLiveSession?: boolean
   handler: CommandHandler<Context>
 }
 
@@ -11,14 +30,27 @@ export type ParsedCommand = {
   args: string
 }
 
+// Read-only view of a registered command, used to generate help text from the
+// registry so the listing can never drift from the actual command set. Aliases
+// are folded into the canonical entry rather than listed as separate commands.
+export type CommandInfo = {
+  name: string
+  aliases: readonly string[]
+  description: string
+  permission: CommandPermission
+  requiresLiveSession: boolean
+}
+
 export type CommandResult =
   | { kind: 'not-command' }
   | { kind: 'unknown-command'; name: string }
-  | { kind: 'handled'; name: string }
+  | { kind: 'handled'; name: string; reply?: string }
 
 export type CommandRegistry<Context> = {
   parse: (text: string) => ParsedCommand | null
   has: (name: string) => boolean
+  get: (name: string) => CommandInfo | undefined
+  list: () => readonly CommandInfo[]
   execute: (text: string, context: Context) => Promise<CommandResult>
 }
 
@@ -33,16 +65,34 @@ export function createCommandRegistry<Context>(commands: readonly Command<Contex
     }
   }
 
+  const info = (command: Command<Context>): CommandInfo => ({
+    name: command.name,
+    aliases: command.aliases ?? [],
+    description: command.description,
+    permission: command.permission ?? 'session.control',
+    requiresLiveSession: command.requiresLiveSession ?? true,
+  })
+
   return {
     parse: parseCommand,
     has: (name) => byName.has(name.toLowerCase()),
+    get: (name) => {
+      const command = byName.get(name.toLowerCase())
+      return command ? info(command) : undefined
+    },
+    // Canonical commands only, in declaration order. Aliases resolve to the
+    // same Command object, so de-dupe by identity to avoid duplicate rows.
+    list: () => commands.map(info),
     execute: async (text, context) => {
       const parsed = parseCommand(text)
       if (parsed === null) return { kind: 'not-command' }
       const command = byName.get(parsed.name)
       if (!command) return { kind: 'unknown-command', name: parsed.name }
-      await command.handler(context, parsed)
-      return { kind: 'handled', name: command.name }
+      const result = await command.handler(context, parsed)
+      const reply = result?.reply
+      return reply !== undefined
+        ? { kind: 'handled', name: command.name, reply }
+        : { kind: 'handled', name: command.name }
     },
   }
 }

package/src/init/dockerfile.ts

@@ -50,6 +50,16 @@ export type BuildDockerfileOptions = {
 // flag the seccomp default profile blocks `unshare(CLONE_NEWUSER)` and bwrap
 // fails at startup. The two changes are load-bearing together — do not drop
 // one without the other.
+//
+// `jq` is in baseline (not behind a toggle) so it is available to the
+// per-tool bwrap sandbox that wraps agent bash calls. The sandbox only
+// `--ro-bind`s `/usr` + `/bin` from the container (see `src/sandbox/build.ts`),
+// so a binary that is not in the base image is invisible inside the sandbox —
+// there is no per-call install path. JSON munging in one-shot read-only
+// pipelines (`curl ... | jq`, `cat foo.json | jq`) is a baseline expectation
+// for the explorer/reviewer/scout subagents, whose prompts already advertise
+// `jq` as an available pipeline tool, so it ships unconditionally rather than
+// as an opt-in toggle.
 const BASELINE_APT_PACKAGES = [
   'git',
   'ca-certificates',
@@ -58,6 +68,7 @@ const BASELINE_APT_PACKAGES = [
   'iptables',
   'util-linux',
   'bubblewrap',
+  'jq',
 ] as const
 
 // curl-impersonate is the only currently-working way to query DuckDuckGo from
@@ -87,6 +98,33 @@ export const CURL_IMPERSONATE_SHA256_ARM64 = '6766bc67fd3e8e2313875f32b36b5a3fab
 // the impersonation to whatever `curl_chrome` resolves to.
 export const CURL_IMPERSONATE_PROFILE = 'chrome136'
 
+// yq is the YAML/JSON/XML processor the `explorer` and `reviewer` subagent
+// prompts advertise alongside `jq` as a sanctioned one-shot read-only
+// pipeline tool (`... | yq`). Like `jq` (shipped in baseline), a binary that
+// is not in the container base image is invisible inside the per-tool bwrap
+// sandbox that wraps agent bash calls — the sandbox only `--ro-bind`s `/usr`
+// + `/bin` from the container, and there is no per-call install path. So `yq`
+// ships unconditionally, same rationale as `jq`/`bubblewrap`/`util-linux`.
+//
+// This is Mike Farah's Go `yq` (https://github.com/mikefarah/yq), NOT the
+// Python jq-wrapper of the same name in Debian's `yq` apt package. The
+// prompts pair `yq` with `jq` for jq-style expression pipelines, which is
+// Farah's syntax — the Python tool's CLI is incompatible. Distributed as a
+// per-arch static binary (no apt package on trixie for the Go variant), so
+// it follows the pinned-version + per-arch SHA256 + `sha256sum -c` pattern of
+// curl-impersonate and cloudflared rather than the apt baseline list.
+//
+// To bump: pick a release from https://github.com/mikefarah/yq/releases,
+// then for each arch download yq_linux_<arch> and `shasum -a 256` it (or read
+// the SHA-256 column from the release's `checksums` file, cross-indexed via
+// `checksums_hashes_order`). Update all three constants in the same commit;
+// the build fails loudly at `sha256sum -c` on a mismatch. Version literal is
+// the release tag exactly as it appears on GitHub (with `v` prefix).
+export const YQ_VERSION = 'v4.53.2'
+export const YQ_SHA256_AMD64 = 'd56bf5c6819e8e696340c312bd70f849dc1678a7cda9c2ad63eebd906371d56b'
+export const YQ_SHA256_ARM64 = '03061b2a50c7a498de2bbb92d7cb078ce433011f085a4994117c2726be4106ea'
+export const YQ_RELEASE_URL_BASE = 'https://github.com/mikefarah/yq/releases/download'
+
 // cloudflared powers `cloudflare-quick` tunnels. Pinned-version + per-arch
 // SHA256 mirrors the curl-impersonate pattern above: bumping requires updating
 // all three constants in the same commit, and the build fails loudly at
@@ -1177,6 +1215,8 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
 
 ${LAYER_2_5_CURL_IMPERSONATE}
 
+${LAYER_2_6_YQ}
+
 ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
 ${LAYER_4_AGENT_BROWSER_INSTALL}
@@ -1256,6 +1296,8 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
 
 ${LAYER_2_5_CURL_IMPERSONATE}
 
+${LAYER_2_6_YQ}
+
 ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
 ${LAYER_4_AGENT_BROWSER_INSTALL}
@@ -1310,6 +1352,24 @@ RUN ARCH_TARBALL="$(if [ "$TARGETARCH" = "arm64" ]; then echo aarch64-linux-gnu;
  && rm curl-impersonate.tar.gz \\
  && /usr/local/bin/curl_${CURL_IMPERSONATE_PROFILE} --version > /dev/null`
 
+// Layer 2.6: install pinned Mike Farah `yq` (Go) so the explorer/reviewer
+// subagents' advertised `... | yq` pipelines resolve inside the bwrap
+// sandbox. Unconditional like the apt baseline (jq, git): a missing binary
+// is invisible to sandboxed bash, so this is not behind a toggle. Placed
+// after curl-impersonate (curl + ca-certificates from baseline guaranteed
+// present) and before agent-browser so an agent-browser bump doesn't
+// invalidate this layer. See the YQ_* constants above for the bump recipe
+// and the Go-vs-Python `yq` rationale.
+const LAYER_2_6_YQ = `# Layer 2.6 (stable): pinned Mike Farah yq for sandbox-visible YAML pipelines.
+RUN ARCH_BIN="$(if [ "$TARGETARCH" = "arm64" ]; then echo arm64; else echo amd64; fi)" \\
+ && ARCH_SHA="$(if [ "$TARGETARCH" = "arm64" ]; then echo ${YQ_SHA256_ARM64}; else echo ${YQ_SHA256_AMD64}; fi)" \\
+ && cd /tmp \\
+ && curl -fsSL -o yq "${YQ_RELEASE_URL_BASE}/${YQ_VERSION}/yq_linux_\${ARCH_BIN}" \\
+ && echo "\${ARCH_SHA}  yq" | sha256sum -c - \\
+ && chmod +x yq \\
+ && mv yq /usr/local/bin/yq \\
+ && /usr/local/bin/yq --version > /dev/null`
+
 const LAYER_3_AGENT_BROWSER_ARM64_CONFIG = `# Layer 3 (stable, arm64 only): point agent-browser at the apt-installed
 # chromium. Independent of the npm install below so it stays cached across
 # agent-browser version bumps.

package/src/init/github-webhook-install.ts

@@ -57,7 +57,7 @@ export async function installGithubWebhooksEagerly(
 
   try {
     const result = await registerGithubWebhooks({
-      token: () => strategy.token(),
+      token: (repoSlug: string) => strategy.token({ repoSlug }),
       webhookUrl,
       webhookSecret: options.webhookSecret,
       repos: options.repos,
@@ -86,7 +86,6 @@ function authToSecretBlock(auth: GithubInitCredentials['auth']) {
     type: 'app' as const,
     appId: auth.appId,
     privateKey: { value: auth.privateKey },
-    ...(auth.installationId !== undefined ? { installationId: auth.installationId } : {}),
   }
 }