typeclaw 0.1.5 → 0.1.6

package/src/agent/session-origin.ts

@@ -22,7 +22,13 @@ export type ChannelOriginContext = {
 
 export type SessionOrigin =
   | { kind: 'tui'; sessionId: string }
-  | { kind: 'cron'; jobId: string; jobKind: 'prompt' | 'exec' | 'subagent' }
+  | {
+      kind: 'cron'
+      jobId: string
+      jobKind: 'prompt' | 'exec' | 'subagent'
+      scheduledByRole?: string
+      scheduledByOrigin?: SessionOrigin | { kind: 'config-file' }
+    }
   | {
       kind: 'channel'
       adapter: AdapterId
@@ -35,24 +41,105 @@ export type SessionOrigin =
       participants?: readonly ChannelParticipant[]
       membership?: MembershipCount
     }
-  | { kind: 'subagent'; subagent: string; parentSessionId: string }
+  | {
+      kind: 'subagent'
+      subagent: string
+      parentSessionId: string
+      spawnedByRole?: string
+      spawnedByOrigin?: SessionOrigin
+    }
 
 export const PARTICIPANTS_TOP_K = 10
 export const PARTICIPANTS_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
 
-export function renderSessionOrigin(origin: SessionOrigin, now: number = Date.now()): string {
+// Each adapter renders mentions differently and the model has to copy the
+// exact shape to actually notify a peer. Until this table existed, the
+// channel origin block hardcoded Discord syntax (`<@USER_ID>`) for every
+// non-Slack adapter, which silently misled KakaoTalk and Telegram sessions
+// into emitting addressing tokens that the platform doesn't recognise. The
+// participants block kept rendering `<@authorId> (name)` lines for the
+// same reason — see `renderParticipants`.
+//
+// `mentionMode` semantics:
+//   - 'angle-id'     — Slack/Discord: `<@USER_ID>` where USER_ID is the
+//                      raw `authorId` we already surface in participants.
+//   - 'at-username'  — Telegram: `@username` plain text. The numeric
+//                      `authorId` is NOT what gets mentioned; usernames are
+//                      a separate field that not every user has.
+//   - 'alias'        — KakaoTalk: type the bot's alias as plain text. The
+//                      adapter's classifier (`kakaotalk-classify.ts`) does
+//                      a substring match against configured aliases; there
+//                      is no in-band syntax to copy.
+type PlatformInfo = {
+  displayName: string
+  mentionMode: 'angle-id' | 'at-username' | 'alias'
+}
+
+const PLATFORM_INFO: Record<AdapterId, PlatformInfo> = {
+  'slack-bot': { displayName: 'Slack', mentionMode: 'angle-id' },
+  'discord-bot': { displayName: 'Discord', mentionMode: 'angle-id' },
+  'telegram-bot': { displayName: 'Telegram', mentionMode: 'at-username' },
+  kakaotalk: { displayName: 'KakaoTalk', mentionMode: 'alias' },
+}
+
+function getPlatformInfo(adapter: AdapterId): PlatformInfo {
+  return PLATFORM_INFO[adapter]
+}
+
+// Compact description of the role the runtime resolved for this session at
+// creation time. Rendered as a single block under the origin text for
+// non-TUI sessions so the agent knows what it can and cannot do without
+// having to call into the PermissionService itself. TUI is omitted because
+// TUI is always `owner` by construction — annotating it would add noise to
+// every interactive session for zero new information.
+//
+// For channel sessions this is a session-creation snapshot. The router
+// re-resolves per-turn for tool gating, but the system prompt is not
+// regenerated mid-session; the role line is accurate at admission and the
+// `typeclaw-permissions` skill spells out how to interpret it on later
+// turns when a different speaker may have spoken last.
+export type SessionRoleContext = {
+  role: string
+  permissions: readonly string[]
+}
+
+export function renderSessionOrigin(
+  origin: SessionOrigin,
+  now: number = Date.now(),
+  roleContext?: SessionRoleContext,
+): string {
   switch (origin.kind) {
     case 'tui':
-      return renderTuiOrigin()
+      return withRoleContext(renderTuiOrigin(), roleContext)
     case 'cron':
-      return renderCronOrigin(origin)
+      return withRoleContext(renderCronOrigin(origin), roleContext)
     case 'channel':
-      return renderChannelOrigin(origin, now)
+      return withRoleContext(renderChannelOrigin(origin, now), roleContext)
     case 'subagent':
-      return renderSubagentOrigin(origin)
+      return withRoleContext(renderSubagentOrigin(origin), roleContext)
   }
 }
 
+function withRoleContext(block: string, ctx: SessionRoleContext | undefined): string {
+  if (ctx === undefined) return block
+  return `${block}\n\n${renderRoleContext(ctx)}`
+}
+
+function renderRoleContext(ctx: SessionRoleContext): string {
+  const permList = ctx.permissions.length === 0 ? 'none' : ctx.permissions.map((p) => `\`${p}\``).join(', ')
+  return [
+    '## Your role in this session',
+    '',
+    `Role: \`${ctx.role}\`. Permissions: ${permList}.`,
+    '',
+    'This is the role the runtime resolved at session creation. Tool calls',
+    'and channel admission are gated by these permissions; a `blocked:` or',
+    '"denied by permissions" message means the current actor lacks the',
+    'permission the guard was looking for. See the `typeclaw-permissions`',
+    'skill for what each role can do and how to grant access.',
+  ].join('\n')
+}
+
 function renderTuiOrigin(): string {
   return [
     '## Session origin',
@@ -118,11 +205,11 @@ function renderChannelOrigin(
   // only `text` and pulls addressing from this origin. We point the model at
   // it as the default, and keep channel_send as the escape hatch for posting
   // elsewhere (different chat, breaking out of the thread on purpose, etc.).
-  const platform = origin.adapter === 'slack-bot' ? 'Slack' : 'Discord'
+  const platformInfo = getPlatformInfo(origin.adapter)
   const lines: string[] = [
     '## Session origin',
     '',
-    `You are responding inside a ${platform} channel session. There is no human`,
+    `You are responding inside a ${platformInfo.displayName} channel session. There is no human`,
     'attached to a console here — your only way to communicate with the user',
     'is a tool call. Plain-text output is invisible.',
   ]
@@ -157,11 +244,10 @@ function renderChannelOrigin(
     "matching the channel's `allow` rules are accepted (the tool returns",
     '`{ ok: false }` otherwise).',
     '',
-    `To mention someone in your reply, use ${platform} syntax \`<@USER_ID>\`.`,
-    ...renderMentionExample(origin.participants ?? [], platform, now),
+    ...renderMentionGuidance(platformInfo, origin.participants ?? [], now),
   )
 
-  const participantsBlock = renderParticipants(origin.participants ?? [], now)
+  const participantsBlock = renderParticipants(origin.participants ?? [], platformInfo, now)
   const membershipLine = renderMembershipSummary(origin, now)
   if (membershipLine !== null) lines.push('', membershipLine)
   if (participantsBlock) lines.push('', participantsBlock)
@@ -189,23 +275,11 @@ function renderMembershipSummary(
   return `This channel has approximately ${total} members (about ${membership.humans} humans, ${membership.bots} bots — the bot count is approximate, the full member list was not enumerated because it exceeds the 50-member cap).${caveat} The 10 most recent speakers are listed below.`
 }
 
-function renderMentionExample(
+function renderMentionGuidance(
+  platformInfo: PlatformInfo,
   participants: readonly ChannelParticipant[],
-  platform: 'Discord' | 'Slack',
   now: number,
 ): string[] {
-  // Concrete worked example anchored on a REAL participant when possible.
-  // Models reliably copy concrete examples; abstract `<@USER_ID>` placeholders
-  // get treated as generic instructions and ignored. Prefer a peer bot for
-  // the example because that's the addressing case where plain-text names
-  // silently fail (the human path is forgiving — humans see their name and
-  // respond regardless of mention syntax). Fall back to any non-self
-  // participant, then to a generic placeholder if the channel is brand new.
-  //
-  // Apply the SAME staleness cutoff as `renderParticipants` so we never name
-  // someone in the example who isn't shown in the participants block — that
-  // would surface a "ghost" name from >7d ago and confuse the model about
-  // who is actually around.
   const cutoff = now - PARTICIPANTS_MAX_AGE_MS
   const fresh = [...participants]
     .filter((p) => p.lastMessageAt >= cutoff)
@@ -214,11 +288,32 @@ function renderMentionExample(
   const anyPeer = peerBot ?? fresh[0]
   const exampleId = anyPeer?.authorId ?? '123456789'
   const exampleName = anyPeer?.authorName ?? 'PeerBot'
-  return [
-    `For example, to address ${exampleName} in this conversation, write \`<@${exampleId}> hello\` —`,
-    `**not** "${exampleName} hello". Plain-text names do not notify the recipient on ${platform},`,
-    'and other bots in this channel will not see the message as addressed to them.',
-  ]
+
+  switch (platformInfo.mentionMode) {
+    case 'angle-id':
+      return [
+        `To mention someone in your reply, use ${platformInfo.displayName} syntax \`<@USER_ID>\`.`,
+        `For example, to address ${exampleName} in this conversation, write \`<@${exampleId}> hello\` —`,
+        `**not** "${exampleName} hello". Plain-text names do not notify the recipient on ${platformInfo.displayName},`,
+        'and other bots in this channel will not see the message as addressed to them.',
+      ]
+    case 'at-username':
+      return [
+        `To mention someone in your reply, use Telegram syntax \`@username\` in plain text.`,
+        `Telegram usernames are a SEPARATE field from \`authorId\`. The \`<@id>\` tokens you see in the participants`,
+        'block below are a typeclaw convention for parsing inbound mentions — do not echo them back as outbound mentions.',
+        'If you only know an author by their display name and they have no `@username`, address them by display name',
+        'and they will see the message via the reply context.',
+      ]
+    case 'alias':
+      return [
+        'KakaoTalk has no in-band mention syntax. To address someone, just type their display name as plain text;',
+        "the participants block below shows display names. To get the BOT's attention from outside this session,",
+        "a user types one of the bot's configured aliases — they do not need to copy any token from the participants list.",
+        `The \`<@id>\` tokens in the participants block below are a typeclaw convention for parsing inbound mentions —`,
+        'do not echo them back as outbound mentions; KakaoTalk would render them as literal text.',
+      ]
+  }
 }
 
 function renderConversationLine(origin: {
@@ -239,26 +334,22 @@ function renderConversationLine(origin: {
   return `Conversation: ${chatLabel} in ${workspaceLabel}.`
 }
 
-function renderParticipants(participants: readonly ChannelParticipant[], now: number): string {
+function renderParticipants(
+  participants: readonly ChannelParticipant[],
+  platformInfo: PlatformInfo,
+  now: number,
+): string {
   const cutoff = now - PARTICIPANTS_MAX_AGE_MS
   const fresh = participants.filter((p) => p.lastMessageAt >= cutoff)
   if (fresh.length === 0) return ''
 
   const top = [...fresh].sort((a, b) => b.lastMessageAt - a.lastMessageAt).slice(0, PARTICIPANTS_TOP_K)
 
-  // Format flipped from `name (id: 123)` to `<@123> (name)` so the model sees
-  // the SAME shape it will need to emit when addressing someone — copy-paste
-  // the leading `<@id>` token verbatim. The previous format presented the
-  // human-readable name first and the ID parenthetically, which (combined
-  // with `<@id> (name) [bot]:` in inbound message lines) trained the model
-  // to treat `<@id>` as Discord's render-time decoration rather than syntax
-  // it must produce. Symptom in the wild: 돌쇠 addressing Winky as "Winky님"
-  // (plain text), which never trips Winky's `isBotMention` check, so Winky
-  // observes silently and the conversation stalls.
   const lines = ['## Recent participants (last 7 days, top 10 by recency)', '']
   for (const p of top) {
     const ago = formatAgo(now - p.lastMessageAt)
-    lines.push(`- <@${p.authorId}> (${p.authorName}) — last message: ${ago}, total: ${p.messageCount}`)
+    const addressing = renderParticipantAddressing(p, platformInfo)
+    lines.push(`- ${addressing} — last message: ${ago}, total: ${p.messageCount}`)
   }
   lines.push(
     '',
@@ -268,14 +359,71 @@ function renderParticipants(participants: readonly ChannelParticipant[], now: nu
     'This is **not** the full guild member list, and **not** an audit log',
     'of everyone who ever spoke here.',
     '',
-    "If a sender in the current turn isn't in the list, you can still",
-    'address them — `<@authorId>` works for any author you have seen,',
-    'even once. The list is a convenience for "who\'s been around lately,"',
-    'not an exhaustive directory.',
+    ...renderParticipantsTrailing(platformInfo),
   )
   return lines.join('\n')
 }
 
+// Per-line addressing token shown for each participant. The shape must match
+// what the model will need to emit when addressing that participant, so the
+// model can copy-paste the leading token verbatim. The previous unconditional
+// `<@id> (name)` format trained the model toward angle-id syntax on every
+// platform — correct for Discord/Slack, wrong for KakaoTalk (no in-band
+// mention syntax) and Telegram (uses `@username`, where `authorId` is a
+// numeric id and NOT the username). See issue #188.
+//
+// Symptom in the wild before PR #183 + this fix: 돌쇠 addressing Winky as
+// "Winky님" (plain text) on Discord, which never trips Winky's `isBotMention`
+// check, so Winky observes silently and the conversation stalls. The
+// angle-id branch here is exactly the fix for that case; the at-username
+// and alias branches keep the platform contract honest for KakaoTalk and
+// Telegram instead of self-contradicting the per-adapter mention guidance
+// produced by `renderMentionGuidance`.
+function renderParticipantAddressing(p: ChannelParticipant, platformInfo: PlatformInfo): string {
+  switch (platformInfo.mentionMode) {
+    case 'angle-id':
+      return `<@${p.authorId}> (${p.authorName})`
+    case 'at-username':
+    case 'alias':
+      return `${p.authorName} (${p.authorId})`
+  }
+}
+
+// Closing prose for the participants block. Mirrors the per-platform branch
+// in `renderParticipantAddressing` so the trailing "address them" guidance
+// matches the format the bullet points just demonstrated. The previous
+// unconditional `<@authorId>` prose was the second voice in the
+// self-contradiction noted in issue #188 — it told KakaoTalk/Telegram
+// sessions to address peers with a syntax `renderMentionGuidance` had
+// just told them not to use.
+function renderParticipantsTrailing(platformInfo: PlatformInfo): string[] {
+  switch (platformInfo.mentionMode) {
+    case 'angle-id':
+      return [
+        "If a sender in the current turn isn't in the list, you can still",
+        'address them — `<@authorId>` works for any author you have seen,',
+        'even once. The list is a convenience for "who\'s been around lately,"',
+        'not an exhaustive directory.',
+      ]
+    case 'at-username':
+      return [
+        "If a sender in the current turn isn't in the list, you can still",
+        'address them by `@username` — Telegram usernames are a SEPARATE field',
+        'from the numeric `authorId` shown in parentheses above, and not every',
+        'user has one. The list is a convenience for "who\'s been around',
+        'lately," not an exhaustive directory.',
+      ]
+    case 'alias':
+      return [
+        "If a sender in the current turn isn't in the list, you can still",
+        'address them by display name as plain text — KakaoTalk has no in-band',
+        'mention syntax, so the `authorId` shown in parentheses above is for',
+        'your reference only and must not be echoed back. The list is a',
+        'convenience for "who\'s been around lately," not an exhaustive directory.',
+      ]
+  }
+}
+
 function formatAgo(ms: number): string {
   const sec = Math.max(0, Math.round(ms / 1000))
   if (sec < 60) return `${sec} seconds ago`

package/src/agent/subagents.ts

@@ -6,6 +6,7 @@ import type { Stream, Unsubscribe } from '@/stream'
 
 import { type AgentSession, createSession } from './index'
 import type { SessionOrigin } from './session-origin'
+import type { ToolResultBudget } from './tool-result-budget'
 
 type AgentSessionTools = NonNullable<Parameters<typeof createSession>[0]>['tools']
 
@@ -19,10 +20,15 @@ export type RunSession = (override?: { userPrompt?: string }) => Promise<void>
 
 export type Subagent<P = unknown> = {
   systemPrompt: string
+  // Model profile this subagent prefers. Resolved against `config.models` at
+  // session construction. Unknown profile names fall back to `default` with
+  // a warning. See `Subagent` in `@/plugin/types` for the full contract.
+  profile?: string
   tools?: AgentSessionTools
   customTools?: ToolDefinition[]
   payloadSchema?: z.ZodType<P>
   handler?: (ctx: SubagentContext<P>, runSession: RunSession) => Promise<void>
+  toolResultBudget?: ToolResultBudget
 }
 
 export type SubagentRegistry = Readonly<Record<string, Subagent<any>>>
@@ -62,6 +68,8 @@ export type CreateSessionForSubagentResult = {
 export type CreateSessionForSubagentOptions = {
   name?: string
   parentSessionId?: string
+  spawnedByRole?: string
+  spawnedByOrigin?: SessionOrigin
 }
 export type CreateSessionForSubagent = (
   subagent: Subagent<any>,
@@ -75,9 +83,13 @@ export const defaultCreateSessionForSubagent: CreateSessionForSubagent = (subage
       kind: 'subagent',
       subagent: options?.name ?? '<unknown>',
       parentSessionId: options?.parentSessionId ?? '<unknown>',
+      ...(options?.spawnedByRole !== undefined ? { spawnedByRole: options.spawnedByRole } : {}),
+      ...(options?.spawnedByOrigin !== undefined ? { spawnedByOrigin: options.spawnedByOrigin } : {}),
     },
     ...(subagent.tools ? { tools: subagent.tools } : {}),
     customTools: subagent.customTools ?? [],
+    ...(subagent.profile !== undefined ? { profile: subagent.profile } : {}),
+    ...(subagent.toolResultBudget !== undefined ? { toolResultBudget: subagent.toolResultBudget } : {}),
   })
 
 type NormalizedSubagentSession = {
@@ -120,6 +132,8 @@ export type InvokeSubagentOptions = {
   userPrompt: string
   payload?: unknown
   parentSessionId?: string
+  spawnedByRole?: string
+  spawnedByOrigin?: SessionOrigin
 }
 
 export async function invokeSubagent(name: string, options: InvokeSubagentOptions): Promise<void> {
@@ -131,6 +145,8 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
   const sessionOptions: CreateSessionForSubagentOptions = {
     name,
     ...(options.parentSessionId !== undefined ? { parentSessionId: options.parentSessionId } : {}),
+    ...(options.spawnedByRole !== undefined ? { spawnedByRole: options.spawnedByRole } : {}),
+    ...(options.spawnedByOrigin !== undefined ? { spawnedByOrigin: options.spawnedByOrigin } : {}),
   }
 
   const runSession: RunSession = async (override) => {
@@ -157,11 +173,12 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
           sessionId,
           parentTranscriptPath: getTranscriptPath?.(),
           idleMs: 0,
+          ...(origin !== undefined ? { origin } : {}),
         })
       }
     } finally {
       if (hooks && sessionId !== undefined) {
-        await hooks.runSessionEnd({ sessionId })
+        await hooks.runSessionEnd({ sessionId, ...(origin !== undefined ? { origin } : {}) })
       }
       session.dispose()
       await dispose()
@@ -215,6 +232,40 @@ const consoleLogger: SubagentConsumerLogger = {
   error: (m) => console.error(m),
 }
 
+function parseSpawnedByOriginJson(
+  raw: string | undefined,
+  logger: SubagentConsumerLogger,
+  subagentName: string,
+): SessionOrigin | undefined {
+  if (raw === undefined) return undefined
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    logger.warn(`[subagent] ${subagentName}: ignoring malformed spawnedByOriginJson on stream target: ${message}`)
+    return undefined
+  }
+  // Shape-validate the decoded value so a malformed sender (or a future
+  // bug in cron consumer's encode side) cannot poison the subagent's
+  // origin with arbitrary shapes. The check is narrow: object with a
+  // `kind` field whose value is one of the SessionOrigin discriminator
+  // strings. Permission resolution treats unknown shapes as guest, so
+  // failing closed here matches the rest of the system.
+  if (!isSessionOriginShape(parsed)) {
+    logger.warn(`[subagent] ${subagentName}: ignoring spawnedByOriginJson with unrecognized SessionOrigin shape`)
+    return undefined
+  }
+  return parsed
+}
+
+const SESSION_ORIGIN_KINDS = new Set(['tui', 'cron', 'channel', 'subagent'])
+function isSessionOriginShape(value: unknown): value is SessionOrigin {
+  if (value === null || typeof value !== 'object') return false
+  const kind = (value as { kind?: unknown }).kind
+  return typeof kind === 'string' && SESSION_ORIGIN_KINDS.has(kind)
+}
+
 export function createSubagentConsumer({
   stream,
   getRegistry,
@@ -234,6 +285,8 @@ export function createSubagentConsumer({
           kind: 'new-session'
           subagent: string
           parentSessionId?: string
+          spawnedByRole?: string
+          spawnedByOriginJson?: string
         }
         const name = target.subagent
         const registry = getRegistry()
@@ -248,6 +301,7 @@ export function createSubagentConsumer({
         }
         inFlight.add(key)
         try {
+          const spawnedByOrigin = parseSpawnedByOriginJson(target.spawnedByOriginJson, logger, name)
           await invokeSubagent(name, {
             registry,
             ...(createSessionForSubagent !== undefined ? { createSessionForSubagent } : {}),
@@ -255,6 +309,8 @@ export function createSubagentConsumer({
             userPrompt: '',
             payload: msg.payload,
             ...(target.parentSessionId !== undefined ? { parentSessionId: target.parentSessionId } : {}),
+            ...(target.spawnedByRole !== undefined ? { spawnedByRole: target.spawnedByRole } : {}),
+            ...(spawnedByOrigin !== undefined ? { spawnedByOrigin } : {}),
           })
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err)

package/src/agent/system-prompt.ts

@@ -20,7 +20,7 @@ These files are not decoration. They shape how you behave. If a task reveals som
 
 - **\`workspace/\`** — the directory where you are free to create files: drafts, notes, downloads, scratch work, generated artifacts, temporary outputs. **Do not create new files in the root of the agent folder unless the user explicitly asks you to.** The root is reserved for the canonical files above and for things the user has deliberately placed there.
 - **\`sessions/\`** — transcripts of past conversations (\`<sessionid>.jsonl\`). Read-only for you in spirit; the runtime manages these.
-- **\`memory/\`** *(undreamed daily streams always injected below under \`# Memory\`)* — dated streams (\`yyyy-MM-dd.md\`) of fragments captured by the memory-logger between sessions. Newest day is closest to the current task. Once dreaming consolidates a day's stream into MEMORY.md, the runtime stops injecting it.
+- **\`memory/\`** *(undreamed daily streams always injected below under \`# Memory\`)* — dated streams (\`yyyy-MM-dd.jsonl\`) of fragments captured by the memory-logger between sessions. Newest day is closest to the current task. Once dreaming consolidates a day's stream into MEMORY.md, the runtime stops injecting it.
 - **\`memory/skills/\`** — *muscle memory*. Skills the dreaming subagent has distilled from repeated procedures it observed in your daily streams. Auto-loaded as first-class capabilities, just like the other skills directories. **You do not write here directly** — dreaming owns it. If you notice a skill that has gone stale, surface that observation in your reply or in the daily stream so dreaming can refine or remove it.
 - **\`.agents/skills/\`** — skills the user installed for you. Treat these as first-class capabilities.
 

package/src/agent/tool-result-budget.ts

@@ -0,0 +1,121 @@
+import type { AgentTool } from '@mariozechner/pi-agent-core'
+import type { ToolDefinition } from '@mariozechner/pi-coding-agent'
+import type { TSchema } from '@sinclair/typebox'
+
+// Subagents that read large files (memory-logger and dreaming each read parent
+// session transcripts that can run hundreds of KB) are vulnerable to a class
+// of bug where a single tool malfunction — a broken `find_entry`, a missing
+// watermark, a transcript that no longer contains the watermark id — causes
+// the agent to fall back to scanning the file in 50KB chunks. Every chunk
+// stays in the subagent's conversation history and gets re-sent to the model
+// on every turn until the subagent stops, so a 1MB transcript can balloon a
+// memory-logger run from ~10K input tokens to several hundred thousand.
+//
+// The budget here is a fail-safe ceiling on the total bytes of tool-result
+// text a subagent run is allowed to accumulate from a chosen set of tools.
+// Once exhausted, subsequent calls to those tools short-circuit with a
+// constant-size message that tells the agent to advance the watermark to the
+// latest entry and exit. The budget is per-run (one BudgetState per session)
+// and tracked only for the named tools; tools like `append` (which write,
+// not read) are unaffected.
+
+export type ToolResultBudget = {
+  maxTotalBytes: number
+  toolNames: readonly string[]
+  exhaustedMessage?: (used: number, max: number) => string
+}
+
+export type BudgetState = {
+  used: number
+  exhausted: boolean
+}
+
+export function createBudgetState(): BudgetState {
+  return { used: 0, exhausted: false }
+}
+
+function defaultExhaustedMessage(used: number, max: number): string {
+  const usedKb = Math.round(used / 1024)
+  const maxKb = Math.round(max / 1024)
+  return [
+    `[tool-result budget exhausted: used ${usedKb}KB of ${maxKb}KB this run]`,
+    '',
+    'Stop reading. This session has consumed its byte budget across calls to',
+    'this tool. Do not call this tool again. Stop and exit; future runs will',
+    'continue from wherever your normal end-of-run bookkeeping left off.',
+  ].join('\n')
+}
+
+function bytesOfContent(content: { type: string; text?: string }[] | undefined): number {
+  if (!content) return 0
+  let total = 0
+  for (const part of content) {
+    if (part.type === 'text' && typeof part.text === 'string') {
+      total += Buffer.byteLength(part.text, 'utf8')
+    }
+  }
+  return total
+}
+
+function buildExhaustedResult(budget: ToolResultBudget, state: BudgetState) {
+  const text = (budget.exhaustedMessage ?? defaultExhaustedMessage)(state.used, budget.maxTotalBytes)
+  return {
+    content: [{ type: 'text' as const, text }],
+    details: { budgetExhausted: true, used: state.used, max: budget.maxTotalBytes },
+  }
+}
+
+// Wraps an AgentTool's execute so that returned text content is counted against
+// `state` and the tool short-circuits once `budget.maxTotalBytes` is exceeded.
+// Tools whose name is not in `budget.toolNames` are returned unchanged so the
+// caller can pass an entire `tools` array through and only the tracked tools
+// are affected. The original tool object is preserved by spreading; only
+// `execute` is replaced.
+export function wrapAgentToolWithBudget<TParams extends TSchema, TDetails = unknown>(
+  tool: AgentTool<TParams, TDetails>,
+  budget: ToolResultBudget,
+  state: BudgetState,
+): AgentTool<TParams, TDetails> {
+  if (!budget.toolNames.includes(tool.name)) return tool
+  const originalExecute = tool.execute.bind(tool)
+  return {
+    ...tool,
+    async execute(toolCallId, args, signal, onUpdate) {
+      if (state.exhausted) {
+        return buildExhaustedResult(budget, state) as Awaited<ReturnType<typeof originalExecute>>
+      }
+      const result = await originalExecute(toolCallId, args, signal, onUpdate)
+      state.used += bytesOfContent(result.content as { type: string; text?: string }[] | undefined)
+      if (state.used >= budget.maxTotalBytes) {
+        state.exhausted = true
+      }
+      return result
+    },
+  }
+}
+
+// Same wrapper for ToolDefinition (the customTools surface). Identical
+// semantics; ToolDefinition's execute has an extra `onUpdate` callback and a
+// `ctx` argument that we forward verbatim.
+export function wrapToolDefinitionWithBudget<TParams extends TSchema, TDetails = unknown, TState = unknown>(
+  tool: ToolDefinition<TParams, TDetails, TState>,
+  budget: ToolResultBudget,
+  state: BudgetState,
+): ToolDefinition<TParams, TDetails, TState> {
+  if (!budget.toolNames.includes(tool.name)) return tool
+  const originalExecute = tool.execute.bind(tool)
+  return {
+    ...tool,
+    async execute(toolCallId, args, signal, onUpdate, ctx) {
+      if (state.exhausted) {
+        return buildExhaustedResult(budget, state) as Awaited<ReturnType<typeof originalExecute>>
+      }
+      const result = await originalExecute(toolCallId, args, signal, onUpdate, ctx)
+      state.used += bytesOfContent(result.content as { type: string; text?: string }[] | undefined)
+      if (state.used >= budget.maxTotalBytes) {
+        state.exhausted = true
+      }
+      return result
+    },
+  }
+}

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

@@ -1,6 +1,6 @@
 import { z } from 'zod'
 
-import { definePlugin, type Subagent } from '@/plugin'
+import { definePlugin, type PluginContext, type SpawnSubagentOptions, type Subagent } from '@/plugin'
 
 import { COMMIT_TIMEOUT_MS, makeDefaultGitSpawn, NETWORK_TIMEOUT_MS, runBackup, type BackupResult } from './runner'
 import {
@@ -78,10 +78,19 @@ export default definePlugin({
       if (activeTurns.size > 0) return
       inFlight = true
       try {
-        await ctx.spawnSubagent(SUBAGENT_BACKUP_RUNNER, {
-          agentDir: ctx.agentDir,
-          pushToOrigin,
-        } satisfies RunnerPayload)
+        await ctx.spawnSubagent(
+          SUBAGENT_BACKUP_RUNNER,
+          {
+            agentDir: ctx.agentDir,
+            pushToOrigin,
+          } satisfies RunnerPayload,
+          // The backup runner is a system-level operation that commits +
+          // pushes on the operator's behalf. It runs after every idle
+          // window regardless of which session caused activity, so it has
+          // no single user session to inherit from. Mark it as TUI-equivalent
+          // so it resolves to `owner` and can use git push, etc.
+          { spawnedByOrigin: { kind: 'tui', sessionId: 'backup-runner' } },
+        )
       } catch (err) {
         ctx.logger.error(`backup runner spawn failed: ${err instanceof Error ? err.message : String(err)}`)
       } finally {
@@ -152,12 +161,18 @@ async function runBackupOnce(
   ctx: {
     agentDir: string
     logger: { info: (m: string) => void; warn: (m: string) => void }
-    spawnSubagent: (name: string, payload?: unknown) => Promise<void>
+    spawnSubagent: PluginContext['spawnSubagent']
   },
 ): Promise<BackupResult> {
   const messagePath = messageFilePath(payload.agentDir)
   await ensureMessageDir(messagePath)
   await cleanupMessageFile(messagePath)
+  // Inherit the backup-runner's owner privileges for the message-picking
+  // and diagnose subagents it spawns. Same rationale as the runner itself
+  // — these are system-level operations on the operator's behalf.
+  const inheritOwner: SpawnSubagentOptions = {
+    spawnedByOrigin: { kind: 'tui', sessionId: 'backup-runner' },
+  }
 
   const result = await runBackup(
     { cwd: payload.agentDir, pushToOrigin: payload.pushToOrigin },
@@ -172,7 +187,7 @@ async function runBackupOnce(
           outputPath: messagePath,
         }
         try {
-          await ctx.spawnSubagent(SUBAGENT_COMMIT_MESSAGE, messagePayload)
+          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)}`,
@@ -191,7 +206,7 @@ async function runBackupOnce(
           stdout: input.stdout,
         }
         try {
-          await ctx.spawnSubagent(SUBAGENT_DIAGNOSE, diagPayload)
+          await ctx.spawnSubagent(SUBAGENT_DIAGNOSE, diagPayload, inheritOwner)
         } catch (err) {
           ctx.logger.warn(`${SUBAGENT_DIAGNOSE} subagent failed: ${err instanceof Error ? err.message : String(err)}`)
         }