typeclaw 0.17.0 → 0.19.0

package/src/init/index.ts

@@ -94,7 +94,7 @@ export type GithubInitCredentials = {
   hostname?: string
   tokenEnv?: string
   repos: string[]
-  auth: { type: 'pat'; pat: string } | { type: 'app'; appId: number; privateKey: string; installationId?: number }
+  auth: { type: 'pat'; pat: string } | { type: 'app'; appId: number; privateKey: string }
 }
 
 export type GithubTunnelProvider = 'cloudflare-quick' | 'cloudflare-named' | 'external' | 'none'
@@ -998,7 +998,7 @@ export type AddChannelOptions = {
       hostname?: string
       tokenEnv?: string
       repos: string[]
-      auth: { type: 'pat'; pat: string } | { type: 'app'; appId: number; privateKey: string; installationId?: number }
+      auth: { type: 'pat'; pat: string } | { type: 'app'; appId: number; privateKey: string }
       fetchImpl?: typeof fetch
     }
 )
@@ -1263,9 +1263,6 @@ async function writeGithubChannelForInit(cwd: string, credentials: GithubInitCre
             type: 'app',
             appId: credentials.auth.appId,
             privateKey: { value: credentials.auth.privateKey } satisfies Secret,
-            ...(credentials.auth.installationId !== undefined
-              ? { installationId: credentials.auth.installationId }
-              : {}),
           },
     webhookSecret: { value: credentials.webhookSecret } satisfies Secret,
   }
@@ -1298,7 +1295,6 @@ async function appendGithubSecrets(
             type: 'app',
             appId: options.auth.appId,
             privateKey: { value: options.auth.privateKey } satisfies Secret,
-            ...(options.auth.installationId !== undefined ? { installationId: options.auth.installationId } : {}),
           },
     webhookSecret: { value: options.webhookSecret } satisfies Secret,
   }
@@ -1461,13 +1457,13 @@ export async function setChannelSecrets(
 // previous auth type, since the two shapes share no fields beyond `type`).
 export type GithubCredentialPatch = {
   webhookSecret?: string
-  auth?: { type: 'pat'; pat: string } | { type: 'app'; privateKey: string; appId?: number; installationId?: number }
+  auth?: { type: 'pat'; pat: string } | { type: 'app'; privateKey: string; appId?: number }
 }
 
 // Update one or more credential fields on an already-configured GitHub
 // channel. Like setChannelSecrets, refuses when secrets.json has no
 // existing github entry. Supports both same-type rotation (preserves env
-// bindings, carries appId/installationId forward when not supplied) and
+// bindings, carries appId forward when not supplied) and
 // auth-type switching (replaces the entire auth block — see
 // `GithubCredentialPatch` above).
 export async function setGithubSecrets(cwd: string, patch: GithubCredentialPatch): Promise<SetChannelTokensResult> {
@@ -1503,7 +1499,6 @@ export async function setGithubSecrets(cwd: string, patch: GithubCredentialPatch
       } else {
         const existingApp = isSameType && isObjectRecord(existingAuth) ? (existingAuth as Record<string, unknown>) : {}
         const appId = patch.auth.appId ?? (existingApp.appId as number | undefined)
-        const installationId = patch.auth.installationId ?? (existingApp.installationId as number | undefined)
         if (typeof appId !== 'number') {
           return {
             result: {
@@ -1518,7 +1513,6 @@ export async function setGithubSecrets(cwd: string, patch: GithubCredentialPatch
           type: 'app',
           appId,
           privateKey: rotatedSecret(existingApp.privateKey, patch.auth.privateKey),
-          ...(installationId !== undefined ? { installationId } : {}),
         }
       }
     }

package/src/init/validate-api-key.ts

@@ -1,3 +1,4 @@
+import { effectiveBaseUrl } from '@/agent/model-overrides'
 import { KNOWN_PROVIDERS, type KnownProviderId } from '@/config/providers'
 
 const PROVIDER_PROBE: Partial<Record<KnownProviderId, { url: string; authHeader: 'bearer' | 'x-api-key' }>> = {
@@ -8,6 +9,19 @@ const PROVIDER_PROBE: Partial<Record<KnownProviderId, { url: string; authHeader:
   'zai-coding': { url: 'https://api.z.ai/api/coding/paas/v4/models', authHeader: 'bearer' },
 }
 
+// When a base-URL override (ANTHROPIC_BASE_URL / OPENAI_BASE_URL) points at a
+// proxy, probe THAT endpoint — validating against the public API would test the
+// wrong gateway (and may reject a proxy-only credential). The path suffix is
+// whatever the hardcoded default probe URL adds on top of the provider's
+// default baseUrl, so providers with different version-segment conventions
+// (anthropic baseUrl omits `/v1`, openai includes it) each keep their own path.
+function probeUrlFor(providerId: KnownProviderId, defaultUrl: string): string {
+  const defaultBase = KNOWN_PROVIDERS[providerId].baseUrl
+  const base = effectiveBaseUrl(providerId, defaultBase)
+  if (base === undefined) return defaultUrl
+  return `${base}${defaultUrl.slice(defaultBase.length)}`
+}
+
 export type KeyValidationResult =
   | { kind: 'ok' }
   | { kind: 'skipped'; reason: 'no-probe' | 'network-error'; detail?: string }
@@ -36,7 +50,7 @@ export async function validateApiKey(
   }
 
   try {
-    const res = await fetchImpl(probe.url, {
+    const res = await fetchImpl(probeUrlFor(providerId, probe.url), {
       method: 'GET',
       headers,
       signal: AbortSignal.timeout(TIMEOUT_MS),

package/src/plugin/context.ts

@@ -1,3 +1,4 @@
+import type { ResolveGithubTokenForRepo } from '@/channels/github-token-bridge'
 import type { PermissionService } from '@/permissions'
 
 import type { PluginContext, PluginLogger, SpawnSubagentOptions } from './types'
@@ -11,10 +12,16 @@ export type CreatePluginContextOptions<TConfig> = {
   config: TConfig
   logger: PluginLogger
   permissions: PermissionService
+  resolveGithubTokenForRepo?: ResolveGithubTokenForRepo
   spawnSubagent: SpawnSubagentFn
   isBooted: () => boolean
 }
 
+const githubTokenUnavailable: ResolveGithubTokenForRepo = async () => ({
+  kind: 'unavailable',
+  reason: 'GitHub token resolution is not wired in this context.',
+})
+
 export function createPluginContext<TConfig>(opts: CreatePluginContextOptions<TConfig>): PluginContext<TConfig> {
   return Object.freeze({
     name: opts.name,
@@ -23,6 +30,7 @@ export function createPluginContext<TConfig>(opts: CreatePluginContextOptions<TC
     config: opts.config,
     logger: opts.logger,
     permissions: opts.permissions,
+    github: { resolveTokenForRepo: opts.resolveGithubTokenForRepo ?? githubTokenUnavailable },
     spawnSubagent: async (name: string, payload?: unknown, options?: SpawnSubagentOptions) => {
       if (!opts.isBooted()) {
         throw new Error(

package/src/plugin/manager.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 
+import type { ResolveGithubTokenForRepo } from '@/channels/github-token-bridge'
 import type { CronJob } from '@/cron'
 import {
   createPermissionService,
@@ -20,6 +21,7 @@ export type LoadPluginsOptions = {
   configsByName: Record<string, unknown>
   loadEntry?: LoadPluginEntryFn
   roles?: RolesConfig
+  resolveGithubTokenForRepo?: ResolveGithubTokenForRepo
   // Bundled plugins resolved by the runtime (not from typeclaw.json). Loaded
   // before user-declared `entries` so a config block named after a bundled
   // plugin (e.g. "memory") is consumed by the bundled plugin, and so plugin-
@@ -101,6 +103,7 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
       config: validatedConfig as never,
       logger,
       permissions,
+      resolveGithubTokenForRepo: opts.resolveGithubTokenForRepo,
       spawnSubagent: (name, payload, options) => spawnSubagentImpl(name, payload, options),
       isBooted: () => booted,
     })

package/src/plugin/types.ts

@@ -2,6 +2,7 @@ import type { z } from 'zod'
 
 import type { SessionOrigin } from '@/agent/session-origin'
 import type { SubagentShared } from '@/agent/subagents'
+import type { ResolveGithubTokenForRepo } from '@/channels/github-token-bridge'
 import type { PermissionService } from '@/permissions'
 
 export type ContentPart = { type: 'text'; text: string } | { type: 'image'; mimeType: string; data: string }
@@ -273,9 +274,14 @@ export type PluginContext<TConfig = never> = {
   readonly config: TConfig
   readonly logger: PluginLogger
   readonly permissions: PermissionService
+  readonly github: PluginGithubServices
   spawnSubagent: (name: string, payload?: unknown, options?: SpawnSubagentOptions) => Promise<void>
 }
 
+export type PluginGithubServices = {
+  resolveTokenForRepo: ResolveGithubTokenForRepo
+}
+
 export type PluginExports = {
   tools?: Record<string, Tool<any>>
   subagents?: Record<string, Subagent<any>>

package/src/run/bundled-plugins.ts

@@ -1,6 +1,7 @@
 import agentBrowserPlugin from '@/bundled-plugins/agent-browser'
 import backupPlugin from '@/bundled-plugins/backup'
 import explorerPlugin from '@/bundled-plugins/explorer'
+import githubCliAuthPlugin from '@/bundled-plugins/github-cli-auth'
 import guardPlugin from '@/bundled-plugins/guard'
 import memoryPlugin from '@/bundled-plugins/memory'
 import operatorPlugin from '@/bundled-plugins/operator'
@@ -28,6 +29,13 @@ import type { ResolvedPlugin } from '@/plugin'
 // Reversing this order would make guard advise on the full oversized payload
 // and then tool-result-cap would clobber the advice text along with the rest.
 //
+// `github-cli-auth` is registered AFTER `security` so security's `tool.before`
+// runs its exfil/secret scanners on the bash command first. github-cli-auth
+// injects the minted token via an env overlay (TYPECLAW_INTERNAL_BASH_ENV), not
+// by rewriting the command string, so the token never enters argv or logs — but
+// ordering security first still matters so a blocked command never reaches the
+// mint path at all.
+//
 // `memory` is registered before `backup` so memory's dreaming commits always
 // land in the same git index window before backup's commit-and-push cycle.
 // They commit disjoint paths today (memory/ vs sessions/ + agent changes),
@@ -37,6 +45,7 @@ export const BUNDLED_PLUGINS: ResolvedPlugin[] = [
   { name: 'security', version: undefined, source: '<bundled>', defined: securityPlugin },
   { name: 'tool-result-cap', version: undefined, source: '<bundled>', defined: toolResultCapPlugin },
   { name: 'guard', version: undefined, source: '<bundled>', defined: guardPlugin },
+  { name: 'github-cli-auth', version: undefined, source: '<bundled>', defined: githubCliAuthPlugin },
   { name: 'memory', version: undefined, source: '<bundled>', defined: memoryPlugin },
   { name: 'backup', version: undefined, source: '<bundled>', defined: backupPlugin },
   { name: 'agent-browser', version: undefined, source: '<bundled>', defined: agentBrowserPlugin },

package/src/run/index.ts

@@ -19,6 +19,7 @@ import { resolveCapOptionsFromConfig } from '@/bundled-plugins/tool-result-cap'
 import {
   createChannelManager,
   createChannelsReloadable,
+  createGithubTokenBridge,
   createSubagentCompletionBridge,
   type ChannelManager,
   type SubagentCompletionBridge,
@@ -138,11 +139,13 @@ export async function startAgent({
 
   const pluginConfigsByName = loadPluginConfigsSync(cwd)
   const cwdConfig = loadConfigSync(cwd)
+  const githubTokenBridge = createGithubTokenBridge()
   const pluginsLoaded = await loadPlugins({
     entries: cwdConfig.plugins,
     agentDir: cwd,
     configsByName: pluginConfigsByName,
     bundled: BUNDLED_PLUGINS,
+    resolveGithubTokenForRepo: githubTokenBridge.resolveTokenForRepo,
     ...(cwdConfig.roles !== undefined ? { roles: cwdConfig.roles } : {}),
   })
 
@@ -255,6 +258,7 @@ export async function startAgent({
     }),
     permissions: pluginsLoaded.permissions,
     claimHandler: claimController.claimHandler,
+    githubTokenBridge,
     stream,
   })
 
@@ -371,6 +375,7 @@ export async function startAgent({
             runtimeVersion: runtimeVersionOpt.runtimeVersion,
             containerName: containerNameOpt.containerName,
             sessionFactory,
+            channelRouter: channelManager.router,
           }),
         subagent: (subName: string, payload?: unknown) =>
           dispatchSpawnSubagent(subName, payload, {
@@ -585,6 +590,7 @@ export async function startAgent({
       containerName,
       outbound,
       sessionFactory,
+      channelRouter: channelManager.router,
     })
 
   const server = createServer({

package/src/secrets/schema.ts

@@ -49,7 +49,6 @@ const githubAppAuthSchema = z.object({
   type: z.literal('app'),
   appId: z.number().int().positive(),
   privateKey: secretFieldSchema,
-  installationId: z.number().int().positive().optional(),
 })
 
 const githubChannelSchema = z.object({

package/src/server/command-runner.ts

@@ -5,6 +5,7 @@ import {
   type CreateSessionResult,
   type SessionOrigin,
 } from '@/agent'
+import type { ChannelRouter } from '@/channels/router'
 import type { PermissionService } from '@/permissions'
 import type {
   CommandExecResult,
@@ -44,6 +45,14 @@ export type CommandRunnerOptions = {
   // `SessionManager.inMemory()` and never persist usage — see
   // `runPromptForCommand` below.
   sessionFactory: SessionFactory
+  // Channel router threaded into every `ctx.prompt` session so the model can
+  // call `channel_send`. Without this, `buildChannelTools` (src/agent/index.ts)
+  // receives `undefined` and emits no channel tools — a plugin command or cron
+  // handler told to post to a channel then has no tool to do it and falls back
+  // to flailing bash loops. The cron `prompt` path already passes
+  // `channelManager.router` via `createSessionForCron`; this is the matching
+  // wire for the handler/command path.
+  channelRouter: ChannelRouter | undefined
 }
 
 type CommandHandle = {
@@ -182,6 +191,7 @@ export function createCommandRunner(opts: CommandRunnerOptions): CommandRunner {
               permissions: opts.permissions,
               signal: abortController.signal,
               sessionFactory: opts.sessionFactory,
+              channelRouter: opts.channelRouter,
             }),
           subagent: (subName, payload) =>
             opts.spawnSubagent(subName, payload, {
@@ -363,6 +373,9 @@ export async function runPromptForCommand(args: {
   // cron `prompt` path uses in src/run/index.ts. Passing in-memory here
   // regresses `typeclaw usage` (see CommandRunnerOptions.sessionFactory).
   sessionFactory: SessionFactory
+  // See CommandRunnerOptions.channelRouter. Threaded to createSessionWithDispose
+  // so the spawned session exposes `channel_send`.
+  channelRouter?: ChannelRouter
   // Test seam for the agent-session boundary. Production passes the real
   // `createSessionWithDispose`; tests inject a fake to verify wiring
   // (specifically: the sessionManager handed off must be persisted, not
@@ -388,6 +401,7 @@ export async function runPromptForCommand(args: {
       sessionId,
       agentDir: args.agentDir,
     },
+    ...(args.channelRouter !== undefined ? { channelRouter: args.channelRouter } : {}),
     ...(args.runtimeVersion !== undefined ? { runtimeVersion: args.runtimeVersion } : {}),
     ...(args.containerName !== undefined ? { containerName: args.containerName } : {}),
   })

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

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-channel-github
-description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `github`, AND before composing replies to GitHub-originated inbounds, AND before opening new issues or PRs with `gh`, AND ALWAYS when an inbound says "requested your review on PR #N" or "requested a review from team @… on PR #N" (the agent has been assigned as a reviewer and must delegate the analysis to the `reviewer` subagent, then translate its findings into line-by-line comments via `gh api`). GitHub renders **real markdown** — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and `inline code` all render natively. Use rich markdown freely. GitHub cannot send file attachments via API — do not call `channel_send` with attachments on github chats. GitHub has no typing indicator. PR review threads use `thread` keyed on the root comment id; reply to a thread to stay in it, or omit `thread` to post a top-level issue/PR comment. To open new issues or PRs use the `gh` CLI — `GH_TOKEN` is pre-set by the adapter. Read this skill before composing anything on GitHub.
+description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `github`, AND before composing replies to GitHub-originated inbounds, AND before opening new issues or PRs with `gh`, AND ALWAYS when you are asked to review a PR — whether the inbound says "requested your review on PR #N" / "requested a review from team @… on PR #N", or a human asks for a review in plain language in an issue/PR body or comment ("@bot review this", "can you take a look at #123"). On a review request you delegate the analysis to the `reviewer` subagent, which produces line-anchored findings, then you post them as an inline review via `gh api`. GitHub renders **real markdown** — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and `inline code` all render natively. Use rich markdown freely. GitHub cannot send file attachments via API — do not call `channel_send` with attachments on github chats. GitHub has no typing indicator. PR review threads use `thread` keyed on the root comment id; reply to a thread to stay in it, or omit `thread` to post a top-level issue/PR comment. To open new issues or PRs use the `gh` CLI — `GH_TOKEN` is pre-set by the adapter. Read this skill before composing anything on GitHub.
 ---
 
 GitHub renders normal Markdown in issues, PRs, discussions, and review comments. Use headings, lists, tables, fenced code blocks, links, and inline code when they improve clarity.
@@ -13,39 +13,44 @@ GitHub renders normal Markdown in issues, PRs, discussions, and review comments.
 
 A successful `channel_reply` ends your turn by default — the runtime stops the model right after the reply lands. That is correct for a final answer, but it will **silently truncate** a turn that still has work to do. If you post a status line like "Reviewing now, I'll be back with findings" and then expect to keep working (fetch the diff, spawn the reviewer, post the review) in the **same** turn, you must call `channel_reply({ text: "…", continue: true })`. Without `continue: true`, the turn ends at that status reply and the review never runs. Reserve `continue: true` for genuine multi-step turns; the final reply that wraps up the turn omits it.
 
-## Opening new issues and PRs
+## What to do, by inbound type
 
-The `gh` CLI is pre-authenticated via `GH_TOKEN` (injected by the adapter at startup). Use it to open new issues or PRs:
+Every GitHub inbound lands on a `chat` keyed by its subject: `issue:N`, `pr:N`, or `discussion:N`. Pick your action from the kind of thing that arrived. The default action for anything addressed to you is a normal `channel_reply` in that thread; the **PR review flow** below is the one exception that requires delegation.
 
-```sh
-# Open a new issue
-gh issue create --repo owner/repo --title "Bug: ..." --body "..."
+| Inbound                                                  | Looks like                                                                           | What to do                                                                                            |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| **New issue** (`issue:N`)                                | A freshly opened issue body.                                                         | Triage or answer it. `channel_reply` on `issue:N`. Open follow-up issues/PRs with `gh` if needed.     |
+| **Issue comment** (`issue:N`)                            | A comment on an issue.                                                               | Reply in the issue thread with `channel_reply`.                                                       |
+| **PR conversation comment** (`pr:N`, no `thread`)        | A comment on a PR's main conversation (GitHub models PR comments as issue comments). | Reply on the PR with `channel_reply`. **If the text asks you to review → go to the PR review flow.**  |
+| **PR review-thread reply** (`pr:N`, `thread` set)        | A reply on an existing inline review comment thread.                                 | Stay in the thread: `channel_reply` with `thread` kept as-is.                                         |
+| **A submitted review** (`pr:N`)                          | Someone submitted a formal review (approve / changes / comment) on a PR.             | React if a response is warranted (answer a question, acknowledge changes). `channel_reply` on `pr:N`. |
+| **New discussion / discussion comment** (`discussion:N`) | A discussion thread or a comment in one.                                             | Reply with `channel_reply` on `discussion:N`.                                                         |
+| **Review requested** (`pr:N`)                            | See "When you are being asked to review" below.                                      | **PR review flow.**                                                                                   |
 
-# Open a new PR
-gh pr create --repo owner/repo --title "Fix: ..." --head my-branch --base main --body "..."
-```
+### When you are being asked to review
 
-For App auth, `GH_TOKEN` is an installation access token that refreshes automatically — it stays current as long as the adapter is running.
+You are being asked to review a PR in **either** of these cases — treat them identically:
 
-## Reviewing pull requests
+- **(A) An explicit review-request inbound.** The message text says **"requested your review on PR #N"** or **"requested a review from team @… on PR #N"**. (You do not need to know how it was triggered — the adapter synthesizes this same text whether a human requested you as a reviewer directly or requested a decoy user account that impersonates you as a GitHub App. From your side it reads the same. See [GitHub decoy reviewer](/docs/internals/github-decoy-reviewer).)
+- **(B) A human asks you to review in plain language** in a PR/issue body or any comment — "@bot review this PR", "can you take a look at #123", "review the changes when you get a chance". There is no synthetic request text here; you recognize the intent from the message.
 
-When an incoming message says **"requested your review on PR #N"** (or "requested a review from team @… on PR #N"), you have been assigned as a reviewer. Do **not** review inline yourself and do **not** just reply in the channel — delegate the analysis to the bundled `reviewer` subagent, then translate its findings into line-by-line comments via `gh api`.
+Both → run the **PR review flow**. Do not review inline yourself and do not just reply with prose impressions: delegate to the `reviewer` subagent so the analysis runs on the `deep` model, then post its findings as an inline review.
 
-Why delegate: the `reviewer` subagent runs on the `deep` model profile, loads a curated `code-review` skill on demand, and produces a structured `<review>` block with severity-tagged findings. You are the integration layer between that output and GitHub's review API.
+A `review_request_removed` inbound ("removed your review request on PR #N") is the inverse: the requester un-assigned you. Cancel any in-flight reviewer subagent (`subagent_cancel`) and do not post a partial review.
 
-### Workflow
+## PR review flow
 
-1. **Confirm the target.** Capture the PR number, the repo, and the head SHA — you'll need the SHA to read files at the revision the reviewer analyzed.
+The `reviewer` subagent is the analyst; you are the integration layer between its output and GitHub's review API. It loads the `code-review` skill on demand and returns line-anchored findings inside a `<review>` block. Your job is mechanics: spawn, wait, translate, post.
+
+1. **Confirm the target.** Capture the PR number, the repo, and the head SHA — you may need the SHA to read files at the revision the reviewer analyzed.
 
    ```sh
    gh pr view <N> --repo owner/repo --json title,body,baseRefName,headRefOid,files
    ```
 
-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.) so the reviewer knows what the requester cares about.
-
-   If you post an "on it" acknowledgement before fetching the diff or 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).
+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"`.
 
-   The reviewer will fetch the diff itself (`gh pr diff`, `gh api /repos/.../pulls/<n>`), load the matching skill (`code-review` for a code PR; `general` for a mixed-format change), and return a `<review>` block.
+   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).
 
 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:
 
@@ -63,11 +68,11 @@ Why delegate: the `reviewer` subagent runs on the `deep` model profile, loads a
    </review>
    ```
 
-4. **Translate findings into a `gh api` review payload.** Each `<finding>` with `severity` of `blocker`, `concern`, or `nit` and a `location="path:line"` becomes one entry in `comments[]`. Compose the inline `body` from the reviewer's `<issue>` + `<evidence>` + `<suggestion>` — preserve the reviewer's wording, do not paraphrase. Findings whose `location` is `general` (no file:line anchor) go into the top-level review `body` instead. **Skip `praise` findings when building `comments[]`** — they are not actionable, and inline praise comments are exactly the noise the reviewer is supposed to filter out at the source; if you want to surface them, weave them into the top-level review `body` alongside the summary.
+4. **Translate findings into a `gh api` review payload.** Each `<finding>` with `severity` of `blocker`, `concern`, or `nit` and a `location="path:line"` becomes one entry in `comments[]`. Compose the inline `body` from the reviewer's `<issue>` + `<evidence>` + `<suggestion>` verbatim (modulo markdown). Findings whose `location` is `general` (no file:line anchor) go into the top-level review `body` instead. **Skip `praise` findings when building `comments[]`** — if you want to surface them, weave them into the top-level `body`.
 
-   **The verdict and the inline comments are independent. The verdict sets only the `event` field; it never decides whether you post `comments[]`.** Whenever there is at least one actionable finding (`blocker`/`concern`/`nit`) with a `location="path:line"`, you MUST submit a formal review via `POST /pulls/<N>/reviews` carrying those findings in `comments[]` — including when the verdict is `approve`. An `approve` with three nits is still a formal `APPROVE` review with three inline comments, **not** a plain approval and **not** a flattened summary posted as a top-level comment. Collapsing inline findings into a single `channel_reply` or issue comment loses the line anchors the reviewer worked to produce — that is the exact failure mode this step exists to prevent.
+   **The verdict and the inline comments are independent. The verdict sets only the `event` field; it never decides whether you post `comments[]`.** Whenever there is at least one actionable finding (`blocker`/`concern`/`nit`) with a `location="path:line"`, you MUST submit a formal review via `POST /pulls/<N>/reviews` carrying those findings in `comments[]` — including when the verdict is `approve`. An `approve` with three nits is still a formal `APPROVE` review with three inline comments, **not** a plain approval and **not** a flattened summary. Collapsing inline findings into a single `channel_reply` or issue comment loses the line anchors the reviewer worked to produce.
 
-   Map the reviewer's `<verdict>` to the GitHub `event`:
+   Map the reviewer's `<verdict>` to the GitHub `event`, and trust it — do not upgrade `comment` → `APPROVE` to seem agreeable, or downgrade `request-changes` → `COMMENT` to soften the tone:
 
    | Reviewer verdict  | GitHub `event`    |
    | ----------------- | ----------------- |
@@ -75,22 +80,35 @@ Why delegate: the `reviewer` subagent runs on the `deep` model profile, loads a
    | `request-changes` | `REQUEST_CHANGES` |
    | `comment`         | `COMMENT`         |
 
-   Then submit the review in one API call:
+   Then submit the review. **Write the JSON payload to a file with the `write` tool, then run a single bare `gh api --input <file>`** — two steps:
 
-   ```sh
-   cat <<'JSON' | gh api -X POST /repos/owner/repo/pulls/<N>/reviews --input -
+   First write `/tmp/review.json` (via the `write` tool, not bash):
+
+   ```json
    {
      "event": "COMMENT",
      "body": "<reviewer's <summary> goes here>",
      "comments": [
-       { "path": "src/foo.ts", "line": 42, "side": "RIGHT", "body": "<issue + evidence + suggestion from the reviewer's finding>" },
+       {
+         "path": "src/foo.ts",
+         "line": 42,
+         "side": "RIGHT",
+         "body": "<issue + evidence + suggestion from the reviewer's finding>"
+       },
        { "path": "src/bar.ts", "line": 10, "side": "RIGHT", "body": "..." }
      ]
    }
-   JSON
    ```
 
-   **Always use `--input -` with a quoted heredoc (`<<'JSON'`) for review bodies.** Do **not** use `-f body=...` or `-F 'comments[][body]=...'`: those go through shell argument parsing, so backticks (\`) trigger command substitution and have to be backslash-escaped, which leaks the literal `\` into the rendered comment. The quoted heredoc passes the JSON through untouched — backticks, newlines, and `${...}` all survive verbatim. The same applies to any other `gh api` POST whose body contains backticks, embedded newlines, or shell metacharacters.
+   Then post it:
+
+   ```sh
+   gh api -X POST /repos/owner/repo/pulls/<N>/reviews --input /tmp/review.json
+   ```
+
+   **A repo-targeting `gh` command must be a single bare `gh` invocation — no pipes, `;`, `&&`, heredocs, or command substitution.** The `github-cli-auth` plugin injects the GitHub App token into the command's environment, so any sibling/upstream stage in a pipeline would inherit a live token; the runtime blocks those shapes. That is why the old `cat <<'JSON' | gh api --input -` heredoc-pipe no longer works: write the JSON to a file and feed it with `--input <file>` instead. Do **not** use `-f body=...` or `-F 'comments[][body]=...'`: those go through shell argument parsing, so backticks trigger command substitution. The file passes the JSON through untouched — backticks, newlines, and `${...}` all survive verbatim. The same file-then-`--input` pattern applies to any `gh api` POST whose body contains backticks, embedded newlines, or shell metacharacters.
+
+   Anchor mechanics: `line` is a line number **in the file**, not a position in the diff. `side: RIGHT` is the new revision (default for additions); `side: LEFT` is the old revision (use for comments on removed lines). For multi-line comments, also set `start_line` and `start_side` (same semantics). If you need to read whole files at the PR's head SHA to validate an anchor before posting, use `gh api /repos/owner/repo/contents/<path>?ref=<headRefOid>`.
 
 5. **Verify the review actually landed before announcing it.** The `gh api` call can fail silently from the model's perspective — a permission denial, a bad `line` anchor, or a malformed payload returns an error you must not paper over. After submitting, confirm the review exists:
 
@@ -100,23 +118,32 @@ Why delegate: the `reviewer` subagent runs on the `deep` model profile, loads a
 
    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 branches in Rules below already use `channel_reply`/issue comments _as_ the substantive reply.
+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.
+
+### Zero actionable findings
+
+A finding is "actionable" if its severity is `blocker`, `concern`, or `nit`. The inline-review post in step 4 applies whenever the actionable count is **at least one**. When the reviewer returns **exactly zero** actionable findings (only `praise`, or none), there is nothing to anchor inline — handle by verdict:
 
-### Rules
+- `approve` → post a plain `APPROVE` with the `<summary>` as the review body (no `comments[]` array).
+- `comment` → post the summary as a top-level PR comment via `gh api -X POST /repos/.../issues/<N>/comments` instead of submitting an empty review.
+- `request-changes` → submit `REQUEST_CHANGES` with the `<summary>` as the review body and no `comments[]` array. This combination is rare (the reviewer's contract says `request-changes` requires at least one blocker or load-bearing concern); if it happens, faithfully encode the verdict and trust the reviewer's reasoning is in the summary.
 
-- **Always delegate to the `reviewer` subagent.** Do not perform the review craft yourself. The reviewer is the source of truth for severity, evidence quality, and what counts as a finding. Your job is mechanics: spawn, wait, translate, post.
-- **Trust the verdict.** Use the GitHub `event` mapped from the reviewer's `<verdict>`. Do not upgrade `comment` → `APPROVE` to seem agreeable, and do not downgrade `request-changes` → `COMMENT` to soften the tone. The reviewer chose deliberately.
-- **No actionable findings → no inline review post.** A finding is "actionable" if its severity is `blocker`, `concern`, or `nit`. This branch applies **only when the actionable count is exactly zero** — if there is even one actionable finding with a line anchor, follow step 4 and submit a formal review with `comments[]` regardless of verdict. When the reviewer returns zero actionable findings:
-  - `approve` verdict → post a plain `APPROVE` with the `<summary>` as the review body (no `comments[]` array).
-  - `comment` verdict → post the summary as a top-level PR comment via `gh api -X POST /repos/.../issues/<N>/comments` instead of submitting an empty review.
-  - `request-changes` verdict → submit `REQUEST_CHANGES` with the `<summary>` as the review body and no `comments[]` array. This combination is rare (the reviewer's contract says `request-changes` requires at least one blocker or load-bearing concern), so if it happens, faithfully encode the verdict and trust the reviewer's reasoning is in the summary.
-- **Preserve the reviewer's wording.** Inline comment bodies should reflect the reviewer's `<issue>`, `<evidence>`, and `<suggestion>` verbatim (modulo markdown formatting). Paraphrasing dilutes the analysis — the deep-model reviewer chose those words on purpose.
-- `line` is a line number **in the file**, not a position in the diff. `side: RIGHT` is the new revision (default for additions); `side: LEFT` is the old revision (use for comments on removed lines).
-- For multi-line comments, also set `start_line` and `start_side` (same semantics).
-- If you need to read whole files at the PR's head SHA, use `gh api /repos/owner/repo/contents/<path>?ref=<headRefOid>`. The reviewer can do this itself, but you may need to as well — e.g., when validating a finding's `location` against the actual file before posting.
-- The bundled `agent-browser` is **not** for PR reviews — `gh api` is faster and more reliable. Only use the browser when the API genuinely can't reach what you need.
-- A `review_request_removed` event means the requester un-assigned you. Cancel any in-flight reviewer subagent (`subagent_cancel`) and do not post a partial review.
+The bundled `agent-browser` is **not** for PR reviews — `gh api` is faster and more reliable. Only use the browser when the API genuinely can't reach what you need.
+
+## Opening new issues and PRs
+
+The `gh` CLI is pre-authenticated via `GH_TOKEN` (injected by the adapter at startup). Use it to open new issues or PRs:
+
+```sh
+# Open a new issue
+gh issue create --repo owner/repo --title "Bug: ..." --body "..."
+
+# Open a new PR
+gh pr create --repo owner/repo --title "Fix: ..." --head my-branch --base main --body "..."
+```
+
+For App auth, `GH_TOKEN` is an installation access token that refreshes automatically — it stays current as long as the adapter is running.
 
-### Self-loop safety
+## 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.