typeclaw 0.24.0 → 0.25.0

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

@@ -83,9 +83,9 @@ export function createChannelReplyTool({
       resolve_review_thread: Type.Optional(
         Type.Boolean({
           description:
-            'GitHub only. Set `true` when this reply acknowledges that a review-comment thread YOU authored has been addressed, to resolve (close) that thread atomically with the reply. ' +
-            'The thread is resolved BEFORE the acknowledgement is posted, and only if its root comment is yours — so it never closes a human reviewer\'s thread, and a failed resolve blocks the misleading "looks resolved" reply. ' +
-            'Valid only on a github session replying inside a thread (the origin must carry a `thread`). Ignored elsewhere.',
+            'GitHub review threads ONLY — ignored on Slack, Discord, Telegram, KakaoTalk, and any non-github session, and ignored on a github reply that is not inside a `thread`. On those, leave this unset and ignore the rest of this description. ' +
+            'On a github reply inside a review thread you authored: when your `text` acknowledges the concern is fixed/verified/addressed (e.g. "verified at <sha>", "thanks, that resolves it"), treat setting this `true` as the expected close-out — do it in the SAME call. This is a strong instruction, not a schema requirement: the field stays optional and nothing rejects an acknowledgement that omits it, but a bare ack without it leaves the thread open, because a successful reply ends the turn and the resolve cannot run in a later one. So this flag is the only way the close-out actually happens. ' +
+            "It is safe to set by default: the runtime resolves BEFORE posting and ONLY if the thread's root comment is yours — it refuses (and blocks the reply) on a human reviewer's thread, so you never close someone else's open question. You need not pre-check authorship; just set it on your acknowledgement and let the runtime enforce ownership. Leave it unset when you intend to keep the thread open (partial fix, disagreement, mid-discussion).",
         }),
       ),
     }),

package/src/agent/tools/curl-impersonate.ts

@@ -101,7 +101,7 @@ export async function curlImpersonate(req: CurlImpersonateRequest): Promise<Curl
   const method = req.method ?? 'GET'
 
   // Per-request random sentinel + UTF-8-safe parsing. The static sentinel
-  // approach (previous revision) had a hardening hole: webfetch reads
+  // approach (previous revision) had a hardening hole: web_fetch reads
   // attacker-controlled pages, and a static sentinel is a public, fixed
   // string. A page could include the sentinel byte sequence plus fabricated
   // metadata before the real write-out tail and `indexOf` would split at
@@ -137,7 +137,7 @@ export async function curlImpersonate(req: CurlImpersonateRequest): Promise<Curl
     '--proto-redir',
     '=http,https',
     // `--fail-with-body` would make curl exit non-zero on >=400 but still
-    // write the body. We intentionally DO NOT pass it: callers (webfetch,
+    // write the body. We intentionally DO NOT pass it: callers (web_fetch,
     // ddg) want to inspect httpStatus themselves and decide. Curl exits 0
     // on a 404-with-body in this mode, which matches our contract.
     '--compressed',

package/src/agent/tools/spawn-subagent.ts

@@ -7,7 +7,7 @@ import type { PermissionService } from '@/permissions'
 import type { Stream } from '@/stream'
 
 import { type LiveSubagentRegistry, type SubagentCompletion } from '../live-subagents'
-import type { SessionOrigin } from '../session-origin'
+import { MAX_SUBAGENT_DEPTH, type SessionOrigin, subagentDepth } from '../session-origin'
 import { type CreateSessionForSubagent, type Subagent, type SubagentRegistry, startSubagent } from '../subagents'
 
 export const SPAWN_TASK_ID_PREFIX = 'bg_'
@@ -95,6 +95,16 @@ export function createSpawnSubagentTool(options: CreateSpawnSubagentToolOptions)
       if (!hasPermissionForSubagent(permissions, origin, params.subagent_type, subagent)) {
         return errorResult('subagent.spawn denied: insufficient permissions')
       }
+      // Fail closed past the chain-length ceiling. The tool is present on
+      // subagent sessions (operator/reviewer can delegate), but a session
+      // already at MAX_SUBAGENT_DEPTH cannot spawn a deeper one — this is the
+      // execute-time guard against runaway recursion, robust to tool-surface
+      // drift and serialized-origin resumes.
+      if (subagentDepth(origin) >= MAX_SUBAGENT_DEPTH) {
+        return errorResult(
+          `subagent.spawn denied: maximum delegation depth (${MAX_SUBAGENT_DEPTH}) reached; a subagent at this depth cannot spawn further subagents`,
+        )
+      }
 
       const taskId = generateTaskId()
       const subagentName = params.subagent_type
@@ -136,6 +146,11 @@ export function createSpawnSubagentTool(options: CreateSpawnSubagentToolOptions)
       }
       liveRegistry.register(live)
 
+      const channelKey =
+        origin?.kind === 'channel'
+          ? { adapter: origin.adapter, workspace: origin.workspace, chat: origin.chat, thread: origin.thread }
+          : undefined
+
       void completion.then((c) => {
         const durationMs = now() - startedAt
         liveRegistry.recordCompletion(taskId, completionToFinalShape(c, durationMs))
@@ -150,6 +165,7 @@ export function createSpawnSubagentTool(options: CreateSpawnSubagentToolOptions)
               ok: c.ok,
               durationMs,
               ...(c.ok ? {} : { error: c.error }),
+              ...(channelKey !== undefined ? { channelKey } : {}),
             },
           })
         }
@@ -218,7 +234,8 @@ export function spawnSubagentDescription(registry: SubagentRegistry): string {
     `When run_in_background=true (preferred for long-running work), the tool returns a task_id immediately and the subagent runs concurrently — ` +
     `you will receive a system-reminder when it completes; do NOT poll subagent_output. ` +
     `When run_in_background=false (default), the tool blocks and returns the subagent's final message synchronously. ` +
-    `Subagents cannot recursively spawn other subagents.`
+    `The delegation chain is depth-limited: a subagent you spawn may itself delegate once more, but no deeper — ` +
+    `keep your delegation tree shallow.`
   )
 }
 

package/src/agent/tools/subagent-access.ts

@@ -13,27 +13,46 @@ export type AuthorizeLiveSubagentAccessArgs = {
   liveRegistry: LiveSubagentRegistry
   taskId: string
   permission: SubagentAccessPermission
+  // The caller's own session id. When the caller is itself a subagent, access
+  // is scoped to subagents IT spawned (live.parentSessionId === callerSessionId)
+  // so a nested subagent cannot read or cancel siblings or parent-branch runs.
+  // Omitted by main-session callers, which keep the role-severity cap only.
+  callerSessionId?: string
 }
 
 // Authorizes a single subagent_output/subagent_cancel call and resolves the
-// live entry in one place so the two tools cannot drift. Caps access to the
-// requester's role: the caller must hold the permission AND resolve to a role
-// at least as high as the role that spawned the subagent.
+// live entry in one place so the two tools cannot drift. Two authorization
+// modes, both requiring the base permission first:
+//   - SUBAGENT caller: scoped to runs it spawned (live.parentSessionId ===
+//     callerSessionId). Ownership is the authorization; the role cap is skipped.
+//   - MAIN-SESSION caller: capped to the requester's role — must resolve to a
+//     role at least as high as the role that spawned the subagent.
 //
 // The ordering closes an existence oracle: the task-independent base-permission
 // check runs BEFORE any registry lookup, and for non-owner callers an absent
 // task, a capped task, and a task with missing provenance all collapse to one
 // identical denial — so a lower-role caller cannot probe which task IDs are
 // live. Only `owner` (the trust root, which outranks every spawner) learns the
-// truthful `Unknown task_id` for a genuine miss. The cap fails closed.
+// truthful `Unknown task_id` for a genuine miss. Both modes fail closed.
 export function authorizeLiveSubagentAccess(args: AuthorizeLiveSubagentAccessArgs): SubagentAccessResult {
-  const { permissions, origin, liveRegistry, taskId, permission } = args
+  const { permissions, origin, liveRegistry, taskId, permission, callerSessionId } = args
+
+  // A subagent caller may only touch subagents it spawned itself — never a
+  // sibling's or its parent's run. For subagent callers this ownership check
+  // REPLACES the role-severity cap (see the ownershipScoped branch below);
+  // main-session callers (subagent origin absent) skip it and fall through to
+  // the role cap, preserving the operator's global visibility over every spawn.
+  const ownershipScoped = origin?.kind === 'subagent'
+  const opaqueOwnershipDenial = `${permission} denied: unknown task_id or not owned by caller`
 
   if (permissions === undefined) {
     const live = liveRegistry.get(taskId)
     if (live === undefined) {
       return { ok: false, message: `Unknown task_id: ${taskId}.` }
     }
+    if (ownershipScoped && live.parentSessionId !== callerSessionId) {
+      return { ok: false, message: opaqueOwnershipDenial }
+    }
     return { ok: true, live }
   }
 
@@ -43,6 +62,22 @@ export function authorizeLiveSubagentAccess(args: AuthorizeLiveSubagentAccessArg
 
   const requesterRole = permissions.resolveRole(origin)
   const accessAll = requesterRole === 'owner'
+
+  // For a subagent caller, ownership of the run IS the authorization: having
+  // passed the base permission check above, it may manage exactly the children
+  // it spawned. The role-severity cap (below) does NOT apply — a deep subagent
+  // that inherited a low role from, say, a guest channel turn must still be
+  // able to read/cancel its own children; the cap is meant to stop a low-role
+  // MAIN session from reaching a higher-role-spawned run, which ownership
+  // already prevents here. A non-owning subagent caller fails closed.
+  if (ownershipScoped) {
+    const live = liveRegistry.get(taskId)
+    if (live === undefined || live.parentSessionId !== callerSessionId) {
+      return { ok: false, message: opaqueOwnershipDenial }
+    }
+    return { ok: true, live }
+  }
+
   const opaqueDenial = `${permission} denied: unknown task_id or insufficient role`
 
   const live = liveRegistry.get(taskId)

package/src/agent/tools/subagent-cancel.ts

@@ -15,10 +15,11 @@ export type CreateSubagentCancelToolOptions = {
   liveRegistry: LiveSubagentRegistry
   getOrigin: () => SessionOrigin | undefined
   permissions?: PermissionService
+  callerSessionId?: string
 }
 
 export function createSubagentCancelTool(options: CreateSubagentCancelToolOptions) {
-  const { liveRegistry, getOrigin, permissions } = options
+  const { liveRegistry, getOrigin, permissions, callerSessionId } = options
 
   return defineTool({
     name: 'subagent_cancel',
@@ -40,6 +41,7 @@ export function createSubagentCancelTool(options: CreateSubagentCancelToolOption
         liveRegistry,
         taskId: params.task_id,
         permission: 'subagent.cancel',
+        ...(callerSessionId !== undefined ? { callerSessionId } : {}),
       })
       if (!access.ok) {
         return errorResult(access.message)

package/src/agent/tools/subagent-output.ts

@@ -7,6 +7,8 @@ import type { LiveSubagentRegistry, StatusSnapshot, SubagentProgressEvent } from
 import type { SessionOrigin } from '../session-origin'
 import { authorizeLiveSubagentAccess } from './subagent-access'
 
+export const SUBAGENT_OUTPUT_TOOL_NAME = 'subagent_output'
+
 export type SubagentOutputToolDetails =
   | {
       ok: true
@@ -42,14 +44,15 @@ export type CreateSubagentOutputToolOptions = {
   liveRegistry: LiveSubagentRegistry
   getOrigin: () => SessionOrigin | undefined
   permissions?: PermissionService
+  callerSessionId?: string
   now?: () => number
 }
 
 export function createSubagentOutputTool(options: CreateSubagentOutputToolOptions) {
-  const { liveRegistry, getOrigin, permissions, now = () => Date.now() } = options
+  const { liveRegistry, getOrigin, permissions, callerSessionId, now = () => Date.now() } = options
 
   return defineTool({
-    name: 'subagent_output',
+    name: SUBAGENT_OUTPUT_TOOL_NAME,
     label: 'Subagent Output',
     description:
       'Fetch the current state of a subagent you previously spawned. Returns one of three statuses: ' +
@@ -71,6 +74,7 @@ export function createSubagentOutputTool(options: CreateSubagentOutputToolOption
         liveRegistry,
         taskId: params.task_id,
         permission: 'subagent.output',
+        ...(callerSessionId !== undefined ? { callerSessionId } : {}),
       })
       if (!access.ok) {
         return errorResult(access.message)

package/src/agent/tools/webfetch/fetch.ts

@@ -1,4 +1,4 @@
-// Webfetch's HTTP transport.
+// WebFetch's HTTP transport.
 //
 // Production path (container, curl-impersonate available): we shell out to
 // `curl_chrome136` so outbound requests carry Chrome 136's TLS handshake
@@ -17,7 +17,7 @@
 //
 // Best-effort doctrine: this transport does NOT guarantee the fetch succeeds.
 // Bot-detected sites can still serve 403/CAPTCHA pages. We surface what we
-// got (status, body, final URL) and let the caller decide. The webfetch tool
+// got (status, body, final URL) and let the caller decide. The web_fetch tool
 // translates non-2xx into a tool-level error message that's useful to the
 // model.
 
@@ -38,10 +38,10 @@ export type FetchResult = {
   bytesIn: number
 }
 
-export class WebfetchError extends Error {
+export class WebFetchError extends Error {
   constructor(message: string) {
     super(message)
-    this.name = 'WebfetchError'
+    this.name = 'WebFetchError'
   }
 }
 
@@ -55,7 +55,7 @@ export function normalizeUrl(input: string): string {
   const trimmed = input.trim()
   if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) {
     if (!trimmed.startsWith('http://') && !trimmed.startsWith('https://')) {
-      throw new WebfetchError('URL must use http:// or https://')
+      throw new WebFetchError('URL must use http:// or https://')
     }
     return trimmed
   }
@@ -100,28 +100,28 @@ async function fetchWithCurlImpersonate(
     })
   } catch (error) {
     if (parentSignal?.aborted) {
-      throw new WebfetchError('Request aborted')
+      throw new WebFetchError('Request aborted')
     }
     if (error instanceof CurlImpersonateError) {
       if (isCurlExitTimeout(error)) {
-        throw new WebfetchError(`Request timed out after ${timeoutSeconds}s`)
+        throw new WebFetchError(`Request timed out after ${timeoutSeconds}s`)
       }
       if (isCurlExitFilesizeExceeded(error)) {
-        throw new WebfetchError(`Response too large (exceeds ${formatBytes(MAX_RESPONSE_BYTES)} limit)`)
+        throw new WebFetchError(`Response too large (exceeds ${formatBytes(MAX_RESPONSE_BYTES)} limit)`)
       }
-      throw new WebfetchError(`Fetch failed: ${error.message}`)
+      throw new WebFetchError(`Fetch failed: ${error.message}`)
     }
     const message = error instanceof Error ? error.message : String(error)
-    throw new WebfetchError(`Fetch failed: ${message}`)
+    throw new WebFetchError(`Fetch failed: ${message}`)
   }
 
   if (response.httpStatus < 200 || response.httpStatus >= 300) {
-    throw new WebfetchError(`Fetch failed: HTTP ${response.httpStatus}`)
+    throw new WebFetchError(`Fetch failed: HTTP ${response.httpStatus}`)
   }
 
   const bodyByteLength = new TextEncoder().encode(response.body).byteLength
   if (bodyByteLength > MAX_RESPONSE_BYTES) {
-    throw new WebfetchError(
+    throw new WebFetchError(
       `Response too large (${formatBytes(bodyByteLength)} exceeds ${formatBytes(MAX_RESPONSE_BYTES)} limit)`,
     )
   }
@@ -148,14 +148,14 @@ async function fetchWithBunFetch(
   try {
     const response = await fetch(url, { headers: FALLBACK_HEADERS, signal: controller.signal, redirect: 'follow' })
     if (!response.ok) {
-      throw new WebfetchError(`Fetch failed: HTTP ${response.status} ${response.statusText}`)
+      throw new WebFetchError(`Fetch failed: HTTP ${response.status} ${response.statusText}`)
     }
 
     const contentLengthHeader = response.headers.get('content-length')
     if (contentLengthHeader) {
       const declared = Number(contentLengthHeader)
       if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
-        throw new WebfetchError(
+        throw new WebFetchError(
           `Response too large (${formatBytes(declared)} exceeds ${formatBytes(MAX_RESPONSE_BYTES)} limit)`,
         )
       }
@@ -163,7 +163,7 @@ async function fetchWithBunFetch(
 
     const buffer = await response.arrayBuffer()
     if (buffer.byteLength > MAX_RESPONSE_BYTES) {
-      throw new WebfetchError(
+      throw new WebFetchError(
         `Response too large (${formatBytes(buffer.byteLength)} exceeds ${formatBytes(MAX_RESPONSE_BYTES)} limit)`,
       )
     }
@@ -182,11 +182,11 @@ async function fetchWithBunFetch(
       controller.signal.reason instanceof Error &&
       controller.signal.reason.message === 'timeout'
     ) {
-      throw new WebfetchError(`Request timed out after ${timeoutSeconds}s`)
+      throw new WebFetchError(`Request timed out after ${timeoutSeconds}s`)
     }
-    if (error instanceof WebfetchError) throw error
+    if (error instanceof WebFetchError) throw error
     const message = error instanceof Error ? error.message : String(error)
-    throw new WebfetchError(`Fetch failed: ${message}`)
+    throw new WebFetchError(`Fetch failed: ${message}`)
   } finally {
     clearTimeout(timeout)
     parentSignal?.removeEventListener('abort', onAbort)

package/src/agent/tools/webfetch/index.ts

@@ -1 +1 @@
-export { webfetchTool } from './tool'
+export { webFetchTool } from './tool'

package/src/agent/tools/webfetch/tool.ts

@@ -1,7 +1,7 @@
 import { Type } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
-import { fetchWithLimits, normalizeUrl, parseMimeType, WebfetchError } from './fetch'
+import { fetchWithLimits, normalizeUrl, parseMimeType, WebFetchError } from './fetch'
 import { applyGrep, GrepError } from './strategies/grep'
 import { applyJq, JqError } from './strategies/jq'
 import { applyRaw } from './strategies/raw'
@@ -13,17 +13,17 @@ import {
   DEFAULT_TIMEOUT_SECONDS,
   MAX_TIMEOUT_SECONDS,
   OUTPUT_CAPS,
-  type WebfetchDetails,
+  type WebFetchDetails,
 } from './types'
 
 const STRATEGY_VALUES = ['readability', 'jq', 'selector', 'grep', 'snapshot', 'raw'] as const
 
-export const webfetchTool = defineTool({
-  name: 'webfetch',
+export const webFetchTool = defineTool({
+  name: 'web_fetch',
   label: 'Web Fetch',
   description:
     'Fetch a single HTTP(S) URL and return the body, optionally compacted by a strategy. ' +
-    'Use this when the user references a specific URL or when websearch surfaced a result you need to read in full. ' +
+    'Use this when the user references a specific URL or when web_search surfaced a result you need to read in full. ' +
     'If `spawn_subagent` is available to you, PREFER delegating to the `scout` subagent by default: spawn it whenever you expect more than one fetch, an "across multiple sources" task, or any search-then-fetch loop. Scout runs the noisy fetching in its own context window and returns a distilled, citation-backed answer, keeping bulky page bodies out of yours. Only call this tool directly for a single known URL whose content you will cite immediately — or whenever you cannot spawn subagents (e.g. you are yourself a subagent), in which case fetch here. ' +
     'Outbound requests impersonate Chrome 136 at the TLS, HTTP/2, and header layers ' +
     '(via curl-impersonate), which helps with TLS/header fingerprint gates on sites behind Cloudflare/Akamai. ' +
@@ -72,7 +72,7 @@ export const webfetchTool = defineTool({
     try {
       normalizedUrl = normalizeUrl(inputUrl)
     } catch (error) {
-      const message = error instanceof WebfetchError ? error.message : `Invalid URL: ${error}`
+      const message = error instanceof WebFetchError ? error.message : `Invalid URL: ${error}`
       return errorResult(inputUrl, message, { startedAt })
     }
 
@@ -130,7 +130,7 @@ export const webfetchTool = defineTool({
     }
 
     const capped = capOutput(output, strategy)
-    const details: WebfetchDetails = {
+    const details: WebFetchDetails = {
       url: normalizedUrl,
       finalUrl: response.finalUrl,
       strategy,
@@ -150,7 +150,7 @@ export const webfetchTool = defineTool({
   },
 })
 
-type WebfetchParams = {
+type WebFetchParams = {
   url: string
   strategy?: CompactionStrategy
   query?: string
@@ -187,7 +187,7 @@ function resolveStrategy(explicit: CompactionStrategy | undefined, mime: string)
   return { kind: 'ok', strategy: 'raw', autoDetected: true }
 }
 
-function validateStrategyArgs(strategy: CompactionStrategy, params: WebfetchParams): string | null {
+function validateStrategyArgs(strategy: CompactionStrategy, params: WebFetchParams): string | null {
   if (strategy === 'jq' && !params.query) return 'Missing required arg `query` for strategy "jq".'
   if (strategy === 'selector' && !params.selector) return 'Missing required arg `selector` for strategy "selector".'
   if (strategy === 'grep' && !params.pattern) return 'Missing required arg `pattern` for strategy "grep".'
@@ -198,7 +198,7 @@ async function runStrategy(
   strategy: CompactionStrategy,
   body: string,
   url: string,
-  params: WebfetchParams,
+  params: WebFetchParams,
 ): Promise<string> {
   switch (strategy) {
     case 'raw':
@@ -250,10 +250,10 @@ function capOutput(text: string, strategy: CompactionStrategy): { text: string;
 function errorResult(
   url: string,
   message: string,
-  partial: Partial<WebfetchDetails> & { startedAt: number },
-): { content: [{ type: 'text'; text: string }]; details: WebfetchDetails } {
+  partial: Partial<WebFetchDetails> & { startedAt: number },
+): { content: [{ type: 'text'; text: string }]; details: WebFetchDetails } {
   const { startedAt, ...rest } = partial
-  const details: WebfetchDetails = {
+  const details: WebFetchDetails = {
     url,
     finalUrl: rest.finalUrl ?? url,
     strategy: rest.strategy ?? 'none',

package/src/agent/tools/webfetch/types.ts

@@ -1,6 +1,6 @@
 export type CompactionStrategy = 'readability' | 'jq' | 'selector' | 'grep' | 'snapshot' | 'raw'
 
-export type WebfetchDetails = {
+export type WebFetchDetails = {
   url: string
   finalUrl: string
   strategy: CompactionStrategy | 'none'

package/src/agent/tools/websearch.ts

@@ -7,7 +7,7 @@ import { wikipediaSearch, type WikipediaResult } from './wikipedia'
 const DEFAULT_LIMIT = 10
 const MAX_LIMIT = 20
 
-type WebsearchDetails = {
+type WebSearchDetails = {
   query: string
   source: 'web' | 'wikipedia' | 'none'
   count: number
@@ -16,12 +16,12 @@ type WebsearchDetails = {
   message?: string
 }
 
-export const websearchTool = defineTool({
-  name: 'websearch',
+export const webSearchTool = defineTool({
+  name: 'web_search',
   label: 'Web Search',
   description:
     'Search the public web. Returns a ranked list of {title, url, snippet} entries. Use `source: "wikipedia"` for encyclopedic lookups; otherwise default to general web results from DuckDuckGo. Pair this with the `read` tool by visiting URLs you find with `bash` (curl) when you need full page contents.\n' +
-    'If `spawn_subagent` is available to you, PREFER delegating to the `scout` subagent by default: spawn it whenever the research is non-trivial (more than 1-2 queries, any "across multiple sources" framing, or follow-up fetches of the results). Scout runs `websearch`/`webfetch` in its own context window and returns a distilled, citation-backed answer, so the search churn never pollutes yours. Only call this tool directly for a single query whose top result you will cite immediately — or whenever you cannot spawn subagents (e.g. you are yourself a subagent), in which case run the searches here.',
+    'If `spawn_subagent` is available to you, PREFER delegating to the `scout` subagent by default: spawn it whenever the research is non-trivial (more than 1-2 queries, any "across multiple sources" framing, or follow-up fetches of the results). Scout runs `web_search`/`web_fetch` in its own context window and returns a distilled, citation-backed answer, so the search churn never pollutes yours. Only call this tool directly for a single query whose top result you will cite immediately — or whenever you cannot spawn subagents (e.g. you are yourself a subagent), in which case run the searches here.',
   parameters: Type.Object({
     query: Type.String({ description: 'The search query.' }),
     limit: Type.Optional(
@@ -66,7 +66,7 @@ function clampLimit(value: number | undefined): number {
 }
 
 function successResult(query: string, source: 'web' | 'wikipedia', results: DdgResult[] | WikipediaResult[]) {
-  const details: WebsearchDetails = { query, source, count: results.length, results }
+  const details: WebSearchDetails = { query, source, count: results.length, results }
   if (results.length === 0) {
     return {
       content: [{ type: 'text' as const, text: `No results for "${query}" on ${source}.` }],
@@ -89,7 +89,7 @@ function successResult(query: string, source: 'web' | 'wikipedia', results: DdgR
 }
 
 function errorResult(message: string) {
-  const details: WebsearchDetails = { query: '', source: 'none', count: 0, results: [], error: true, message }
+  const details: WebSearchDetails = { query: '', source: 'none', count: 0, results: [], error: true, message }
   return {
     content: [{ type: 'text' as const, text: message }],
     details,

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

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 
+import { withGitLock } from '@/git/mutex'
 import { definePlugin, type PluginContext, type SpawnSubagentOptions, type Subagent } from '@/plugin'
 
 import { COMMIT_TIMEOUT_MS, makeDefaultGitSpawn, NETWORK_TIMEOUT_MS, runBackup, type BackupResult } from './runner'
@@ -174,44 +175,46 @@ async function runBackupOnce(
     spawnedByOrigin: { kind: 'tui', sessionId: 'backup-runner' },
   }
 
-  const result = await runBackup(
-    { cwd: payload.agentDir, pushToOrigin: payload.pushToOrigin },
-    {
-      gitSpawn: makeDefaultGitSpawn(),
-      pickCommitMessage: async ({ status, diffstat }) => {
-        await cleanupMessageFile(messagePath)
-        const messagePayload: CommitMessagePayload = {
-          agentDir: payload.agentDir,
-          status,
-          diffstat,
-          outputPath: messagePath,
-        }
-        try {
-          await ctx.spawnSubagent(SUBAGENT_COMMIT_MESSAGE, messagePayload, inheritOwner)
-        } catch (err) {
-          ctx.logger.warn(
-            `${SUBAGENT_COMMIT_MESSAGE} subagent failed, using fallback: ${err instanceof Error ? err.message : String(err)}`,
-          )
-        }
-        const written = await readMessageFile(messagePath)
-        await cleanupMessageFile(messagePath)
-        return written ?? 'chore: backup'
-      },
-      diagnoseFailure: async (input) => {
-        const diagPayload: DiagnoseFailurePayload = {
-          agentDir: input.cwd,
-          stage: input.stage,
-          exitCode: input.exitCode,
-          stderr: input.stderr,
-          stdout: input.stdout,
-        }
-        try {
-          await ctx.spawnSubagent(SUBAGENT_DIAGNOSE, diagPayload, inheritOwner)
-        } catch (err) {
-          ctx.logger.warn(`${SUBAGENT_DIAGNOSE} subagent failed: ${err instanceof Error ? err.message : String(err)}`)
-        }
+  const result = await withGitLock(payload.agentDir, () =>
+    runBackup(
+      { cwd: payload.agentDir, pushToOrigin: payload.pushToOrigin },
+      {
+        gitSpawn: makeDefaultGitSpawn(),
+        pickCommitMessage: async ({ status, diffstat }) => {
+          await cleanupMessageFile(messagePath)
+          const messagePayload: CommitMessagePayload = {
+            agentDir: payload.agentDir,
+            status,
+            diffstat,
+            outputPath: messagePath,
+          }
+          try {
+            await ctx.spawnSubagent(SUBAGENT_COMMIT_MESSAGE, messagePayload, inheritOwner)
+          } catch (err) {
+            ctx.logger.warn(
+              `${SUBAGENT_COMMIT_MESSAGE} subagent failed, using fallback: ${err instanceof Error ? err.message : String(err)}`,
+            )
+          }
+          const written = await readMessageFile(messagePath)
+          await cleanupMessageFile(messagePath)
+          return written ?? 'chore: backup'
+        },
+        diagnoseFailure: async (input) => {
+          const diagPayload: DiagnoseFailurePayload = {
+            agentDir: input.cwd,
+            stage: input.stage,
+            exitCode: input.exitCode,
+            stderr: input.stderr,
+            stdout: input.stdout,
+          }
+          try {
+            await ctx.spawnSubagent(SUBAGENT_DIAGNOSE, diagPayload, inheritOwner)
+          } catch (err) {
+            ctx.logger.warn(`${SUBAGENT_DIAGNOSE} subagent failed: ${err instanceof Error ? err.message : String(err)}`)
+          }
+        },
       },
-    },
+    ),
   )
 
   await cleanupMessageFile(messagePath)

package/src/bundled-plugins/backup/runner.ts

@@ -217,7 +217,7 @@ function sanitizeCommitMessage(raw: string): string {
 }
 
 export function makeDefaultGitSpawn(): GitSpawn {
-  return async (args, { cwd, timeoutMs }) => {
+  return withIndexLockRetry(async (args, { cwd, timeoutMs }) => {
     const bun = (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
     if (!bun) {
       return { exitCode: 127, stdout: '', stderr: 'Bun runtime not available', timedOut: false }
@@ -249,5 +249,26 @@ export function makeDefaultGitSpawn(): GitSpawn {
     } finally {
       clearTimeout(timer)
     }
+  })
+}
+
+export function withIndexLockRetry(spawn: GitSpawn): GitSpawn {
+  return async (args, opts) => {
+    let result = await spawn(args, opts)
+    for (const delayMs of [50, 150, 350]) {
+      if (result.exitCode === 0 || !isIndexLockContention(result.stderr)) return result
+      await sleep(delayMs)
+      result = await spawn(args, opts)
+    }
+    return result
   }
 }
+
+function isIndexLockContention(stderr: string): boolean {
+  const lower = stderr.toLowerCase()
+  return lower.includes('index.lock') || (lower.includes('unable to create') && lower.includes('index.lock'))
+}
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise<void>((resolve) => setTimeout(resolve, ms))
+}