typeclaw 0.1.4 → 0.1.6

package/src/permissions/permissions.ts

@@ -0,0 +1,196 @@
+import type { SessionOrigin } from '@/agent/session-origin'
+
+import { BUILTIN_ROLE_NAMES, BUILTIN_ROLES, CORE_PERMISSIONS, expandOwnerWildcard, isBuiltinRoleName } from './builtins'
+import type { MatchRule } from './match-rule'
+import { matchesOrigin } from './resolve'
+import type { RoleConfig, RolesConfig } from './schema'
+
+export type PermissionService = {
+  has(origin: SessionOrigin | undefined, permission: string): boolean
+  resolveRole(origin: SessionOrigin | undefined): string
+  describe(origin: SessionOrigin | undefined): { role: string; permissions: readonly string[] }
+  // Rebuilds the resolved role table from the given roles config, preserving
+  // the same plugin-permission set captured at construction time. Used by
+  // the config reloadable so role match-rule edits (typeclaw role claim,
+  // hand-edits to typeclaw.json) take effect without a container restart.
+  replaceRoles(roles: RolesConfig | undefined): void
+}
+
+export type UnknownPermissionWarning = {
+  role: string
+  permission: string
+  hint: string
+}
+
+export const noopPermissionService: PermissionService = {
+  has: () => false,
+  resolveRole: () => 'guest',
+  describe: () => ({ role: 'guest', permissions: [] }),
+  replaceRoles: () => {},
+}
+
+type ResolvedRole = {
+  name: string
+  match: readonly MatchRule[]
+  permissions: readonly string[]
+}
+
+export type CreatePermissionServiceOptions = {
+  roles?: RolesConfig
+  pluginPermissions?: readonly string[]
+}
+
+// Returns warnings for user-declared `permissions[]` strings that aren't
+// in the known universe (core permissions ∪ plugin-declared). Non-fatal;
+// the runtime still resolves the role with the unknown string in its
+// permission list -- `has()` checks for that exact string and would return
+// true if someone happened to check for it. The warning surfaces typos
+// like `security.bypass.secretExfilBach` before they silently fail to
+// gate the corresponding guard.
+export function findUnknownPermissions(
+  roles: RolesConfig | undefined,
+  pluginPermissions: readonly string[],
+): UnknownPermissionWarning[] {
+  if (!roles) return []
+  const known = new Set<string>([...Object.values(CORE_PERMISSIONS), ...pluginPermissions])
+  const out: UnknownPermissionWarning[] = []
+  for (const [role, config] of Object.entries(roles)) {
+    if (config.permissions === undefined) continue
+    for (const perm of config.permissions) {
+      if (!known.has(perm)) {
+        out.push({ role, permission: perm, hint: closestPermission(perm, known) })
+      }
+    }
+  }
+  return out
+}
+
+function closestPermission(target: string, known: ReadonlySet<string>): string {
+  let best: { name: string; distance: number } | null = null
+  for (const name of known) {
+    const d = levenshtein(target, name)
+    if (best === null || d < best.distance) best = { name, distance: d }
+  }
+  if (best === null || best.distance > Math.max(3, Math.floor(target.length * 0.25))) {
+    return 'no close match in known permissions; check spelling'
+  }
+  return `did you mean '${best.name}'?`
+}
+
+function levenshtein(a: string, b: string): number {
+  const la = a.length
+  const lb = b.length
+  if (la === 0) return lb
+  if (lb === 0) return la
+  const prev = new Array<number>(lb + 1)
+  const curr = new Array<number>(lb + 1)
+  for (let j = 0; j <= lb; j++) prev[j] = j
+  for (let i = 1; i <= la; i++) {
+    curr[0] = i
+    for (let j = 1; j <= lb; j++) {
+      curr[j] = Math.min(prev[j]! + 1, curr[j - 1]! + 1, prev[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1))
+    }
+    for (let j = 0; j <= lb; j++) prev[j] = curr[j]!
+  }
+  return prev[lb]!
+}
+
+export function createPermissionService(opts: CreatePermissionServiceOptions = {}): PermissionService {
+  const pluginPermissions = opts.pluginPermissions ?? []
+  let resolved = buildRoleTable(opts.roles ?? {}, pluginPermissions)
+  let byName = new Map(resolved.map((r) => [r.name, r]))
+
+  function resolveRole(origin: SessionOrigin | undefined): string {
+    if (origin === undefined) return 'guest'
+
+    if (origin.kind === 'cron') {
+      const role = origin.scheduledByRole
+      if (role !== undefined && byName.has(role)) return role
+      return 'guest'
+    }
+    if (origin.kind === 'subagent') {
+      const role = origin.spawnedByRole
+      if (role !== undefined && byName.has(role)) return role
+      return 'guest'
+    }
+
+    const matchable = toMatchable(origin)
+    if (matchable === null) return 'guest'
+
+    for (const role of resolved) {
+      for (const rule of role.match) {
+        if (matchesOrigin(rule, matchable)) return role.name
+      }
+    }
+    return 'guest'
+  }
+
+  return {
+    has(origin, permission) {
+      const roleName = resolveRole(origin)
+      const role = byName.get(roleName)
+      if (!role) return false
+      return role.permissions.includes(permission)
+    },
+    resolveRole,
+    describe(origin) {
+      const name = resolveRole(origin)
+      const role = byName.get(name)
+      return { role: name, permissions: role?.permissions ?? [] }
+    },
+    replaceRoles(roles) {
+      resolved = buildRoleTable(roles ?? {}, pluginPermissions)
+      byName = new Map(resolved.map((r) => [r.name, r]))
+    },
+  }
+}
+
+function buildRoleTable(roles: RolesConfig, pluginPermissions: readonly string[]): ResolvedRole[] {
+  const out: ResolvedRole[] = []
+  const seen = new Set<string>()
+
+  for (const name of Object.keys(roles)) {
+    if (seen.has(name)) continue
+    seen.add(name)
+    out.push(resolveOne(name, roles[name], pluginPermissions))
+  }
+
+  for (const name of BUILTIN_ROLE_NAMES) {
+    if (seen.has(name)) continue
+    out.push(resolveOne(name, undefined, pluginPermissions))
+  }
+
+  return out
+}
+
+function resolveOne(name: string, user: RoleConfig | undefined, pluginPermissions: readonly string[]): ResolvedRole {
+  if (isBuiltinRoleName(name)) {
+    const builtin = BUILTIN_ROLES[name]
+    const match = [...builtin.match, ...(user?.match ?? [])]
+    const rawPerms = user?.permissions !== undefined ? user.permissions : [...builtin.permissions]
+    const permissions = name === 'owner' ? expandOwnerWildcard(rawPerms, pluginPermissions) : rawPerms
+    return { name, match, permissions }
+  }
+  return {
+    name,
+    match: user?.match ?? [],
+    permissions: user?.permissions ?? [],
+  }
+}
+
+function toMatchable(origin: SessionOrigin): Parameters<typeof matchesOrigin>[1] | null {
+  switch (origin.kind) {
+    case 'tui':
+      return { kind: 'tui', sessionId: origin.sessionId }
+    case 'channel':
+      return {
+        kind: 'channel',
+        adapter: origin.adapter,
+        workspace: origin.workspace,
+        chat: origin.chat,
+        ...(origin.lastInboundAuthorId !== undefined ? { lastInboundAuthorId: origin.lastInboundAuthorId } : {}),
+      }
+    default:
+      return null
+  }
+}

package/src/permissions/resolve.ts

@@ -0,0 +1,80 @@
+import type { AdapterId } from '@/channels/schema'
+
+import type { MatchRule, Platform } from './match-rule'
+
+const ADAPTER_TO_PLATFORM: Record<AdapterId, Platform> = {
+  'slack-bot': 'slack',
+  'discord-bot': 'discord',
+  'telegram-bot': 'telegram',
+  kakaotalk: 'kakao',
+}
+
+export type MatchableOrigin =
+  | { kind: 'tui'; sessionId?: string }
+  | { kind: 'cron'; jobId?: string }
+  | { kind: 'subagent'; subagent?: string }
+  | {
+      kind: 'channel'
+      adapter: AdapterId
+      workspace: string
+      chat: string
+      lastInboundAuthorId?: string
+    }
+
+export function matchesOrigin(rule: MatchRule, origin: MatchableOrigin): boolean {
+  switch (rule.kind) {
+    case 'wildcard':
+      return origin.kind === 'channel'
+    case 'tui':
+      return origin.kind === 'tui'
+    case 'cron':
+      return origin.kind === 'cron'
+    case 'subagent':
+      if (origin.kind !== 'subagent') return false
+      if (rule.subagent === undefined) return true
+      return origin.subagent === rule.subagent
+    case 'channel':
+      return matchesChannel(rule, origin)
+  }
+}
+
+function matchesChannel(rule: Extract<MatchRule, { kind: 'channel' }>, origin: MatchableOrigin): boolean {
+  if (origin.kind !== 'channel') return false
+  if (ADAPTER_TO_PLATFORM[origin.adapter] !== rule.platform) return false
+
+  if (rule.bucket !== undefined) {
+    if (!matchesBucket(rule.bucket, origin)) return false
+    if (rule.chat !== undefined && rule.chat !== origin.chat) return false
+  } else {
+    if (rule.workspace !== undefined && rule.workspace !== origin.workspace) return false
+    if (rule.chat !== undefined && rule.chat !== origin.chat) return false
+  }
+
+  if (rule.author !== undefined && rule.author !== origin.lastInboundAuthorId) return false
+  return true
+}
+
+// DM and group buckets are inferred from the workspace/chat shape of the
+// inbound origin. Different adapters mark DMs differently — Slack uses an
+// `@dm` workspace marker today, Discord uses a `dm` workspace marker, and
+// KakaoTalk preserves group/open/dm explicitly in its workspace field. We
+// keep the heuristic narrow: a rule that says `slack:dm/*` matches only when
+// the origin's workspace is `@dm` (Slack) or `dm` (Discord). KakaoTalk uses
+// the workspace prefix itself.
+function matchesBucket(
+  bucket: 'dm' | 'group' | 'open',
+  origin: Extract<MatchableOrigin, { kind: 'channel' }>,
+): boolean {
+  const platform = ADAPTER_TO_PLATFORM[origin.adapter]
+  if (platform === 'kakao') {
+    if (bucket === 'dm') return origin.workspace === '@kakao-dm'
+    if (bucket === 'group') return origin.workspace === '@kakao-group'
+    if (bucket === 'open') return origin.workspace === '@kakao-open'
+    return false
+  }
+  if (bucket !== 'dm') return false
+  if (platform === 'slack') return origin.workspace === '@dm'
+  if (platform === 'discord') return origin.workspace === 'dm' || origin.workspace === '@dm'
+  if (platform === 'telegram') return origin.workspace === 'dm' || origin.workspace.startsWith('@')
+  return false
+}

package/src/permissions/schema.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod'
+
+import { isBuiltinRoleName } from './builtins'
+import { type MatchRule, MATCH_RULE_REGEX_SOURCE, parseMatchRule } from './match-rule'
+
+// The `.regex()` is added so the generated JSON Schema emits a `pattern`
+// for editor-time validation (catches typos like `tem:T0123` before the
+// agent ever boots). The pattern is intentionally a permissive
+// over-approximation of what `parseMatchRule` accepts; the parser owns
+// the precise semantic errors (typo suggestions, redundant-form rejection,
+// etc.) at boot time. Layering the two means editors flag obvious shape
+// mistakes immediately and the parser flags the rest with actionable
+// messages.
+const matchRuleSchema: z.ZodType<MatchRule> = z
+  .string()
+  .regex(new RegExp(MATCH_RULE_REGEX_SOURCE), {
+    message: "match rule must look like 'tui' / 'slack:T0123' / 'discord:9999 author:U_X'",
+  })
+  .transform((raw, ctx) => {
+    const parsed = parseMatchRule(raw)
+    if (!parsed.ok) {
+      ctx.addIssue({ code: 'custom', message: parsed.error })
+      return z.NEVER
+    }
+    return parsed.value
+  })
+
+export const MATCH_RULE_JSON_SCHEMA_PATTERN = MATCH_RULE_REGEX_SOURCE
+
+const PERMISSION_NAME = /^[a-z][a-z0-9]*(\.[a-z][a-zA-Z0-9]*)+$/
+
+const permissionSchema = z.string().min(1).regex(PERMISSION_NAME, {
+  message: "permission must be lowercase dotted form like 'cron.schedule' or 'security.bypass.foo'",
+})
+
+const roleConfigSchema = z
+  .object({
+    match: z.array(matchRuleSchema).default([]),
+    permissions: z.array(permissionSchema).optional(),
+  })
+  .strict()
+
+export type RoleConfig = z.infer<typeof roleConfigSchema>
+
+export const rolesConfigSchema = z.record(z.string(), roleConfigSchema).superRefine((roles, ctx) => {
+  for (const [name, role] of Object.entries(roles)) {
+    if (!isValidRoleName(name)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: [name],
+        message: `role name '${name}' must match /^[a-z][a-z0-9-]*$/`,
+      })
+      continue
+    }
+    if (!isBuiltinRoleName(name)) {
+      if (role.permissions === undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [name, 'permissions'],
+          message: `custom role '${name}' must declare 'permissions' (built-in defaults apply only to built-in role names)`,
+        })
+      }
+      if (role.match.length === 0) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [name, 'match'],
+          message: `custom role '${name}' must declare at least one 'match' rule`,
+        })
+      }
+    }
+  }
+})
+
+export type RolesConfig = z.infer<typeof rolesConfigSchema>
+
+const ROLE_NAME = /^[a-z][a-z0-9-]*$/
+function isValidRoleName(name: string): boolean {
+  return ROLE_NAME.test(name)
+}

package/src/plugin/context.ts

@@ -1,6 +1,8 @@
-import type { PluginContext, PluginLogger } from './types'
+import type { PermissionService } from '@/permissions'
 
-export type SpawnSubagentFn = (name: string, payload?: unknown) => Promise<void>
+import type { PluginContext, PluginLogger, SpawnSubagentOptions } from './types'
+
+export type SpawnSubagentFn = (name: string, payload?: unknown, options?: SpawnSubagentOptions) => Promise<void>
 
 export type CreatePluginContextOptions<TConfig> = {
   name: string
@@ -8,6 +10,7 @@ export type CreatePluginContextOptions<TConfig> = {
   agentDir: string
   config: TConfig
   logger: PluginLogger
+  permissions: PermissionService
   spawnSubagent: SpawnSubagentFn
   isBooted: () => boolean
 }
@@ -19,13 +22,14 @@ export function createPluginContext<TConfig>(opts: CreatePluginContextOptions<TC
     agentDir: opts.agentDir,
     config: opts.config,
     logger: opts.logger,
-    spawnSubagent: async (name: string, payload?: unknown) => {
+    permissions: opts.permissions,
+    spawnSubagent: async (name: string, payload?: unknown, options?: SpawnSubagentOptions) => {
       if (!opts.isBooted()) {
         throw new Error(
           `plugin ${opts.name}: spawnSubagent("${name}") called before boot completed; subagent registry is not yet wired`,
         )
       }
-      await opts.spawnSubagent(name, payload)
+      await opts.spawnSubagent(name, payload, options)
     },
   })
 }

package/src/plugin/define.ts

@@ -6,9 +6,11 @@ type DefinePluginSpec<S extends z.ZodType<unknown> | undefined> =
   S extends z.ZodType<infer T>
     ? {
         configSchema: S
+        permissions?: readonly string[]
         plugin: (ctx: PluginContext<T>) => Promise<PluginExports>
       }
     : {
+        permissions?: readonly string[]
         plugin: (ctx: PluginContext<unknown>) => Promise<PluginExports>
       }
 

package/src/plugin/index.ts

@@ -36,6 +36,7 @@ export type {
   SessionIdleEvent,
   SessionPromptEvent,
   SessionStartEvent,
+  SpawnSubagentOptions,
   Subagent,
   SubagentContext,
   Tool,
@@ -54,6 +55,7 @@ export {
   type LoadPluginsOptions,
   type LoadPluginsResult,
 } from './manager'
+export type { PermissionService } from '@/permissions'
 export type { LoadPluginEntryFn, ResolvedPlugin } from './loader'
 export { loadPluginEntry, derivePluginNameFromPackage } from './loader'
 export { materializeSkills, type MaterializedSkills, type SkillEntry } from './skills'

package/src/plugin/manager.ts

@@ -1,6 +1,12 @@
 import { z } from 'zod'
 
 import type { CronJob } from '@/cron'
+import {
+  createPermissionService,
+  findUnknownPermissions,
+  type PermissionService,
+  type RolesConfig,
+} from '@/permissions'
 
 import { createPluginContext, createPluginLogger, type SpawnSubagentFn } from './context'
 import { createHookBus, type HookBus } from './hooks'
@@ -13,6 +19,7 @@ export type LoadPluginsOptions = {
   agentDir: string
   configsByName: Record<string, unknown>
   loadEntry?: LoadPluginEntryFn
+  roles?: RolesConfig
   // Bundled plugins resolved by the runtime (not from typeclaw.json). Loaded
   // before user-declared `entries` so a config block named after a bundled
   // plugin (e.g. "memory") is consumed by the bundled plugin, and so plugin-
@@ -23,6 +30,8 @@ export type LoadPluginsOptions = {
 export type LoadPluginsResult = {
   registry: PluginRegistry
   hooks: HookBus
+  permissions: PermissionService
+  declaredPermissions: readonly string[]
   loadedPlugins: { name: string; version: string | undefined; source: string }[]
   markBooted: () => void
   setSpawnSubagent: (fn: SpawnSubagentFn) => void
@@ -46,6 +55,23 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
     )),
   ]
 
+  const declaredPermissions = collectDeclaredPermissions(allPlugins)
+  const permissions = createPermissionService({
+    ...(opts.roles !== undefined ? { roles: opts.roles } : {}),
+    pluginPermissions: declaredPermissions,
+  })
+
+  // Non-fatal: surface user-declared `permissions[]` strings that aren't in
+  // the known set, so a typo like `security.bypass.secretExfilBach` is
+  // visible at boot rather than silently failing to bypass the matching
+  // guard. We log instead of throw because the runtime still functions --
+  // the unknown string just never matches anything.
+  for (const warning of findUnknownPermissions(opts.roles, declaredPermissions)) {
+    console.warn(
+      `[permissions] role "${warning.role}" declares unknown permission "${warning.permission}" — ${warning.hint}`,
+    )
+  }
+
   for (const { entry, resolved } of allPlugins) {
     if (loaded.find((l) => l.name === resolved.name)) {
       throw new Error(`plugin name conflict: ${resolved.name} (entry ${entry}) already loaded`)
@@ -72,6 +98,7 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
       agentDir: opts.agentDir,
       config: validatedConfig as never,
       logger,
+      permissions,
       spawnSubagent: (name, payload) => spawnSubagentImpl(name, payload),
       isBooted: () => booted,
     })
@@ -106,6 +133,8 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
   return {
     registry,
     hooks,
+    permissions,
+    declaredPermissions,
     loadedPlugins: loaded,
     markBooted: () => {
       booted = true
@@ -116,6 +145,18 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
   }
 }
 
+function collectDeclaredPermissions(
+  plugins: readonly { entry: string; resolved: ResolvedPlugin }[],
+): readonly string[] {
+  const out: string[] = []
+  for (const { resolved } of plugins) {
+    for (const perm of resolved.defined.permissions ?? []) {
+      if (!out.includes(perm)) out.push(perm)
+    }
+  }
+  return out
+}
+
 export function summarizeLoaded(loaded: LoadPluginsResult['loadedPlugins'], registry: PluginRegistry): string {
   const head = loaded.map((p) => (p.version !== undefined ? `${p.name} v${p.version}` : p.name)).join(', ')
   const counts = [

package/src/plugin/registry.ts

@@ -150,6 +150,13 @@ function assertNotEmpty(kind: string, value: string, pluginName: string): void {
 }
 
 function toCronJob(globalId: string, spec: PluginCronJob): CronJob {
+  // Plugin-contributed jobs default to `owner` because they are part of the
+  // agent's bundled (or operator-installed) runtime, not user-channel
+  // schedules. Without this default they would resolve to `guest` and the
+  // bundled memory dreaming cron (which writes MEMORY.md, runs git, etc.)
+  // would lose every security bypass. Hand-authored cron.json entries take
+  // a different path and must declare scheduledByRole explicitly.
+  const scheduledByRole: PromptJob['scheduledByRole'] = 'owner'
   if (spec.kind === 'prompt') {
     const job: PromptJob = {
       id: globalId,
@@ -157,6 +164,7 @@ function toCronJob(globalId: string, spec: PluginCronJob): CronJob {
       enabled: spec.enabled ?? true,
       kind: 'prompt',
       prompt: spec.prompt,
+      scheduledByRole,
       ...(spec.timezone !== undefined ? { timezone: spec.timezone } : {}),
       ...(spec.subagent !== undefined ? { subagent: spec.subagent } : {}),
       ...(spec.payload !== undefined ? { payload: spec.payload } : {}),
@@ -169,6 +177,7 @@ function toCronJob(globalId: string, spec: PluginCronJob): CronJob {
     enabled: spec.enabled ?? true,
     kind: 'exec',
     command: spec.command,
+    scheduledByRole,
     ...(spec.timezone !== undefined ? { timezone: spec.timezone } : {}),
   }
 }

package/src/plugin/types.ts

@@ -1,6 +1,8 @@
 import type { z } from 'zod'
 
 import type { SessionOrigin } from '@/agent/session-origin'
+import type { ToolResultBudget } from '@/agent/tool-result-budget'
+import type { PermissionService } from '@/permissions'
 
 export type ContentPart = { type: 'text'; text: string } | { type: 'image'; mimeType: string; data: string }
 
@@ -40,6 +42,13 @@ export type RunSession = (override?: { userPrompt?: string }) => Promise<void>
 
 export type Subagent<P = unknown> = {
   systemPrompt: string
+  // Model profile this subagent prefers. Resolved against `models` in
+  // typeclaw.json at session construction. Unknown profile names fall back to
+  // `default` with a warning. Well-known names: `default`, `fast`, `deep`,
+  // `vision`. Subagents that want a specific tier (e.g. memory-logger wants
+  // `fast`, dreaming wants `deep`) declare it here so the user only has to
+  // map tier → model in config rather than wire each subagent individually.
+  profile?: string
   tools?: BuiltinToolRef[]
   customTools?: Tool<any>[]
   payloadSchema?: z.ZodType<P>
@@ -50,6 +59,16 @@ export type Subagent<P = unknown> = {
   // parentSessionId so different parent sessions run in parallel while
   // duplicate runs against the same session deduplicate.
   inFlightKey?: (payload: P) => string
+  // Defensive ceiling on cumulative bytes of tool-result text per subagent
+  // run, applied to the named tools only. Once exceeded, subsequent calls to
+  // those tools short-circuit with a fixed message instructing the agent to
+  // stop reading. See `src/agent/tool-result-budget.ts` for the full
+  // rationale; the short version is: a single broken tool (e.g. find_entry
+  // failing because of a schema mismatch) can cause an agent to fall back to
+  // chunked reads of huge files, ballooning subagent token cost. The budget
+  // bounds the blast radius without changing per-call semantics for healthy
+  // runs.
+  toolResultBudget?: ToolResultBudget
 }
 
 // Cron job map keys are local; the runtime prefixes with `__plugin_<plugin-name>_`
@@ -88,6 +107,7 @@ export type SessionStartEvent = {
 
 export type SessionEndEvent = {
   sessionId: string
+  origin?: SessionOrigin
 }
 
 export type SessionIdleEvent = {
@@ -132,6 +152,7 @@ export type ToolBeforeEvent = {
   sessionId: string
   callId: string
   args: Record<string, unknown>
+  origin?: SessionOrigin
 }
 
 export type ToolBeforeResult = void | undefined | { block: true; reason: string }
@@ -168,13 +189,25 @@ export type PluginLogger = {
   error: (msg: string) => void
 }
 
+export type SpawnSubagentOptions = {
+  // Identifies the spawning session so the subagent's session origin carries
+  // parent provenance. Hook handlers that own this context (e.g. session.idle,
+  // session.turn.end) should pass at minimum `parentSessionId` and
+  // `spawnedByOrigin: event.origin`. The runtime resolves `spawnedByRole`
+  // from the origin via the PermissionService, so the spawning session's
+  // role is inherited rather than forged from outside.
+  parentSessionId?: string
+  spawnedByOrigin?: SessionOrigin
+}
+
 export type PluginContext<TConfig = never> = {
   readonly name: string
   readonly version: string | undefined
   readonly agentDir: string
   readonly config: TConfig
   readonly logger: PluginLogger
-  spawnSubagent: (name: string, payload?: unknown) => Promise<void>
+  readonly permissions: PermissionService
+  spawnSubagent: (name: string, payload?: unknown, options?: SpawnSubagentOptions) => Promise<void>
 }
 
 export type PluginExports = {
@@ -233,5 +266,6 @@ export type PluginFixResult = {
 
 export type DefinedPlugin<TConfig = never> = {
   readonly configSchema?: z.ZodType<TConfig>
+  readonly permissions?: readonly string[]
   readonly plugin: (ctx: PluginContext<TConfig>) => Promise<PluginExports>
 }

package/src/reload/client.ts

@@ -16,22 +16,36 @@ export async function requestReload({
   timeoutMs = DEFAULT_TIMEOUT_MS,
 }: RequestReloadOptions): Promise<ReloadResult[]> {
   const ws = new WebSocket(url)
+  const displayUrl = redactUrl(url)
 
   await new Promise<void>((resolve, reject) => {
+    let timer: ReturnType<typeof setTimeout> | undefined
     const onOpen = () => {
       cleanup()
       resolve()
     }
     const onError = (err: unknown) => {
       cleanup()
-      reject(err instanceof Error ? err : new Error(`failed to connect to ${url}`))
+      reject(new Error(`failed to connect to ${displayUrl}: ${err instanceof Error ? err.message : String(err)}`))
+    }
+    const onClose = () => {
+      cleanup()
+      reject(new Error(`connection to ${displayUrl} closed before opening`))
     }
     const cleanup = () => {
+      if (timer !== undefined) clearTimeout(timer)
       ws.removeEventListener('open', onOpen)
       ws.removeEventListener('error', onError)
+      ws.removeEventListener('close', onClose)
     }
+    timer = setTimeout(() => {
+      cleanup()
+      ws.close()
+      reject(new Error(`timed out connecting to ${displayUrl} after ${timeoutMs}ms`))
+    }, timeoutMs)
     ws.addEventListener('open', onOpen, { once: true })
     ws.addEventListener('error', onError, { once: true })
+    ws.addEventListener('close', onClose, { once: true })
   })
 
   try {
@@ -57,3 +71,13 @@ export async function requestReload({
     ws.close()
   }
 }
+
+function redactUrl(url: string): string {
+  try {
+    const parsed = new URL(url)
+    if (parsed.searchParams.has('token')) parsed.searchParams.set('token', '<redacted>')
+    return parsed.toString()
+  } catch {
+    return url
+  }
+}