typeclaw 0.23.0 → 0.25.0

package/src/agent/todo/scope.ts

@@ -0,0 +1,77 @@
+import type { SessionOrigin } from '@/agent/session-origin'
+
+// A todo scope is the durable identity a todo list hangs off. It is
+// deliberately NOT the raw sessionId: sessionIds churn across TUI reconnects
+// and every cron fire, and a channel session can roll to a fresh sessionId on
+// stale-rollover (see src/channels/router.ts SESSION_FRESHNESS_TTL_MS). Keying
+// on origin identity instead lets a todo list survive those transitions so
+// interrupted work can be resumed.
+//
+// `key` is a filesystem-safe relative path segment (no leading slash, no `..`).
+// `kind` mirrors the originating `SessionOrigin['kind']` so the continuation
+// injector can enforce that a nudge only fires into a live session whose origin
+// matches the scope (the eligible-session invariant).
+export type TodoScope = {
+  kind: 'tui' | 'channel' | 'cron'
+  key: string
+}
+
+// Resolve the durable todo scope for a session origin, or `null` when the
+// origin owns no todo list.
+//
+// - tui      → singleton `tui`. There is no stable per-operator identity (the
+//              sessionId churns on every reconnect and the restart handoff is
+//              once-per-boot), so TUI is modeled as one global workstream per
+//              agent. Concurrent TUI attaches therefore share a scope; this is
+//              an accepted, documented limitation.
+// - channel  → keyed by the adapter/workspace/chat/thread tuple, matching how
+//              channels/sessions.json already identifies a conversation. This
+//              survives both container restart and stale-rollover.
+// - cron     → keyed by jobId. The sessionId is useless here (fresh every
+//              fire); the job is the durable identity.
+// - subagent → null. Subagents do not own continuation; their parent does.
+// - system   → null. Runtime infrastructure (memory/backup) is not
+//              user-delegated work and must never auto-continue.
+export function resolveTodoScope(origin: SessionOrigin): TodoScope | null {
+  switch (origin.kind) {
+    case 'tui':
+      return { kind: 'tui', key: 'tui' }
+    case 'channel':
+      return { kind: 'channel', key: channelScopeKey(origin) }
+    case 'cron':
+      return { kind: 'cron', key: `cron/${encodeComponent(origin.jobId)}` }
+    case 'subagent':
+    case 'system':
+      return null
+    default: {
+      const _exhaustive: never = origin
+      void _exhaustive
+      return null
+    }
+  }
+}
+
+function channelScopeKey(origin: { adapter: string; workspace: string; chat: string; thread: string | null }): string {
+  const parts = [
+    encodeComponent(origin.adapter),
+    encodeComponent(origin.workspace),
+    encodeComponent(origin.chat),
+    encodeComponent(origin.thread),
+  ]
+  return `channel/${parts.join(':')}`
+}
+
+// Encode one scope component injectively. Every component is emitted as a
+// discriminant prefix plus its `encodeURIComponent` form:
+//   - null          → `n`        (the channel-root / no-thread case)
+//   - any string s  → `s<encoded>`
+// The prefix makes the three cases pairwise distinguishable that lossy schemes
+// confused: a null thread vs a literal "n" string, an empty string vs a
+// literal "_empty" string, and any value vs another whose unsafe chars happen
+// to map together. `encodeURIComponent` is itself injective and never emits
+// `/` or `:`, so the joined key is both a single filesystem-safe path segment
+// and a collision-free identity for the conversation whose todo file it names.
+function encodeComponent(value: string | null): string {
+  if (value === null) return 'n'
+  return `s${encodeURIComponent(value)}`
+}

package/src/agent/todo/store.ts

@@ -0,0 +1,98 @@
+import { randomUUID } from 'node:crypto'
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname, isAbsolute, join, relative } from 'node:path'
+
+import type { TodoScope } from './scope'
+
+export const TODO_STATUSES = ['pending', 'in_progress', 'completed', 'cancelled'] as const
+export type TodoStatus = (typeof TODO_STATUSES)[number]
+
+export const TODO_PRIORITIES = ['high', 'medium', 'low'] as const
+export type TodoPriority = (typeof TODO_PRIORITIES)[number]
+
+export type Todo = {
+  content: string
+  status: TodoStatus
+  priority?: TodoPriority
+  id?: string
+}
+
+type TodoFile = {
+  version: 1
+  todos: Todo[]
+}
+
+export function todoDir(agentDir: string): string {
+  return join(agentDir, 'todo')
+}
+
+// Defense-in-depth: the resolved file must stay inside todo/. Scope keys from
+// resolveTodoScope are already collision- and traversal-safe, but this function
+// is an exported primitive — a future caller passing a hand-built scope like
+// `{ key: '../sessions/x' }` would otherwise escape. We assert here rather than
+// trust every caller to use resolveTodoScope.
+export function todoContentPath(agentDir: string, scope: TodoScope): string {
+  const dir = todoDir(agentDir)
+  const path = join(dir, `${scope.key}.json`)
+  const rel = relative(dir, path)
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`todo scope key escapes the todo directory: ${JSON.stringify(scope.key)}`)
+  }
+  return path
+}
+
+export async function readTodos(agentDir: string, scope: TodoScope): Promise<Todo[]> {
+  const path = todoContentPath(agentDir, scope)
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch (err) {
+    if (isEnoent(err)) return []
+    throw err
+  }
+  let parsed: Partial<TodoFile>
+  try {
+    parsed = JSON.parse(raw) as Partial<TodoFile>
+  } catch {
+    return []
+  }
+  if (!Array.isArray(parsed.todos)) return []
+  // The file is force-committed and hand-editable, so a corrupt or partially
+  // edited entry can appear. Drop anything that is not a well-formed Todo
+  // rather than let a `null`/malformed item crash incompleteTodos (`t.status`)
+  // or surface as trusted state to the model.
+  return parsed.todos.filter(isValidTodo)
+}
+
+function isValidTodo(value: unknown): value is Todo {
+  if (typeof value !== 'object' || value === null) return false
+  const t = value as Record<string, unknown>
+  if (typeof t.content !== 'string' || t.content.length === 0) return false
+  if (typeof t.status !== 'string' || !(TODO_STATUSES as readonly string[]).includes(t.status)) return false
+  if (t.priority !== undefined && !(TODO_PRIORITIES as readonly string[]).includes(t.priority as string)) return false
+  if (t.id !== undefined && typeof t.id !== 'string') return false
+  return true
+}
+
+// Write is atomic (temp file + rename) so a crash mid-write can never leave a
+// half-serialized JSON file that the next read would throw on. Mirrors the
+// channels/sessions.json writer. A scope is normally owned by a single live
+// session (see resolveTodoScope), so the only concurrent writers are the rare
+// duplicate-attach case, where last-writer-wins on the rename is acceptable —
+// the alternative (lost-update detection) is not worth a lock for a todo list.
+export async function writeTodos(agentDir: string, scope: TodoScope, todos: Todo[]): Promise<void> {
+  const path = todoContentPath(agentDir, scope)
+  const payload: TodoFile = { version: 1, todos }
+  await mkdir(dirname(path), { recursive: true })
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`
+  await writeFile(tmp, `${JSON.stringify(payload, null, 2)}\n`, 'utf8')
+  await rename(tmp, path)
+}
+
+export function incompleteTodos(todos: readonly Todo[]): Todo[] {
+  return todos.filter((t) => t.status !== 'completed' && t.status !== 'cancelled')
+}
+
+function isEnoent(err: unknown): boolean {
+  return typeof err === 'object' && err !== null && (err as { code?: unknown }).code === 'ENOENT'
+}

package/src/agent/tool-not-found-nudge.ts

@@ -0,0 +1,126 @@
+// Minimal structural view of the pieces of pi's AgentSession this module
+// touches. Declared locally (not imported) so the pure nudge logic stays
+// testable with a hand-rolled fake and does not drag in the full session type.
+export type NudgeableSession = {
+  subscribe: (listener: (event: unknown) => void) => () => void
+  steer: (text: string) => Promise<void>
+}
+
+const NOT_FOUND_RE = /^Tool (.+?) not found$/
+
+// Levenshtein distance ceiling for a name to count as "did you mean". A typo
+// like websearch -> web_search is distance 1 (one '_' inserted); read_file ->
+// read is larger but still a clear prefix relationship. Keeping the ceiling
+// small avoids suggesting an unrelated tool for a genuinely unknown name.
+const MAX_SUGGESTION_DISTANCE = 4
+
+export function extractNotFoundToolName(resultText: string): string | null {
+  const match = NOT_FOUND_RE.exec(resultText.trim())
+  return match?.[1] ?? null
+}
+
+export function closestToolName(requested: string, known: readonly string[]): string | null {
+  let best: string | null = null
+  let bestDistance = Number.POSITIVE_INFINITY
+  for (const candidate of known) {
+    if (candidate === requested) return candidate
+    const distance = boundedLevenshtein(requested, candidate, MAX_SUGGESTION_DISTANCE)
+    if (distance < bestDistance) {
+      bestDistance = distance
+      best = candidate
+    }
+  }
+  return bestDistance <= MAX_SUGGESTION_DISTANCE ? best : null
+}
+
+export function renderToolNotFoundNudge(requested: string, suggestion: string): string {
+  return (
+    `<system-reminder>\n` +
+    `You called the tool \`${requested}\`, which does not exist. ` +
+    `Did you mean \`${suggestion}\`? Re-issue the call using the exact name \`${suggestion}\`.\n` +
+    `</system-reminder>`
+  )
+}
+
+export function buildToolNotFoundNudge(resultText: string, known: readonly string[]): string | null {
+  const requested = extractNotFoundToolName(resultText)
+  if (requested === null) return null
+  const suggestion = closestToolName(requested, known)
+  if (suggestion === null || suggestion === requested) return null
+  return renderToolNotFoundNudge(requested, suggestion)
+}
+
+function firstTextChunk(result: unknown): string | null {
+  const content = (result as { content?: unknown })?.content
+  if (!Array.isArray(content)) return null
+  for (const part of content) {
+    if (part && typeof part === 'object' && (part as { type?: unknown }).type === 'text') {
+      const text = (part as { text?: unknown }).text
+      if (typeof text === 'string') return text
+    }
+  }
+  return null
+}
+
+// Watches a session's tool-execution events and, when the model calls a tool
+// name that does not exist but is a near-miss of a real one, steers a
+// "did you mean" reminder into the running turn so the model self-corrects.
+//
+// This lives here, on the session event stream, because pi-agent-core's
+// `prepareToolCall` returns the `Tool X not found` result BEFORE any
+// `beforeToolCall`/`afterToolCall` hook runs — so TypeClaw's tool.before/after
+// buses never see an unknown tool name. The emitted `tool_execution_end` event
+// is the only seam reachable without forking pi. `steer` (not `followUp`)
+// delivers the reminder after the current assistant turn's tool calls settle,
+// which is exactly when the model is ready to retry.
+//
+// The model re-issues the call under the suggested (canonical) name, so every
+// security guard, budget, and loop-guard keyed on that real name applies
+// normally — unlike a silent alias, this rescue path cannot bypass policy.
+export function attachToolNotFoundNudge(session: NudgeableSession, knownToolNames: readonly string[]): () => void {
+  const known = [...new Set(knownToolNames)]
+  // A wedged model re-calls the same wrong name every turn; each steer
+  // spawns a fresh assistant turn that clobbers the subagent's captured
+  // final message (see attachFinalMessageCapture). One reminder per mistake.
+  const nudged = new Set<string>()
+  return session.subscribe((event) => {
+    const e = event as { type?: unknown; isError?: unknown; result?: unknown }
+    if (e?.type !== 'tool_execution_end' || e.isError !== true) return
+    const text = firstTextChunk(e.result)
+    if (text === null) return
+    const requested = extractNotFoundToolName(text)
+    if (requested === null || nudged.has(requested)) return
+    const nudge = buildToolNotFoundNudge(text, known)
+    if (nudge === null) return
+    nudged.add(requested)
+    void session.steer(nudge)
+  })
+}
+
+// Wagner–Fischer with an early bail-out once every cell in a row exceeds the
+// ceiling: a name far from every candidate never produces a suggestion, and
+// the bound keeps the scan cheap when the known-tool list is large.
+function boundedLevenshtein(a: string, b: string, ceiling: number): number {
+  if (a === b) return 0
+  if (Math.abs(a.length - b.length) > ceiling) return ceiling + 1
+
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i)
+  let curr = Array.from({ length: b.length + 1 }, () => 0)
+
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i
+    let rowMin = i
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      const deletion = (prev[j] ?? 0) + 1
+      const insertion = (curr[j - 1] ?? 0) + 1
+      const substitution = (prev[j - 1] ?? 0) + cost
+      const cell = Math.min(deletion, insertion, substitution)
+      curr[j] = cell
+      if (cell < rowMin) rowMin = cell
+    }
+    if (rowMin > ceiling) return ceiling + 1
+    ;[prev, curr] = [curr, prev]
+  }
+  return prev[b.length] ?? ceiling + 1
+}

package/src/agent/tools/channel-reply.ts

@@ -80,6 +80,14 @@ export function createChannelReplyTool({
             'Do not set it just to seem responsive; only when genuine multi-step work follows in the same turn.',
         }),
       ),
+      resolve_review_thread: Type.Optional(
+        Type.Boolean({
+          description:
+            'GitHub review threads ONLY — ignored on Slack, Discord, Telegram, KakaoTalk, and any non-github session, and ignored on a github reply that is not inside a `thread`. On those, leave this unset and ignore the rest of this description. ' +
+            'On a github reply inside a review thread you authored: when your `text` acknowledges the concern is fixed/verified/addressed (e.g. "verified at <sha>", "thanks, that resolves it"), treat setting this `true` as the expected close-out — do it in the SAME call. This is a strong instruction, not a schema requirement: the field stays optional and nothing rejects an acknowledgement that omits it, but a bare ack without it leaves the thread open, because a successful reply ends the turn and the resolve cannot run in a later one. So this flag is the only way the close-out actually happens. ' +
+            "It is safe to set by default: the runtime resolves BEFORE posting and ONLY if the thread's root comment is yours — it refuses (and blocks the reply) on a human reviewer's thread, so you never close someone else's open question. You need not pre-check authorship; just set it on your acknowledgement and let the runtime enforce ownership. Leave it unset when you intend to keep the thread open (partial fix, disagreement, mid-discussion).",
+        }),
+      ),
     }),
 
     async execute(_toolCallId, params) {
@@ -123,6 +131,22 @@ export function createChannelReplyTool({
         }
       }
 
+      // Resolve BEFORE posting: a successful channel_reply ends the turn, so a
+      // resolve attempted "after" the ack would never run (the exact bug this
+      // flag fixes). Resolve-failure blocks the reply so the agent never posts
+      // a "looks resolved" ack next to a still-open thread; the router enforces
+      // that only the bot's own threads can be resolved.
+      if (params.resolve_review_thread === true) {
+        const resolveError = await resolveReviewThreadBeforeReply(router, origin)
+        if (resolveError !== null) {
+          logger.warn(formatChannelToolFailure('channel_reply', resolveError))
+          return {
+            content: [{ type: 'text' as const, text: `channel_reply denied: ${resolveError}` }],
+            details: { ok: false, error: resolveError },
+          }
+        }
+      }
+
       const result = await router.send({
         adapter: origin.adapter,
         workspace: origin.workspace,
@@ -192,6 +216,33 @@ export function createChannelReplyTool({
   })
 }
 
+// Returns an error string when the resolve should block the reply, or null
+// when it's safe to proceed. Only `no-match` (the thread is already gone, so
+// there's nothing to close) joins success as non-blocking; every hard failure
+// — wrong author, permission denial, HTTP 404 on a misdirected lookup,
+// transient API error — blocks, so the agent never claims a thread is settled
+// when the resolve did not actually run.
+async function resolveReviewThreadBeforeReply(
+  router: ChannelRouter,
+  origin: ChannelReplyOrigin,
+): Promise<string | null> {
+  if (origin.adapter !== 'github') {
+    return 'resolve_review_thread is only supported on github sessions.'
+  }
+  if (origin.thread === null) {
+    return 'resolve_review_thread requires replying inside a review thread (no thread on this origin).'
+  }
+  const result = await router.resolveReviewThread({
+    adapter: origin.adapter,
+    workspace: origin.workspace,
+    chat: origin.chat,
+    rootCommentId: origin.thread,
+  })
+  if (result.ok) return null
+  if (result.code === 'no-match') return null
+  return `could not resolve review thread: ${result.error}`
+}
+
 // Tool results reach the model as USER-role messages (OpenAI / Anthropic
 // tool-API contract — the engine cannot tag them as system). Without this
 // marker a persona-rich model reads its own echo as a fresh user inbound

package/src/agent/tools/curl-impersonate.ts

@@ -101,7 +101,7 @@ export async function curlImpersonate(req: CurlImpersonateRequest): Promise<Curl
   const method = req.method ?? 'GET'
 
   // Per-request random sentinel + UTF-8-safe parsing. The static sentinel
-  // approach (previous revision) had a hardening hole: webfetch reads
+  // approach (previous revision) had a hardening hole: web_fetch reads
   // attacker-controlled pages, and a static sentinel is a public, fixed
   // string. A page could include the sentinel byte sequence plus fabricated
   // metadata before the real write-out tail and `indexOf` would split at
@@ -137,7 +137,7 @@ export async function curlImpersonate(req: CurlImpersonateRequest): Promise<Curl
     '--proto-redir',
     '=http,https',
     // `--fail-with-body` would make curl exit non-zero on >=400 but still
-    // write the body. We intentionally DO NOT pass it: callers (webfetch,
+    // write the body. We intentionally DO NOT pass it: callers (web_fetch,
     // ddg) want to inspect httpStatus themselves and decide. Curl exits 0
     // on a 404-with-body in this mode, which matches our contract.
     '--compressed',

package/src/agent/tools/restart.ts

@@ -2,6 +2,7 @@ import { Type } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
 import { requestContainerRestart } from '@/agent/restart'
+import type { RestartHandoffOrigin } from '@/agent/restart-handoff'
 import type { Stream } from '@/stream'
 
 const EXIT_DELAY_MS = 500
@@ -47,11 +48,15 @@ export type CreateRestartToolOptions = {
   // so the `typeclaw.restart-self` custom message entry that was just
   // appended is part of the LLM context on the next turn. When omitted,
   // no handoff is written — the new container cold-starts and no
-  // "I'm back" greeting fires. Gates the handoff on the origin being a
-  // TUI session: channel/cron/subagent origins should pass undefined so
-  // the next boot does not produce a stray channel post or unattended
-  // greeting (see issue #291's scoping concerns).
+  // "I'm back" greeting fires. Written for persisted TUI and channel
+  // origins; cron/subagent/system origins pass undefined so the next boot
+  // does not resume an unattended session.
   originatingSessionFile?: string
+  // Which subsystem owns resuming the originating session on the next boot
+  // (tui → websocket open handler; channel → channel router startup). Required
+  // alongside `originatingSessionFile` for the handoff to be written; omit to
+  // skip the handoff. See buildRestartHandoffWiring in src/agent/index.ts.
+  handoffOrigin?: RestartHandoffOrigin
 }
 
 export type RestartToolDetails = { ok: boolean; containerName: string; reason?: string }
@@ -69,6 +74,7 @@ export function createRestartTool({
   ackTimeoutMs,
   agentDir,
   originatingSessionFile,
+  handoffOrigin,
 }: CreateRestartToolOptions) {
   const doExit = exit ?? ((code: number) => process.exit(code))
 
@@ -114,6 +120,7 @@ export function createRestartTool({
         ...(stream !== undefined ? { stream } : {}),
         ...(agentDir !== undefined ? { agentDir } : {}),
         ...(originatingSessionFile !== undefined ? { originatingSessionFile } : {}),
+        ...(handoffOrigin !== undefined ? { handoffOrigin } : {}),
       })
       if (!result.ok) {
         const details: RestartToolDetails = { ok: false, containerName, reason: result.reason }

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

@@ -7,7 +7,7 @@ import type { PermissionService } from '@/permissions'
 import type { Stream } from '@/stream'
 
 import { type LiveSubagentRegistry, type SubagentCompletion } from '../live-subagents'
-import type { SessionOrigin } from '../session-origin'
+import { MAX_SUBAGENT_DEPTH, type SessionOrigin, subagentDepth } from '../session-origin'
 import { type CreateSessionForSubagent, type Subagent, type SubagentRegistry, startSubagent } from '../subagents'
 
 export const SPAWN_TASK_ID_PREFIX = 'bg_'
@@ -95,6 +95,16 @@ export function createSpawnSubagentTool(options: CreateSpawnSubagentToolOptions)
       if (!hasPermissionForSubagent(permissions, origin, params.subagent_type, subagent)) {
         return errorResult('subagent.spawn denied: insufficient permissions')
       }
+      // Fail closed past the chain-length ceiling. The tool is present on
+      // subagent sessions (operator/reviewer can delegate), but a session
+      // already at MAX_SUBAGENT_DEPTH cannot spawn a deeper one — this is the
+      // execute-time guard against runaway recursion, robust to tool-surface
+      // drift and serialized-origin resumes.
+      if (subagentDepth(origin) >= MAX_SUBAGENT_DEPTH) {
+        return errorResult(
+          `subagent.spawn denied: maximum delegation depth (${MAX_SUBAGENT_DEPTH}) reached; a subagent at this depth cannot spawn further subagents`,
+        )
+      }
 
       const taskId = generateTaskId()
       const subagentName = params.subagent_type
@@ -136,6 +146,11 @@ export function createSpawnSubagentTool(options: CreateSpawnSubagentToolOptions)
       }
       liveRegistry.register(live)
 
+      const channelKey =
+        origin?.kind === 'channel'
+          ? { adapter: origin.adapter, workspace: origin.workspace, chat: origin.chat, thread: origin.thread }
+          : undefined
+
       void completion.then((c) => {
         const durationMs = now() - startedAt
         liveRegistry.recordCompletion(taskId, completionToFinalShape(c, durationMs))
@@ -150,6 +165,7 @@ export function createSpawnSubagentTool(options: CreateSpawnSubagentToolOptions)
               ok: c.ok,
               durationMs,
               ...(c.ok ? {} : { error: c.error }),
+              ...(channelKey !== undefined ? { channelKey } : {}),
             },
           })
         }
@@ -218,7 +234,8 @@ export function spawnSubagentDescription(registry: SubagentRegistry): string {
     `When run_in_background=true (preferred for long-running work), the tool returns a task_id immediately and the subagent runs concurrently — ` +
     `you will receive a system-reminder when it completes; do NOT poll subagent_output. ` +
     `When run_in_background=false (default), the tool blocks and returns the subagent's final message synchronously. ` +
-    `Subagents cannot recursively spawn other subagents.`
+    `The delegation chain is depth-limited: a subagent you spawn may itself delegate once more, but no deeper — ` +
+    `keep your delegation tree shallow.`
   )
 }
 

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

@@ -13,27 +13,46 @@ export type AuthorizeLiveSubagentAccessArgs = {
   liveRegistry: LiveSubagentRegistry
   taskId: string
   permission: SubagentAccessPermission
+  // The caller's own session id. When the caller is itself a subagent, access
+  // is scoped to subagents IT spawned (live.parentSessionId === callerSessionId)
+  // so a nested subagent cannot read or cancel siblings or parent-branch runs.
+  // Omitted by main-session callers, which keep the role-severity cap only.
+  callerSessionId?: string
 }
 
 // Authorizes a single subagent_output/subagent_cancel call and resolves the
-// live entry in one place so the two tools cannot drift. Caps access to the
-// requester's role: the caller must hold the permission AND resolve to a role
-// at least as high as the role that spawned the subagent.
+// live entry in one place so the two tools cannot drift. Two authorization
+// modes, both requiring the base permission first:
+//   - SUBAGENT caller: scoped to runs it spawned (live.parentSessionId ===
+//     callerSessionId). Ownership is the authorization; the role cap is skipped.
+//   - MAIN-SESSION caller: capped to the requester's role — must resolve to a
+//     role at least as high as the role that spawned the subagent.
 //
 // The ordering closes an existence oracle: the task-independent base-permission
 // check runs BEFORE any registry lookup, and for non-owner callers an absent
 // task, a capped task, and a task with missing provenance all collapse to one
 // identical denial — so a lower-role caller cannot probe which task IDs are
 // live. Only `owner` (the trust root, which outranks every spawner) learns the
-// truthful `Unknown task_id` for a genuine miss. The cap fails closed.
+// truthful `Unknown task_id` for a genuine miss. Both modes fail closed.
 export function authorizeLiveSubagentAccess(args: AuthorizeLiveSubagentAccessArgs): SubagentAccessResult {
-  const { permissions, origin, liveRegistry, taskId, permission } = args
+  const { permissions, origin, liveRegistry, taskId, permission, callerSessionId } = args
+
+  // A subagent caller may only touch subagents it spawned itself — never a
+  // sibling's or its parent's run. For subagent callers this ownership check
+  // REPLACES the role-severity cap (see the ownershipScoped branch below);
+  // main-session callers (subagent origin absent) skip it and fall through to
+  // the role cap, preserving the operator's global visibility over every spawn.
+  const ownershipScoped = origin?.kind === 'subagent'
+  const opaqueOwnershipDenial = `${permission} denied: unknown task_id or not owned by caller`
 
   if (permissions === undefined) {
     const live = liveRegistry.get(taskId)
     if (live === undefined) {
       return { ok: false, message: `Unknown task_id: ${taskId}.` }
     }
+    if (ownershipScoped && live.parentSessionId !== callerSessionId) {
+      return { ok: false, message: opaqueOwnershipDenial }
+    }
     return { ok: true, live }
   }
 
@@ -43,6 +62,22 @@ export function authorizeLiveSubagentAccess(args: AuthorizeLiveSubagentAccessArg
 
   const requesterRole = permissions.resolveRole(origin)
   const accessAll = requesterRole === 'owner'
+
+  // For a subagent caller, ownership of the run IS the authorization: having
+  // passed the base permission check above, it may manage exactly the children
+  // it spawned. The role-severity cap (below) does NOT apply — a deep subagent
+  // that inherited a low role from, say, a guest channel turn must still be
+  // able to read/cancel its own children; the cap is meant to stop a low-role
+  // MAIN session from reaching a higher-role-spawned run, which ownership
+  // already prevents here. A non-owning subagent caller fails closed.
+  if (ownershipScoped) {
+    const live = liveRegistry.get(taskId)
+    if (live === undefined || live.parentSessionId !== callerSessionId) {
+      return { ok: false, message: opaqueOwnershipDenial }
+    }
+    return { ok: true, live }
+  }
+
   const opaqueDenial = `${permission} denied: unknown task_id or insufficient role`
 
   const live = liveRegistry.get(taskId)

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

@@ -15,10 +15,11 @@ export type CreateSubagentCancelToolOptions = {
   liveRegistry: LiveSubagentRegistry
   getOrigin: () => SessionOrigin | undefined
   permissions?: PermissionService
+  callerSessionId?: string
 }
 
 export function createSubagentCancelTool(options: CreateSubagentCancelToolOptions) {
-  const { liveRegistry, getOrigin, permissions } = options
+  const { liveRegistry, getOrigin, permissions, callerSessionId } = options
 
   return defineTool({
     name: 'subagent_cancel',
@@ -40,6 +41,7 @@ export function createSubagentCancelTool(options: CreateSubagentCancelToolOption
         liveRegistry,
         taskId: params.task_id,
         permission: 'subagent.cancel',
+        ...(callerSessionId !== undefined ? { callerSessionId } : {}),
       })
       if (!access.ok) {
         return errorResult(access.message)

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

@@ -7,6 +7,8 @@ import type { LiveSubagentRegistry, StatusSnapshot, SubagentProgressEvent } from
 import type { SessionOrigin } from '../session-origin'
 import { authorizeLiveSubagentAccess } from './subagent-access'
 
+export const SUBAGENT_OUTPUT_TOOL_NAME = 'subagent_output'
+
 export type SubagentOutputToolDetails =
   | {
       ok: true
@@ -42,14 +44,15 @@ export type CreateSubagentOutputToolOptions = {
   liveRegistry: LiveSubagentRegistry
   getOrigin: () => SessionOrigin | undefined
   permissions?: PermissionService
+  callerSessionId?: string
   now?: () => number
 }
 
 export function createSubagentOutputTool(options: CreateSubagentOutputToolOptions) {
-  const { liveRegistry, getOrigin, permissions, now = () => Date.now() } = options
+  const { liveRegistry, getOrigin, permissions, callerSessionId, now = () => Date.now() } = options
 
   return defineTool({
-    name: 'subagent_output',
+    name: SUBAGENT_OUTPUT_TOOL_NAME,
     label: 'Subagent Output',
     description:
       'Fetch the current state of a subagent you previously spawned. Returns one of three statuses: ' +
@@ -71,6 +74,7 @@ export function createSubagentOutputTool(options: CreateSubagentOutputToolOption
         liveRegistry,
         taskId: params.task_id,
         permission: 'subagent.output',
+        ...(callerSessionId !== undefined ? { callerSessionId } : {}),
       })
       if (!access.ok) {
         return errorResult(access.message)