typeclaw 0.12.0 → 0.14.0

package/src/agent/plugin-tools.ts

@@ -31,11 +31,19 @@ import type {
   ToolResult,
 } from '@/plugin'
 
+import { createLoopGuard, type LoopGuard } from './loop-guard'
 import { checkImageReadRedirect } from './multimodal/read-redirect'
 import type { SessionOrigin } from './session-origin'
 import { webfetchTool } from './tools/webfetch'
 import { websearchTool } from './tools/websearch'
 
+// Process-wide loop guard. State is keyed by sessionId so concurrent sessions
+// don't interfere; the guard's own LRU bound keeps it from growing without
+// limit. Wrappers consult it before invoking the underlying tool so the
+// detector covers every tool category — plugin tools, TypeClaw system tools,
+// and pi-coding-agent builtins — through one chokepoint.
+let sharedLoopGuard: LoopGuard = createLoopGuard()
+
 const ACKNOWLEDGE_GUARDS_SCHEMA = Type.Optional(
   Type.Object(
     {
@@ -177,6 +185,11 @@ export function wrapPluginTool(tool: Tool<any>, opts: WrapToolOptions): ToolDefi
         return errorResult(`blocked: ${blockResult.reason}`)
       }
 
+      const loopDecision = sharedLoopGuard.check(opts.sessionId, opts.toolName, before.args)
+      if (loopDecision.kind === 'block') {
+        return errorResult(loopDecision.message)
+      }
+
       const toolCtx: ToolContext = {
         signal,
         sessionId: opts.sessionId,
@@ -192,6 +205,10 @@ export function wrapPluginTool(tool: Tool<any>, opts: WrapToolOptions): ToolDefi
         return errorResult(message)
       }
 
+      if (loopDecision.kind === 'warn') {
+        result = appendLoopWarning(result, loopDecision.message)
+      }
+
       await opts.hooks.runToolAfter({
         tool: opts.toolName,
         sessionId: opts.sessionId,
@@ -227,6 +244,10 @@ export function wrapSystemTool<TParams extends TSchema, TDetails = unknown, TSta
       if (blockResult !== undefined) {
         throw new Error(`blocked: ${blockResult.reason}`)
       }
+      const loopDecision = sharedLoopGuard.check(opts.sessionId, tool.name, mutableArgs)
+      if (loopDecision.kind === 'block') {
+        throw new Error(loopDecision.message)
+      }
       const guardResult = await runFinalWriteGuards({
         tool: tool.name,
         args: mutableArgs,
@@ -246,6 +267,11 @@ export function wrapSystemTool<TParams extends TSchema, TDetails = unknown, TSta
         content: result.content as ContentPart[],
         details: result.details,
       }
+      if (loopDecision.kind === 'warn') {
+        const warned = appendLoopWarning(hookResult, loopDecision.message)
+        hookResult.content = warned.content
+        hookResult.details = warned.details
+      }
       await opts.hooks.runToolAfter({
         tool: tool.name,
         sessionId: opts.sessionId,
@@ -280,6 +306,10 @@ export function wrapSystemAgentTool<TParams extends TSchema, TDetails = unknown>
       if (blockResult !== undefined) {
         throw new Error(`blocked: ${blockResult.reason}`)
       }
+      const loopDecision = sharedLoopGuard.check(opts.sessionId, tool.name, mutableArgs)
+      if (loopDecision.kind === 'block') {
+        throw new Error(loopDecision.message)
+      }
       const guardResult = await runFinalWriteGuards({
         tool: tool.name,
         args: mutableArgs,
@@ -299,6 +329,11 @@ export function wrapSystemAgentTool<TParams extends TSchema, TDetails = unknown>
         content: result.content as ContentPart[],
         details: result.details,
       }
+      if (loopDecision.kind === 'warn') {
+        const warned = appendLoopWarning(hookResult, loopDecision.message)
+        hookResult.content = warned.content
+        hookResult.details = warned.details
+      }
       await opts.hooks.runToolAfter({
         tool: tool.name,
         sessionId: opts.sessionId,
@@ -340,6 +375,10 @@ export function wrapAgentToolAsCustomToolDefinition<TParams extends TSchema, TDe
       if (blockResult !== undefined) {
         throw new Error(`blocked: ${blockResult.reason}`)
       }
+      const loopDecision = sharedLoopGuard.check(opts.sessionId, tool.name, mutableArgs)
+      if (loopDecision.kind === 'block') {
+        throw new Error(loopDecision.message)
+      }
       const guardResult = await runFinalWriteGuards({
         tool: tool.name,
         args: mutableArgs,
@@ -359,6 +398,11 @@ export function wrapAgentToolAsCustomToolDefinition<TParams extends TSchema, TDe
         content: result.content as ContentPart[],
         details: result.details,
       }
+      if (loopDecision.kind === 'warn') {
+        const warned = appendLoopWarning(hookResult, loopDecision.message)
+        hookResult.content = warned.content
+        hookResult.details = warned.details
+      }
       await opts.hooks.runToolAfter({
         tool: tool.name,
         sessionId: opts.sessionId,
@@ -381,6 +425,19 @@ export function buildBuiltinPiToolOverrides(opts: WrapSystemToolOptions): ToolDe
   return defaultBuiltinPiAgentTools().map((tool) => wrapAgentToolAsCustomToolDefinition(tool, opts))
 }
 
+function appendLoopWarning(result: ToolResult, message: string): ToolResult {
+  const content: ContentPart[] = [...(result.content as ContentPart[]), { type: 'text', text: message }]
+  return { content, details: result.details }
+}
+
+// Test-only seam: swaps the shared loop guard for a fresh instance so tests
+// that reuse sessionIds across cases don't see cross-test streak counts.
+// Production code never calls this; the guard's LRU bound handles
+// long-running processes.
+export function __resetSharedLoopGuardForTests(): void {
+  sharedLoopGuard = createLoopGuard()
+}
+
 function errorResult(message: string) {
   return {
     content: [{ type: 'text' as const, text: message }],

package/src/agent/subagents.ts

@@ -7,6 +7,7 @@ import type { Stream, Unsubscribe } from '@/stream'
 import { type AgentSession, createSession } from './index'
 import { subscribeProviderErrors } from './provider-error'
 import type { SessionOrigin } from './session-origin'
+import { renderTurnTimeAnchor } from './system-prompt'
 import type { ToolResultBudget } from './tool-result-budget'
 
 type AgentSessionTools = NonNullable<Parameters<typeof createSession>[0]>['tools']
@@ -226,7 +227,7 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
         await hooks.runSessionTurnStart({ ...turnEvent, userPrompt: userPromptForTurn })
       }
       try {
-        await session.prompt(userPromptForTurn)
+        await session.prompt(`${renderTurnTimeAnchor()}\n\n${userPromptForTurn}`)
       } finally {
         if (hooks && turnEvent !== undefined) {
           await hooks.runSessionTurnEnd(turnEvent)

package/src/agent/system-prompt.ts

@@ -1,4 +1,4 @@
-import { formatLocalDateTime, resolveLocalTimezoneName } from '@/shared'
+import { formatLocalDateTime, formatLocalWeekday, resolveLocalTimezoneName } from '@/shared'
 
 export const DEFAULT_SYSTEM_PROMPT = `You are a general-purpose AI agent running inside TypeClaw.
 
@@ -12,7 +12,17 @@ TypeClaw is domain-agnostic — your purpose is defined by \`IDENTITY.md\`, your
 - **AGENTS.md** *(read on demand)* — your operating manual. Read at the start of any non-trivial task and re-read whenever process is unclear.
 - **\`memory/topics/\`** *(always injected below, READ-ONLY)* — sharded long-term memory, owned by the dreaming subagent. To capture something memorable, surface it in your reply or let the memory-logger append to \`memory/streams/\`; never edit memory shards directly.
 
-If a task reveals durable guidance or identity/user context, update the owning file (IDENTITY / SOUL / USER / AGENTS) — never memory shards.
+If a task reveals durable guidance or identity/user context, update the owning file (IDENTITY / SOUL / USER / AGENTS) — never memory shards. **Use this routing when you have something durable to record:**
+
+- *role, function, scope of work, who you are to this user* → IDENTITY.md
+- *voice, tone, register, language preferences, persona quirks* → SOUL.md
+- *facts about the user (name, timezone, projects, preferences they hold across tasks)* → USER.md
+- *working conventions, repeatable procedures, "always do X" rules, things future-you needs to read before acting* → AGENTS.md
+- *one-off context for this conversation only* → don't write a file; it'll be captured in \`memory/streams/\` automatically
+
+When in doubt between SOUL.md and AGENTS.md: if it describes *how you sound*, it's SOUL; if it describes *how you work*, it's AGENTS. Tone preferences ("be more terse") go to SOUL.md; process rules ("always run tests before committing") go to AGENTS.md.
+
+**Edit discipline.** Prefer rewriting in place to growing files. SOUL.md should stay short — a paragraph or two; if it's drifting past a screen, you're using it as a scratchpad and the model that reads it will start ignoring the back half. IDENTITY.md is similar — a few lines of who you are, not a résumé. AGENTS.md is the one allowed to grow. Don't rewrite SOUL.md on the first piece of tone feedback in a session — wait until the user repeats a preference or asks you directly to update it; a single off-day request isn't a durable change.
 
 ## Your workspace
 
@@ -66,6 +76,8 @@ The bundled \`explorer\` subagent is the right tool for **local** reconnaissance
 
 The bundled \`scout\` subagent is its external counterpart — web research only. Use it when you need information from public sources (docs, library references, vendor changelogs, news, anything not already in this agent's folder). Scout runs \`websearch\` and \`webfetch\` in a fresh context window so the search churn does not pollute yours; it returns a citation-backed answer with a confidence rating. Prefer scout over running \`websearch\`/\`webfetch\` yourself when the research is non-trivial (more than 1-2 queries) or when you want to save your context for the synthesis step.
 
+The bundled \`reviewer\` subagent is for **deep read-only analysis** — code review, PR review, plan review, design review, docs review. It runs on the \`deep\` profile (falls back to \`default\` if \`models.deep\` is unconfigured) so it can spend tokens on careful reasoning. It has the read-only filesystem tools, \`bash\` (for \`gh pr diff\`, \`git log\`, \`git diff\`, \`gh api -X GET\`, etc.), and the web tools (for verifying claims against OWASP, RFCs, library docs). It returns a structured \`<review>\` block with findings (severity \`blocker\`/\`concern\`/\`nit\`/\`praise\`, evidence quotes, suggestions) and a verdict (\`approve\`/\`request-changes\`/\`comment\`). Reviewer does NOT post — when reviewing a PR for a channel that wants comments posted, YOU translate its findings into \`gh api\` review-comment payloads and post them yourself. Use reviewer instead of doing review work in your own session whenever the target is non-trivial: a single-file lookup or a one-paragraph sanity check stays with you; a real PR, a multi-page design doc, a non-trivial plan — delegate.
+
 **Mode B — Delegate-and-converse** (the user asked you to DO something long-running)
 
 When the user hands you a task that will take minutes (a multi-step browser session, a long build, a complex external operation), acknowledge in plain language ("Alright, running that in the background — I'll let you know when it's done"), spawn one subagent with \`run_in_background: true\`, then KEEP TALKING. Stay available for follow-ups, related questions, parallel small tasks. When the completion reminder lands, weave the result into your next reply naturally. If the conversation has gone idle, proactively message the user with the result rather than waiting.
@@ -123,34 +135,35 @@ export function renderRuntimeBlock(version: string): string {
 TypeClaw runtime version: ${version}.`
 }
 
-// Wall-clock anchor for the agent. Without this, models hallucinate the
-// current time (typically defaulting to a UTC-shaped guess from training
-// data), which surfaces as confidently-wrong replies like "it's 6am" when
-// the actual wall-clock is 15:11 +09:00. The container's clock is correct
-// — `-e TZ=<host-tz>` propagation makes `new Date()` resolve to host local
-// time — but the model never sees that value unless we put it in the
-// prompt.
+// Wall-clock anchor injected into the **user turn**, not the system prompt.
+//
+// Why per-turn instead of session-creation: long-lived channel sessions can
+// outlive a session-creation timestamp by days (a session opened Friday and
+// woken Thursday morning happily reports "today is Friday" because the only
+// dated reference in its context is the stale stamp). The per-turn anchor
+// always reflects the moment the turn is about to be sent, so the model
+// answers "what day is it" against `new Date()` rather than against the
+// session-creation snapshot.
 //
-// Positioned as the very last block of the system prompt (after memory)
-// because it changes on every session creation, which is more frequent
-// than any other section: memory changes per dreaming/memory-logger cycle,
-// gitNudge changes per session, but `now` changes per second. Pinning it
-// to the tail means every byte UP TO this block stays in the provider's
-// cache prefix across session resurrections, and only the trailing ~60
-// bytes invalidate.
+// Why this still respects the prompt cache: the user turn is the only
+// non-cacheable suffix in every provider's KV cache shape. Putting the
+// anchor here invalidates exactly zero cached bytes — the same bytes that
+// would already be re-billed on each turn's user message — so this is
+// cache-free relative to the previous "## Now" placement.
 //
-// The model still needs to know this is a session-creation snapshot, not
-// a live clock: long-lived channel sessions can outlive the stamp by
-// hours, and the resource loader is not re-rendered per turn (see the
-// CreateSessionOptions doc at the top of src/agent/index.ts). The prose
-// names the snapshot semantics and tells the model how to get a fresh
-// reading when it matters (run `date` via bash).
-export function renderNowBlock(now: Date): string {
+// The block emits both English and Korean weekday names alongside the ISO
+// timestamp because models replying in a non-English language frequently
+// compute weekday-from-ISO incorrectly; pre-computing the weekday in both
+// candidate reply languages removes that arithmetic step entirely. The
+// framing is a single `<current-time>` XML tag for parity with other
+// runtime-injected per-turn blocks the agent already sees
+// (`<system-reminder>` etc.), so the model reads it as a structured anchor
+// rather than as content authored by a human in the chat.
+export function renderTurnTimeAnchor(now: Date = new Date()): string {
   const iso = formatLocalDateTime(now)
   const zone = resolveLocalTimezoneName()
-  return `## Now
-
-Session started at \`${iso}\` (${zone}). This is a session-creation snapshot, not a live clock — the value above does not advance during this session. If you need the current wall-clock time precisely (e.g. before scheduling a cron, replying with "it's 3pm", or computing a deadline), run \`date\` via bash instead of trusting this stamp; the container's timezone is set to the host's, so \`date\` returns the user's local time.`
+  const weekday = formatLocalWeekday(now)
+  return `<current-time>${iso} (${zone}, ${weekday.en} / ${weekday.ko})</current-time>`
 }
 
 // Compact replacement for DEFAULT_SYSTEM_PROMPT, used by non-interactive

package/src/agent/tools/channel-fetch-attachment.ts

@@ -8,9 +8,13 @@ import type { ChannelRouter } from '@/channels/router'
 import type { AdapterId } from '@/channels/schema'
 
 import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
+import { normalizeRef } from './normalize-ref'
 
 export type ChannelFetchAttachmentOrigin = {
   adapter: AdapterId
+  workspace: string
+  chat: string
+  thread: string | null
 }
 
 export type CreateChannelFetchAttachmentToolOptions = {
@@ -34,18 +38,16 @@ export function createChannelFetchAttachmentTool({
     name: 'channel_fetch_attachment',
     label: 'Channel Fetch Attachment',
     description:
-      'Download a file the user attached to the inbound channel message and save it to disk. Inbound channel ' +
-      'messages with uploads carry a `[<Platform> message with attachment: <name> (<mime>) <ref>]` summary — pass ' +
-      "the literal `<ref>` value as `ref`. For Slack the ref looks like `id=Fxxxx` (use `Fxxxx`); for Discord it's " +
-      'the full `https://cdn.discordapp.com/...` URL. The tool authenticates with the channel adapter (Slack ' +
-      'url_private requires the bot token; Discord CDN URLs are signed and expire ~24h, so fetch promptly). On ' +
-      'success returns the absolute path of the saved file plus its detected mimetype and size. On failure returns ' +
-      'the upstream error verbatim.',
+      'Download a file the user attached to the current inbound channel message and save it to disk. Inbound channel ' +
+      'messages with attachments show `[<Platform> attachment #N: <kind> <metadata>]` in the text. Pass `N` as ' +
+      '`attachment_id`; do not invent ids that are not present in the inbound message. The router validates the id ' +
+      'against the current turn and resolves the private platform ref itself. On success returns the absolute path ' +
+      'of the saved file plus its detected mimetype and size.',
     parameters: Type.Object({
-      ref: Type.String({
+      attachment_id: Type.Integer({
         description:
-          'Slack: the file id `Fxxxx` (with or without the `id=` prefix). Discord: the full `https://cdn.discordapp.com/...` or `https://media.discordapp.net/...` URL.',
-        minLength: 1,
+          'The number N from the inbound `[<Platform> attachment #N: ...]` placeholder. Must be present in this turn.',
+        minimum: 1,
       }),
       filename: Type.Optional(
         Type.String({
@@ -58,10 +60,38 @@ export function createChannelFetchAttachmentTool({
 
     async execute(_toolCallId, params) {
       type Details = { ok: boolean; error?: string; path?: string; mimetype?: string; size?: number }
-      const ref = normalizeRef(params.ref)
+      const found = router.lookupInboundAttachment({
+        adapter,
+        workspace: origin.workspace,
+        chat: origin.chat,
+        thread: origin.thread,
+        id: params.attachment_id,
+      })
+      if (found === null) {
+        const validIds = router.listInboundAttachmentIds({
+          adapter,
+          workspace: origin.workspace,
+          chat: origin.chat,
+          thread: origin.thread,
+        })
+        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 channel_fetch_attachment for attachments that do not appear in the inbound message — they do not exist.`,
+        )
+      }
+      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.`,
+        )
+      }
+      const ref = normalizeRef(found.ref)
+      const filename = params.filename ?? found.filename
       const result = await router.fetchAttachment(adapter, {
         ref,
-        ...(params.filename !== undefined ? { filename: params.filename } : {}),
+        ...(filename !== undefined ? { filename } : {}),
       })
       if (!result.ok) {
         logger.warn(formatChannelToolFailure('channel_fetch_attachment', `${adapter}: ${result.error}`))
@@ -98,10 +128,9 @@ export function createChannelFetchAttachmentTool({
   })
 }
 
-function normalizeRef(ref: string): string {
-  const trimmed = ref.trim()
-  if (trimmed.startsWith('id=')) return trimmed.slice(3)
-  return trimmed
+function errorResult(message: string) {
+  const details = { ok: false, error: message }
+  return { content: [{ type: 'text' as const, text: `channel_fetch_attachment error: ${message}` }], details }
 }
 
 const UNSAFE_FILENAME_CHARS = /[^A-Za-z0-9._-]/g

package/src/agent/tools/normalize-ref.ts

@@ -0,0 +1,11 @@
+export function normalizeRef(ref: string): string {
+  const trimmed = ref.trim()
+  // New classifiers store bare Slack file ids; legacy persisted refs (and
+  // anything still hitting the lookup path from older contextBuffer state)
+  // may carry the old prompt-visible `id=Fxxxx` prefix. Strip it here so
+  // both attachment-fetching tools route the same ref through the adapter
+  // callback — without this, `channel_fetch_attachment` would silently
+  // succeed on a legacy ref while `look_at_channel_attachment` would fail.
+  if (trimmed.startsWith('id=')) return trimmed.slice(3)
+  return trimmed
+}

package/src/agent/tools/skip-response.ts

@@ -39,10 +39,13 @@ export type SkipResponseDetails = {
 // `skip_response` is preferred whenever the model has a reason worth
 // recording. See session-origin.ts for the prompt-level decision rule.
 //
-// Order-dependence with `channel_reply`/`channel_send`: once `skip_response`
-// fires in a turn, the router rejects any subsequent tool-source send for
-// the same turn with `SKIP_RESPONSE_LOCK_ERROR`. The model gets a clear
-// error and learns to commit on the next turn instead of mid-turn.
+// Order-dependence with `channel_reply`/`channel_send` is asymmetric:
+//   - skip BEFORE any send → commits to silence; the router rejects any
+//     subsequent tool-source send this turn with `SKIP_RESPONSE_LOCK_ERROR`.
+//   - skip AFTER a send → accepted as a terminal no-op (`recorded-after-send`).
+//     The earlier reply stands; this posts nothing and ends the turn. Rejecting
+//     it (the old behavior) drove a livelock: denied a clean silent exit, the
+//     model re-sent, got re-denied on the next skip, and repeated to the cap.
 export function createSkipResponseTool({
   router,
   sessionId,
@@ -55,12 +58,14 @@ export function createSkipResponseTool({
       'Decline to send a user-facing reply this turn, with a logged reason. Use this ' +
       'instead of narrating "I have nothing to add" / "I will stay quiet" in your visible ' +
       'response. The reason is written to host logs (visible via `typeclaw logs -f`) but ' +
-      'never delivered to the user. The contract is bidirectional: after calling this, any ' +
-      '`channel_reply` / `channel_send` in the same turn will be rejected, AND calling this ' +
-      'after a `channel_reply` / `channel_send` has already landed in this turn will also ' +
-      'be rejected — commit to silence or commit to replying, not both. Decide before you ' +
-      'send, and call this as your terminal tool when you decide to stay silent. Prefer ' +
-      'this over the `NO_REPLY` text sentinel whenever you have a reason worth recording.',
+      'never delivered to the user. If you call this BEFORE sending anything this turn, it ' +
+      'commits you to silence and any later `channel_reply` / `channel_send` in the same ' +
+      'turn is rejected. If you call it AFTER a reply has already landed this turn (e.g. you ' +
+      'posted an ack and now want to wait quietly for a backgrounded subagent), it is ' +
+      'accepted as a terminal no-op: your earlier reply stands, nothing further is sent, and ' +
+      'your turn ends. Either way, call this as your terminal tool when you decide to stop ' +
+      'talking — do NOT keep sending "still working" updates. Prefer this over the ' +
+      '`NO_REPLY` text sentinel whenever you have a reason worth recording.',
     parameters: Type.Object({
       reason: Type.String({
         description:
@@ -85,33 +90,20 @@ export function createSkipResponseTool({
       }
 
       const result = router.markTurnSkipped({ parentSessionId: sessionId, reason })
-      if (result.kind === 'send-already-happened') {
-        // Symmetric counterpart of the send-after-skip lock in `router.send()`.
-        // The model already committed to replying earlier in this turn; calling
-        // skip_response now would land the reply AND claim silence at the same
-        // time, which is the contract violation the lock exists to prevent.
-        // Surface a clear error and refuse to stamp the flag so the rest of
-        // the turn behaves as a normal reply turn.
-        logger.warn(
-          formatChannelToolFailure(
-            'skip_response',
-            `channel send already happened this turn (reason=${JSON.stringify(reason)})`,
-          ),
-        )
-        const details: SkipResponseDetails = {
-          ok: false,
-          suppressed: false,
-          reason,
-          error: 'send-already-happened',
-        }
+      if (result.kind === 'recorded-after-send') {
+        // Reply-first skip: an ack already landed; this just ends the turn
+        // quietly. Not suppressed (the reply stands) and not an error (erroring
+        // here is what drove the historical re-send livelock). Router logged it.
+        const details: SkipResponseDetails = { ok: true, suppressed: false, reason }
         return {
           content: [
             {
               type: 'text' as const,
               text:
-                'skip_response denied: you already sent a channel reply in this turn. ' +
-                'Commit to silence or commit to replying, not both. ' +
-                'End your turn now; the reply you already sent stands.',
+                'skip_response accepted: your earlier channel reply this turn stands, and ' +
+                'no further message will be sent. End your turn now — do not send "still ' +
+                'working" updates while a backgrounded subagent runs; the completion ' +
+                'reminder will wake you when it finishes.',
             },
           ],
           details,

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

@@ -103,6 +103,7 @@ export function createSpawnSubagentTool(options: CreateSpawnSubagentToolOptions)
       if (params.description !== undefined) payload.description = params.description
 
       const startedAt = now()
+      const spawnedByRole = permissions?.resolveRole(origin)
       const { handle, completion } = startSubagent(subagentName, {
         registry,
         createSessionForSubagent,
@@ -110,6 +111,7 @@ export function createSpawnSubagentTool(options: CreateSpawnSubagentToolOptions)
         userPrompt: params.prompt,
         payload: subagent.payloadSchema ? payload : undefined,
         parentSessionId,
+        ...(spawnedByRole !== undefined ? { spawnedByRole } : {}),
         ...(origin !== undefined ? { spawnedByOrigin: origin } : {}),
         taskId,
       })

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

@@ -0,0 +1,11 @@
+import { definePlugin } from '@/plugin'
+
+import { createReviewerSubagent } from './reviewer'
+
+export default definePlugin({
+  plugin: async () => ({
+    subagents: {
+      reviewer: createReviewerSubagent(),
+    },
+  }),
+})