typeclaw 0.1.5 → 0.2.0

package/src/role-claim/controller.ts

@@ -0,0 +1,194 @@
+import type { ClaimHandler } from '@/channels/router'
+import { grantRole, type PermissionService } from '@/permissions'
+
+import { extractClaimCode } from './code'
+import { formatClaimMatchRule } from './match-rule'
+import { createPendingClaimRegistry, type PendingClaim, type PendingClaimRegistry } from './pending'
+
+// ClaimController is the runtime singleton that ties the four moving parts
+// of the role-claim flow together:
+//
+//   1. The host CLI (typeclaw role claim) opens a WS and sends `claim_start`.
+//   2. The WS server forwards that to controller.startClaim().
+//   3. The channel router's claimHandler (also wired here) intercepts DMs
+//      bearing the code and calls controller.tryConsumeInbound().
+//   4. On consume, the controller writes to typeclaw.json#roles.<role>.match
+//      via grantRole, then reloads the live PermissionService so the new
+//      match rule takes effect without a container restart.
+//
+// Result events (completed / error / cancelled) are pushed to subscribers
+// the WS server registers, so the host CLI's open WS receives the outcome
+// over the same connection.
+
+export type ClaimCompletedEvent = {
+  kind: 'completed'
+  code: string
+  role: string
+  matchRule: string
+  adapter: string
+  authorId: string
+}
+
+export type ClaimErrorEvent = {
+  kind: 'error'
+  code: string
+  reason: string
+}
+
+export type ClaimCancelledEvent = {
+  kind: 'cancelled'
+  code: string
+}
+
+export type ClaimResultEvent = ClaimCompletedEvent | ClaimErrorEvent | ClaimCancelledEvent
+
+export type ClaimController = {
+  startClaim: (input: { code: string; role: string; channel?: string; ttlMs: number }) =>
+    | {
+        ok: true
+        expiresAt: number
+      }
+    | { ok: false; reason: string }
+  cancelClaim: (code: string) => boolean
+  current: () => PendingClaim | null
+  onResult: (subscriber: (event: ClaimResultEvent) => void) => () => void
+  claimHandler: ClaimHandler
+}
+
+export type CreateClaimControllerOptions = {
+  cwd: string
+  permissions: PermissionService
+  rolesProvider: () => import('@/permissions').RolesConfig | undefined
+  now?: () => number
+  registry?: PendingClaimRegistry
+  // Test seam: injectable role granter so tests don't touch disk. Production
+  // wires the real `grantRole` from src/permissions/grant.ts.
+  grant?: (roleName: string, matchRule: string) => { ok: true; added: boolean } | { ok: false; reason: string }
+  logger?: { info: (m: string) => void; warn: (m: string) => void; error: (m: string) => void }
+}
+
+const KNOWN_BUILT_IN_ROLES = new Set(['owner', 'member', 'trusted'])
+
+export function createClaimController(opts: CreateClaimControllerOptions): ClaimController {
+  const now = opts.now ?? Date.now
+  const registry = opts.registry ?? createPendingClaimRegistry({ now })
+  const grant =
+    opts.grant ?? ((roleName: string, matchRule: string) => grantRole({ cwd: opts.cwd, roleName, matchRule }))
+  const logger = opts.logger ?? defaultLogger
+  const subscribers = new Set<(event: ClaimResultEvent) => void>()
+
+  const emit = (event: ClaimResultEvent): void => {
+    for (const sub of subscribers) {
+      try {
+        sub(event)
+      } catch (err) {
+        logger.warn(`[role-claim] subscriber threw: ${describe(err)}`)
+      }
+    }
+  }
+
+  const startClaim: ClaimController['startClaim'] = ({ code, role, channel, ttlMs }) => {
+    if (!isValidRoleName(role)) {
+      return { ok: false, reason: `unknown role '${role}' — built-in roles are owner, member, trusted` }
+    }
+    const startedAt = now()
+    const pending: PendingClaim = {
+      code,
+      role,
+      ttlMs,
+      startedAt,
+      expiresAt: startedAt + ttlMs,
+      ...(channel !== undefined ? { channel } : {}),
+    }
+    registry.start(pending)
+    return { ok: true, expiresAt: pending.expiresAt }
+  }
+
+  const claimHandler: ClaimHandler = async (input) => {
+    const code = extractClaimCode(input.text)
+    if (code === null) return { kind: 'fallthrough' }
+
+    const result = registry.tryConsume(
+      code,
+      {
+        adapter: input.adapter,
+        workspace: input.workspace,
+        chat: input.chat,
+        isDm: input.isDm,
+        authorId: input.authorId,
+      },
+      formatClaimMatchRule,
+    )
+
+    if (result.kind === 'no-pending') return { kind: 'fallthrough' }
+    if (result.kind === 'no-match') return { kind: 'fallthrough' }
+    if (result.kind === 'wrong-channel') {
+      const reply = `That claim is for a different channel — please run typeclaw role claim again on this one.`
+      emit({ kind: 'error', code, reason: 'wrong-channel' })
+      return { kind: 'fail', reply }
+    }
+    if (result.kind === 'expired') {
+      const reply = `That claim code has expired. Run typeclaw role claim again to start a new one.`
+      emit({ kind: 'error', code, reason: 'expired' })
+      return { kind: 'fail', reply }
+    }
+
+    const granted = grant(result.role, result.matchRule)
+    if (!granted.ok) {
+      const reply = `Sorry, I couldn't save your role: ${granted.reason}`
+      emit({ kind: 'error', code, reason: granted.reason })
+      return { kind: 'fail', reply }
+    }
+
+    try {
+      opts.permissions.replaceRoles(opts.rolesProvider())
+    } catch (err) {
+      logger.warn(`[role-claim] replaceRoles failed after grant: ${describe(err)}`)
+    }
+
+    emit({
+      kind: 'completed',
+      code,
+      role: result.role,
+      matchRule: result.matchRule,
+      adapter: result.origin.adapter,
+      authorId: result.origin.authorId,
+    })
+
+    const noteAdded = granted.added ? '' : ' (already on file)'
+    const reply = `You're paired as ${result.role}${noteAdded}. Welcome aboard!`
+    return { kind: 'consumed', reply }
+  }
+
+  return {
+    startClaim,
+    cancelClaim: (code) => {
+      const cancelled = registry.cancel(code)
+      if (cancelled) emit({ kind: 'cancelled', code })
+      return cancelled
+    },
+    current: () => registry.current(),
+    onResult: (sub) => {
+      subscribers.add(sub)
+      return () => {
+        subscribers.delete(sub)
+      }
+    },
+    claimHandler,
+  }
+}
+
+function isValidRoleName(role: string): boolean {
+  if (KNOWN_BUILT_IN_ROLES.has(role)) return true
+  return /^[a-z][a-z0-9-]*$/.test(role) && role !== 'guest'
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+const defaultLogger = {
+  info: (m: string) => console.log(m),
+  warn: (m: string) => console.warn(m),
+  error: (m: string) => console.error(m),
+}

package/src/role-claim/index.ts

@@ -0,0 +1,19 @@
+export { runClaimSession, type ClaimSessionOptions, type ClaimSessionResult } from './client'
+export { CLAIM_CODE_PREFIX, extractClaimCode, generateClaimCode, normalizeClaimCode } from './code'
+export {
+  createClaimController,
+  type ClaimCancelledEvent,
+  type ClaimCompletedEvent,
+  type ClaimController,
+  type ClaimErrorEvent,
+  type ClaimResultEvent,
+  type CreateClaimControllerOptions,
+} from './controller'
+export { formatClaimMatchRule, type PartialChannelOrigin } from './match-rule'
+export {
+  createPendingClaimRegistry,
+  type ClaimResult,
+  type PendingClaim,
+  type PendingClaimRegistry,
+  type PendingClaimRegistryOptions,
+} from './pending'

package/src/role-claim/match-rule.ts

@@ -0,0 +1,43 @@
+// Builds a canonical match-rule DSL string from an inbound channel origin,
+// for the role table. Output shapes:
+//
+//   slack:T0123 author:U_ALICE
+//   discord:9999 author:U_ALICE
+//   telegram:42 author:U_ALICE
+//   kakao:dm/<chatId> author:<authorId>
+//
+// The author qualifier is always emitted so a claim grants the specific
+// human, not the whole workspace. To grant the whole workspace, the
+// operator edits typeclaw.json by hand or runs a future `typeclaw role grant`
+// without --claim.
+
+import type { ChannelKey } from '@/channels/types'
+
+export type PartialChannelOrigin = {
+  adapter: ChannelKey['adapter']
+  workspace: string
+  chat: string
+  isDm: boolean
+  authorId: string
+}
+
+const ADAPTER_TO_PLATFORM: Record<ChannelKey['adapter'], 'slack' | 'discord' | 'telegram' | 'kakao'> = {
+  'slack-bot': 'slack',
+  'discord-bot': 'discord',
+  'telegram-bot': 'telegram',
+  kakaotalk: 'kakao',
+}
+
+export function formatClaimMatchRule(origin: PartialChannelOrigin): string {
+  const platform = ADAPTER_TO_PLATFORM[origin.adapter]
+  const authorQual = ` author:${origin.authorId}`
+  if (origin.adapter === 'kakaotalk') {
+    // Kakao has no workspace; routes use dm/group/open buckets. We can't
+    // know which bucket from a partial origin alone (adapter-side classifies
+    // it), so claim flows are restricted to DM and we emit the specific
+    // chat-id form so the rule grants only this 1:1 conversation, not every
+    // DM the agent is in.
+    return `${platform}:dm/${origin.chat}${authorQual}`
+  }
+  return `${platform}:${origin.workspace}${authorQual}`
+}

package/src/role-claim/pending.ts

@@ -0,0 +1,100 @@
+import type { PartialChannelOrigin } from './match-rule'
+
+export type PendingClaim = {
+  code: string
+  role: string
+  channel?: string
+  ttlMs: number
+  startedAt: number
+  expiresAt: number
+}
+
+export type ClaimResult =
+  | { kind: 'consumed'; code: string; role: string; matchRule: string; origin: PartialChannelOrigin }
+  | { kind: 'no-pending' }
+  | { kind: 'no-match' }
+  | { kind: 'expired' }
+  | { kind: 'wrong-channel' }
+
+export type PendingClaimRegistry = {
+  start: (claim: PendingClaim) => void
+  cancel: (code: string) => boolean
+  current: () => PendingClaim | null
+  // Snapshot of consumption result without actually committing the grant.
+  // The router calls this on every DM-shaped inbound; the grant only fires
+  // when the result is 'consumed'.
+  tryConsume: (
+    code: string,
+    origin: PartialChannelOrigin,
+    formatMatchRule: (origin: PartialChannelOrigin) => string,
+  ) => ClaimResult
+  size: () => number
+}
+
+export type PendingClaimRegistryOptions = {
+  now?: () => number
+}
+
+// Single-claim-at-a-time registry. A second `start` while one is pending
+// replaces the prior code (cancels it implicitly): the operator running
+// `typeclaw role claim` twice from two terminals expects the second invocation
+// to take over, not error.
+//
+// Stored in-memory only — claim sessions are short-lived (default 10 min)
+// and a container restart legitimately invalidates any pending window.
+export function createPendingClaimRegistry(opts: PendingClaimRegistryOptions = {}): PendingClaimRegistry {
+  const now = opts.now ?? Date.now
+  let pending: PendingClaim | null = null
+
+  type ExpiryCheck = { live: PendingClaim } | { live: null; reason: 'no-pending' | 'expired' }
+
+  const expireIfDue = (): ExpiryCheck => {
+    if (pending === null) return { live: null, reason: 'no-pending' }
+    if (now() >= pending.expiresAt) {
+      pending = null
+      return { live: null, reason: 'expired' }
+    }
+    return { live: pending }
+  }
+
+  return {
+    start(claim) {
+      pending = { ...claim }
+    },
+    cancel(code) {
+      if (pending !== null && pending.code === code) {
+        pending = null
+        return true
+      }
+      return false
+    },
+    current() {
+      const check = expireIfDue()
+      return check.live
+    },
+    tryConsume(code, origin, formatMatchRule) {
+      const check = expireIfDue()
+      if (check.live === null) {
+        return { kind: check.reason }
+      }
+      const live = check.live
+      if (code !== live.code) return { kind: 'no-match' }
+      if (live.channel !== undefined && live.channel !== origin.adapter) {
+        return { kind: 'wrong-channel' }
+      }
+      const matchRule = formatMatchRule(origin)
+      const consumed: ClaimResult = {
+        kind: 'consumed',
+        code: live.code,
+        role: live.role,
+        matchRule,
+        origin,
+      }
+      pending = null
+      return consumed
+    },
+    size() {
+      return expireIfDue().live === null ? 0 : 1
+    },
+  }
+}

package/src/run/channel-session-factory.ts

@@ -1,13 +1,26 @@
 import { SessionManager } from '@mariozechner/pi-coding-agent'
 
 import { createSession as defaultCreateSession } from '@/agent'
+import { capJsonlFileInPlace } from '@/bundled-plugins/tool-result-cap/cap-jsonl'
+import type { CapOptions } from '@/bundled-plugins/tool-result-cap/cap-result'
 import type { CreateSessionForChannel, ChannelRouter } from '@/channels'
+import type { PermissionService } from '@/permissions'
 import type { ReloadRegistry } from '@/reload'
 import type { SessionFactory } from '@/sessions'
 import type { Stream } from '@/stream'
 
 import type { PluginRuntime } from './plugin-runtime'
 
+export type FactoryLogger = {
+  info: (message: string) => void
+  warn: (message: string) => void
+}
+
+const consoleLogger: FactoryLogger = {
+  info: (m) => console.info(m),
+  warn: (m) => console.warn(m),
+}
+
 export type BuildChannelSessionFactoryDeps = {
   cwd: string
   sessionFactory: SessionFactory
@@ -20,12 +33,35 @@ export type BuildChannelSessionFactoryDeps = {
   // their inbound messages came from.
   getChannelRouter: () => ChannelRouter
   containerName?: string
+  // When set, rehydrating a session JSONL caps oversized tool results in the
+  // file before pi-coding-agent reads it. `null` disables the load-time pass
+  // (tool-result-cap.enabled=false in config, or no plugin block at all).
+  rehydrateCapOptions: CapOptions | null
+  logger?: FactoryLogger
+  // Forwarded to createSession so the resolved role / permissions for the
+  // session origin get rendered into the agent's system prompt. Optional so
+  // the production wiring can plumb in pluginsLoaded.permissions while tests
+  // (or stand-alone callers) keep the previous no-annotation behavior.
+  permissions?: PermissionService
   // Test seam: lets a fake stand in for the agent session creator so tests
   // can assert exactly which CreateSessionOptions the factory builds without
   // needing a live LLM, plugin runtime, or session manager on disk.
   createSession?: typeof defaultCreateSession
 }
 
+// Tight basename validation so a tampered or corrupt channels/sessions.json
+// can't point the load-time rewrite (or SessionManager.open) at a file
+// outside `sessionDir`. We never receive sessionFile from a remote source
+// during normal operation, but the file is operator-editable, so defense-
+// in-depth is cheap. Match pi-coding-agent's filename convention loosely:
+// no path separators, no NUL, must end in `.jsonl`.
+function isValidSessionFileBasename(name: string): boolean {
+  if (name.length === 0 || name.length > 255) return false
+  if (name.includes('/') || name.includes('\\') || name.includes('\0')) return false
+  if (name === '.' || name === '..' || name.startsWith('.')) return false
+  return name.endsWith('.jsonl')
+}
+
 // The production wiring for channel-routed sessions. Channel inbounds arrive
 // at the router, the router calls this factory to get an AgentSession, and
 // the agent uses `channel_send` to reply. If `channelRouter` is missing here
@@ -35,11 +71,19 @@ export type BuildChannelSessionFactoryDeps = {
 // "channel-aware" sessions that need the same full plumbing.
 export function buildChannelSessionFactory(deps: BuildChannelSessionFactoryDeps): CreateSessionForChannel {
   const createSession = deps.createSession ?? defaultCreateSession
-  return async ({ existingSessionId, existingSessionFile, origin }) => {
+  const logger = deps.logger ?? consoleLogger
+  return async ({ existingSessionId, existingSessionFile, origin, originRef }) => {
     const sessionDir = deps.sessionFactory.sessionDir()
     const sessionManager =
       existingSessionId !== undefined
-        ? tryReopenOrCreate(deps.cwd, sessionDir, existingSessionId, existingSessionFile)
+        ? tryReopenOrCreate(
+            deps.cwd,
+            sessionDir,
+            existingSessionId,
+            existingSessionFile,
+            deps.rehydrateCapOptions,
+            logger,
+          )
         : SessionManager.create(deps.cwd, sessionDir)
 
     const snap = deps.pluginRuntime.get()
@@ -49,6 +93,7 @@ export function buildChannelSessionFactory(deps: BuildChannelSessionFactoryDeps)
       stream: deps.stream,
       channelRouter: deps.getChannelRouter(),
       origin,
+      originRef,
       ...(snap.hasAnyPluginContent
         ? {
             plugins: {
@@ -60,6 +105,7 @@ export function buildChannelSessionFactory(deps: BuildChannelSessionFactoryDeps)
           }
         : {}),
       ...(deps.containerName !== undefined ? { containerName: deps.containerName } : {}),
+      ...(deps.permissions !== undefined ? { permissions: deps.permissions } : {}),
     })
 
     return {
@@ -86,18 +132,43 @@ function tryReopenOrCreate(
   sessionDir: string,
   existingSessionId: string,
   existingSessionFile: string | undefined,
+  capOptions: CapOptions | null,
+  logger: FactoryLogger,
 ): SessionManager {
   if (existingSessionFile === undefined) {
-    console.warn(
+    logger.warn(
       `[channels] session ${existingSessionId} has no sessionFile (v2 mapping not yet migrated); creating new`,
     )
     return SessionManager.create(cwd, sessionDir)
   }
+  if (!isValidSessionFileBasename(existingSessionFile)) {
+    logger.warn(
+      `[channels] session ${existingSessionId} has invalid sessionFile (${JSON.stringify(existingSessionFile)}); creating new`,
+    )
+    return SessionManager.create(cwd, sessionDir)
+  }
+  const path = `${sessionDir}/${existingSessionFile}`
+  if (capOptions !== null) {
+    try {
+      const stats = capJsonlFileInPlace(path, capOptions)
+      if (stats.entriesMutated > 0) {
+        logger.info(
+          `[channels] rehydrate-cap ${existingSessionFile}: entriesMutated=${stats.entriesMutated} imagesReplaced=${stats.imagesReplaced} textsTruncated=${stats.textsTruncated} bytesElided=${stats.bytesElided}`,
+        )
+      }
+    } catch (err) {
+      // Capping is best-effort: if the rewrite fails, fall through to the
+      // regular open path so the session still rehydrates uncapped rather
+      // than being killed by a transient FS error.
+      const reason = err instanceof Error ? err.message : String(err)
+      logger.warn(`[channels] rehydrate-cap failed for ${existingSessionFile}: ${reason}; continuing with open`)
+    }
+  }
   try {
-    return SessionManager.open(`${sessionDir}/${existingSessionFile}`)
+    return SessionManager.open(path)
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err)
-    console.warn(
+    logger.warn(
       `[channels] could not rehydrate session ${existingSessionId} from ${existingSessionFile}: ${reason}; creating new`,
     )
     return SessionManager.create(cwd, sessionDir)

package/src/run/index.ts

@@ -1,6 +1,7 @@
 import { SessionManager } from '@mariozechner/pi-coding-agent'
 
 import { createSession, createSessionWithDispose } from '@/agent'
+import type { SessionOrigin } from '@/agent/session-origin'
 import {
   createSubagentConsumer,
   defaultCreateSessionForSubagent,
@@ -9,6 +10,7 @@ import {
   type SubagentConsumer,
   type SubagentRegistry,
 } from '@/agent/subagents'
+import { resolveCapOptionsFromConfig } from '@/bundled-plugins/tool-result-cap'
 import { createChannelManager, createChannelsReloadable, type ChannelManager } from '@/channels'
 import { createConfigReloadable, getConfig, loadConfigSync, loadPluginConfigsSync } from '@/config'
 import {
@@ -25,6 +27,7 @@ import {
 import { loadPlugins, type LoadPluginsResult, pluginCronJobs, type PluginRegistry, summarizeLoaded } from '@/plugin'
 import { createContainerBroker, publishForwardResult } from '@/portbroker'
 import { ReloadRegistry } from '@/reload'
+import { createClaimController } from '@/role-claim'
 import { hydrateChannelEnvFromSecrets } from '@/secrets'
 import { createServer, type Server } from '@/server'
 import { createSessionFactory, type SessionFactory } from '@/sessions'
@@ -89,7 +92,6 @@ export async function startAgent({
   const containerNameOpt = containerName !== undefined ? { containerName } : {}
   const tuiToken = process.env.TYPECLAW_TUI_TOKEN
   const tuiTokenOpt = tuiToken !== undefined && tuiToken !== '' ? { tuiToken } : {}
-  reloadRegistry.register(createConfigReloadable({ cwd }))
 
   const pluginConfigsByName = loadPluginConfigsSync(cwd)
   const cwdConfig = loadConfigSync(cwd)
@@ -98,7 +100,10 @@ export async function startAgent({
     agentDir: cwd,
     configsByName: pluginConfigsByName,
     bundled: BUNDLED_PLUGINS,
+    ...(cwdConfig.roles !== undefined ? { roles: cwdConfig.roles } : {}),
   })
+
+  reloadRegistry.register(createConfigReloadable({ cwd, permissions: pluginsLoaded.permissions }))
   const pluginRegistry = pluginsLoaded.registry
   const pluginHooks = pluginsLoaded.hooks
 
@@ -130,6 +135,12 @@ export async function startAgent({
   // stay in env, the file stays user-owned. See src/secrets/hydrate.ts.
   hydrateChannelEnvFromSecrets({ agentDir: cwd })
 
+  const claimController = createClaimController({
+    cwd,
+    permissions: pluginsLoaded.permissions,
+    rolesProvider: () => getConfig().roles,
+  })
+
   const channelManager = createChannelManager({
     agentDir: cwd,
     channelsConfigRef: () => getConfig().channels,
@@ -141,8 +152,12 @@ export async function startAgent({
       reloadRegistry,
       pluginRuntime,
       getChannelRouter: () => channelManager.router,
+      rehydrateCapOptions: resolveCapOptionsFromConfig(pluginConfigsByName['tool-result-cap']),
+      permissions: pluginsLoaded.permissions,
       ...containerNameOpt,
     }),
+    permissions: pluginsLoaded.permissions,
+    claimHandler: claimController.claimHandler,
   })
 
   const createSessionForSubagent: import('@/agent/subagents').CreateSessionForSubagent = async (
@@ -152,16 +167,21 @@ export async function startAgent({
     const snap = pluginRuntime.get()
     const entry = snap.pluginSubagentByShim.get(subagent)
     if (entry) {
-      const sessionId = `subagent-${entry.pluginName}-${crypto.randomUUID()}`
-      const origin = {
+      const sessionManager = SessionManager.create(cwd, sessionFactory.sessionDir())
+      const sessionId = sessionManager.getSessionId()
+      const origin: SessionOrigin = {
         kind: 'subagent' as const,
         subagent: subagentOptions?.name ?? entry.subagentName,
         parentSessionId: subagentOptions?.parentSessionId ?? '<unknown>',
+        ...(subagentOptions?.spawnedByRole !== undefined ? { spawnedByRole: subagentOptions.spawnedByRole } : {}),
+        ...(subagentOptions?.spawnedByOrigin !== undefined ? { spawnedByOrigin: subagentOptions.spawnedByOrigin } : {}),
       }
       const created = await createSessionWithDispose({
         systemPromptOverride: entry.pluginSubagent.systemPrompt,
+        sessionManager,
         channelRouter: channelManager.router,
         origin,
+        permissions: pluginsLoaded.permissions,
         plugins: {
           registry: snap.registry,
           hooks: snap.hooks,
@@ -174,6 +194,10 @@ export async function startAgent({
           ...(entry.pluginSubagent.customTools ? { customTools: entry.pluginSubagent.customTools } : {}),
           toolNamePrefix: `__plugin_${entry.pluginName}_${entry.subagentName}`,
         },
+        ...(entry.pluginSubagent.profile !== undefined ? { profile: entry.pluginSubagent.profile } : {}),
+        ...(entry.pluginSubagent.toolResultBudget !== undefined
+          ? { toolResultBudget: entry.pluginSubagent.toolResultBudget }
+          : {}),
       })
       return {
         ...created,
@@ -181,6 +205,7 @@ export async function startAgent({
         sessionId,
         agentDir: cwd,
         origin,
+        getTranscriptPath: () => sessionManager.getSessionFile(),
       }
     }
     return defaultCreateSessionForSubagent(subagent, subagentOptions)
@@ -213,12 +238,24 @@ export async function startAgent({
       const snap = pluginRuntime.get()
       const sessionManager = SessionManager.create(cwd, sessionFactory.sessionDir())
       const sessionId = sessionManager.getSessionId()
+      const cronOrigin: SessionOrigin = {
+        kind: 'cron',
+        jobId: job.id,
+        jobKind: 'prompt',
+        ...(job.scheduledByRole !== undefined ? { scheduledByRole: job.scheduledByRole } : {}),
+        // Honor the persisted audit snapshot when present (TUI-authored
+        // crons, or jobs scheduled by a future `cron_schedule` tool).
+        // Hand-authored entries fall back to the config-file synthetic
+        // marker so the audit trail records "user edited cron.json".
+        scheduledByOrigin: (job.scheduledByOrigin as SessionOrigin | undefined) ?? { kind: 'config-file' },
+      }
       const session = await createSession({
         reloadRegistry,
         sessionManager,
         stream,
         channelRouter: channelManager.router,
-        origin: { kind: 'cron', jobId: job.id, jobKind: 'prompt' },
+        origin: cronOrigin,
+        permissions: pluginsLoaded.permissions,
         ...(snap.hasAnyPluginContent
           ? {
               plugins: {
@@ -236,7 +273,7 @@ export async function startAgent({
         dispose: () => session.dispose(),
         sessionId,
         agentDir: cwd,
-        origin: { kind: 'cron' as const, jobId: job.id, jobKind: 'prompt' as const },
+        origin: cronOrigin,
         ...(snap.hasAnyPluginContent ? { hooks: snap.hooks } : {}),
         getTranscriptPath: () => sessionManager.getSessionFile(),
       }
@@ -264,13 +301,24 @@ export async function startAgent({
   reloadRegistry.register(createChannelsReloadable({ manager: channelManager }))
   await channelManager.start()
 
-  pluginsLoaded.setSpawnSubagent(async (name, payload) => {
+  pluginsLoaded.setSpawnSubagent(async (name, payload, options) => {
+    // Resolve the spawning session's role from its origin so the subagent
+    // inherits it. Callers (hooks like session.idle) pass the parent origin
+    // verbatim; we look up the role rather than letting the caller forge it,
+    // closing the laundering vector the design doc calls out for cron.
+    const spawnedByRole =
+      options?.spawnedByOrigin !== undefined
+        ? pluginsLoaded.permissions.resolveRole(options.spawnedByOrigin)
+        : undefined
     await invokeSubagent(name, {
       registry: pluginRuntime.get().subagents,
       createSessionForSubagent,
       agentDir: cwd,
       userPrompt: '',
       payload,
+      ...(options?.parentSessionId !== undefined ? { parentSessionId: options.parentSessionId } : {}),
+      ...(spawnedByRole !== undefined ? { spawnedByRole } : {}),
+      ...(options?.spawnedByOrigin !== undefined ? { spawnedByOrigin: options.spawnedByOrigin } : {}),
     })
   })
   pluginsLoaded.markBooted()
@@ -313,6 +361,7 @@ export async function startAgent({
     channelRouter: channelManager.router,
     agentDir: cwd,
     pluginRuntime,
+    claimController,
     ...containerNameOpt,
     ...tuiTokenOpt,
     ...containerBrokerOpt,