typeclaw 0.23.0 → 0.25.0

package/README.md

@@ -34,7 +34,7 @@ If you're like me, TypeClaw is the right choice. If not, that's fine too.
 - 💬 **Multi-channel** — Slack, Discord, Telegram, KakaoTalk, GitHub webhooks, and a websocket TUI; one agent, many inboxes
 - ⏰ **Cron** — schedule prompts or shell commands; per-job coalescing so slow jobs don't pile up
 - 📚 **Skills on demand** — markdown procedures the agent loads only when relevant; zero token cost until used
-- 🔎 **Web research** — bundled `scout` subagent plus first-class `websearch` and `webfetch` tools (DuckDuckGo via curl-impersonate, Wikipedia)
+- 🔎 **Web research** — bundled `scout` subagent plus first-class `web_search` and `web_fetch` tools (DuckDuckGo via curl-impersonate, Wikipedia)
 - 🛡 **Security guards** — bundled `tool.before` policies catch secret exfil, SSRF, prompt injection, tainted git remotes, and silent privilege escalation (role/cron promotion) before they fire
 - 📊 **Usage, inspect, doctor** — `typeclaw usage` reports token/$ spend per session, model, or day; `typeclaw inspect` replays a session transcript and tails live activity; `typeclaw doctor` diagnoses host, agent folder, and plugin state
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/src/agent/index.ts

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url'
 
 import {
   createAgentSession,
+  createCodingTools,
   DefaultResourceLoader,
   defineTool as definePiTool,
   SessionManager,
@@ -34,6 +35,7 @@ import { getAuthFor } from './auth'
 import { createCompactionSettingsManager } from './compaction'
 import { renderGitNudge } from './git-nudge'
 import type { LiveSubagentRegistry } from './live-subagents'
+import { sanitizeMessagesForLlmReplay } from './llm-replay-sanitizer'
 import { applyModelRuntimeOverrides } from './model-overrides'
 import { createChannelLookAtTool, lookAtTool } from './multimodal'
 import {
@@ -45,11 +47,13 @@ import {
   zodToToolParameters,
 } from './plugin-tools'
 import { createReloadTool } from './reload-tool'
+import type { RestartHandoffOrigin } from './restart-handoff'
 import { loadSelf } from './self'
 import { SESSION_META_CUSTOM_TYPE, sessionMetaPayload } from './session-meta'
 import { renderSessionOrigin, type SessionOrigin, type SessionRoleContext } from './session-origin'
 import type { CreateSessionForSubagent, SubagentRegistry } from './subagents'
 import { DEFAULT_SYSTEM_PROMPT, renderRuntimeBlock, SLIM_SYSTEM_PROMPT } from './system-prompt'
+import { attachToolNotFoundNudge } from './tool-not-found-nudge'
 import {
   createBudgetState,
   type ToolResultBudget,
@@ -68,8 +72,9 @@ import { createSpawnSubagentTool } from './tools/spawn-subagent'
 import { createStreamSnapshotTool } from './tools/stream-snapshot'
 import { createSubagentCancelTool } from './tools/subagent-cancel'
 import { createSubagentOutputTool } from './tools/subagent-output'
-import { webfetchTool } from './tools/webfetch'
-import { websearchTool } from './tools/websearch'
+import { createTodoTools } from './tools/todo'
+import { webFetchTool } from './tools/webfetch'
+import { webSearchTool } from './tools/websearch'
 
 export type { SessionOrigin } from './session-origin'
 
@@ -79,6 +84,13 @@ export { renderTurnRoleAnchor, renderTurnTimeAnchor } from './system-prompt'
 
 type AgentSessionTools = NonNullable<Parameters<typeof createAgentSession>[0]>['tools']
 
+// pi's default active built-in tools when a session declares no `tools:` filter
+// (pi `createAgentSession` falls back to `defaultActiveToolNames`, which is the
+// name set of `codingTools`). Derived from pi's own `createCodingTools()` rather
+// than hardcoded so the list can't silently drift if pi adds/removes/renames a
+// default builtin; `default-pi-builtins match pi's coding tool set` pins it.
+const DEFAULT_PI_BUILTIN_TOOL_NAMES = createCodingTools(process.cwd()).map((t) => t.name)
+
 export type PluginSessionWiring = {
   registry: PluginRegistry
   hooks: HookBus
@@ -248,6 +260,13 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
   const getOrigin: () => SessionOrigin | undefined =
     options.originRef !== undefined ? () => options.originRef!.current : () => options.origin
 
+  // Holds the session's signal-only abort once `createAgentSession` resolves.
+  // Tools are wrapped BEFORE the session exists, so the loop guard reaches the
+  // abort through this lazily-resolved getter. See `fireLoopAbort` in
+  // plugin-tools.ts for why aborting (not throwing) is what stops the loop.
+  const abortHolder: { abort?: () => void } = {}
+  const getAbort: () => (() => void) | undefined = () => abortHolder.abort
+
   // Subagent built-in tool refs are dual-routed (see BUILTIN_TOOL_DEFINITION
   // dual-map in plugin-tools.ts): pi-side coding tools go to `tools:` so they
   // become the strict base set, typeclaw-side web tools go to `customTools:`.
@@ -259,8 +278,8 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
     ? resolveBuiltinToolRefs(options.pluginSubagent.toolRefs)
     : { agentTools: [], toolDefinitions: [] }
   const pluginCustomTools = options.pluginSubagent
-    ? wrapSubagentCustomTools(options.pluginSubagent, options.plugins, getOrigin)
-    : wrapRegistryTools(options.plugins, getOrigin)
+    ? wrapSubagentCustomTools(options.pluginSubagent, options.plugins, getOrigin, getAbort)
+    : wrapRegistryTools(options.plugins, getOrigin, getAbort)
 
   // Per-run budget state for the tool-result byte ceiling. Allocated once per
   // session creation and threaded into every wrapped tool so they share the
@@ -276,7 +295,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
 
   const effectiveTools =
     options.tools ?? (options.pluginSubagent ? (resolvedSubagentBuiltins.agentTools as AgentSessionTools) : undefined)
-  const hookWrappedTools = wrapSystemAgentTools(effectiveTools, options.plugins, getOrigin)
+  const hookWrappedTools = wrapSystemAgentTools(effectiveTools, options.plugins, getOrigin, getAbort)
   const tools =
     sessionBudget && sessionBudgetState && hookWrappedTools
       ? (hookWrappedTools.map((t) =>
@@ -309,14 +328,33 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
     }
   }
 
+  // Plugin subagents (operator/reviewer) see ONLY their declared builtins plus
+  // the orchestration tools — never the full main-session tool surface. The
+  // orchestration tools self-omit unless `liveSubagentRegistry`/
+  // `subagentRegistry`/`createSessionForSubagent` are wired (see
+  // buildSubagentOrchestrationTools); `spawn_subagent` enforces MAX_SUBAGENT_DEPTH
+  // at execute time so a depth-capped subagent's spawn fails closed even though
+  // the tool is present.
   const customSystemTools =
     options.customTools !== undefined
       ? options.customTools
       : options.pluginSubagent
-        ? resolvedSubagentBuiltins.toolDefinitions
+        ? [
+            ...resolvedSubagentBuiltins.toolDefinitions,
+            ...buildSubagentOrchestrationTools({
+              liveRegistry: options.liveSubagentRegistry,
+              registry: options.subagentRegistry,
+              createSessionForSubagent: options.createSessionForSubagent,
+              agentDir: options.plugins?.agentDir,
+              parentSessionId: sessionManager.getSessionId(),
+              getOrigin,
+              permissions: options.permissions,
+              stream: options.stream,
+            }),
+          ]
         : [
-            websearchTool,
-            webfetchTool,
+            webSearchTool,
+            webFetchTool,
             lookAtTool,
             ...(options.mcpManager ? buildMcpDispatcherToolDefinitions(options.mcpManager) : []),
             ...(options.reloadRegistry ? [createReloadTool({ registry: options.reloadRegistry })] : []),
@@ -348,6 +386,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
               permissions: options.permissions,
               reloadRoles: options.reloadRoles,
             }),
+            ...buildTodoTools(options.plugins?.agentDir, getOrigin),
           ]
   // Hook coverage for pi's builtin coding tools (read/bash/edit/write/grep/
   // find/ls) — pi 0.67.3 ignores `tools:` for implementation, so the only
@@ -361,10 +400,11 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
           sessionId: options.plugins.sessionId,
           hooks: options.plugins.hooks,
           getOrigin,
+          getAbort,
           ...(options.permissions ? { permissions: options.permissions } : {}),
         })
       : []
-  const wrappedCustomSystemTools = wrapSystemTools(customSystemTools, options.plugins, getOrigin)
+  const wrappedCustomSystemTools = wrapSystemTools(customSystemTools, options.plugins, getOrigin, getAbort)
   const customToolsPreBudget = [...wrappedCustomSystemTools, ...pluginCustomTools, ...builtinPiToolOverrides]
   const customTools =
     sessionBudget && sessionBudgetState
@@ -385,25 +425,56 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
     ...(thinkingLevel ? { thinkingLevel } : {}),
   })
 
+  // Layer the replay sanitizer over pi's convertToLlm so a transcript with an
+  // orphaned toolResult (e.g. a torn-down restart turn) can't wedge the session
+  // with an Anthropic 400 on every replay. Runs on every provider call path
+  // that goes through the agent. Honors pi's contract that convertToLlm must
+  // not throw: on any failure it falls back to the unsanitized output.
+  const innerConvertToLlm = session.agent.convertToLlm
+  session.agent.convertToLlm = async (messages) => {
+    const converted = await innerConvertToLlm(messages)
+    try {
+      return sanitizeMessagesForLlmReplay(converted).messages
+    } catch {
+      return converted
+    }
+  }
+
+  abortHolder.abort = () => {
+    if (session.agent.signal?.aborted !== true) session.agent.abort()
+  }
+
+  // The names the session actually exposes to the model: pi's active base set
+  // (the caller's `tools:` filter, or pi's default builtins when unset) union
+  // the typeclaw/plugin custom tools. Deliberately EXCLUDES
+  // `builtinPiToolOverrides` — those replace builtin implementations by name,
+  // they are not additional callable names. This is the single source of truth
+  // for both the active-set re-narrowing below and the tool-not-found nudge
+  // vocabulary, so the two never drift (a divergence would make the nudge miss
+  // real tools or suggest tools the session deliberately did not expose).
+  const intendedActiveToolNames = [
+    ...new Set([
+      ...(tools !== undefined ? tools.map((t) => t.name) : DEFAULT_PI_BUILTIN_TOOL_NAMES),
+      ...[...wrappedCustomSystemTools, ...pluginCustomTools].map((t) => t.name),
+    ]),
+  ]
+
   // Re-narrow the active tool set after `createAgentSession`. pi 0.67.3's
   // `_refreshToolRegistry` runs with `includeAllExtensionTools: true` and
   // pushes every customTool name into the active set, which would widen
   // a subagent's declared `[edit]` to all 7 builtin overrides plus every
-  // typeclaw custom tool. The intended active set is the names the caller
-  // would have gotten WITHOUT the builtin overrides: pi's `initialActiveToolNames`
-  // (derived from `tools:`) union the names from typeclaw/plugin customTools.
-  // `builtinPiToolOverrides` are implementation overrides, never additions.
+  // typeclaw custom tool.
   if (builtinPiToolOverrides.length > 0) {
-    const baseActiveNames = tools !== undefined ? tools.map((t) => t.name) : ['read', 'bash', 'edit', 'write']
-    const customToolActiveNames = [...wrappedCustomSystemTools, ...pluginCustomTools].map((t) => t.name)
-    const intendedActive = [...new Set([...baseActiveNames, ...customToolActiveNames])]
-    session.setActiveToolsByName(intendedActive)
+    session.setActiveToolsByName(intendedActiveToolNames)
   }
 
   const unsubRestart = subscribeRestartNotice(options.stream, sessionManager)
 
+  const unsubToolNudge = attachToolNotFoundNudge(session, intendedActiveToolNames)
+
   const dispose = async () => {
     unsubRestart?.()
+    unsubToolNudge()
     if (materializedSkills) await materializedSkills.dispose()
   }
   return { session, dispose }
@@ -411,22 +482,39 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
 
 // Decides whether the restart tool should write the cross-restart handoff
 // file (`<agentDir>/.typeclaw/restart-pending.json`) and supplies the agentDir
-// + session file path it needs to do so. Returns an empty object — meaning
-// "no handoff" — for any session whose origin is not TUI, so a channel-
-// originated or cron-originated `restart` call cannot accidentally produce an
-// "I'm back" greeting in the next container's first TUI session. See
-// issue #291's scoping concerns. Also returns empty when the session is not
-// persisted to disk (in-memory sessions have no file the next container could
-// reopen).
+// + session file path + origin metadata it needs to do so. Returns an empty
+// object — meaning "no handoff" — for cron/subagent/system origins (no
+// attended session the next boot could resume) and for in-memory sessions
+// (no file to reopen).
+//
+// TUI and channel origins both resume: a TUI restart reattaches to the
+// reconnecting client (websocket open handler), a channel restart reopens the
+// originating chat session on the channel router's boot path. The `origin`
+// discriminator in the handoff is what routes the next boot to the correct
+// subsystem.
 export function buildRestartHandoffWiring(
   options: { origin?: SessionOrigin; plugins?: { agentDir: string } },
   sessionManager: SessionManager,
-): { agentDir?: string; originatingSessionFile?: string } {
-  if (options.origin?.kind !== 'tui') return {}
+): { agentDir?: string; originatingSessionFile?: string; handoffOrigin?: RestartHandoffOrigin } {
+  const origin = options.origin
+  if (origin === undefined) return {}
+  const handoffOrigin = restartHandoffOriginFor(origin)
+  if (handoffOrigin === null) return {}
   const agentDir = options.plugins?.agentDir
   const sessionFile = sessionManager.getSessionFile()
   if (agentDir === undefined || sessionFile === undefined) return {}
-  return { agentDir, originatingSessionFile: sessionFile }
+  return { agentDir, originatingSessionFile: sessionFile, handoffOrigin }
+}
+
+function restartHandoffOriginFor(origin: SessionOrigin): RestartHandoffOrigin | null {
+  if (origin.kind === 'tui') return { kind: 'tui' }
+  if (origin.kind === 'channel') {
+    return {
+      kind: 'channel',
+      key: { adapter: origin.adapter, workspace: origin.workspace, chat: origin.chat, thread: origin.thread },
+    }
+  }
+  return null
 }
 
 // Subscribes the given session to the in-process broadcast that the `restart`
@@ -633,11 +721,13 @@ export function buildSubagentOrchestrationTools(opts: {
     createSubagentOutputTool({
       liveRegistry: opts.liveRegistry,
       getOrigin: opts.getOrigin,
+      callerSessionId: opts.parentSessionId,
       ...(opts.permissions ? { permissions: opts.permissions } : {}),
     }),
     createSubagentCancelTool({
       liveRegistry: opts.liveRegistry,
       getOrigin: opts.getOrigin,
+      callerSessionId: opts.parentSessionId,
       ...(opts.permissions ? { permissions: opts.permissions } : {}),
     }),
   ]
@@ -662,9 +752,18 @@ export function buildRoleGrantTools(opts: {
   ]
 }
 
+export function buildTodoTools(
+  agentDir: string | undefined,
+  getOrigin: () => SessionOrigin | undefined,
+): ToolDefinition[] {
+  if (agentDir === undefined) return []
+  return createTodoTools({ agentDir, getOrigin })
+}
+
 function wrapRegistryTools(
   plugins: PluginSessionWiring | undefined,
   getOrigin: () => SessionOrigin | undefined,
+  getAbort: () => (() => void) | undefined,
 ): ToolDefinition[] {
   if (!plugins) return []
   return plugins.registry.tools.map((t: PluginRegisteredTool) =>
@@ -676,6 +775,7 @@ function wrapRegistryTools(
       logger: t.logger,
       hooks: plugins.hooks,
       getOrigin,
+      getAbort,
     }),
   )
 }
@@ -684,6 +784,7 @@ function wrapSystemAgentTools(
   tools: AgentSessionTools | undefined,
   plugins: PluginSessionWiring | undefined,
   getOrigin: () => SessionOrigin | undefined,
+  getAbort: () => (() => void) | undefined,
 ): AgentSessionTools | undefined {
   if (!tools || !hasToolHooks(plugins)) return tools
   return tools.map((tool) =>
@@ -692,6 +793,7 @@ function wrapSystemAgentTools(
       sessionId: plugins.sessionId,
       hooks: plugins.hooks,
       getOrigin,
+      getAbort,
     }),
   )
 }
@@ -700,6 +802,7 @@ function wrapSystemTools(
   tools: ToolDefinition[],
   plugins: PluginSessionWiring | undefined,
   getOrigin: () => SessionOrigin | undefined,
+  getAbort: () => (() => void) | undefined,
 ): ToolDefinition[] {
   if (!hasToolHooks(plugins)) return tools
   return tools.map((tool) =>
@@ -708,6 +811,7 @@ function wrapSystemTools(
       sessionId: plugins.sessionId,
       hooks: plugins.hooks,
       getOrigin,
+      getAbort,
     }),
   )
 }
@@ -721,6 +825,7 @@ function wrapSubagentCustomTools(
   selection: PluginSubagentSelection,
   plugins: PluginSessionWiring | undefined,
   getOrigin: () => SessionOrigin | undefined,
+  getAbort: () => (() => void) | undefined,
 ): ToolDefinition[] {
   if (!selection.customTools || !plugins) return []
   const logger = makePluginLogger(selection.pluginName)
@@ -733,6 +838,7 @@ function wrapSubagentCustomTools(
       logger,
       hooks: plugins.hooks,
       getOrigin,
+      getAbort,
     }),
   )
 }

package/src/agent/llm-replay-sanitizer.ts

@@ -0,0 +1,120 @@
+// Defensive projection applied to the LLM message array right before each
+// provider call, layered on top of pi-coding-agent's `convertToLlm`. It exists
+// to un-wedge sessions whose persisted transcript contains a `toolResult` with
+// no live preceding `toolCall` — the exact shape Anthropic rejects with
+// "unexpected `tool_use_id` found in `tool_result` blocks" (HTTP 400).
+//
+// How a transcript gets poisoned: the self-`restart` tool exits the container
+// mid-turn. The assistant turn carrying the restart `toolCall` can land in the
+// JSONL with `stopReason: "error"/"aborted"` (or be torn down), while its
+// `toolResult` is persisted. On replay, pi-ai's provider-side `transformMessages`
+// DROPS error/aborted assistant turns but passes the `toolResult` through
+// unchanged, leaving a true orphan that the API rejects on every subsequent
+// turn — the session is permanently stuck.
+//
+// pi-ai's `transformMessages` already handles the inverse cases (a `toolCall`
+// with no result → synthetic "No result provided" result; error/aborted
+// assistant turns → dropped). The one gap is an orphaned `toolResult`. This
+// sanitizer fills exactly that gap and nothing more.
+//
+// Invariant (local pending-window, NOT a global id union — Anthropic requires
+// tool results to belong to the immediately preceding tool-use turn):
+//   1. Assistant turns with stopReason "error"/"aborted" are dropped here, so
+//      orphan detection sees the same message set the provider will after its
+//      own drop pass. Without this, a result tied to a dropped assistant would
+//      survive us and be orphaned downstream — the original bug.
+//   2. A `toolResult` is kept only if its `toolCallId` was declared by the most
+//      recent kept assistant tool-use turn AND has not already been emitted in
+//      that window. Any user or assistant message closes the window.
+//   3. Missing results are NOT synthesized here — pi-ai's existing pass inserts
+//      the synthetic placeholder, so dropping an orphan that leaves a bare
+//      `toolCall` is safe and self-healing.
+//
+// This is a read-only projection: it never mutates the persisted JSONL, so an
+// already-poisoned session becomes usable without destructive migration.
+
+import type { Message } from '@mariozechner/pi-ai'
+
+export type ReplaySanitizerStats = {
+  droppedOrphans: number
+  droppedDuplicates: number
+  droppedErrorAssistants: number
+}
+
+export type SanitizeResult = {
+  messages: Message[]
+  stats: ReplaySanitizerStats
+}
+
+function isErroredAssistant(message: Message): boolean {
+  return message.role === 'assistant' && (message.stopReason === 'error' || message.stopReason === 'aborted')
+}
+
+function toolCallIdsOf(message: Extract<Message, { role: 'assistant' }>): string[] {
+  return message.content
+    .filter((block): block is Extract<typeof block, { type: 'toolCall' }> => block.type === 'toolCall')
+    .map((block) => block.id)
+    .filter((id): id is string => typeof id === 'string' && id.length > 0)
+}
+
+export function sanitizeMessagesForLlmReplay(messages: Message[]): SanitizeResult {
+  const output: Message[] = []
+  const stats: ReplaySanitizerStats = {
+    droppedOrphans: 0,
+    droppedDuplicates: 0,
+    droppedErrorAssistants: 0,
+  }
+
+  let pendingToolCallIds = new Set<string>()
+  let emittedResultIds = new Set<string>()
+
+  const closeWindow = () => {
+    pendingToolCallIds = new Set()
+    emittedResultIds = new Set()
+  }
+
+  for (const message of messages) {
+    if (message.role === 'assistant') {
+      closeWindow()
+
+      // Mirror pi-ai's provider-side drop of incomplete turns so orphan
+      // detection matches the message set the provider will actually send.
+      if (isErroredAssistant(message)) {
+        stats.droppedErrorAssistants += 1
+        continue
+      }
+
+      const callIds = toolCallIdsOf(message)
+      if (callIds.length > 0) pendingToolCallIds = new Set(callIds)
+      output.push(message)
+      continue
+    }
+
+    if (message.role === 'user') {
+      closeWindow()
+      output.push(message)
+      continue
+    }
+
+    if (message.role === 'toolResult') {
+      const id = message.toolCallId
+      if (!pendingToolCallIds.has(id)) {
+        // Orphan: true orphan, stale late result, or result for a dropped
+        // error/aborted assistant turn.
+        stats.droppedOrphans += 1
+        continue
+      }
+      if (emittedResultIds.has(id)) {
+        stats.droppedDuplicates += 1
+        continue
+      }
+      emittedResultIds.add(id)
+      output.push(message)
+      continue
+    }
+
+    output.push(message)
+  }
+
+  return { messages: output, stats }
+}

package/src/agent/loop-guard.ts

@@ -63,6 +63,14 @@ export type LoopGuard = {
   check: (sessionId: string, tool: string, args: unknown) => LoopGuardDecision
   reset: (sessionId: string) => void
   forget: (sessionId: string) => void
+  // Clears only the residue a single tool left behind in a session: its entries
+  // in the windowed history and, if the current consecutive streak belongs to
+  // that tool, the streak itself. Used when a state-change boundary makes a
+  // tool's prior calls irrelevant — e.g. a backgrounded subagent finishing
+  // makes the next `subagent_output` fetch legitimate even though earlier
+  // premature polls poisoned the window. Narrower than `forget`, so an
+  // unrelated tool's accumulating loop on the same session is preserved.
+  forgetTool: (sessionId: string, tool: string) => void
 }
 
 type SessionState = {
@@ -215,9 +223,35 @@ export function createLoopGuard(options: CreateLoopGuardOptions = {}): LoopGuard
     forget(sessionId) {
       sessions.delete(sessionId)
     },
+    forgetTool(sessionId, tool) {
+      const state = sessions.get(sessionId)
+      if (state === undefined) return
+      const retained: string[] = []
+      for (const sig of state.window) {
+        if (signatureBelongsToTool(sig, tool)) {
+          state.windowWarned.delete(sig)
+        } else {
+          retained.push(sig)
+        }
+      }
+      state.window = retained
+      if (signatureBelongsToTool(state.signature, tool)) {
+        state.signature = ''
+        state.count = 0
+        state.warned = false
+      }
+    },
   }
 }
 
+// Both signature builders prefix the tool name: exact signatures as `tool:...`
+// and path-coarsened ones as `tool#path:...`. A tool's residue is therefore any
+// signature starting with `tool:` or `tool#`, never a different tool whose name
+// merely shares this one as a prefix (the delimiter rules that out).
+function signatureBelongsToTool(signature: string, tool: string): boolean {
+  return signature.startsWith(`${tool}:`) || signature.startsWith(`${tool}#`)
+}
+
 function formatWarnMessage(tool: string, count: number): string {
   return (
     `\n\n[loop-guard] You have called \`${tool}\` ${count} times in a row with identical arguments. ` +

package/src/agent/multimodal/look-at.ts

@@ -161,7 +161,7 @@ async function runLookAtImages(imageContents: ImageContent[], prompt: string | u
     origin,
     profile: 'vision',
     // Both knobs are required to fully disarm the subagent's tool surface:
-    // `customTools: []` blocks typeclaw's system tools (websearch/webfetch/
+    // `customTools: []` blocks typeclaw's system tools (web_search/web_fetch/
     // look_at/restart/...) — without it, the look_at tool would recurse
     // into itself. `tools: []` blocks pi-coding-agent's defaults
     // (read/bash/edit/write) — without it, a vision model could be talked