typeclaw 0.23.0 → 0.25.0

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

@@ -0,0 +1,119 @@
+import { Type } from '@mariozechner/pi-ai'
+import { defineTool } from '@mariozechner/pi-coding-agent'
+
+import type { SessionOrigin } from '@/agent/session-origin'
+import { resolveTodoScope, type TodoScope } from '@/agent/todo/scope'
+import { incompleteTodos, type Todo, TODO_PRIORITIES, TODO_STATUSES, readTodos, writeTodos } from '@/agent/todo/store'
+
+export type CreateTodoToolsOptions = {
+  agentDir: string
+  getOrigin: () => SessionOrigin | undefined
+}
+
+const NO_SCOPE_NOTICE =
+  'Todos are owned by the originating session. This session (a subagent, system task, or one ' +
+  'with no resolvable origin) does not own a todo list, so the call was a no-op.'
+
+type TodoToolDetails = {
+  ok: boolean
+  reason?: string
+  total?: number
+  remaining?: number
+}
+
+// Resolve the scope for the current origin, or null when this session owns no
+// todo list. An UNDEFINED origin is treated as no-scope, NOT defaulted to the
+// shared TUI scope — defaulting would fail open, silently routing an unknown
+// actor's todos into the operator's global `tui` list.
+function scopeForOrigin(getOrigin: () => SessionOrigin | undefined): TodoScope | null {
+  const origin = getOrigin()
+  return origin === undefined ? null : resolveTodoScope(origin)
+}
+
+const TODO_ITEM = Type.Object({
+  content: Type.String({ minLength: 1, description: 'What the task is.' }),
+  status: Type.Union(
+    TODO_STATUSES.map((s) => Type.Literal(s)),
+    { description: 'One of: pending, in_progress, completed, cancelled.' },
+  ),
+  priority: Type.Optional(Type.Union(TODO_PRIORITIES.map((p) => Type.Literal(p)))),
+  id: Type.Optional(Type.String()),
+})
+
+export function createTodoTools({ agentDir, getOrigin }: CreateTodoToolsOptions) {
+  const writeTool = defineTool({
+    name: 'todo_write',
+    label: 'Write Todos',
+    description:
+      'Replace your entire todo list for this session with the provided items. Maintain a todo ' +
+      'list for any multi-step or long-running task so that if this session is interrupted ' +
+      '(restart, crash, or a later turn), you can resume the remaining work instead of silently ' +
+      'dropping it. Mark items `completed` (or `cancelled`) as you finish them by writing the full ' +
+      'list again with updated statuses. This is a full replace, not a merge: include every item ' +
+      'you still care about on each call.',
+    parameters: Type.Object({
+      todos: Type.Array(TODO_ITEM, { description: 'The complete todo list. Replaces any prior list.' }),
+    }),
+    async execute(_toolCallId, params) {
+      const scope = scopeForOrigin(getOrigin)
+      if (scope === null) {
+        const details: TodoToolDetails = { ok: false, reason: 'no-scope' }
+        return { content: [{ type: 'text' as const, text: NO_SCOPE_NOTICE }], details }
+      }
+      const todos = params.todos as Todo[]
+      await writeTodos(agentDir, scope, todos)
+      const remaining = incompleteTodos(todos).length
+      const details: TodoToolDetails = { ok: true, total: todos.length, remaining }
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Saved ${todos.length} todo(s); ${remaining} remaining (${todos.length - remaining} done).`,
+          },
+        ],
+        details,
+      }
+    },
+  })
+
+  const readTool = defineTool({
+    name: 'todo_read',
+    label: 'Read Todos',
+    description: 'Return your current todo list for this session. Use it to re-sync after an interruption.',
+    parameters: Type.Object({}),
+    async execute() {
+      const scope = scopeForOrigin(getOrigin)
+      if (scope === null) {
+        const details: TodoToolDetails = { ok: false, reason: 'no-scope' }
+        return { content: [{ type: 'text' as const, text: NO_SCOPE_NOTICE }], details }
+      }
+      const todos = await readTodos(agentDir, scope)
+      const details: TodoToolDetails = { ok: true, total: todos.length }
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(todos, null, 2) }],
+        details,
+      }
+    },
+  })
+
+  const clearTool = defineTool({
+    name: 'todo_clear',
+    label: 'Clear Todos',
+    description:
+      'Empty your todo list for this session. Call this when all work is genuinely done or the ' +
+      'task was abandoned, so the runtime stops tracking pending work.',
+    parameters: Type.Object({}),
+    async execute() {
+      const scope = scopeForOrigin(getOrigin)
+      if (scope === null) {
+        const details: TodoToolDetails = { ok: false, reason: 'no-scope' }
+        return { content: [{ type: 'text' as const, text: NO_SCOPE_NOTICE }], details }
+      }
+      await writeTodos(agentDir, scope, [])
+      const details: TodoToolDetails = { ok: true }
+      return { content: [{ type: 'text' as const, text: 'Todo list cleared.' }], details }
+    },
+  })
+
+  return [writeTool, readTool, clearTool]
+}

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

@@ -5,7 +5,7 @@ export const COMMIT_TIMEOUT_MS = 30_000
 export const NETWORK_TIMEOUT_MS = 60_000
 
 const RUNTIME_OWNED_PREFIXES = ['memory/'] as const
-const FORCE_ADD_PREFIXES = ['sessions/'] as const
+const FORCE_ADD_PREFIXES = ['sessions/', 'todo/'] as const
 
 const NONINTERACTIVE_ENV = {
   GIT_TERMINAL_PROMPT: '0',
@@ -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))
+}

package/src/bundled-plugins/github-cli-auth/gh-command.ts

@@ -281,7 +281,7 @@ function isCommandBoundaryBefore(tokens: readonly string[], index: number): bool
   while (cursor >= 0) {
     const prev = tokens[cursor]
     if (prev === undefined) return false
-    if (prev === '&&' || prev === '||' || prev === '|' || prev === ';') return true
+    if (prev === '&&' || prev === '||' || prev === '|' || prev === ';' || prev === '\n') return true
     if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(prev)) {
       cursor -= 1
       continue
@@ -409,11 +409,14 @@ function isPlaceholderSegment(segment: string): boolean {
   return segment.includes('{') || segment.includes('}')
 }
 
-// Splits on whitespace AND shell control operators (; | & && ||) so a boundary
-// like `true; gh ...` (no surrounding spaces) yields a standalone operator
-// token. Quote-aware: operators inside quotes are literal. This is a
-// command-position detector, not a full shell parser — it does not interpret
-// redirections, subshells, or backgrounding semantics beyond boundary marking.
+// Splits on whitespace AND shell control operators (newline ; | & && ||) so a
+// boundary like `true; gh ...` (no surrounding spaces) or a `gh` on its own line
+// yields a standalone separator token. A newline ends a simple command in bash,
+// so it must be a boundary too — otherwise a `gh` on a later line (e.g. after a
+// heredoc) is not seen at command position and escapes classification. Quote-
+// aware: operators inside quotes are literal. This is a command-position
+// detector, not a full shell parser — it does not interpret redirections,
+// subshells, heredoc bodies, or backgrounding semantics beyond boundary marking.
 function tokenize(command: string): string[] {
   const tokens: string[] = []
   let current = ''
@@ -441,10 +444,15 @@ function tokenize(command: string): string[] {
       hasContent = true
       continue
     }
-    if (ch === ' ' || ch === '\t' || ch === '\n') {
+    if (ch === ' ' || ch === '\t') {
       flush()
       continue
     }
+    if (ch === '\n') {
+      flush()
+      tokens.push('\n')
+      continue
+    }
     if (ch === ';' || ch === '|' || ch === '&') {
       flush()
       const next = command[i + 1]

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

@@ -43,15 +43,27 @@ export async function checkNonWorkspaceWriteGuard(options: {
 
   const targetPath = path.resolve(agentDir, rawPath)
   const workspacePath = path.resolve(agentDir, 'workspace')
-  const [realTargetPath, realWorkspacePath] = await Promise.all([
+  const [realTargetPath, realWorkspacePath, realAgentDir, realTmpRoot] = await Promise.all([
     resolveRealIntendedPath(targetPath),
     resolveRealIntendedPath(workspacePath),
+    resolveRealIntendedPath(path.resolve(agentDir)),
+    resolveRealIntendedPath('/tmp'),
   ])
   if (await isSkillAuthoringAllowed({ tool, args, agentDir })) return undefined
   if (await isMemoryRetrievalCacheWriteAllowed({ tool, args, agentDir, origin })) return undefined
   if (await isMemoryTopicsWriteAllowed({ tool, args, agentDir, origin })) return undefined
   if (await isAllowedAgentRootWrite(agentDir, targetPath, realTargetPath)) return undefined
   if (isInside(realWorkspacePath, realTargetPath)) return undefined
+  // /tmp is virtual per-session scratch (see src/sandbox/session-tmp.ts), not a
+  // project or secret surface — throwaway, never committed, so an unacknowledged
+  // write is expected. Allowed only on LEXICAL intent: the model's raw path must
+  // itself be an absolute /tmp/... path. A relative path that merely realpaths
+  // into /tmp (e.g. `workspace/link` where `link -> /tmp/x`) is a workspace
+  // escape, not scratch, and must stay blocked by the rules above. The physical
+  // target must also still resolve under real /tmp (blocks `/tmp/../agent/.env`
+  // and a `/tmp/link -> /agent/.env`) and must not land inside the agent dir
+  // (a container/test agent dir can itself sit under /tmp).
+  if (isTmpScratchWrite(rawPath, realTargetPath, realAgentDir, realTmpRoot)) return undefined
   if (isGuardAcknowledged(args, GUARD_NON_WORKSPACE_WRITE)) return undefined
 
   return {
@@ -77,6 +89,31 @@ async function isAllowedAgentRootWrite(agentDir: string, targetPath: string, rea
   return false
 }
 
+// `rawPath`: the model's RAW path normalized; only an absolute /tmp/... path
+// counts as scratch intent (a relative workspace path that escapes into /tmp is
+// handled by the escape rules above, never here). `realTargetPath`: the
+// realpath-resolved physical target — must still land under /tmp (not /agent via
+// `..` or a planted symlink) and must not land inside the agent dir.
+function isTmpScratchWrite(
+  rawPath: string,
+  realTargetPath: string,
+  realAgentDir: string,
+  realTmpRoot: string,
+): boolean {
+  const normalizedRaw = path.normalize(rawPath)
+  const rawIsAbsoluteTmp = normalizedRaw === '/tmp' || isInside('/tmp', normalizedRaw)
+  if (!rawIsAbsoluteTmp) return false
+
+  // Compare against the REALPATH of /tmp, not the literal: on macOS /tmp is a
+  // symlink to /private/tmp, so realTargetPath resolves there and a literal-/tmp
+  // containment check would never match.
+  const physicallyUnderTmp = realTargetPath === realTmpRoot || isInside(realTmpRoot, realTargetPath)
+  if (!physicallyUnderTmp) return false
+
+  const insideAgent = realTargetPath === realAgentDir || isInside(realAgentDir, realTargetPath)
+  return !insideAgent
+}
+
 function isInside(parent: string, child: string): boolean {
   const relative = path.relative(parent, child)
   return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))