From bf171362a650bc0bfe36e809aea15747227bb284 Mon Sep 17 00:00:00 2001
From: Hugo Richard <hugo.richard@vercel.com>
Date: Wed, 26 Aug 2026 09:54:12 +0100
Subject: [PATCH 1/2] feat(sdk): attach rate-limit metadata on object-shaped
 tool results

Capture x-ratelimit headers on the Octokit client so hooks and the chat UI can read remaining quota, while toModelOutput strips the field from the model.
---
 .changeset/rate-limit-on-results.md           |   5 +
 apps/chat/app/components/tool/Github.vue      |  34 +++++
 .../docs/2.frameworks/1.eve-extension.md      |   2 +
 apps/docs/content/docs/5.api/2.reference.md   |  12 ++
 apps/docs/skills/github-tools-agents/SKILL.md |   2 +-
 .../references/eve-extension.md               |   2 +-
 packages/github-tools-eve-extension/README.md |   2 +-
 .../extension/tools/github.ts                 |   5 +-
 packages/github-tools/README.md               |  12 ++
 packages/github-tools/src/client.test.ts      |  62 +++++++++
 packages/github-tools/src/client.ts           |  29 ++++
 packages/github-tools/src/core/bundles.ts     |  17 +--
 packages/github-tools/src/core/checks.ts      |   8 +-
 packages/github-tools/src/core/commits.ts     |  14 +-
 packages/github-tools/src/core/discussions.ts |  11 +-
 packages/github-tools/src/core/gists.ts       |  23 ++--
 packages/github-tools/src/core/issues.ts      |  53 +++++---
 .../github-tools/src/core/notifications.ts    |   8 +-
 .../github-tools/src/core/pull-requests.ts    |  38 ++++--
 .../github-tools/src/core/rate-limit.test.ts  |  97 ++++++++++++++
 packages/github-tools/src/core/rate-limit.ts  | 126 ++++++++++++++++++
 packages/github-tools/src/core/reactions.ts   |  14 +-
 packages/github-tools/src/core/releases.ts    |  20 ++-
 packages/github-tools/src/core/repository.ts  |  26 ++--
 packages/github-tools/src/core/search.ts      |  11 +-
 packages/github-tools/src/core/workflows.ts   |  23 ++--
 packages/github-tools/src/eve-runtime.ts      |   1 +
 packages/github-tools/src/eve/build.test.ts   |  30 +++++
 packages/github-tools/src/eve/build.ts        |   4 +-
 packages/github-tools/src/eve/registry.ts     |   8 +-
 packages/github-tools/src/index.ts            |  22 ++-
 31 files changed, 614 insertions(+), 107 deletions(-)
 create mode 100644 .changeset/rate-limit-on-results.md
 create mode 100644 packages/github-tools/src/core/rate-limit.test.ts
 create mode 100644 packages/github-tools/src/core/rate-limit.ts

diff --git a/.changeset/rate-limit-on-results.md b/.changeset/rate-limit-on-results.md
new file mode 100644
index 0000000..2d57f66
--- /dev/null
+++ b/.changeset/rate-limit-on-results.md
@@ -0,0 +1,5 @@
+---
+'@github-tools/sdk': minor
+---
+
+Object-shaped tool results now include `rateLimit` (`remaining`, `limit`, `reset`, `resource`) from the last GitHub response. The field is stripped before the model sees the output. Array-shaped list tools are unchanged. 403/429 errors include remaining/reset in the message.
diff --git a/apps/chat/app/components/tool/Github.vue b/apps/chat/app/components/tool/Github.vue
index 04f1912..e3e5af6 100644
--- a/apps/chat/app/components/tool/Github.vue
+++ b/apps/chat/app/components/tool/Github.vue
@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import type { GithubRateLimit } from '@github-tools/sdk'
 import { GITHUB_TOOL_META } from '#shared/utils/tools/github'
 import type { GithubToolName, GithubUIToolInvocation } from '#shared/utils/tools/github'
 
@@ -41,6 +42,38 @@ const context = computed(() => {
   if (input.path) return String(input.path)
   return null
 })
+
+const rateLimit = computed(() => readRateLimit(props.invocation.output))
+
+const rateLimitLabel = computed(() => {
+  const value = rateLimit.value
+  if (!value) return null
+  const counts = `${value.remaining}/${value.limit}`
+  return value.resource && value.resource !== 'core' ? `${value.resource} ${counts}` : counts
+})
+
+const rateLimitTitle = computed(() => {
+  const value = rateLimit.value
+  if (!value) return undefined
+  return `Resets ${new Date(value.reset * 1000).toISOString()}`
+})
+
+function readRateLimit(output: unknown): GithubRateLimit | null {
+  if (output == null || typeof output !== 'object' || Array.isArray(output)) return null
+  const value = (output as { rateLimit?: unknown }).rateLimit
+  if (value == null || typeof value !== 'object') return null
+  const remaining = (value as GithubRateLimit).remaining
+  const limit = (value as GithubRateLimit).limit
+  const reset = (value as GithubRateLimit).reset
+  if (typeof remaining !== 'number' || typeof limit !== 'number' || typeof reset !== 'number') return null
+  const resource = (value as GithubRateLimit).resource
+  return {
+    remaining,
+    limit,
+    reset,
+    ...typeof resource === 'string' ? { resource } : {}
+  }
+}
 </script>
 
 <template>
@@ -48,6 +81,7 @@ const context = computed(() => {
     <UIcon :name="meta.icon" class="size-3 shrink-0 text-muted" />
     <span class="text-default/70 font-medium">{{ label }}</span>
     <span v-if="context" class="text-muted font-mono">{{ context }}</span>
+    <span v-if="rateLimitLabel" class="text-muted font-mono" :title="rateLimitTitle">{{ rateLimitLabel }}</span>
     <UIcon v-if="isRunning" name="i-lucide-loader-circle" class="size-3 shrink-0 text-muted animate-spin" />
     <UIcon v-else-if="isDone" name="i-lucide-check" class="size-3 shrink-0 text-success/60" />
     <UIcon v-else-if="isDenied" name="i-lucide-ban" class="size-3 shrink-0 text-warning/60" />
diff --git a/apps/docs/content/docs/2.frameworks/1.eve-extension.md b/apps/docs/content/docs/2.frameworks/1.eve-extension.md
index 4dd504d..2d87cec 100644
--- a/apps/docs/content/docs/2.frameworks/1.eve-extension.md
+++ b/apps/docs/content/docs/2.frameworks/1.eve-extension.md
@@ -210,6 +210,8 @@ export default githubExtension({
 
 The extension registers each tool with an **authored inline** `execute` and `toModelOutput` that only close over a serializable tool `name`, then rebuilds session options from the extension config on every call via `@github-tools/sdk/eve-runtime`. Tools resolve on `step.started` so registration stays fresh across durable steps. That pattern survives multi-turn eve Workflow replay (see [#51](https://github.com/vercel-labs/github-tools/issues/51), [#99](https://github.com/vercel-labs/github-tools/issues/99)). Prefer this mount over the deprecated [`createGithubTools`](/deprecated/eve) / [`connectGithubTools`](/deprecated/eve) paths for Slack / multi-turn durable agents — those register tools from inside `node_modules` and are skipped on replay. Author `overrides.toModelOutput` inline in the agent; a function imported from a library will not get a durable descriptor.
 
+Object-shaped execute results include `rateLimit` (`remaining`, `limit`, `reset`, `resource`). `toModelOutput` strips it so the model never sees the remaining count; `toolResultFrom` and channels still do. See [Rate-limit metadata](/api/reference#rate-limit-metadata).
+
 ## Durable approval, done right
 
 Approval **pauses the session durably** until a human responds, and policies are expressive:
diff --git a/apps/docs/content/docs/5.api/2.reference.md b/apps/docs/content/docs/5.api/2.reference.md
index a056c4e..9529002 100644
--- a/apps/docs/content/docs/5.api/2.reference.md
+++ b/apps/docs/content/docs/5.api/2.reference.md
@@ -156,6 +156,18 @@ Supported override properties:
 
 Core properties (`execute`, `inputSchema`, `outputSchema`) cannot be overridden.
 
+### Rate-limit metadata
+
+Object-shaped tool results include a `rateLimit` field from the last GitHub response (`x-ratelimit-remaining`, `x-ratelimit-limit`, `x-ratelimit-reset`, `x-ratelimit-resource`, and `retry-after` when present). Array-shaped results (`listIssues`, `listPullRequests`, …) are unchanged. The field is stripped before the model sees the output (`toModelOutput`); hooks, channels, and the chat UI still receive it.
+
+```ts [rate-limit.ts]
+import type { GithubRateLimit } from '@github-tools/sdk'
+
+const remaining = (result as { rateLimit?: GithubRateLimit }).rateLimit?.remaining
+```
+
+`resource` is `core`, `search`, or `graphql` — search is the tightest bucket. On HTTP 403/429 the thrown error message also includes remaining/reset.
+
 ### Commit attribution
 
 The `author`, `committer`, and `coAuthors` options control how commits are attributed when using `createOrUpdateFile` or `mergePullRequest`:
diff --git a/apps/docs/skills/github-tools-agents/SKILL.md b/apps/docs/skills/github-tools-agents/SKILL.md
index 19561b0..4fd769a 100644
--- a/apps/docs/skills/github-tools-agents/SKILL.md
+++ b/apps/docs/skills/github-tools-agents/SKILL.md
@@ -125,7 +125,7 @@ Array presets merge: `preset: ['code-review', 'issue-triage']`. Start with the s
 
 ## Working context
 
-Pass `context: { owner, repo, pullNumber?, issueNumber?, ref? }` to `createGithubTools` / `createGithubAgent` / `createDurableGithubAgent` to default those fields on tool inputs and inject them into the agent system prompt. Prefer composite tools (`getPullRequestContext`, `getIssueContext`, `getReleaseContext`, `getCiFailureContext`) for multi-part reads — call follow-up reads in the same step when possible. Diff patches are omitted by default — set `includePatch: true` (optionally with `filenames`) when you need specific diffs. Bodies are truncated by default (`detail: 'summary'`). `getIssueContext` returns `labelNames` (strings) rather than full label objects. Prefer `getFileContent` with `startLine`/`endLine` or `maxLines` for large files.
+Pass `context: { owner, repo, pullNumber?, issueNumber?, ref? }` to `createGithubTools` / `createGithubAgent` / `createDurableGithubAgent` to default those fields on tool inputs and inject them into the agent system prompt. Prefer composite tools (`getPullRequestContext`, `getIssueContext`, `getReleaseContext`, `getCiFailureContext`) for multi-part reads — call follow-up reads in the same step when possible. Diff patches are omitted by default — set `includePatch: true` (optionally with `filenames`) when you need specific diffs. Bodies are truncated by default (`detail: 'summary'`). `getIssueContext` returns `labelNames` (strings) rather than full label objects. Prefer `getFileContent` with `startLine`/`endLine` or `maxLines` for large files. Object-shaped execute results include `rateLimit` (`remaining` / `limit` / `reset` / `resource`); it is stripped from the model-facing output. Array-shaped list tools do not carry it. On 403/429 the error text includes remaining/reset.
 
 ## Write safety
 
diff --git a/apps/docs/skills/github-tools-agents/references/eve-extension.md b/apps/docs/skills/github-tools-agents/references/eve-extension.md
index f322bf2..e95309f 100644
--- a/apps/docs/skills/github-tools-agents/references/eve-extension.md
+++ b/apps/docs/skills/github-tools-agents/references/eve-extension.md
@@ -55,7 +55,7 @@ export default githubExtension({
 })
 ```
 
-Built-in `toModelOutput` formatters are applied via an inline callback that only closes over the tool name. Author `overrides.toModelOutput` inline in the agent — a library function will not get a durable descriptor on eve 0.44+.
+Built-in `toModelOutput` formatters are applied via an inline callback that only closes over the tool name. That callback also strips `rateLimit` from the model-facing payload. Author `overrides.toModelOutput` inline in the agent — a library function will not get a durable descriptor on eve 0.44+.
 
 ## Approval
 
diff --git a/packages/github-tools-eve-extension/README.md b/packages/github-tools-eve-extension/README.md
index bd21b21..45c08b2 100644
--- a/packages/github-tools-eve-extension/README.md
+++ b/packages/github-tools-eve-extension/README.md
@@ -43,7 +43,7 @@ export default githubExtension({
 
 > `code-review` pairs cleanly with a Connect `connector`. `maintainer` and `repo-explorer` include gist tools, and GitHub only grants gist access to user access tokens, never the installation tokens Connect mints, so gist calls 403 over Connect. Write tools already require approval via `always()` by default, so a plain `{ someTool: true }` is a no-op, use a predicate (as above) when you actually want to narrow or loosen the default.
 
-Tools are registered with **inline** `execute` and `toModelOutput` handlers in the extension package so they survive multi-turn durable eve Workflow replay (see [#51](https://github.com/vercel-labs/github-tools/issues/51), [#99](https://github.com/vercel-labs/github-tools/issues/99)). Do not use the deprecated `@github-tools/sdk/connect/eve` one-liner for durable Slack/multi-turn agents.
+Tools are registered with **inline** `execute` and `toModelOutput` handlers in the extension package so they survive multi-turn durable eve Workflow replay (see [#51](https://github.com/vercel-labs/github-tools/issues/51), [#99](https://github.com/vercel-labs/github-tools/issues/99)). `toModelOutput` strips `rateLimit` from the model-facing payload; the execute result still carries it for hooks and channels. Do not use the deprecated `@github-tools/sdk/connect/eve` one-liner for durable Slack/multi-turn agents.
 
 `connector` also accepts a `() => string | Promise<string>` resolver, so the same config can pick a connector dynamically (e.g. by environment):
 
diff --git a/packages/github-tools-eve-extension/extension/tools/github.ts b/packages/github-tools-eve-extension/extension/tools/github.ts
index 49edcd9..79c9952 100644
--- a/packages/github-tools-eve-extension/extension/tools/github.ts
+++ b/packages/github-tools-eve-extension/extension/tools/github.ts
@@ -2,7 +2,6 @@ import { connectGithubToken } from '@github-tools/sdk/connect'
 import {
   executeGithubEveTool,
   formatGithubEveToolOutput,
-  hasGithubEveToolModelOutput,
   isEveApprovalDisabled,
   listEveToolDescriptors,
   mapEveApprovalValue,
@@ -113,9 +112,7 @@ export default defineDynamic({
           }),
           ...(override?.toModelOutput !== undefined
             ? { toModelOutput: override.toModelOutput }
-            : hasGithubEveToolModelOutput(name)
-              ? { toModelOutput: (output: unknown) => formatGithubEveToolOutput(name, output) }
-              : {}),
+            : { toModelOutput: (output: unknown) => formatGithubEveToolOutput(name, output) }),
           ...(override?.outputSchema !== undefined && {
             outputSchema: override.outputSchema,
           }),
diff --git a/packages/github-tools/README.md b/packages/github-tools/README.md
index 6aeab93..b2c8ec6 100644
--- a/packages/github-tools/README.md
+++ b/packages/github-tools/README.md
@@ -186,6 +186,18 @@ Supported override properties:
 
 Core properties (`execute`, `inputSchema`, `outputSchema`) cannot be overridden.
 
+## Rate-limit metadata
+
+Object-shaped tool results include a `rateLimit` field from the last GitHub response. Array-shaped results are unchanged. The field is stripped before the model sees the output; hooks, channels, and UIs still receive it.
+
+```ts
+import type { GithubRateLimit } from '@github-tools/sdk'
+
+result.rateLimit?.remaining
+```
+
+`resource` is `core`, `search`, or `graphql`. On HTTP 403/429 the thrown error message also includes remaining/reset.
+
 ## Commit Attribution
 
 Control how commits are attributed when using `createOrUpdateFile` or `mergePullRequest`:
diff --git a/packages/github-tools/src/client.test.ts b/packages/github-tools/src/client.test.ts
index f1db221..17ef719 100644
--- a/packages/github-tools/src/client.test.ts
+++ b/packages/github-tools/src/client.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { GITHUB_API_VERSION, createOctokit } from './client'
+import { finishGithubResult, peekGithubRateLimit } from './core/rate-limit'
 
 describe('createOctokit', () => {
   it('sets X-GitHub-Api-Version on REST requests', async () => {
@@ -27,4 +28,65 @@ describe('createOctokit', () => {
 
     expect(seen.at(-1)).toBe(GITHUB_API_VERSION)
   })
+
+  it('records rate-limit headers on a successful request', async () => {
+    const octokit = createOctokit('ghp_test')
+    octokit.request = octokit.request.defaults({
+      request: {
+        fetch: async () => new Response(JSON.stringify({
+          resources: { core: { limit: 5000, remaining: 38, reset: 1774800000, used: 0 } },
+          rate: { limit: 5000, remaining: 38, reset: 1774800000, used: 0 },
+        }), {
+          status: 200,
+          headers: {
+            'content-type': 'application/json',
+            'x-ratelimit-limit': '5000',
+            'x-ratelimit-remaining': '38',
+            'x-ratelimit-reset': '1774800000',
+            'x-ratelimit-resource': 'core',
+          },
+        }),
+      },
+    })
+
+    await octokit.rest.rateLimit.get()
+
+    expect(peekGithubRateLimit(octokit)).toEqual({
+      remaining: 38,
+      limit: 5000,
+      reset: 1774800000,
+      resource: 'core',
+    })
+    expect(finishGithubResult(octokit, { ok: true })).toEqual({
+      ok: true,
+      rateLimit: {
+        remaining: 38,
+        limit: 5000,
+        reset: 1774800000,
+        resource: 'core',
+      },
+    })
+  })
+
+  it('appends rate-limit state on a 403', async () => {
+    const octokit = createOctokit('ghp_test')
+    octokit.request = octokit.request.defaults({
+      request: {
+        fetch: async () => new Response(JSON.stringify({ message: 'API rate limit exceeded' }), {
+          status: 403,
+          headers: {
+            'content-type': 'application/json',
+            'x-ratelimit-limit': '30',
+            'x-ratelimit-remaining': '0',
+            'x-ratelimit-reset': '1774800000',
+            'x-ratelimit-resource': 'search',
+          },
+        }),
+      },
+    })
+
+    await expect(octokit.rest.search.code({ q: 'test' })).rejects.toThrow(
+      'GitHub rate limit search: 0/30 remaining, resets at 1774800000',
+    )
+  })
 })
diff --git a/packages/github-tools/src/client.ts b/packages/github-tools/src/client.ts
index 1f4e178..2b8833c 100644
--- a/packages/github-tools/src/client.ts
+++ b/packages/github-tools/src/client.ts
@@ -1,8 +1,20 @@
 import { Octokit } from 'octokit'
+import {
+  enrichGithubRateLimitError,
+  finishGithubResult,
+  parseGithubRateLimit,
+  recordGithubRateLimit,
+} from './core/rate-limit'
 
 /** @see https://docs.github.com/en/rest/about-the-rest-api/api-versions */
 export const GITHUB_API_VERSION = '2026-03-10'
 
+function errorResponseHeaders(error: unknown): Record<string, unknown> | undefined {
+  if (error == null || typeof error !== 'object' || !('response' in error)) return undefined
+  const response = (error as { response?: { headers?: Record<string, unknown> } }).response
+  return response?.headers
+}
+
 export function createOctokit(token: string): Octokit {
   const octokit = new Octokit({ auth: token })
 
@@ -13,5 +25,22 @@ export function createOctokit(token: string): Octokit {
     }
   })
 
+  octokit.hook.after('request', (response) => {
+    recordGithubRateLimit(octokit, response.headers)
+  })
+
+  octokit.hook.error('request', (error) => {
+    const rateLimit = parseGithubRateLimit(errorResponseHeaders(error))
+    if (rateLimit) recordGithubRateLimit(octokit, errorResponseHeaders(error))
+    throw enrichGithubRateLimitError(error, rateLimit)
+  })
+
   return octokit
 }
+
+/** Run a GitHub `*Core` body and attach `rateLimit` from this Octokit instance. */
+export async function withOctokit<T>(token: string, fn: (octokit: Octokit) => Promise<T>): Promise<T> {
+  const octokit = createOctokit(token)
+  const result = await fn(octokit)
+  return finishGithubResult(octokit, result)
+}
diff --git a/packages/github-tools/src/core/bundles.ts b/packages/github-tools/src/core/bundles.ts
index fe5744d..23dbc6f 100644
--- a/packages/github-tools/src/core/bundles.ts
+++ b/packages/github-tools/src/core/bundles.ts
@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { withComposedRateLimit } from './rate-limit'
 import { getCombinedStatusCore, listCheckRunsCore } from './checks'
 import { compareCommitsCore } from './commits'
 import { detailSchema, type DetailLevel } from './detail'
@@ -77,12 +78,12 @@ export async function getPullRequestContextCore({
       : Promise.resolve(undefined),
   ])
 
-  return {
+  return withComposedRateLimit({
     pullRequest,
     ...files !== undefined ? { files } : {},
     ...reviews !== undefined ? { reviews } : {},
     ...checks !== undefined ? { checks } : {},
-  }
+  })
 }
 
 export const getIssueContextInputSchema = z.object({
@@ -139,12 +140,12 @@ export async function getIssueContextCore({
       : Promise.resolve(undefined),
   ])
 
-  return {
+  return withComposedRateLimit({
     issue,
     // Names only — full label objects (color/description) dominate triage payloads on large repos
     ...labels !== undefined ? { labelNames: labels.map(label => label.name) } : {},
     ...comments !== undefined ? { comments } : {},
-  }
+  })
 }
 
 export const getReleaseContextInputSchema = z.object({
@@ -204,11 +205,11 @@ export async function getReleaseContextCore({
     })
   }
 
-  return {
+  return withComposedRateLimit({
     release,
     ...previous !== undefined ? { previousRelease: previous } : {},
     ...comparison !== undefined ? { comparison } : {},
-  }
+  })
 }
 
 export const getCiFailureContextInputSchema = z.object({
@@ -311,12 +312,12 @@ export async function getCiFailureContextCore({
     latestFailure = { run: latestFailedRun, jobs: failedJobs }
   }
 
-  return {
+  return withComposedRateLimit({
     ref,
     combinedStatus,
     failedCheckRuns,
     checkRunTotalCount: checkRunsResult.totalCount,
     recentFailedRuns: failedRuns.runs,
     ...latestFailure !== undefined ? { latestFailure } : {},
-  }
+  })
 }
diff --git a/packages/github-tools/src/core/checks.ts b/packages/github-tools/src/core/checks.ts
index 2ca5fc7..b9a5c74 100644
--- a/packages/github-tools/src/core/checks.ts
+++ b/packages/github-tools/src/core/checks.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { createOctokit } from '../client'
+import { withOctokit } from '../client'
 import { fetchAllPages, maxPagesSchema } from './pagination'
 
 export const listCheckRunsInputSchema = z.object({
@@ -13,7 +13,7 @@ export const listCheckRunsInputSchema = z.object({
 export const listCheckRunsDescription = 'List check runs (Checks API — GitHub Actions and other CI providers) for a commit, branch, or tag'
 
 export async function listCheckRunsCore({ token, owner, repo, ref, perPage, maxPages }: { token: string, owner: string, repo: string, ref: string, perPage: number, maxPages?: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   let totalCount = 0
   const checkRuns = await fetchAllPages(async page => {
     const { data } = await octokit.rest.checks.listForRef({ owner, repo, ref, per_page: perPage, page })
@@ -32,6 +32,7 @@ export async function listCheckRunsCore({ token, owner, repo, ref, perPage, maxP
       completedAt: run.completed_at,
     })),
   }
+  })
 }
 
 export const getCombinedStatusInputSchema = z.object({
@@ -43,7 +44,7 @@ export const getCombinedStatusInputSchema = z.object({
 export const getCombinedStatusDescription = 'Get the combined commit status (Statuses API — legacy CI integrations) for a commit, branch, or tag'
 
 export async function getCombinedStatusCore({ token, owner, repo, ref }: { token: string, owner: string, repo: string, ref: string }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.repos.getCombinedStatusForRef({ owner, repo, ref })
   return {
     state: data.state,
@@ -55,4 +56,5 @@ export async function getCombinedStatusCore({ token, owner, repo, ref }: { token
       url: status.target_url,
     })),
   }
+  })
 }
diff --git a/packages/github-tools/src/core/commits.ts b/packages/github-tools/src/core/commits.ts
index 309fa5f..a7c399e 100644
--- a/packages/github-tools/src/core/commits.ts
+++ b/packages/github-tools/src/core/commits.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { createOctokit } from '../client'
+import { withOctokit } from '../client'
 import { fetchAllPages, maxPagesSchema } from './pagination'
 
 export const BLAME_QUERY = `
@@ -78,7 +78,7 @@ export const listCommitsDescription =
   'List commits for a GitHub repository. Filter by file path to see commits that touched a file. For line-by-line attribution at a given ref, use getBlame instead.'
 
 export async function listCommitsCore({ token, owner, repo, path, sha, author, since, until, perPage, maxPages }: { token: string, owner: string, repo: string, path?: string, sha?: string, author?: string, since?: string, until?: string, perPage: number, maxPages?: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const commits = await fetchAllPages(async page => {
     const { data } = await octokit.rest.repos.listCommits({
       owner,
@@ -101,6 +101,7 @@ export async function listCommitsCore({ token, owner, repo, path, sha, author, s
     date: commit.commit.author?.date,
     url: commit.html_url,
   }))
+  })
 }
 
 export const getCommitInputSchema = z.object({
@@ -113,7 +114,7 @@ export const getCommitInputSchema = z.object({
 export const getCommitDescription = 'Get detailed information about a specific commit, including the list of files changed with additions and deletions. Patches are omitted by default — set includePatch true to include diffs'
 
 export async function getCommitCore({ token, owner, repo, ref, includePatch }: { token: string, owner: string, repo: string, ref: string, includePatch: boolean }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.repos.getCommit({ owner, repo, ref })
   return {
     sha: data.sha,
@@ -135,6 +136,7 @@ export async function getCommitCore({ token, owner, repo, ref, includePatch }: {
       ...includePatch && file.patch != null ? { patch: file.patch } : {},
     })),
   }
+  })
 }
 
 export const getBlameInputSchema = z.object({
@@ -169,7 +171,7 @@ export const getBlameDescription =
   'Line-level git blame for a file at a commit-like ref (branch, tag, or SHA). Returns contiguous ranges mapping lines to the commits that last modified them — use this to see who introduced a line and when (GitHub GraphQL API).'
 
 export async function getBlameCore({ token, owner, repo, path, ref, line, lineStart, lineEnd }: { token: string, owner: string, repo: string, path: string, ref?: string, line?: number, lineStart?: number, lineEnd?: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   let expression = ref
   if (!expression) {
     const { data } = await octokit.rest.repos.get({ owner, repo })
@@ -226,6 +228,7 @@ export async function getBlameCore({ token, owner, repo, path, ref, line, lineSt
     rangeCount: ranges.length,
     ranges,
   }
+  })
 }
 
 export const compareCommitsInputSchema = z.object({
@@ -239,7 +242,7 @@ export const compareCommitsInputSchema = z.object({
 export const compareCommitsDescription = 'Compare two branches, tags, or commits — shows ahead/behind counts, the commits in between, and the files that differ. Patches are omitted by default — set includePatch true to include diffs'
 
 export async function compareCommitsCore({ token, owner, repo, base, head, includePatch }: { token: string, owner: string, repo: string, base: string, head: string, includePatch: boolean }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.repos.compareCommitsWithBasehead({ owner, repo, basehead: `${base}...${head}` })
   return {
     status: data.status,
@@ -261,4 +264,5 @@ export async function compareCommitsCore({ token, owner, repo, base, head, inclu
       ...includePatch && file.patch != null ? { patch: file.patch } : {},
     })),
   }
+  })
 }
diff --git a/packages/github-tools/src/core/discussions.ts b/packages/github-tools/src/core/discussions.ts
index 21d1ee7..1ab2cbc 100644
--- a/packages/github-tools/src/core/discussions.ts
+++ b/packages/github-tools/src/core/discussions.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { createOctokit } from '../client'
+import { withOctokit } from '../client'
 import { applyDetailBody, detailSchema, type DetailLevel } from './detail'
 import type { Octokit } from '../types'
 
@@ -163,7 +163,7 @@ export const listDiscussionsInputSchema = z.object({
 export const listDiscussionsDescription = 'List discussions in a GitHub repository, most recently updated first, optionally filtered by category (GitHub GraphQL API)'
 
 export async function listDiscussionsCore({ token, owner, repo, category, perPage, after }: { token: string, owner: string, repo: string, category?: string, perPage: number, after?: string }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
 
   let categoryId: string | undefined
   if (category) {
@@ -198,6 +198,7 @@ export async function listDiscussionsCore({ token, owner, repo, category, perPag
       updatedAt: node.updatedAt,
     })),
   }
+  })
 }
 
 export const getDiscussionInputSchema = z.object({
@@ -210,7 +211,7 @@ export const getDiscussionInputSchema = z.object({
 export const getDiscussionDescription = 'Get a GitHub discussion by number. Body is truncated by default (detail: summary) — set detail full for the complete text (GitHub GraphQL API)'
 
 export async function getDiscussionCore({ token, owner, repo, discussionNumber, detail = 'summary' }: { token: string, owner: string, repo: string, discussionNumber: number, detail?: DetailLevel }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const data = (await octokit.graphql(GET_DISCUSSION_QUERY, {
     owner,
     name: repo,
@@ -233,6 +234,7 @@ export async function getDiscussionCore({ token, owner, repo, discussionNumber,
     createdAt: discussion.createdAt,
     updatedAt: discussion.updatedAt,
   }
+  })
 }
 
 export const addDiscussionCommentInputSchema = z.object({
@@ -246,7 +248,7 @@ export const addDiscussionCommentDescription = 'Add a comment to a GitHub discus
 
 /** Not idempotent — each call adds another comment. */
 export async function addDiscussionCommentCore({ token, owner, repo, discussionNumber, body }: { token: string, owner: string, repo: string, discussionNumber: number, body: string }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const lookup = (await octokit.graphql(DISCUSSION_ID_QUERY, {
     owner,
     name: repo,
@@ -269,4 +271,5 @@ export async function addDiscussionCommentCore({ token, owner, repo, discussionN
     author: comment.author?.login ?? null,
     createdAt: comment.createdAt,
   }
+  })
 }
diff --git a/packages/github-tools/src/core/gists.ts b/packages/github-tools/src/core/gists.ts
index 3e20d0c..669e21c 100644
--- a/packages/github-tools/src/core/gists.ts
+++ b/packages/github-tools/src/core/gists.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { createOctokit } from '../client'
+import { withOctokit } from '../client'
 
 export const listGistsInputSchema = z.object({
   username: z.string().optional().describe('GitHub username — omit to list your own gists'),
@@ -10,7 +10,7 @@ export const listGistsInputSchema = z.object({
 export const listGistsDescription = 'List gists for the authenticated user or a specific user'
 
 export async function listGistsCore({ token, username, perPage, page }: { token: string, username?: string, perPage: number, page: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = username
     ? await octokit.rest.gists.listForUser({ username, per_page: perPage, page })
     : await octokit.rest.gists.list({ per_page: perPage, page })
@@ -25,6 +25,7 @@ export async function listGistsCore({ token, username, perPage, page }: { token:
     createdAt: gist.created_at,
     updatedAt: gist.updated_at,
   }))
+  })
 }
 
 export const getGistInputSchema = z.object({
@@ -34,7 +35,7 @@ export const getGistInputSchema = z.object({
 export const getGistDescription = 'Get a gist by ID, including file contents'
 
 export async function getGistCore({ token, gistId }: { token: string, gistId: string }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.gists.get({ gist_id: gistId })
   return {
     id: data.id,
@@ -52,6 +53,7 @@ export async function getGistCore({ token, gistId }: { token: string, gistId: st
     createdAt: data.created_at,
     updatedAt: data.updated_at,
   }
+  })
 }
 
 export const listGistCommentsInputSchema = z.object({
@@ -63,7 +65,7 @@ export const listGistCommentsInputSchema = z.object({
 export const listGistCommentsDescription = 'List comments on a gist'
 
 export async function listGistCommentsCore({ token, gistId, perPage, page }: { token: string, gistId: string, perPage: number, page: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.gists.listComments({ gist_id: gistId, per_page: perPage, page })
   return data.map(comment => ({
     id: comment.id,
@@ -73,6 +75,7 @@ export async function listGistCommentsCore({ token, gistId, perPage, page }: { t
     createdAt: comment.created_at,
     updatedAt: comment.updated_at,
   }))
+  })
 }
 
 export const createGistInputSchema = z.object({
@@ -86,7 +89,7 @@ export const createGistDescription = 'Create a new gist with one or more files'
 
 /** Not idempotent — each call creates a new gist. */
 export async function createGistCore({ token, description, files, isPublic }: { token: string, description?: string, files: Record<string, { content: string }>, isPublic: boolean }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.gists.create({
     description,
     files,
@@ -100,6 +103,7 @@ export async function createGistCore({ token, description, files, isPublic }: {
     files: Object.keys(data.files ?? {}),
     owner: data.owner?.login,
   }
+  })
 }
 
 export const updateGistInputSchema = z.object({
@@ -114,7 +118,7 @@ export const updateGistDescription = 'Update an existing gist — edit descripti
 
 /** Not idempotent — each call applies a new revision. */
 export async function updateGistCore({ token, gistId, description, files, filesToDelete }: { token: string, gistId: string, description?: string, files?: Record<string, { content: string }>, filesToDelete?: string[] }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const fileUpdates: Record<string, { content: string } | null> = {}
   if (files) Object.assign(fileUpdates, files)
   if (filesToDelete) {
@@ -131,6 +135,7 @@ export async function updateGistCore({ token, gistId, description, files, filesT
     url: data.html_url,
     files: Object.keys(data.files ?? {}),
   }
+  })
 }
 
 export const deleteGistInputSchema = z.object({
@@ -141,9 +146,10 @@ export const deleteGistDescription = 'Delete a gist permanently'
 
 /** Not idempotent — deleting an already-deleted gist returns 404 from GitHub. */
 export async function deleteGistCore({ token, gistId }: { token: string, gistId: string }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   await octokit.rest.gists.delete({ gist_id: gistId })
   return { deleted: true, gistId }
+  })
 }
 
 export const createGistCommentInputSchema = z.object({
@@ -155,7 +161,7 @@ export const createGistCommentDescription = 'Add a comment to a gist'
 
 /** Not idempotent — each call adds another comment. */
 export async function createGistCommentCore({ token, gistId, body }: { token: string, gistId: string, body: string }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.gists.createComment({ gist_id: gistId, body })
   return {
     id: data.id,
@@ -164,4 +170,5 @@ export async function createGistCommentCore({ token, gistId, body }: { token: st
     author: data.user?.login,
     createdAt: data.created_at,
   }
+  })
 }
diff --git a/packages/github-tools/src/core/issues.ts b/packages/github-tools/src/core/issues.ts
index d5d520d..893775e 100644
--- a/packages/github-tools/src/core/issues.ts
+++ b/packages/github-tools/src/core/issues.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { createOctokit } from '../client'
+import { withOctokit } from '../client'
 import { applyDetailBody, detailSchema, type DetailLevel } from './detail'
 import { fetchAllPages, maxPagesSchema } from './pagination'
 
@@ -15,7 +15,7 @@ export const listIssuesInputSchema = z.object({
 export const listIssuesDescription = 'List issues for a GitHub repository (excludes pull requests)'
 
 export async function listIssuesCore({ token, owner, repo, state, labels, perPage, maxPages }: { token: string, owner: string, repo: string, state: 'open' | 'closed' | 'all', labels?: string, perPage: number, maxPages?: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const issues = await fetchAllPages(async page => {
     const { data } = await octokit.rest.issues.listForRepo({
       owner,
@@ -39,6 +39,7 @@ export async function listIssuesCore({ token, owner, repo, state, labels, perPag
       createdAt: issue.created_at,
       updatedAt: issue.updated_at,
     }))
+  })
 }
 
 export const getIssueInputSchema = z.object({
@@ -51,7 +52,7 @@ export const getIssueInputSchema = z.object({
 export const getIssueDescription = 'Get detailed information about a specific issue. Body is truncated by default (detail: summary) — set detail full for the complete description'
 
 export async function getIssueCore({ token, owner, repo, issueNumber, detail = 'summary' }: { token: string, owner: string, repo: string, issueNumber: number, detail?: DetailLevel }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.issues.get({ owner, repo, issue_number: issueNumber })
   return {
     number: data.number,
@@ -67,6 +68,7 @@ export async function getIssueCore({ token, owner, repo, issueNumber, detail = '
     updatedAt: data.updated_at,
     closedAt: data.closed_at,
   }
+  })
 }
 
 export const listIssueCommentsInputSchema = z.object({
@@ -81,7 +83,7 @@ export const listIssueCommentsInputSchema = z.object({
 export const listIssueCommentsDescription = 'List comments on a GitHub issue. Bodies are truncated by default (detail: summary)'
 
 export async function listIssueCommentsCore({ token, owner, repo, issueNumber, perPage, page, detail = 'summary' }: { token: string, owner: string, repo: string, issueNumber: number, perPage: number, page: number, detail?: DetailLevel }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.issues.listComments({ owner, repo, issue_number: issueNumber, per_page: perPage, page })
   return data.map(comment => ({
     id: comment.id,
@@ -91,6 +93,7 @@ export async function listIssueCommentsCore({ token, owner, repo, issueNumber, p
     createdAt: comment.created_at,
     updatedAt: comment.updated_at,
   }))
+  })
 }
 
 export const createIssueInputSchema = z.object({
@@ -106,7 +109,7 @@ export const createIssueDescription = 'Create a new issue in a GitHub repository
 
 /** Not idempotent — each call creates a new issue. */
 export async function createIssueCore({ token, owner, repo, title, body, labels, assignees }: { token: string, owner: string, repo: string, title: string, body?: string, labels?: string[], assignees?: string[] }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.issues.create({ owner, repo, title, body, labels, assignees })
   return {
     number: data.number,
@@ -115,6 +118,7 @@ export async function createIssueCore({ token, owner, repo, title, body, labels,
     state: data.state,
     labels: data.labels.map(l => (typeof l === 'string' ? l : l.name)),
   }
+  })
 }
 
 export const addIssueCommentInputSchema = z.object({
@@ -128,7 +132,7 @@ export const addIssueCommentDescription = 'Add a comment to a GitHub issue'
 
 /** Not idempotent — each call adds another comment. */
 export async function addIssueCommentCore({ token, owner, repo, issueNumber, body }: { token: string, owner: string, repo: string, issueNumber: number, body: string }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.issues.createComment({ owner, repo, issue_number: issueNumber, body })
   return {
     id: data.id,
@@ -137,6 +141,7 @@ export async function addIssueCommentCore({ token, owner, repo, issueNumber, bod
     author: data.user?.login,
     createdAt: data.created_at,
   }
+  })
 }
 
 export const closeIssueInputSchema = z.object({
@@ -150,7 +155,7 @@ export const closeIssueDescription = 'Close an open GitHub issue'
 
 /** Idempotent when the issue is already closed. */
 export async function closeIssueCore({ token, owner, repo, issueNumber, stateReason }: { token: string, owner: string, repo: string, issueNumber: number, stateReason: 'completed' | 'not_planned' }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data: existing } = await octokit.rest.issues.get({ owner, repo, issue_number: issueNumber })
   if (existing.state === 'closed') {
     return {
@@ -176,6 +181,7 @@ export async function closeIssueCore({ token, owner, repo, issueNumber, stateRea
     url: data.html_url,
     closedAt: data.closed_at,
   }
+  })
 }
 
 export const updateIssueInputSchema = z.object({
@@ -195,7 +201,7 @@ export const updateIssueDescription = 'Update a GitHub issue — title, body, la
 
 /** Not idempotent — each call applies a new revision. */
 export async function updateIssueCore({ token, owner, repo, issueNumber, title, body, state, stateReason, labels, milestone, assignees }: { token: string, owner: string, repo: string, issueNumber: number, title?: string, body?: string, state?: 'open' | 'closed', stateReason?: 'completed' | 'not_planned' | 'reopened', labels?: string[], milestone?: number | null, assignees?: string[] }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.issues.update({
     owner,
     repo,
@@ -219,6 +225,7 @@ export async function updateIssueCore({ token, owner, repo, issueNumber, title,
     closedAt: data.closed_at,
     updatedAt: data.updated_at,
   }
+  })
 }
 
 export const updateIssueCommentInputSchema = z.object({
@@ -232,7 +239,7 @@ export const updateIssueCommentDescription = 'Update the body of a comment on a
 
 /** Not idempotent — each call applies a new revision. */
 export async function updateIssueCommentCore({ token, owner, repo, commentId, body }: { token: string, owner: string, repo: string, commentId: number, body: string }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.issues.updateComment({ owner, repo, comment_id: commentId, body })
   return {
     id: data.id,
@@ -240,6 +247,7 @@ export async function updateIssueCommentCore({ token, owner, repo, commentId, bo
     body: data.body,
     updatedAt: data.updated_at,
   }
+  })
 }
 
 export const deleteIssueCommentInputSchema = z.object({
@@ -252,9 +260,10 @@ export const deleteIssueCommentDescription = 'Delete a comment from a GitHub iss
 
 /** Not idempotent — deleting an already-deleted comment returns 404 from GitHub. */
 export async function deleteIssueCommentCore({ token, owner, repo, commentId }: { token: string, owner: string, repo: string, commentId: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   await octokit.rest.issues.deleteComment({ owner, repo, comment_id: commentId })
   return { deleted: true, commentId }
+  })
 }
 
 export const listLabelsInputSchema = z.object({
@@ -267,13 +276,14 @@ export const listLabelsInputSchema = z.object({
 export const listLabelsDescription = 'List labels available in a GitHub repository'
 
 export async function listLabelsCore({ token, owner, repo, perPage, page }: { token: string, owner: string, repo: string, perPage: number, page: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.issues.listLabelsForRepo({ owner, repo, per_page: perPage, page })
   return data.map(label => ({
     name: label.name,
     color: label.color,
     description: label.description,
   }))
+  })
 }
 
 export const addLabelsInputSchema = z.object({
@@ -287,13 +297,14 @@ export const addLabelsDescription = 'Add labels to an issue or pull request'
 
 /** Not idempotent — re-adding labels is a no-op on GitHub but still mutates. */
 export async function addLabelsCore({ token, owner, repo, issueNumber, labels }: { token: string, owner: string, repo: string, issueNumber: number, labels: string[] }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.issues.addLabels({ owner, repo, issue_number: issueNumber, labels })
   return data.map(label => ({
     name: label.name,
     color: label.color,
     description: label.description,
   }))
+  })
 }
 
 export const removeLabelInputSchema = z.object({
@@ -307,9 +318,10 @@ export const removeLabelDescription = 'Remove a label from an issue or pull requ
 
 /** Not idempotent — removing a missing label returns 404 from GitHub. */
 export async function removeLabelCore({ token, owner, repo, issueNumber, label }: { token: string, owner: string, repo: string, issueNumber: number, label: string }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   await octokit.rest.issues.removeLabel({ owner, repo, issue_number: issueNumber, name: label })
   return { removed: true, label, issueNumber }
+  })
 }
 
 export const createLabelInputSchema = z.object({
@@ -324,13 +336,14 @@ export const createLabelDescription = 'Create a label in a GitHub repository'
 
 /** Not idempotent — creating a label that already exists returns 422 from GitHub. */
 export async function createLabelCore({ token, owner, repo, name, color, description }: { token: string, owner: string, repo: string, name: string, color: string, description?: string }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.issues.createLabel({ owner, repo, name, color, description })
   return {
     name: data.name,
     color: data.color,
     description: data.description,
   }
+  })
 }
 
 export const updateLabelInputSchema = z.object({
@@ -346,7 +359,7 @@ export const updateLabelDescription = 'Update a label in a GitHub repository —
 
 /** Not idempotent — each call applies a new revision. */
 export async function updateLabelCore({ token, owner, repo, name, newName, color, description }: { token: string, owner: string, repo: string, name: string, newName?: string, color?: string, description?: string | null }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.issues.updateLabel({
     owner,
     repo,
@@ -360,6 +373,7 @@ export async function updateLabelCore({ token, owner, repo, name, newName, color
     color: data.color,
     description: data.description,
   }
+  })
 }
 
 export const deleteLabelInputSchema = z.object({
@@ -372,9 +386,10 @@ export const deleteLabelDescription = 'Delete a label from a GitHub repository p
 
 /** Not idempotent — deleting a missing label returns 404 from GitHub. */
 export async function deleteLabelCore({ token, owner, repo, name }: { token: string, owner: string, repo: string, name: string }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   await octokit.rest.issues.deleteLabel({ owner, repo, name })
   return { deleted: true, name }
+  })
 }
 
 export const addAssigneesInputSchema = z.object({
@@ -388,12 +403,13 @@ export const addAssigneesDescription = 'Assign users to an issue or pull request
 
 /** Not idempotent — re-adding an existing assignee is a no-op on GitHub but still mutates. */
 export async function addAssigneesCore({ token, owner, repo, issueNumber, assignees }: { token: string, owner: string, repo: string, issueNumber: number, assignees: string[] }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.issues.addAssignees({ owner, repo, issue_number: issueNumber, assignees })
   return {
     number: data.number,
     assignees: data.assignees?.map(a => a.login),
   }
+  })
 }
 
 export const removeAssigneesInputSchema = z.object({
@@ -407,10 +423,11 @@ export const removeAssigneesDescription = 'Remove assignees from an issue or pul
 
 /** Idempotent — removing an assignee that is not assigned is a no-op on GitHub. */
 export async function removeAssigneesCore({ token, owner, repo, issueNumber, assignees }: { token: string, owner: string, repo: string, issueNumber: number, assignees: string[] }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.issues.removeAssignees({ owner, repo, issue_number: issueNumber, assignees })
   return {
     number: data.number,
     assignees: data.assignees?.map(a => a.login),
   }
+  })
 }
diff --git a/packages/github-tools/src/core/notifications.ts b/packages/github-tools/src/core/notifications.ts
index 89fb06a..5ddb925 100644
--- a/packages/github-tools/src/core/notifications.ts
+++ b/packages/github-tools/src/core/notifications.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { createOctokit } from '../client'
+import { withOctokit } from '../client'
 
 export const listNotificationsInputSchema = z.object({
   all: z.boolean().optional().default(false).describe('Include notifications already marked as read'),
@@ -11,7 +11,7 @@ export const listNotificationsInputSchema = z.object({
 export const listNotificationsDescription = 'List notification threads for the authenticated user. Unread only by default — set all true to include read threads. Requires a token with notifications access'
 
 export async function listNotificationsCore({ token, all, participating, perPage, page }: { token: string, all: boolean, participating: boolean, perPage: number, page: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.activity.listNotificationsForAuthenticatedUser({
     all,
     participating,
@@ -30,6 +30,7 @@ export async function listNotificationsCore({ token, all, participating, perPage
     unread: thread.unread,
     updatedAt: thread.updated_at,
   }))
+  })
 }
 
 export const markNotificationReadInputSchema = z.object({
@@ -40,7 +41,8 @@ export const markNotificationReadDescription = 'Mark a single notification threa
 
 /** Idempotent — marking an already-read thread is a no-op on GitHub. */
 export async function markNotificationReadCore({ token, threadId }: { token: string, threadId: string }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   await octokit.rest.activity.markThreadAsRead({ thread_id: Number(threadId) })
   return { marked: true, threadId }
+  })
 }
diff --git a/packages/github-tools/src/core/pull-requests.ts b/packages/github-tools/src/core/pull-requests.ts
index 8bcb1f6..f3195f5 100644
--- a/packages/github-tools/src/core/pull-requests.ts
+++ b/packages/github-tools/src/core/pull-requests.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { createOctokit } from '../client'
+import { withOctokit } from '../client'
 import type { CommitIdentity } from '../types'
 import { applyDetailBody, detailSchema, type DetailLevel } from './detail'
 import { fetchAllPages, maxPagesSchema } from './pagination'
@@ -16,7 +16,7 @@ export const listPullRequestsInputSchema = z.object({
 export const listPullRequestsDescription = 'List pull requests for a GitHub repository'
 
 export async function listPullRequestsCore({ token, owner, repo, state, perPage, maxPages }: { token: string, owner: string, repo: string, state: 'open' | 'closed' | 'all', perPage: number, maxPages?: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const pullRequests = await fetchAllPages(async page => {
     const { data } = await octokit.rest.pulls.list({ owner, repo, state, per_page: perPage, page })
     return data
@@ -33,6 +33,7 @@ export async function listPullRequestsCore({ token, owner, repo, state, perPage,
     createdAt: pr.created_at,
     updatedAt: pr.updated_at,
   }))
+  })
 }
 
 export const getPullRequestInputSchema = z.object({
@@ -45,7 +46,7 @@ export const getPullRequestInputSchema = z.object({
 export const getPullRequestDescription = 'Get detailed information about a specific pull request. Body is truncated by default (detail: summary) — set detail full for the complete description'
 
 export async function getPullRequestCore({ token, owner, repo, pullNumber, detail = 'summary' }: { token: string, owner: string, repo: string, pullNumber: number, detail?: DetailLevel }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.pulls.get({ owner, repo, pull_number: pullNumber })
   return {
     number: data.number,
@@ -67,6 +68,7 @@ export async function getPullRequestCore({ token, owner, repo, pullNumber, detai
     updatedAt: data.updated_at,
     mergedAt: data.merged_at,
   }
+  })
 }
 
 export const createPullRequestInputSchema = z.object({
@@ -83,7 +85,7 @@ export const createPullRequestDescription = 'Create a new pull request in a GitH
 
 /** Not idempotent — each call creates a new pull request. */
 export async function createPullRequestCore({ token, owner, repo, title, body, head, base, draft }: { token: string, owner: string, repo: string, title: string, body?: string, head: string, base: string, draft: boolean }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.pulls.create({ owner, repo, title, body, head, base, draft })
   return {
     number: data.number,
@@ -94,6 +96,7 @@ export async function createPullRequestCore({ token, owner, repo, title, body, h
     branch: data.head.ref,
     base: data.base.ref,
   }
+  })
 }
 
 const MARK_READY_FOR_REVIEW_MUTATION = `
@@ -127,7 +130,7 @@ export const updatePullRequestDescription = 'Update a pull request — title, bo
 
 /** Not idempotent — each call applies a new revision. */
 export async function updatePullRequestCore({ token, owner, repo, pullNumber, title, body, state, base, draft }: { token: string, owner: string, repo: string, pullNumber: number, title?: string, body?: string, state?: 'open' | 'closed', base?: string, draft?: boolean }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const hasRestUpdate = title !== undefined || body !== undefined || state !== undefined || base !== undefined
   const { data } = hasRestUpdate
     ? await octokit.rest.pulls.update({ owner, repo, pull_number: pullNumber, title, body, state, base })
@@ -146,6 +149,7 @@ export async function updatePullRequestCore({ token, owner, repo, pullNumber, ti
     base: data.base.ref,
     updatedAt: data.updated_at,
   }
+  })
 }
 
 export const mergePullRequestInputSchema = z.object({
@@ -179,7 +183,7 @@ export async function mergePullRequestCore({
   mergeMethod: 'merge' | 'squash' | 'rebase'
   coAuthors?: CommitIdentity[]
 }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const finalMessage = composeCommitMessage(commitMessage ?? '', coAuthors) || undefined
   const { data } = await octokit.rest.pulls.merge({
     owner,
@@ -194,6 +198,7 @@ export async function mergePullRequestCore({
     message: data.message,
     sha: data.sha,
   }
+  })
 }
 
 export const addPullRequestCommentInputSchema = z.object({
@@ -207,7 +212,7 @@ export const addPullRequestCommentDescription = 'Add a comment to a pull request
 
 /** Not idempotent — each call adds another comment. */
 export async function addPullRequestCommentCore({ token, owner, repo, pullNumber, body }: { token: string, owner: string, repo: string, pullNumber: number, body: string }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.issues.createComment({ owner, repo, issue_number: pullNumber, body })
   return {
     id: data.id,
@@ -216,6 +221,7 @@ export async function addPullRequestCommentCore({ token, owner, repo, pullNumber
     author: data.user?.login,
     createdAt: data.created_at,
   }
+  })
 }
 
 export const updatePullRequestCommentInputSchema = z.object({
@@ -229,7 +235,7 @@ export const updatePullRequestCommentDescription = 'Update the body of a comment
 
 /** Not idempotent — each call applies a new revision. */
 export async function updatePullRequestCommentCore({ token, owner, repo, commentId, body }: { token: string, owner: string, repo: string, commentId: number, body: string }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.issues.updateComment({ owner, repo, comment_id: commentId, body })
   return {
     id: data.id,
@@ -237,6 +243,7 @@ export async function updatePullRequestCommentCore({ token, owner, repo, comment
     body: data.body,
     updatedAt: data.updated_at,
   }
+  })
 }
 
 export const deletePullRequestCommentInputSchema = z.object({
@@ -249,9 +256,10 @@ export const deletePullRequestCommentDescription = 'Delete a comment from a pull
 
 /** Not idempotent — deleting an already-deleted comment returns 404 from GitHub. */
 export async function deletePullRequestCommentCore({ token, owner, repo, commentId }: { token: string, owner: string, repo: string, commentId: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   await octokit.rest.issues.deleteComment({ owner, repo, comment_id: commentId })
   return { deleted: true, commentId }
+  })
 }
 
 export const listPullRequestFilesInputSchema = z.object({
@@ -267,7 +275,7 @@ export const listPullRequestFilesInputSchema = z.object({
 export const listPullRequestFilesDescription = 'List files changed in a pull request with status and stats. Patches are omitted by default — set includePatch true (optionally with filenames) to fetch diffs'
 
 export async function listPullRequestFilesCore({ token, owner, repo, pullNumber, includePatch, filenames, perPage, page }: { token: string, owner: string, repo: string, pullNumber: number, includePatch: boolean, filenames?: string[], perPage: number, page: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.pulls.listFiles({ owner, repo, pull_number: pullNumber, per_page: perPage, page })
   const filenameSet = filenames?.length ? new Set(filenames) : null
   return data
@@ -280,6 +288,7 @@ export async function listPullRequestFilesCore({ token, owner, repo, pullNumber,
       changes: file.changes,
       ...includePatch && file.patch != null ? { patch: file.patch } : {},
     }))
+  })
 }
 
 export const listPullRequestReviewsInputSchema = z.object({
@@ -293,7 +302,7 @@ export const listPullRequestReviewsInputSchema = z.object({
 export const listPullRequestReviewsDescription = 'List reviews on a pull request (approvals, change requests, and comments)'
 
 export async function listPullRequestReviewsCore({ token, owner, repo, pullNumber, perPage, page }: { token: string, owner: string, repo: string, pullNumber: number, perPage: number, page: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.pulls.listReviews({ owner, repo, pull_number: pullNumber, per_page: perPage, page })
   return data.map(review => ({
     id: review.id,
@@ -303,6 +312,7 @@ export async function listPullRequestReviewsCore({ token, owner, repo, pullNumbe
     url: review.html_url,
     submittedAt: review.submitted_at,
   }))
+  })
 }
 
 export const createPullRequestReviewInputSchema = z.object({
@@ -323,7 +333,7 @@ export const createPullRequestReviewDescription = 'Submit a pull request review
 
 /** Not idempotent — each call submits a new review. */
 export async function createPullRequestReviewCore({ token, owner, repo, pullNumber, body, event, comments }: { token: string, owner: string, repo: string, pullNumber: number, body?: string, event: 'APPROVE' | 'REQUEST_CHANGES' | 'COMMENT', comments?: Array<{ path: string, body: string, line?: number, side?: 'LEFT' | 'RIGHT' }> }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.pulls.createReview({
     owner,
     repo,
@@ -340,6 +350,7 @@ export async function createPullRequestReviewCore({ token, owner, repo, pullNumb
     author: data.user?.login,
     submittedAt: data.submitted_at,
   }
+  })
 }
 
 export const requestReviewersInputSchema = z.object({
@@ -354,7 +365,7 @@ export const requestReviewersDescription = 'Request reviews from users or teams
 
 /** Not idempotent — re-requesting an existing reviewer is a no-op on GitHub but still mutates. */
 export async function requestReviewersCore({ token, owner, repo, pullNumber, reviewers, teamReviewers }: { token: string, owner: string, repo: string, pullNumber: number, reviewers?: string[], teamReviewers?: string[] }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.pulls.requestReviewers({
     owner,
     repo,
@@ -368,4 +379,5 @@ export async function requestReviewersCore({ token, owner, repo, pullNumber, rev
     requestedReviewers: data.requested_reviewers?.map(r => r.login),
     requestedTeams: data.requested_teams?.map(t => t.slug),
   }
+  })
 }
diff --git a/packages/github-tools/src/core/rate-limit.test.ts b/packages/github-tools/src/core/rate-limit.test.ts
new file mode 100644
index 0000000..8ba802c
--- /dev/null
+++ b/packages/github-tools/src/core/rate-limit.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest'
+import {
+  enrichGithubRateLimitError,
+  finishGithubResult,
+  parseGithubRateLimit,
+  recordGithubRateLimit,
+  stripRateLimit,
+  withComposedRateLimit,
+} from './rate-limit'
+
+const headers = {
+  'x-ratelimit-remaining': '38',
+  'x-ratelimit-limit': '5000',
+  'x-ratelimit-reset': '1774800000',
+  'x-ratelimit-resource': 'core',
+}
+
+const rateLimit = {
+  remaining: 38,
+  limit: 5000,
+  reset: 1774800000,
+  resource: 'core',
+}
+
+describe('parseGithubRateLimit', () => {
+  it('reads remaining, limit, reset, and resource', () => {
+    expect(parseGithubRateLimit(headers)).toEqual(rateLimit)
+  })
+
+  it('includes retry-after when present', () => {
+    expect(parseGithubRateLimit({ ...headers, 'retry-after': '12' })).toEqual({
+      ...rateLimit,
+      retryAfter: 12,
+    })
+  })
+
+  it('returns undefined when the required headers are missing', () => {
+    expect(parseGithubRateLimit({ 'content-type': 'application/json' })).toBeUndefined()
+  })
+})
+
+describe('stripRateLimit', () => {
+  it('drops rateLimit from a plain object', () => {
+    expect(stripRateLimit({ name: 'hello-world', rateLimit })).toEqual({
+      name: 'hello-world',
+    })
+  })
+
+  it('leaves arrays unchanged', () => {
+    const branches = [{ name: 'main' }]
+    expect(stripRateLimit(branches)).toBe(branches)
+  })
+})
+
+describe('finishGithubResult', () => {
+  it('attaches rateLimit on plain objects', () => {
+    const owner = {}
+    recordGithubRateLimit(owner, headers)
+    expect(finishGithubResult(owner, { name: 'hello-world' })).toEqual({
+      name: 'hello-world',
+      rateLimit,
+    })
+  })
+
+  it('does not wrap arrays', () => {
+    const owner = {}
+    recordGithubRateLimit(owner, headers)
+    expect(finishGithubResult(owner, [{ name: 'main' }])).toEqual([{ name: 'main' }])
+  })
+})
+
+describe('enrichGithubRateLimitError', () => {
+  it('appends remaining/reset on 403 errors', () => {
+    const error = Object.assign(new Error('API rate limit exceeded'), { status: 403 })
+    const parsed = parseGithubRateLimit({
+      ...headers,
+      'x-ratelimit-remaining': '0',
+      'x-ratelimit-resource': 'search',
+    })
+    expect(() => {
+      throw enrichGithubRateLimitError(error, parsed)
+    }).toThrow('GitHub rate limit search: 0/5000 remaining, resets at 1774800000')
+  })
+})
+
+describe('withComposedRateLimit', () => {
+  it('lifts a nested rateLimit onto the composed object and strips children', () => {
+    expect(withComposedRateLimit({
+      pullRequest: { number: 1, rateLimit },
+      files: [{ filename: 'a.ts' }],
+    })).toEqual({
+      pullRequest: { number: 1 },
+      files: [{ filename: 'a.ts' }],
+      rateLimit,
+    })
+  })
+})
diff --git a/packages/github-tools/src/core/rate-limit.ts b/packages/github-tools/src/core/rate-limit.ts
new file mode 100644
index 0000000..73fc82f
--- /dev/null
+++ b/packages/github-tools/src/core/rate-limit.ts
@@ -0,0 +1,126 @@
+/**
+ * GitHub REST/GraphQL rate-limit snapshot from the last request in a tool call.
+ * Present on object-shaped execute results; stripped before the model sees the output.
+ */
+export type GithubRateLimit = {
+  remaining: number
+  limit: number
+  reset: number
+  resource?: string
+  retryAfter?: number
+}
+
+const snapshots = new WeakMap<object, GithubRateLimit>()
+
+function headerValue(headers: Record<string, unknown> | undefined, name: string): string | undefined {
+  if (!headers) return undefined
+  const value = headers[name] ?? headers[name.toLowerCase()]
+  if (value == null) return undefined
+  return String(value)
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype
+}
+
+function isRateLimit(value: unknown): value is GithubRateLimit {
+  return isPlainObject(value) && typeof value.remaining === 'number' && typeof value.limit === 'number' && typeof value.reset === 'number'
+}
+
+/** Parse GitHub `x-ratelimit-*` / `retry-after` headers. Returns undefined when the trio is missing. */
+export function parseGithubRateLimit(headers: Record<string, unknown> | undefined): GithubRateLimit | undefined {
+  const remaining = Number(headerValue(headers, 'x-ratelimit-remaining'))
+  const limit = Number(headerValue(headers, 'x-ratelimit-limit'))
+  const reset = Number(headerValue(headers, 'x-ratelimit-reset'))
+  if (!Number.isFinite(remaining) || !Number.isFinite(limit) || !Number.isFinite(reset)) {
+    return undefined
+  }
+
+  const resource = headerValue(headers, 'x-ratelimit-resource')
+  const retryAfter = Number(headerValue(headers, 'retry-after'))
+
+  return {
+    remaining,
+    limit,
+    reset,
+    ...resource ? { resource } : {},
+    ...Number.isFinite(retryAfter) ? { retryAfter } : {},
+  }
+}
+
+export function recordGithubRateLimit(owner: object, headers: Record<string, unknown> | undefined): void {
+  const rateLimit = parseGithubRateLimit(headers)
+  if (rateLimit) snapshots.set(owner, rateLimit)
+}
+
+export function peekGithubRateLimit(owner: object): GithubRateLimit | undefined {
+  return snapshots.get(owner)
+}
+
+export function stripRateLimit<T>(output: T): T {
+  if (!isPlainObject(output) || !('rateLimit' in output)) {
+    return output
+  }
+  const rest = { ...output }
+  delete rest.rateLimit
+  return rest as T
+}
+
+function attachRateLimit<T>(result: T, rateLimit: GithubRateLimit | undefined): T {
+  if (!rateLimit || !isPlainObject(result)) return result
+  return { ...result, rateLimit } as T
+}
+
+export function finishGithubResult<T>(owner: object, result: T): T {
+  return attachRateLimit(result, snapshots.get(owner))
+}
+
+function pickRateLimitDeep(value: unknown): GithubRateLimit | undefined {
+  let found: GithubRateLimit | undefined
+  if (isPlainObject(value)) {
+    if (isRateLimit(value.rateLimit)) found = value.rateLimit
+    for (const child of Object.values(value)) {
+      const nested = pickRateLimitDeep(child)
+      if (nested) found = nested
+    }
+  }
+  return found
+}
+
+function stripRateLimitDeep<T>(value: T): T {
+  if (Array.isArray(value)) return value
+  if (!isPlainObject(value)) return value
+  const next = stripRateLimit({ ...value })
+  return Object.fromEntries(
+    Object.entries(next).map(([key, child]) => [key, stripRateLimit(child)]),
+  ) as T
+}
+
+/** Lift a nested child's `rateLimit` onto a composed object and strip it from children. */
+export function withComposedRateLimit<T extends Record<string, unknown>>(result: T): T {
+  return attachRateLimit(stripRateLimitDeep(result), pickRateLimitDeep(result))
+}
+
+function errorStatus(error: unknown): number | undefined {
+  if (error == null || typeof error !== 'object' || !('status' in error)) return undefined
+  const status = (error as { status?: unknown }).status
+  return typeof status === 'number' ? status : undefined
+}
+
+export function formatRateLimitSuffix(rateLimit: GithubRateLimit): string {
+  const resource = rateLimit.resource ? ` ${rateLimit.resource}` : ''
+  const retry = rateLimit.retryAfter != null ? `, retry after ${rateLimit.retryAfter}s` : ''
+  return `GitHub rate limit${resource}: ${rateLimit.remaining}/${rateLimit.limit} remaining, resets at ${rateLimit.reset}${retry}`
+}
+
+export function enrichGithubRateLimitError(error: unknown, rateLimit: GithubRateLimit | undefined): unknown {
+  const status = errorStatus(error)
+  if (!rateLimit || (status !== 403 && status !== 429) || !(error instanceof Error)) {
+    return error
+  }
+  const suffix = formatRateLimitSuffix(rateLimit)
+  if (!error.message.includes(suffix)) {
+    error.message = `${error.message} (${suffix})`
+  }
+  return error
+}
diff --git a/packages/github-tools/src/core/reactions.ts b/packages/github-tools/src/core/reactions.ts
index 6b4fcc6..93a716a 100644
--- a/packages/github-tools/src/core/reactions.ts
+++ b/packages/github-tools/src/core/reactions.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { createOctokit } from '../client'
+import { withOctokit } from '../client'
 
 const REACTION_CONTENTS = ['+1', '-1', 'laugh', 'confused', 'heart', 'hooray', 'rocket', 'eyes'] as const
 
@@ -31,7 +31,7 @@ export const listIssueReactionsInputSchema = z.object({
 export const listIssueReactionsDescription = 'List reactions on an issue or pull request conversation, with per-emoji counts for the returned page'
 
 export async function listIssueReactionsCore({ token, owner, repo, issueNumber, content, perPage, page }: { token: string, owner: string, repo: string, issueNumber: number, content?: ReactionContent, perPage: number, page: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.reactions.listForIssue({
     owner,
     repo,
@@ -41,6 +41,7 @@ export async function listIssueReactionsCore({ token, owner, repo, issueNumber,
     page,
   })
   return shapeReactions(data)
+  })
 }
 
 export const addIssueReactionInputSchema = z.object({
@@ -54,7 +55,7 @@ export const addIssueReactionDescription = 'React to an issue or pull request wi
 
 /** Idempotent — GitHub returns the existing reaction when the user already reacted with the same content. */
 export async function addIssueReactionCore({ token, owner, repo, issueNumber, content }: { token: string, owner: string, repo: string, issueNumber: number, content: ReactionContent }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.reactions.createForIssue({
     owner,
     repo,
@@ -67,6 +68,7 @@ export async function addIssueReactionCore({ token, owner, repo, issueNumber, co
     user: data.user?.login,
     issueNumber,
   }
+  })
 }
 
 export const listCommentReactionsInputSchema = z.object({
@@ -81,7 +83,7 @@ export const listCommentReactionsInputSchema = z.object({
 export const listCommentReactionsDescription = 'List reactions on an issue or pull request comment, with per-emoji counts for the returned page'
 
 export async function listCommentReactionsCore({ token, owner, repo, commentId, content, perPage, page }: { token: string, owner: string, repo: string, commentId: number, content?: ReactionContent, perPage: number, page: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.reactions.listForIssueComment({
     owner,
     repo,
@@ -91,6 +93,7 @@ export async function listCommentReactionsCore({ token, owner, repo, commentId,
     page,
   })
   return shapeReactions(data)
+  })
 }
 
 export const addCommentReactionInputSchema = z.object({
@@ -104,7 +107,7 @@ export const addCommentReactionDescription = 'React to an issue or pull request
 
 /** Idempotent — GitHub returns the existing reaction when the user already reacted with the same content. */
 export async function addCommentReactionCore({ token, owner, repo, commentId, content }: { token: string, owner: string, repo: string, commentId: number, content: ReactionContent }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.reactions.createForIssueComment({
     owner,
     repo,
@@ -117,4 +120,5 @@ export async function addCommentReactionCore({ token, owner, repo, commentId, co
     user: data.user?.login,
     commentId,
   }
+  })
 }
diff --git a/packages/github-tools/src/core/releases.ts b/packages/github-tools/src/core/releases.ts
index bd74c90..75193ed 100644
--- a/packages/github-tools/src/core/releases.ts
+++ b/packages/github-tools/src/core/releases.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { createOctokit } from '../client'
+import { withOctokit } from '../client'
 import { applyDetailBody, detailSchema, type DetailLevel } from './detail'
 import { fetchAllPages, maxPagesSchema } from './pagination'
 
@@ -14,7 +14,7 @@ export const listReleasesInputSchema = z.object({
 export const listReleasesDescription = 'List releases for a GitHub repository, newest first (includes drafts and prereleases). Bodies truncated by default (detail: summary)'
 
 export async function listReleasesCore({ token, owner, repo, perPage, maxPages, detail = 'summary' }: { token: string, owner: string, repo: string, perPage: number, maxPages?: number, detail?: DetailLevel }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const releases = await fetchAllPages(async page => {
     const { data } = await octokit.rest.repos.listReleases({ owner, repo, per_page: perPage, page })
     return data
@@ -31,6 +31,7 @@ export async function listReleasesCore({ token, owner, repo, perPage, maxPages,
     createdAt: release.created_at,
     publishedAt: release.published_at,
   }))
+  })
 }
 
 export const getLatestReleaseInputSchema = z.object({
@@ -42,7 +43,7 @@ export const getLatestReleaseInputSchema = z.object({
 export const getLatestReleaseDescription = 'Get the latest published release for a GitHub repository (excludes drafts and prereleases). Body truncated by default (detail: summary)'
 
 export async function getLatestReleaseCore({ token, owner, repo, detail = 'summary' }: { token: string, owner: string, repo: string, detail?: DetailLevel }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.repos.getLatestRelease({ owner, repo })
   return {
     id: data.id,
@@ -60,6 +61,7 @@ export async function getLatestReleaseCore({ token, owner, repo, detail = 'summa
       downloadCount: asset.download_count,
     })),
   }
+  })
 }
 
 export const getReleaseInputSchema = z.object({
@@ -72,7 +74,7 @@ export const getReleaseInputSchema = z.object({
 export const getReleaseDescription = 'Get a specific release by ID, including its assets. Body truncated by default (detail: summary)'
 
 export async function getReleaseCore({ token, owner, repo, releaseId, detail = 'summary' }: { token: string, owner: string, repo: string, releaseId: number, detail?: DetailLevel }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.repos.getRelease({ owner, repo, release_id: releaseId })
   return {
     id: data.id,
@@ -92,6 +94,7 @@ export async function getReleaseCore({ token, owner, repo, releaseId, detail = '
       downloadCount: asset.download_count,
     })),
   }
+  })
 }
 
 export const createReleaseInputSchema = z.object({
@@ -110,7 +113,7 @@ export const createReleaseDescription = 'Create a new release (and its tag if ne
 
 /** Not idempotent — creating a release with an existing tag name returns an error from GitHub. */
 export async function createReleaseCore({ token, owner, repo, tagName, target, name, body, draft, prerelease, generateReleaseNotes }: { token: string, owner: string, repo: string, tagName: string, target?: string, name?: string, body?: string, draft: boolean, prerelease: boolean, generateReleaseNotes: boolean }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.repos.createRelease({
     owner,
     repo,
@@ -132,6 +135,7 @@ export async function createReleaseCore({ token, owner, repo, tagName, target, n
     prerelease: data.prerelease,
     createdAt: data.created_at,
   }
+  })
 }
 
 export const updateReleaseInputSchema = z.object({
@@ -150,7 +154,7 @@ export const updateReleaseDescription = 'Update an existing release — tag, tar
 
 /** Not idempotent — each call applies a new revision. */
 export async function updateReleaseCore({ token, owner, repo, releaseId, tagName, target, name, body, draft, prerelease }: { token: string, owner: string, repo: string, releaseId: number, tagName?: string, target?: string, name?: string, body?: string, draft?: boolean, prerelease?: boolean }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.repos.updateRelease({
     owner,
     repo,
@@ -172,6 +176,7 @@ export async function updateReleaseCore({ token, owner, repo, releaseId, tagName
     prerelease: data.prerelease,
     publishedAt: data.published_at,
   }
+  })
 }
 
 export const deleteReleaseInputSchema = z.object({
@@ -184,7 +189,8 @@ export const deleteReleaseDescription = 'Delete a release permanently (does not
 
 /** Not idempotent — deleting an already-deleted release returns 404 from GitHub. */
 export async function deleteReleaseCore({ token, owner, repo, releaseId }: { token: string, owner: string, repo: string, releaseId: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   await octokit.rest.repos.deleteRelease({ owner, repo, release_id: releaseId })
   return { deleted: true, releaseId }
+  })
 }
diff --git a/packages/github-tools/src/core/repository.ts b/packages/github-tools/src/core/repository.ts
index 339899e..b4302c5 100644
--- a/packages/github-tools/src/core/repository.ts
+++ b/packages/github-tools/src/core/repository.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { createOctokit } from '../client'
+import { withOctokit } from '../client'
 import type { CommitIdentity, Octokit } from '../types'
 import { gitBlobSha } from './git-blob-sha'
 
@@ -67,7 +67,7 @@ export const getRepositoryInputSchema = z.object({
 export const getRepositoryDescription = 'Get information about a GitHub repository including description, stars, forks, language, and default branch'
 
 export async function getRepositoryCore({ token, owner, repo }: { token: string, owner: string, repo: string }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.repos.get({ owner, repo })
   return {
     name: data.name,
@@ -83,6 +83,7 @@ export async function getRepositoryCore({ token, owner, repo }: { token: string,
     createdAt: data.created_at,
     updatedAt: data.updated_at,
   }
+  })
 }
 
 export const listBranchesInputSchema = z.object({
@@ -94,13 +95,14 @@ export const listBranchesInputSchema = z.object({
 export const listBranchesDescription = 'List branches in a GitHub repository'
 
 export async function listBranchesCore({ token, owner, repo, perPage }: { token: string, owner: string, repo: string, perPage: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.repos.listBranches({ owner, repo, per_page: perPage })
   return data.map(branch => ({
     name: branch.name,
     sha: branch.commit.sha,
     protected: branch.protected,
   }))
+  })
 }
 
 export const getFileContentInputSchema = z.object({
@@ -134,7 +136,7 @@ export async function getFileContentCore({
   endLine?: number
   maxLines?: number
 }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.repos.getContent({ owner, repo, path, ref })
   if (Array.isArray(data)) {
     return { type: 'directory' as const, entries: data.map(e => ({ name: e.name, type: e.type, path: e.path })) }
@@ -175,6 +177,7 @@ export async function getFileContentCore({
     truncated: clampedFrom > 1 || clampedTo < totalLines,
     content: slice.join('\n'),
   }
+  })
 }
 
 export const getRepositoryTreeInputSchema = z.object({
@@ -187,7 +190,7 @@ export const getRepositoryTreeInputSchema = z.object({
 export const getRepositoryTreeDescription = 'List the file and directory structure of a repository at a given ref'
 
 export async function getRepositoryTreeCore({ token, owner, repo, ref, recursive }: { token: string, owner: string, repo: string, ref?: string, recursive: boolean }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const treeSha = ref || (await octokit.rest.repos.get({ owner, repo })).data.default_branch
   const { data } = await octokit.rest.git.getTree({ owner, repo, tree_sha: treeSha, recursive: recursive ? 'true' : undefined })
   return {
@@ -200,6 +203,7 @@ export async function getRepositoryTreeCore({ token, owner, repo, ref, recursive
       sha: entry.sha,
     })),
   }
+  })
 }
 
 export const createBranchInputSchema = z.object({
@@ -213,7 +217,7 @@ export const createBranchDescription = 'Create a new branch in a GitHub reposito
 
 /** Idempotent when the branch already exists at the target SHA. Not idempotent otherwise. */
 export async function createBranchCore({ token, owner, repo, branch, from }: { token: string, owner: string, repo: string, branch: string, from?: string }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   let sha = from
   if (!sha || !sha.match(/^[0-9a-f]{40}$/i)) {
     const { data: ref } = await octokit.rest.git.getRef({
@@ -248,6 +252,7 @@ export async function createBranchCore({ token, owner, repo, branch, from }: { t
     sha: data.object.sha,
     url: data.url,
   }
+  })
 }
 
 export const forkRepositoryInputSchema = z.object({
@@ -261,7 +266,7 @@ export const forkRepositoryDescription = 'Fork a GitHub repository to the authen
 
 /** Not idempotent — each call may create another fork attempt. */
 export async function forkRepositoryCore({ token, owner, repo, organization, name }: { token: string, owner: string, repo: string, organization?: string, name?: string }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.repos.createFork({
     owner,
     repo,
@@ -278,6 +283,7 @@ export async function forkRepositoryCore({ token, owner, repo, organization, nam
     private: data.private,
     parent: data.parent ? { fullName: data.parent.full_name, url: data.parent.html_url } : null,
   }
+  })
 }
 
 export const createRepositoryInputSchema = z.object({
@@ -294,7 +300,7 @@ export const createRepositoryDescription = 'Create a new GitHub repository for t
 
 /** Not idempotent — each call creates a new repository. */
 export async function createRepositoryCore({ token, name, description, isPrivate, autoInit, gitignoreTemplate, licenseTemplate, org }: { token: string, name: string, description?: string, isPrivate: boolean, autoInit: boolean, gitignoreTemplate?: string, licenseTemplate?: string, org?: string }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const params = {
     name,
     description,
@@ -319,6 +325,7 @@ export async function createRepositoryCore({ token, name, description, isPrivate
     private: data.private,
     createdAt: data.created_at,
   }
+  })
 }
 
 export const createOrUpdateFileInputSchema = z.object({
@@ -359,7 +366,7 @@ export async function createOrUpdateFileCore({
   committer?: CommitIdentity
   coAuthors?: CommitIdentity[]
 }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
 
   if (sha) {
     const branchName = branch || (await octokit.rest.repos.get({ owner, repo })).data.default_branch
@@ -427,4 +434,5 @@ export async function createOrUpdateFileCore({
     commitSha: data.commit.sha,
     commitUrl: data.commit.html_url,
   }
+  })
 }
diff --git a/packages/github-tools/src/core/search.ts b/packages/github-tools/src/core/search.ts
index e84b099..334538a 100644
--- a/packages/github-tools/src/core/search.ts
+++ b/packages/github-tools/src/core/search.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { createOctokit } from '../client'
+import { withOctokit } from '../client'
 
 const MAX_FRAGMENT_LENGTH = 300
 
@@ -16,7 +16,7 @@ export const searchCodeInputSchema = z.object({
 export const searchCodeDescription = 'Search for code in GitHub repositories. Use qualifiers like "repo:owner/name" to scope the search. Results include matching text snippets when GitHub returns them.'
 
 export async function searchCodeCore({ token, query, perPage }: { token: string, query: string, perPage: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.search.code({
     q: query,
     per_page: perPage,
@@ -35,6 +35,7 @@ export async function searchCodeCore({ token, query, perPage }: { token: string,
       })),
     })),
   }
+  })
 }
 
 export const searchRepositoriesInputSchema = z.object({
@@ -47,7 +48,7 @@ export const searchRepositoriesInputSchema = z.object({
 export const searchRepositoriesDescription = 'Search for GitHub repositories by keyword, topic, language, or other qualifiers'
 
 export async function searchRepositoriesCore({ token, query, perPage, sort, order }: { token: string, query: string, perPage: number, sort?: 'stars' | 'forks' | 'help-wanted-issues' | 'updated', order: 'asc' | 'desc' }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.search.repos({ q: query, per_page: perPage, sort, order })
   return {
     totalCount: data.total_count,
@@ -62,6 +63,7 @@ export async function searchRepositoriesCore({ token, query, perPage, sort, orde
       topics: repo.topics,
     })),
   }
+  })
 }
 
 export const searchIssuesInputSchema = z.object({
@@ -74,7 +76,7 @@ export const searchIssuesInputSchema = z.object({
 export const searchIssuesDescription = 'Search for issues and pull requests across GitHub using search qualifiers like "repo:owner/name is:open"'
 
 export async function searchIssuesCore({ token, query, perPage, sort, order }: { token: string, query: string, perPage: number, sort?: 'comments' | 'reactions' | 'created' | 'updated' | 'interactions', order: 'asc' | 'desc' }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.search.issuesAndPullRequests({ q: query, per_page: perPage, sort, order })
   return {
     totalCount: data.total_count,
@@ -92,4 +94,5 @@ export async function searchIssuesCore({ token, query, perPage, sort, order }: {
       isPullRequest: Boolean(item.pull_request),
     })),
   }
+  })
 }
diff --git a/packages/github-tools/src/core/workflows.ts b/packages/github-tools/src/core/workflows.ts
index a80d4f4..34e6716 100644
--- a/packages/github-tools/src/core/workflows.ts
+++ b/packages/github-tools/src/core/workflows.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { createOctokit } from '../client'
+import { withOctokit } from '../client'
 import { fetchAllPages, maxPagesSchema } from './pagination'
 
 export const listWorkflowsInputSchema = z.object({
@@ -12,7 +12,7 @@ export const listWorkflowsInputSchema = z.object({
 export const listWorkflowsDescription = 'List GitHub Actions workflows in a repository'
 
 export async function listWorkflowsCore({ token, owner, repo, perPage, page }: { token: string, owner: string, repo: string, perPage: number, page: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.actions.listRepoWorkflows({ owner, repo, per_page: perPage, page })
   return {
     totalCount: data.total_count,
@@ -26,6 +26,7 @@ export async function listWorkflowsCore({ token, owner, repo, perPage, page }: {
       updatedAt: wf.updated_at,
     })),
   }
+  })
 }
 
 type WorkflowRunStatus = 'completed' | 'action_required' | 'cancelled' | 'failure' | 'neutral' | 'skipped' | 'stale' | 'success' | 'timed_out' | 'in_progress' | 'queued' | 'requested' | 'waiting' | 'pending'
@@ -45,7 +46,7 @@ export const listWorkflowRunsInputSchema = z.object({
 export const listWorkflowRunsDescription = 'List workflow runs for a repository, optionally filtered by workflow, branch, status, or event'
 
 export async function listWorkflowRunsCore({ token, owner, repo, workflowId, branch, event, status, perPage, page, maxPages }: { token: string, owner: string, repo: string, workflowId?: string | number, branch?: string, event?: string, status?: WorkflowRunStatus, perPage: number, page: number, maxPages?: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   let totalCount = 0
   const runs = await fetchAllPages(async currentPage => {
     const { data } = workflowId
@@ -72,6 +73,7 @@ export async function listWorkflowRunsCore({ token, owner, repo, workflowId, bra
       runAttempt: run.run_attempt,
     })),
   }
+  })
 }
 
 export const getWorkflowRunInputSchema = z.object({
@@ -83,7 +85,7 @@ export const getWorkflowRunInputSchema = z.object({
 export const getWorkflowRunDescription = 'Get details of a specific workflow run including status, timing, and trigger info'
 
 export async function getWorkflowRunCore({ token, owner, repo, runId }: { token: string, owner: string, repo: string, runId: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.actions.getWorkflowRun({ owner, repo, run_id: runId })
   return {
     id: data.id,
@@ -101,6 +103,7 @@ export async function getWorkflowRunCore({ token, owner, repo, runId }: { token:
     updatedAt: data.updated_at,
     runStartedAt: data.run_started_at,
   }
+  })
 }
 
 export const listWorkflowJobsInputSchema = z.object({
@@ -115,7 +118,7 @@ export const listWorkflowJobsInputSchema = z.object({
 export const listWorkflowJobsDescription = 'List jobs for a workflow run, including step-level status and timing'
 
 export async function listWorkflowJobsCore({ token, owner, repo, runId, filter, perPage, page }: { token: string, owner: string, repo: string, runId: number, filter: 'latest' | 'all', perPage: number, page: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   const { data } = await octokit.rest.actions.listJobsForWorkflowRun({ owner, repo, run_id: runId, filter, per_page: perPage, page })
   return {
     totalCount: data.total_count,
@@ -138,6 +141,7 @@ export async function listWorkflowJobsCore({ token, owner, repo, runId, filter,
       })),
     })),
   }
+  })
 }
 
 export const triggerWorkflowInputSchema = z.object({
@@ -152,7 +156,7 @@ export const triggerWorkflowDescription = 'Trigger a workflow via workflow_dispa
 
 /** Not idempotent — each call starts a new workflow run. */
 export async function triggerWorkflowCore({ token, owner, repo, workflowId, ref, inputs }: { token: string, owner: string, repo: string, workflowId: string | number, ref: string, inputs?: Record<string, string> }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   await octokit.rest.actions.createWorkflowDispatch({
     owner,
     repo,
@@ -161,6 +165,7 @@ export async function triggerWorkflowCore({ token, owner, repo, workflowId, ref,
     inputs,
   })
   return { triggered: true, workflowId, ref }
+  })
 }
 
 export const cancelWorkflowRunInputSchema = z.object({
@@ -173,9 +178,10 @@ export const cancelWorkflowRunDescription = 'Cancel an in-progress workflow run'
 
 /** Not idempotent — cancelling an already-finished run is a no-op on GitHub but still mutates. */
 export async function cancelWorkflowRunCore({ token, owner, repo, runId }: { token: string, owner: string, repo: string, runId: number }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   await octokit.rest.actions.cancelWorkflowRun({ owner, repo, run_id: runId })
   return { cancelled: true, runId }
+  })
 }
 
 export const rerunWorkflowRunInputSchema = z.object({
@@ -189,11 +195,12 @@ export const rerunWorkflowRunDescription = 'Re-run a workflow run, optionally on
 
 /** Not idempotent — each call starts another run attempt. */
 export async function rerunWorkflowRunCore({ token, owner, repo, runId, onlyFailedJobs }: { token: string, owner: string, repo: string, runId: number, onlyFailedJobs: boolean }) {
-  const octokit = createOctokit(token)
+  return withOctokit(token, async (octokit) => {
   if (onlyFailedJobs) {
     await octokit.rest.actions.reRunWorkflowFailedJobs({ owner, repo, run_id: runId })
   } else {
     await octokit.rest.actions.reRunWorkflow({ owner, repo, run_id: runId })
   }
   return { rerun: true, runId, onlyFailedJobs }
+  })
 }
diff --git a/packages/github-tools/src/eve-runtime.ts b/packages/github-tools/src/eve-runtime.ts
index 59d5f7f..5e4364b 100644
--- a/packages/github-tools/src/eve-runtime.ts
+++ b/packages/github-tools/src/eve-runtime.ts
@@ -24,6 +24,7 @@ export type {
   EveToolOverrides,
 } from './eve/types'
 export type { GithubToolPreset, PresetToolName, CombinedPresetToolNames } from './core/presets'
+export type { GithubRateLimit } from './core/rate-limit'
 export type { GithubToolName } from './core/tool-names'
 export type { GithubWriteToolName } from './core/write-tools'
 export type { AllGithubTools, GithubToolsForPreset, PickGithubTools } from './core/tool-types'
diff --git a/packages/github-tools/src/eve/build.test.ts b/packages/github-tools/src/eve/build.test.ts
index c0b0686..11d2bb0 100644
--- a/packages/github-tools/src/eve/build.test.ts
+++ b/packages/github-tools/src/eve/build.test.ts
@@ -147,4 +147,34 @@ describe('createGithubTools eve integration', () => {
       },
     })
   })
+
+  it('strips rateLimit before applying a built-in formatter', () => {
+    expect(formatGithubEveToolOutput('getFileContent', {
+      type: 'file',
+      path: 'README.md',
+      sha: 'abc',
+      size: 5,
+      content: 'hello',
+      rateLimit: { remaining: 38, limit: 5000, reset: 1774800000, resource: 'core' },
+    })).toEqual({
+      type: 'json',
+      value: {
+        type: 'file',
+        path: 'README.md',
+        sha: 'abc',
+        size: 5,
+        content: 'hello',
+      },
+    })
+  })
+
+  it('returns stripped json for tools without a built-in formatter', () => {
+    expect(formatGithubEveToolOutput('getRepository', {
+      name: 'hello-world',
+      rateLimit: { remaining: 38, limit: 5000, reset: 1774800000 },
+    })).toEqual({
+      type: 'json',
+      value: { name: 'hello-world' },
+    })
+  })
 })
diff --git a/packages/github-tools/src/eve/build.ts b/packages/github-tools/src/eve/build.ts
index adbcaed..c311a86 100644
--- a/packages/github-tools/src/eve/build.ts
+++ b/packages/github-tools/src/eve/build.ts
@@ -76,7 +76,7 @@ export function buildEveToolDefinition(
     description: entry.description,
     inputSchema: entry.inputSchema,
     ...(approval && { approval }),
-    ...(entry.toModelOutput && { toModelOutput: entry.toModelOutput }),
+    toModelOutput: (output: unknown) => formatGithubEveToolOutput(name, output),
     execute: async (input) => runGithubToolStep(name, input as Record<string, unknown>, ctx),
   })
 
@@ -108,7 +108,7 @@ export function buildEveToolMap(options: EveGithubToolsOptions = {}): EveToolMap
       description: entry.description,
       inputSchema: entry.inputSchema,
       ...(approval && { approval }),
-      ...(entry.toModelOutput && { toModelOutput: entry.toModelOutput }),
+      toModelOutput: (output: unknown) => formatGithubEveToolOutput(entry.name, output),
       execute: async (input) => runGithubToolStep(entry.name, input as Record<string, unknown>, ctx),
     })
 
diff --git a/packages/github-tools/src/eve/registry.ts b/packages/github-tools/src/eve/registry.ts
index b8b623e..b3512cf 100644
--- a/packages/github-tools/src/eve/registry.ts
+++ b/packages/github-tools/src/eve/registry.ts
@@ -22,6 +22,7 @@ import * as releases from '../core/releases'
 import * as repository from '../core/repository'
 import * as search from '../core/search'
 import * as workflows from '../core/workflows'
+import { stripRateLimit } from '../core/rate-limit'
 import { resolveGithubToken, type GithubTokenInput } from '../core/token'
 import type { GithubWriteToolName } from '../core/write-tools'
 import type { GithubToolName } from '../core/tool-names'
@@ -79,14 +80,17 @@ export function hasGithubEveToolModelOutput(name: GithubToolName): boolean {
 
 /**
  * Apply the built-in eve `toModelOutput` projection for a tool.
+ * Strips `rateLimit` so it never reaches the model. Tools without a dedicated
+ * formatter get `{ type: 'json', value }` of the remaining payload.
  * Used by `@github-tools/eve-extension` so the callback only closes over a serializable tool name.
  */
 export function formatGithubEveToolOutput(name: GithubToolName, output: unknown): ToolModelOutput {
+  const stripped = stripRateLimit(output)
   const format = GITHUB_EVE_TOOL_MODEL_OUTPUT[name as keyof typeof GITHUB_EVE_TOOL_MODEL_OUTPUT]
   if (!format) {
-    throw new Error(`No toModelOutput formatter for GitHub tool: ${name}`)
+    return { type: 'json', value: stripped }
   }
-  return format(output)
+  return format(stripped)
 }
 
 export function createToolRegistry(ctx: ToolBuildContext): ToolRegistryEntry[] {
diff --git a/packages/github-tools/src/index.ts b/packages/github-tools/src/index.ts
index 62cdf58..cb022a7 100644
--- a/packages/github-tools/src/index.ts
+++ b/packages/github-tools/src/index.ts
@@ -14,7 +14,9 @@ import { listReleases, getLatestRelease, getRelease, createRelease, updateReleas
 import { getPullRequestContext, getIssueContext, getReleaseContext, getCiFailureContext } from './tools/bundles'
 import { resolveAiSdkApproval } from './core/approval'
 import { bindToolsContext } from './core/context'
+import { stripRateLimit } from './core/rate-limit'
 import { resolvePresetTools, type CombinedPresetToolNames, type GithubToolPreset, type PresetToolName } from './core/presets'
+import type { GithubTool } from './types'
 import { type GithubToolName } from './core/tool-names'
 import { type AllGithubTools, type GithubToolsBaseOptions } from './core/tool-types'
 import { createGithubTokenResolver } from './core/token'
@@ -203,7 +205,12 @@ export function createGithubTools({
     }
   }
 
-  const scoped = bindToolsContext(allTools, context)
+  const scoped = bindToolsContext(
+    Object.fromEntries(
+      Object.entries(allTools).map(([name, tool]) => [name, withStrippedRateLimit(tool)]),
+    ) as typeof allTools,
+    context,
+  )
 
   if (!allowed) return scoped
 
@@ -212,6 +219,18 @@ export function createGithubTools({
   ) as Pick<typeof scoped, GithubToolName>
 }
 
+function withStrippedRateLimit(tool: GithubTool): GithubTool {
+  const inner = tool.toModelOutput
+  return {
+    ...tool,
+    toModelOutput: (options) => {
+      const next = { ...options, output: stripRateLimit(options.output) }
+      if (inner) return inner(next)
+      return { type: 'json' as const, value: next.output }
+    },
+  }
+}
+
 export type GithubTools = AllGithubTools & ToolSet
 
 // Re-export individual tool factories for cherry-picking
@@ -229,6 +248,7 @@ export { listWorkflows, listWorkflowRuns, getWorkflowRun, listWorkflowJobs, trig
 export { listCheckRuns, getCombinedStatus } from './tools/checks'
 export { listReleases, getLatestRelease, getRelease, createRelease, updateRelease, deleteRelease } from './tools/releases'
 export { getPullRequestContext, getIssueContext, getReleaseContext, getCiFailureContext } from './tools/bundles'
+export type { GithubRateLimit } from './core/rate-limit'
 export type { CommitIdentity, CommitToolOptions, GithubTool, Octokit, ToolOptions, ToolOverrides } from './types'
 export type { GithubTokenInput } from './core/token'
 export { resolveGithubToken } from './core/token'

From 64f60a28d201cb2bdd81eef739d5bba5670fc45c Mon Sep 17 00:00:00 2001
From: Hugo <hugo.richard@vercel.com>
Date: Wed, 26 Aug 2026 11:16:39 +0200
Subject: [PATCH 2/2] Update packages/github-tools/src/core/rate-limit.ts

Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
---
 packages/github-tools/src/core/rate-limit.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/github-tools/src/core/rate-limit.ts b/packages/github-tools/src/core/rate-limit.ts
index 73fc82f..b4fa8ad 100644
--- a/packages/github-tools/src/core/rate-limit.ts
+++ b/packages/github-tools/src/core/rate-limit.ts
@@ -92,7 +92,7 @@ function stripRateLimitDeep<T>(value: T): T {
   if (!isPlainObject(value)) return value
   const next = stripRateLimit({ ...value })
   return Object.fromEntries(
-    Object.entries(next).map(([key, child]) => [key, stripRateLimit(child)]),
+    Object.entries(next).map(([key, child]) => [key, stripRateLimitDeep(child)]),
   ) as T
 }