typeclaw 0.12.0 → 0.14.0

package/package.json

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

package/scripts/dump-system-prompt.ts

@@ -2,19 +2,19 @@
 
 import { parseArgs } from 'node:util'
 
-import { composeSystemPrompt, deriveSystemPromptMode, type SystemPromptMode } from '@/agent'
+import { composeSystemPrompt, deriveSystemPromptMode, renderTurnTimeAnchor, type SystemPromptMode } from '@/agent'
 import type { SessionOrigin, SessionRoleContext } from '@/agent/session-origin'
-import { renderNowBlock } from '@/agent/system-prompt'
 
 type OriginKind = 'tui' | 'cron' | 'channel' | 'subagent'
 const ALL_KINDS: readonly OriginKind[] = ['tui', 'cron', 'channel', 'subagent'] as const
 
 const PLACEHOLDER_RUNTIME_VERSION = '1.2.3-debug'
 
-// Fixed wall-clock for the `## Now` block. The dumper needs a deterministic
-// timestamp so successive runs produce byte-identical output (and so the
-// snapshot tests in dump-system-prompt.test.ts don't drift). Production
-// callers always pass the live `new Date()` — see `composeSystemPrompt`.
+// Fixed wall-clock for the per-turn `<current-time>` anchor. The dumper
+// needs a deterministic timestamp so successive runs produce byte-identical
+// output (and so the snapshot tests in dump-system-prompt.test.ts don't
+// drift). Production callers always pass the live `new Date()` — see
+// `renderTurnTimeAnchor` in src/agent/system-prompt.ts.
 const PLACEHOLDER_NOW = new Date('2026-05-22T15:11:00+09:00')
 
 const PLACEHOLDER_SELF = [
@@ -243,14 +243,12 @@ function dumpSubagentOverridePrompt(): DumpResult {
   const fixture = buildFixture('subagent')
   const runtimeBlock = `## Runtime\n\nTypeClaw runtime version: ${PLACEHOLDER_RUNTIME_VERSION}.`
   const originBlock = `## Session origin\n\nYou are a \`${(fixture.origin as { subagent: string }).subagent}\` subagent spawned by parent session\n\`${(fixture.origin as { parentSessionId: string }).parentSessionId}\`. Stay narrowly within the task you were given.\nReturn cleanly when done; do not sprawl into unrelated work.\n\n## Your role in this session\n\nRole: \`${fixture.roleContext.role}\`. Permissions: ${fixture.roleContext.permissions.map((p) => `\`${p}\``).join(', ')}.\n\nThis is the role the runtime resolved at session creation. Tool calls\nand channel admission are gated by these permissions; a \`blocked:\` or\n"denied by permissions" message means the current actor lacks the\npermission the guard was looking for. See the \`typeclaw-permissions\`\nskill for what each role can do and how to grant access.`
-  const nowBlock = renderNowBlock(PLACEHOLDER_NOW)
 
-  const prompt = `${PLACEHOLDER_SUBAGENT_OVERRIDE}\n\n${runtimeBlock}\n\n${originBlock}\n\n${nowBlock}`
+  const prompt = `${PLACEHOLDER_SUBAGENT_OVERRIDE}\n\n${runtimeBlock}\n\n${originBlock}`
   const sections: SectionBreakdown[] = [
     mkSection('Subagent override prompt', PLACEHOLDER_SUBAGENT_OVERRIDE),
     mkSection('Runtime block', runtimeBlock),
     mkSection('Session origin + role', originBlock),
-    mkSection('Now (wall clock)', nowBlock),
   ]
   return {
     prompt,
@@ -273,7 +271,6 @@ function dumpDefaultLoaderPrompt(kind: Exclude<OriginKind, 'subagent'>, options:
     roleContext: fixture.roleContext,
     gitNudge: wantGitNudge ? PLACEHOLDER_GIT_NUDGE : '',
     memorySection: fixture.memory,
-    now: PLACEHOLDER_NOW,
   } as const
 
   const prompt = composeSystemPrompt(parts)
@@ -299,7 +296,6 @@ function dumpDefaultLoaderPrompt(kind: Exclude<OriginKind, 'subagent'>, options:
     sections.push(mkSection('Git nudge', parts.gitNudge))
   }
   sections.push(mkSection('Memory (MEMORY.md + streams)', parts.memorySection))
-  sections.push(mkSection('Now (wall clock)', renderNowBlock(PLACEHOLDER_NOW)))
 
   return {
     prompt,
@@ -405,6 +401,11 @@ function main(): void {
     process.stdout.write(result.prompt)
     process.stdout.write('\n')
   }
+
+  const anchor = renderTurnTimeAnchor(PLACEHOLDER_NOW)
+  const bar = '═'.repeat(78)
+  process.stdout.write(`\n${bar}\n  PER-TURN INJECTION (prepended to every user message)\n${bar}\n\n`)
+  process.stdout.write(`${anchor}\n`)
 }
 
 if (import.meta.main) {

package/src/agent/index.ts

@@ -26,7 +26,7 @@ import { getAuthFor } from './auth'
 import { createCompactionSettingsManager } from './compaction'
 import { renderGitNudge } from './git-nudge'
 import type { LiveSubagentRegistry } from './live-subagents'
-import { lookAtTool } from './multimodal'
+import { createChannelLookAtTool, lookAtTool } from './multimodal'
 import {
   buildBuiltinPiToolOverrides,
   resolveBuiltinToolRefs,
@@ -39,7 +39,7 @@ 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, renderNowBlock, renderRuntimeBlock, SLIM_SYSTEM_PROMPT } from './system-prompt'
+import { DEFAULT_SYSTEM_PROMPT, renderRuntimeBlock, SLIM_SYSTEM_PROMPT } from './system-prompt'
 import {
   createBudgetState,
   type ToolResultBudget,
@@ -63,6 +63,8 @@ export type { SessionOrigin } from './session-origin'
 
 export type { AgentSession }
 
+export { renderTurnTimeAnchor } from './system-prompt'
+
 type AgentSessionTools = NonNullable<Parameters<typeof createAgentSession>[0]>['tools']
 
 export type PluginSessionWiring = {
@@ -519,9 +521,10 @@ export function buildChannelTools(
     tools.push(
       createChannelFetchAttachmentTool({
         router: channelRouter,
-        origin: { adapter: origin.adapter },
+        origin: channelOrigin,
       }),
     )
+    tools.push(createChannelLookAtTool(channelRouter, channelOrigin))
     if (sessionId !== undefined) {
       tools.push(createSkipResponseTool({ router: channelRouter, sessionId }))
     }
@@ -662,12 +665,10 @@ export async function createOverrideResourceLoader(
   origin?: SessionOrigin,
   permissions?: PermissionService,
   runtimeVersion?: string,
-  now: Date = new Date(),
 ): Promise<DefaultResourceLoader> {
   const withRuntime =
     runtimeVersion !== undefined ? `${systemPrompt}\n\n${renderRuntimeBlock(runtimeVersion)}` : systemPrompt
-  const withOriginRendered = withOrigin(withRuntime, origin, permissions)
-  const finalPrompt = `${withOriginRendered}\n\n${renderNowBlock(now)}`
+  const finalPrompt = withOrigin(withRuntime, origin, permissions)
   const loader = new DefaultResourceLoader({
     systemPromptOverride: () => finalPrompt,
     appendSystemPromptOverride: () => [],
@@ -688,11 +689,6 @@ export type CreateResourceLoaderOptions = {
   // 'full' to force the heavy prompt even on an unattended origin (rarely
   // useful; mostly an escape hatch for ad-hoc debugging).
   mode?: SystemPromptMode
-  // Wall-clock anchor stamped into the trailing `## Now` block of the
-  // rendered system prompt. Production callers omit this so each session
-  // gets the current time at creation; tests pass a fixed Date to keep
-  // assertions deterministic. See `renderNowBlock` in system-prompt.ts.
-  now?: Date
 }
 
 // Origins where the operator-facing DEFAULT_SYSTEM_PROMPT, git-nudge, and the
@@ -750,7 +746,6 @@ export type SystemPromptComposition = {
   roleContext?: SessionRoleContext
   gitNudge: string
   memorySection: string
-  now?: Date
 }
 
 // Section-order contract for the system prompt. Kept as a pure string→string
@@ -769,12 +764,14 @@ export type SystemPromptComposition = {
 // 3. memorySection — volatile: MEMORY.md grows on every dream cycle and
 //    memory/yyyy-MM-dd.md grows after every channel turn that triggers
 //    memory-logger.
-// 4. now block — most volatile: changes per second. Pinned to the very
-//    end so every byte UP TO this block stays in the provider's cache
-//    prefix; only the trailing ~60 bytes invalidate on each new session.
-//    `now` is optional — when omitted (debug dumps without a fixed clock,
-//    legacy callers) the block is skipped entirely. See `renderNowBlock`
-//    in system-prompt.ts for why this block exists at all.
+//
+// The wall-clock anchor that used to live here as `## Now` moved out
+// entirely. It is now injected into the user turn at each `session.prompt`
+// site via `renderTurnTimeAnchor` (src/agent/system-prompt.ts) so the
+// stamp reflects the moment of THIS turn, not session creation. Per-turn
+// injection costs zero cached bytes — the user turn is the non-cacheable
+// suffix anyway — and removes the staleness failure mode where a session
+// opened Friday answered "today is Friday" on Thursday.
 export function composeSystemPrompt(parts: SystemPromptComposition): string {
   const base = parts.mode === 'slim' ? SLIM_SYSTEM_PROMPT : DEFAULT_SYSTEM_PROMPT
   let prompt = `${base}\n\n${parts.self}`
@@ -790,9 +787,6 @@ export function composeSystemPrompt(parts: SystemPromptComposition): string {
   if (parts.memorySection !== '') {
     prompt = `${prompt}\n\n${parts.memorySection}`
   }
-  if (parts.now !== undefined) {
-    prompt = `${prompt}\n\n${renderNowBlock(parts.now)}`
-  }
   return prompt
 }
 
@@ -868,7 +862,6 @@ export async function createResourceLoader(options: CreateResourceLoaderOptions
     ...(roleContext !== undefined ? { roleContext } : {}),
     gitNudge,
     memorySection,
-    now: options.now ?? new Date(),
   })
 
   const additionalSkillPaths = [getBundledSkillsDir()]

package/src/agent/loop-guard.ts

@@ -0,0 +1,170 @@
+// Detects when the model calls the same tool with byte-identical arguments in
+// a tight streak — the classic "stuck in a thought-loop" failure where the
+// agent repeats `bash("ls")` or `read("foo.ts")` indefinitely waiting for a
+// different answer. Two-tier escalation:
+//
+//   - At LOOP_SOFT_WARN consecutive identical calls (default 3), the next call
+//     completes normally but the wrapped tool's output is suffixed with a nudge
+//     telling the model it's looping. Soft warning fires ONCE per streak so
+//     the model isn't drowning in identical reminders.
+//   - At LOOP_HARD_BLOCK consecutive identical calls (default 5), the call is
+//     refused outright. The wrapping in plugin-tools.ts maps the refusal to
+//     `errorResult` for plugin tools (the model sees a tool error and must
+//     change strategy) and to a thrown Error for system / pi-builtin tools
+//     (matches the existing `tool.before { block: true }` plumbing).
+//
+// State is per-session and bounded: the guard keeps at most MAX_SESSIONS
+// session entries with LRU eviction, and each session holds at most one
+// signature + counter (we only care about the current tail streak). When a
+// different tool/args combination arrives, the streak resets to 1.
+//
+// The detector is intentionally placed INSIDE the tool wrappers (not as a
+// `tool.before` plugin) so it covers every tool category — plugin tools,
+// TypeClaw system tools, and pi-coding-agent builtins — through one chokepoint.
+
+export const LOOP_SOFT_WARN = 3
+export const LOOP_HARD_BLOCK = 5
+
+// Caps in-process memory across many sessions. Each entry is small
+// (signature string + small counters), so this bound is generous; we just
+// don't want unbounded growth if sessionIds churn.
+const MAX_SESSIONS = 256
+
+export type LoopGuardDecision =
+  | { kind: 'ok' }
+  | { kind: 'warn'; count: number; message: string }
+  | { kind: 'block'; count: number; message: string }
+
+export type LoopGuard = {
+  check: (sessionId: string, tool: string, args: unknown) => LoopGuardDecision
+  reset: (sessionId: string) => void
+  forget: (sessionId: string) => void
+}
+
+type SessionState = {
+  signature: string
+  count: number
+  // Fires the soft warning exactly once per streak instead of every call
+  // from the 3rd onwards. Re-arms when the streak breaks.
+  warned: boolean
+}
+
+export type CreateLoopGuardOptions = {
+  softWarn?: number
+  hardBlock?: number
+  maxSessions?: number
+}
+
+export function createLoopGuard(options: CreateLoopGuardOptions = {}): LoopGuard {
+  const softWarn = options.softWarn ?? LOOP_SOFT_WARN
+  const hardBlock = options.hardBlock ?? LOOP_HARD_BLOCK
+  const maxSessions = options.maxSessions ?? MAX_SESSIONS
+
+  if (softWarn < 2) throw new Error(`loop-guard: softWarn must be >= 2 (got ${softWarn})`)
+  if (hardBlock <= softWarn) {
+    throw new Error(`loop-guard: hardBlock (${hardBlock}) must be greater than softWarn (${softWarn})`)
+  }
+
+  // Map preserves insertion order; we rely on that for LRU eviction.
+  const sessions = new Map<string, SessionState>()
+
+  function touch(sessionId: string, state: SessionState): void {
+    sessions.delete(sessionId)
+    sessions.set(sessionId, state)
+    if (sessions.size > maxSessions) {
+      const oldest = sessions.keys().next().value
+      if (oldest !== undefined) sessions.delete(oldest)
+    }
+  }
+
+  return {
+    check(sessionId, tool, args) {
+      const signature = makeCallSignature(tool, args)
+      const existing = sessions.get(sessionId)
+
+      if (!existing || existing.signature !== signature) {
+        touch(sessionId, { signature, count: 1, warned: false })
+        return { kind: 'ok' }
+      }
+
+      const nextCount = existing.count + 1
+      const nextState: SessionState = {
+        signature,
+        count: nextCount,
+        warned: existing.warned,
+      }
+
+      if (nextCount >= hardBlock) {
+        touch(sessionId, nextState)
+        return {
+          kind: 'block',
+          count: nextCount,
+          message: formatBlockMessage(tool, nextCount),
+        }
+      }
+
+      if (nextCount >= softWarn && !nextState.warned) {
+        nextState.warned = true
+        touch(sessionId, nextState)
+        return {
+          kind: 'warn',
+          count: nextCount,
+          message: formatWarnMessage(tool, nextCount),
+        }
+      }
+
+      touch(sessionId, nextState)
+      return { kind: 'ok' }
+    },
+    reset(sessionId) {
+      const existing = sessions.get(sessionId)
+      if (!existing) return
+      // Resetting is what `tool.after` does on a non-identical call too;
+      // exposed for callers that observe a strategy change externally.
+      sessions.delete(sessionId)
+    },
+    forget(sessionId) {
+      sessions.delete(sessionId)
+    },
+  }
+}
+
+function formatWarnMessage(tool: string, count: number): string {
+  return (
+    `\n\n[loop-guard] You have called \`${tool}\` ${count} times in a row with identical arguments. ` +
+    `This looks like a thought-loop. If you have enough information, produce the final answer now. ` +
+    `If something is unclear, ask the user one specific question. Do not repeat this exact call.`
+  )
+}
+
+function formatBlockMessage(tool: string, count: number): string {
+  return (
+    `loop-guard: refused \`${tool}\` — identical call repeated ${count} times in a row. ` +
+    `Stop. Either (1) produce the final answer with the data you already have, ` +
+    `(2) ask the user a clarifying question, or (3) try a meaningfully different approach. ` +
+    `Do not retry this exact call.`
+  )
+}
+
+function makeCallSignature(tool: string, args: unknown): string {
+  try {
+    return `${tool}:${stableStringify(args)}`
+  } catch {
+    return `${tool}:<unstringifiable>`
+  }
+}
+
+// Order-independent JSON serialization so semantically-identical objects
+// produce identical signatures regardless of key insertion order.
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== 'object') {
+    const s = JSON.stringify(value)
+    return s ?? 'null'
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(',')}]`
+  }
+  const obj = value as Record<string, unknown>
+  const keys = Object.keys(obj).sort()
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(',')}}`
+}

package/src/agent/model-fallback.ts

@@ -4,6 +4,7 @@ import type { KnownModelRef } from '@/config/providers'
 
 import type { AgentSession } from './index'
 import { subscribeProviderErrors } from './provider-error'
+import { renderTurnTimeAnchor } from './system-prompt'
 
 // Result of a single fallback-aware prompt run.
 // - `refUsed` is the ref whose session ultimately handled the turn.
@@ -88,7 +89,7 @@ export async function promptWithFallback(opts: {
     })
     try {
       try {
-        await session.prompt(opts.text)
+        await session.prompt(`${renderTurnTimeAnchor()}\n\n${opts.text}`)
       } catch (err) {
         const error = err instanceof Error ? err : new Error(String(err))
         const attempt: FallbackAttempt = { ref, outcome: 'hard', errorMessage: error.message }

package/src/agent/multimodal/index.ts

@@ -1,4 +1,4 @@
-export { lookAtTool } from './look-at'
+export { createChannelLookAtTool, lookAtTool } from './look-at'
 export {
   buildMultimodalLookerSystemPrompt,
   imageInputSchema,

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

@@ -3,6 +3,9 @@ import type { ImageContent } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
 import { createSessionWithDispose, type SessionOrigin } from '@/agent'
+import { normalizeRef } from '@/agent/tools/normalize-ref'
+import type { ChannelRouter } from '@/channels/router'
+import type { AdapterId } from '@/channels/schema'
 
 import { buildMultimodalLookerSystemPrompt, resolveImage, type ImageInput } from './looker'
 
@@ -20,6 +23,13 @@ type LookAtDetails = {
   error?: string
 }
 
+export type ChannelLookAtOrigin = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  thread: string | null
+}
+
 // Routes an image-bearing turn to a vision-capable subagent so the main
 // session never sees the bytes. Saves main-agent context: when `models.default`
 // is text-only, this is the only way to get vision; when `models.default` IS
@@ -62,61 +72,8 @@ export const lookAtTool = defineTool({
     try {
       const imageInputs = args.images.map(toImageInput)
       const resolved = await Promise.all(imageInputs.map((i) => resolveImage(i, signal)))
-      const imageContents: ImageContent[] = resolved.map((r) => ({
-        type: 'image' as const,
-        data: r.data,
-        mimeType: r.mimeType,
-      }))
-
-      const systemPrompt = buildMultimodalLookerSystemPrompt(args.prompt)
-      const userText =
-        args.prompt !== undefined && args.prompt.trim() !== ''
-          ? args.prompt.trim()
-          : 'Please describe the attached image(s).'
-
-      const origin: SessionOrigin = {
-        kind: 'subagent',
-        subagent: 'multimodal-looker',
-        parentSessionId: '<look-at-tool>',
-      }
-
-      // TODO(usage-accounting): this falls through to SessionManager.inMemory()
-      // because no sessionManager is passed, so the look_at subagent's
-      // message.usage never reaches the sessions/ JSONLs that `typeclaw usage`
-      // and the bundled `backup` plugin scan. Same root-cause class as the
-      // plugin-command/cron-handler path fixed in `runPromptForCommand`
-      // (src/server/command-runner.ts). Fixing this requires threading a
-      // SessionFactory into pi-coding-agent's tool execute() signature, which
-      // is a separate change.
-      const { session, dispose } = await createSessionWithDispose({
-        systemPromptOverride: systemPrompt,
-        origin,
-        profile: 'vision',
-        // Both knobs are required to fully disarm the subagent's tool surface:
-        // `customTools: []` blocks typeclaw's system tools (websearch/webfetch/
-        // 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
-        // into running shell commands or editing files inside its short-lived
-        // session. The looker should only describe images, not act.
-        tools: [],
-        customTools: [],
-      })
-
-      try {
-        await session.prompt(userText, { images: imageContents })
-        const text = extractLastAssistantText(session.messages)
-        if (text === null) {
-          return errorResult('multimodal-looker returned no text response', {
-            count: resolved.length,
-            prompt: args.prompt,
-          })
-        }
-        return successResult(text, { count: resolved.length, prompt: args.prompt })
-      } finally {
-        session.dispose()
-        await dispose()
-      }
+      const imageContents: ImageContent[] = resolved.map((r) => toImageContent(r.data, r.mimeType))
+      return await runLookAtImages(imageContents, args.prompt)
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error)
       return errorResult(message, { count: args.images.length, prompt: args.prompt })
@@ -124,6 +81,112 @@ export const lookAtTool = defineTool({
   },
 })
 
+// Channel attachments intentionally use a separate tool instead of adding
+// channel-only dependencies to the global look_at implementation. This keeps
+// non-channel sessions' image source validation unchanged while channel
+// sessions get router-validated attachment_id lookup.
+export function createChannelLookAtTool(router: ChannelRouter, origin: ChannelLookAtOrigin) {
+  return defineTool({
+    name: 'look_at_channel_attachment',
+    label: 'Look at channel attachment',
+    description:
+      'View an image attached to the current inbound channel message. Inbound messages show ' +
+      '`[<Platform> attachment #N: <kind> <metadata>]`; pass `N` as `attachment_id`. Do not invent ids.',
+    parameters: Type.Object({
+      attachment_id: Type.Integer({
+        description: 'The number N from the inbound `[<Platform> attachment #N: ...]` placeholder.',
+        minimum: 1,
+      }),
+      prompt: Type.Optional(
+        Type.String({ description: 'Optional question to ask about the image; omitted means describe it.' }),
+      ),
+    }),
+    async execute(_toolCallId, params) {
+      const found = router.lookupInboundAttachment({ ...origin, id: params.attachment_id })
+      if (found === null) {
+        const validIds = router.listInboundAttachmentIds(origin)
+        const validMsg =
+          validIds.length === 0
+            ? 'no attachments are present in the current turn'
+            : `valid attachment_ids in this turn: ${validIds.join(', ')}`
+        return errorResult(
+          `no attachment with id=${params.attachment_id} in this turn (${validMsg}). Do not call look_at_channel_attachment for attachments that do not appear in the inbound message — they do not exist.`,
+          { count: 0, prompt: params.prompt },
+        )
+      }
+      if (found.ref === '') {
+        return errorResult(
+          `attachment #${params.attachment_id} (${found.kind}) has no fetchable ref — likely a sticker or an upstream payload without a public URL. Acknowledge the user but do not promise to view it.`,
+          { count: 0, prompt: params.prompt },
+        )
+      }
+      const result = await router.fetchAttachment(origin.adapter, {
+        ref: normalizeRef(found.ref),
+        ...(found.filename !== undefined ? { filename: found.filename } : {}),
+      })
+      if (!result.ok) return errorResult(result.error, { count: 0, prompt: params.prompt })
+      return await runLookAtImages(
+        [toImageContent(result.buffer.toString('base64'), result.mimetype ?? 'image/jpeg')],
+        params.prompt,
+      )
+    },
+  })
+}
+
+function toImageContent(data: string, mimeType: string): ImageContent {
+  return { type: 'image', data, mimeType }
+}
+
+async function runLookAtImages(imageContents: ImageContent[], prompt: string | undefined) {
+  const systemPrompt = buildMultimodalLookerSystemPrompt(prompt)
+  const userText =
+    prompt !== undefined && prompt.trim() !== '' ? prompt.trim() : 'Please describe the attached image(s).'
+
+  const origin: SessionOrigin = {
+    kind: 'subagent',
+    subagent: 'multimodal-looker',
+    parentSessionId: '<look-at-tool>',
+  }
+
+  // TODO(usage-accounting): this falls through to SessionManager.inMemory()
+  // because no sessionManager is passed, so the look_at subagent's
+  // message.usage never reaches the sessions/ JSONLs that `typeclaw usage`
+  // and the bundled `backup` plugin scan. Same root-cause class as the
+  // plugin-command/cron-handler path fixed in `runPromptForCommand`
+  // (src/server/command-runner.ts). Fixing this requires threading a
+  // SessionFactory into pi-coding-agent's tool execute() signature, which
+  // is a separate change.
+  const { session, dispose } = await createSessionWithDispose({
+    systemPromptOverride: systemPrompt,
+    origin,
+    profile: 'vision',
+    // Both knobs are required to fully disarm the subagent's tool surface:
+    // `customTools: []` blocks typeclaw's system tools (websearch/webfetch/
+    // 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
+    // into running shell commands or editing files inside its short-lived
+    // session. The looker should only describe images, not act.
+    tools: [],
+    customTools: [],
+  })
+
+  try {
+    await session.prompt(userText, { images: imageContents })
+    const text = extractLastAssistantText(session.messages)
+    if (text === null) {
+      return errorResult('multimodal-looker returned no text response', {
+        count: imageContents.length,
+        prompt,
+      })
+    }
+    return successResult(text, { count: imageContents.length, prompt })
+  } finally {
+    session.dispose()
+    await dispose()
+  }
+}
+
 function toImageInput(p: ImageParam): ImageInput {
   const hasUrl = 'url' in p && p.url !== undefined && p.url !== ''
   const hasPath = 'path' in p && p.path !== undefined && p.path !== ''