typeclaw 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/src/agent/index.ts

@@ -9,7 +9,7 @@ import { loadMemory } from '@/bundled-plugins/memory/load-memory'
 import type { ChannelRouter } from '@/channels/router'
 import { getConfig, resolveModel, resolveProfile } from '@/config'
 import { defaultThinkingLevelForRef, providerForModelRef, type KnownModelRef } from '@/config/providers'
-import type { PermissionService } from '@/permissions'
+import type { PermissionService, RolesConfig } from '@/permissions'
 import type {
   BuiltinToolRef,
   HookBus,
@@ -50,6 +50,7 @@ import { createChannelFetchAttachmentTool } from './tools/channel-fetch-attachme
 import { createChannelHistoryTool } from './tools/channel-history'
 import { createChannelReplyTool } from './tools/channel-reply'
 import { createChannelSendTool } from './tools/channel-send'
+import { createGrantRoleTool } from './tools/grant-role'
 import { createRestartTool } from './tools/restart'
 import { createSkipResponseTool } from './tools/skip-response'
 import { createSpawnSubagentTool } from './tools/spawn-subagent'
@@ -141,6 +142,11 @@ export type CreateSessionOptions = {
   // prompt is not regenerated; see `typeclaw-permissions` skill for how the
   // agent should interpret the snapshot on later turns.
   permissions?: PermissionService
+  // Re-reads roles from disk for the grant_role tool's hot-reload after a match
+  // grant. Production threads a reload-then-read (reloadConfig + getConfig);
+  // must not be an in-memory snapshot or the grant reapplies stale roles.
+  // Omitted when no grant_role tool is wired (the tool requires permissions).
+  reloadRoles?: () => RolesConfig | undefined
   // Model profile name. Resolved against `config.models` to pick the concrete
   // model ref this session binds to. Unknown profile names fall back to
   // `default` with a one-time console warning. Omitted → `default`. Threaded
@@ -322,6 +328,12 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
               permissions: options.permissions,
               stream: options.stream,
             }),
+            ...buildRoleGrantTools({
+              agentDir: options.plugins?.agentDir,
+              getOrigin,
+              permissions: options.permissions,
+              reloadRoles: options.reloadRoles,
+            }),
           ]
   // Hook coverage for pi's builtin coding tools (read/bash/edit/write/grep/
   // find/ls) — pi 0.67.3 ignores `tools:` for implementation, so the only
@@ -577,6 +589,25 @@ export function buildSubagentOrchestrationTools(opts: {
   ]
 }
 
+export function buildRoleGrantTools(opts: {
+  agentDir: string | undefined
+  getOrigin: () => SessionOrigin | undefined
+  permissions: PermissionService | undefined
+  reloadRoles: (() => RolesConfig | undefined) | undefined
+}): ToolDefinition[] {
+  if (opts.agentDir === undefined || opts.permissions === undefined || opts.reloadRoles === undefined) {
+    return []
+  }
+  return [
+    createGrantRoleTool({
+      agentDir: opts.agentDir,
+      getOrigin: opts.getOrigin,
+      permissions: opts.permissions,
+      reloadRoles: opts.reloadRoles,
+    }),
+  ]
+}
+
 function wrapRegistryTools(
   plugins: PluginSessionWiring | undefined,
   getOrigin: () => SessionOrigin | undefined,

package/src/agent/session-origin.ts

@@ -111,11 +111,12 @@ function getPlatformInfo(adapter: AdapterId): PlatformInfo {
 // 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.
+// Channel origins do NOT render this concrete role. A channel session is
+// keyed by chat/thread, so the opener's role is wrong for every later
+// speaker and printing their permission list leaks it into shared context.
+// Channel origins render renderChannelRolePolicy() instead, and the
+// authoritative per-turn role rides in the non-cacheable `<your-role>`
+// turn anchor (renderTurnRoleAnchor in system-prompt.ts).
 export type SessionRoleContext = {
   role: string
   permissions: readonly string[]
@@ -128,21 +129,22 @@ export function renderSessionOrigin(
 ): string {
   switch (origin.kind) {
     case 'tui':
-      return withRoleContext(renderTuiOrigin(), roleContext)
+      return withRoleContext(renderTuiOrigin(), roleContext, origin.kind)
     case 'cron':
-      return withRoleContext(renderCronOrigin(origin), roleContext)
+      return withRoleContext(renderCronOrigin(origin), roleContext, origin.kind)
     case 'channel':
-      return withRoleContext(renderChannelOrigin(origin, now), roleContext)
+      return withRoleContext(renderChannelOrigin(origin, now), roleContext, origin.kind)
     case 'subagent':
-      return withRoleContext(renderSubagentOrigin(origin), roleContext)
+      return withRoleContext(renderSubagentOrigin(origin), roleContext, origin.kind)
     case 'system':
-      return withRoleContext(renderSystemOrigin(origin), roleContext)
+      return withRoleContext(renderSystemOrigin(origin), roleContext, origin.kind)
   }
 }
 
-function withRoleContext(block: string, ctx: SessionRoleContext | undefined): string {
+function withRoleContext(block: string, ctx: SessionRoleContext | undefined, kind: SessionOrigin['kind']): string {
   if (ctx === undefined) return block
-  return `${block}\n\n${renderRoleContext(ctx)}`
+  const roleBlock = kind === 'channel' ? renderChannelRolePolicy() : renderRoleContext(ctx)
+  return `${block}\n\n${roleBlock}`
 }
 
 function renderRoleContext(ctx: SessionRoleContext): string {
@@ -160,6 +162,30 @@ function renderRoleContext(ctx: SessionRoleContext): string {
   ].join('\n')
 }
 
+// Channel sessions are keyed by chat/thread, not by author: one session can see
+// many speakers with different roles. Rendering the opener's concrete role here
+// would (1) be wrong for every later speaker and (2) leak the opener's full
+// permission list into shared context. So channel origins get a cache-stable
+// policy instead of a resolved identity; the authoritative per-turn role rides
+// in the non-cacheable `<your-role>` turn anchor.
+function renderChannelRolePolicy(): string {
+  return [
+    '## Your role in this session',
+    '',
+    'This is a channel conversation that may include multiple speakers. Do not',
+    'assume one speaker’s role applies to later messages. For each user turn the',
+    'current speaker’s effective role is provided in the turn context as a',
+    '`<your-role>` tag; that per-turn role is authoritative for the current',
+    'message and overrides any role implied by session-opening context. An absent',
+    '`<your-role>` tag means the current speaker is the unconstrained default.',
+    '',
+    'Tool calls and channel admission are gated by the current speaker’s',
+    'permissions; a `blocked:` or "denied by permissions" message means that',
+    'speaker lacks the permission the guard wanted. See the',
+    '`typeclaw-permissions` skill for what each role can do.',
+  ].join('\n')
+}
+
 function renderTuiOrigin(): string {
   return [
     '## Session origin',
@@ -262,6 +288,22 @@ function renderChannelOrigin(
     'is a tool call. Plain-text output is invisible.',
   ]
 
+  // GitHub has no separate "chat" surface — channel_reply IS a public comment
+  // on this PR/issue. Without saying so, models default to the Slack-style
+  // two-surface split and post operator-facing meta-commentary ("Posted review
+  // result for PR #511") straight into the PR thread, where it reads absurdly.
+  if (origin.adapter === 'github') {
+    lines.push(
+      '',
+      '**`channel_reply` posts a public comment directly on this PR/issue.** It',
+      'is not a side-report to an operator — the reply lands in this exact',
+      'thread, read by everyone on the PR. Write the substance for that',
+      'audience: post the answer (or review summary) itself, never a status',
+      'line about having posted it elsewhere. A narrated "Posted review result',
+      'for PR #N: …" inside the PR is exactly the failure to avoid.',
+    )
+  }
+
   const conversationLine = renderConversationLine(origin)
   if (conversationLine !== null) lines.push('', conversationLine)
 

package/src/agent/system-prompt.ts

@@ -173,7 +173,7 @@ export function renderTurnTimeAnchor(now: Date = new Date()): string {
 // block for a TUI owner.
 export function renderTurnRoleAnchor(role: string): string | undefined {
   if (role === 'owner') return undefined
-  return `<your-role>${role}</your-role>`
+  return `<your-role authority="current-speaker">${role}</your-role> (authoritative for this message; overrides any role implied by the system prompt)`
 }
 
 // Compact replacement for DEFAULT_SYSTEM_PROMPT, used by non-interactive

package/src/agent/tools/grant-role.ts

@@ -0,0 +1,214 @@
+import { Type } from '@mariozechner/pi-ai'
+import { defineTool } from '@mariozechner/pi-coding-agent'
+
+import {
+  grantRole,
+  grantRolePermission,
+  isDmChannelOrigin,
+  parseMatchRule,
+  type PermissionService,
+  type RolesConfig,
+} from '@/permissions'
+
+import type { SessionOrigin } from '../session-origin'
+
+export type GrantRoleToolDetails =
+  | { ok: true; mode: 'match' | 'permission'; role: string; value: string; added: boolean; restartRequired: boolean }
+  | { ok: false; error: string }
+
+export type CreateGrantRoleToolOptions = {
+  agentDir: string
+  getOrigin: () => SessionOrigin | undefined
+  permissions: PermissionService
+  // Re-reads roles FROM DISK and returns the fresh set, for hot-reloading a
+  // match-grant after grantRole writes typeclaw.json. Must NOT read an
+  // in-memory config snapshot: grantRole writes the file directly, so a
+  // snapshot taken before the live config pointer is reloaded would be stale
+  // and replaceRoles would reapply the pre-grant table. Production wires this
+  // to reloadConfig(agentDir) + getConfig().roles, matching the config
+  // reloadable. A permission-grant is restart-required, so the reload has no
+  // runtime effect for it, but we reload anyway to keep a same-session
+  // subsequent match-grant reading a consistent table.
+  reloadRoles: () => RolesConfig | undefined
+}
+
+// Roles this tool may target, lowest to highest. `guest` is a valid target
+// (an operator opening guest channel.respond) but never a granter — the gate
+// below requires the caller to resolve to owner/trusted.
+const TIER_ORDER = ['guest', 'member', 'trusted', 'owner'] as const
+type TierRole = (typeof TIER_ORDER)[number]
+
+function tierOf(role: string): number {
+  return TIER_ORDER.indexOf(role as TierRole)
+}
+
+function isTierRole(role: string): role is TierRole {
+  return (TIER_ORDER as readonly string[]).includes(role)
+}
+
+// A single-principal turn carries only the principal's own first-party words:
+// the TUI (a human typing directly) or a 1:1 DM (principal + bot, no
+// third-party messages buffered in). A group/open channel turn always mixes in
+// other authors' messages, which is the confused-deputy surface that lets a
+// guest prompt-inject a trusted turn into rewriting the access-control table.
+// Role grants are confined to single-principal turns so that surface does not
+// exist.
+function isSinglePrincipalOrigin(origin: SessionOrigin | undefined): boolean {
+  if (origin === undefined) return false
+  if (origin.kind === 'tui') return true
+  if (origin.kind === 'channel') return isDmChannelOrigin(origin)
+  return false
+}
+
+export function createGrantRoleTool(options: CreateGrantRoleToolOptions) {
+  const { agentDir, getOrigin, permissions, reloadRoles } = options
+
+  return defineTool({
+    name: 'grant_role',
+    label: 'Grant Role',
+    description:
+      'Assign an author to a role (match grant) or give a role a capability (permission grant), by editing typeclaw.json#roles. ' +
+      'Use this to onboard a teammate ("respond to author U_X" → grant them member) or to open the agent to a wider audience ' +
+      '("let anyone in this channel message you" → grant guest channel.respond). ' +
+      'Only callable from the TUI or a 1:1 DM by an owner or trusted user — group-channel turns cannot use it. ' +
+      'Permission grants are restart-required: they land in typeclaw.json but take effect on the next `typeclaw restart`.',
+    parameters: Type.Object({
+      role: Type.Union(
+        [Type.Literal('owner'), Type.Literal('trusted'), Type.Literal('member'), Type.Literal('guest')],
+        {
+          description: 'The role to grant TO.',
+        },
+      ),
+      match: Type.Optional(
+        Type.String({
+          description:
+            'A match rule assigning an author/scope to the role, e.g. "slack:T0123 author:U_WIFE". ' +
+            'Provide exactly one of match or permission.',
+        }),
+      ),
+      permission: Type.Optional(
+        Type.String({
+          description:
+            'A capability to add to the role, e.g. "channel.respond". Provide exactly one of match or permission. ' +
+            'security.bypass.* permissions cannot be granted through this tool.',
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params): Promise<ToolReturn> {
+      const origin = getOrigin()
+
+      if (!isSinglePrincipalOrigin(origin)) {
+        return err(
+          'grant_role is only available from the TUI or a 1:1 DM. A group-channel turn cannot change roles, ' +
+            'because it mixes in other participants\u2019 messages (prompt-injection surface).',
+        )
+      }
+
+      const callerRole = permissions.resolveRole(origin)
+      if (callerRole !== 'owner' && callerRole !== 'trusted') {
+        return err(`grant_role denied: caller resolves to '${callerRole}'; only owner or trusted may grant roles.`)
+      }
+
+      const hasMatch = typeof params.match === 'string' && params.match.length > 0
+      const hasPermission = typeof params.permission === 'string' && params.permission.length > 0
+      if (hasMatch === hasPermission) {
+        return err('Provide exactly one of `match` or `permission`.')
+      }
+
+      if (!isTierRole(params.role)) {
+        return err(`Unknown target role '${params.role}'.`)
+      }
+
+      // Tier ceiling: a granter may not assign or empower a role ABOVE its own.
+      // owner(3) ≥ trusted(2) ≥ member(1) ≥ guest(0).
+      if (tierOf(params.role) > tierOf(callerRole)) {
+        return err(`grant_role denied: a ${callerRole} caller cannot grant the higher '${params.role}' role.`)
+      }
+
+      return hasMatch
+        ? grantMatch(params.role, params.match as string)
+        : grantPermission(callerRole, params.role, params.permission as string)
+    },
+  })
+
+  function grantMatch(role: string, matchRule: string): ToolReturn {
+    const parsed = parseMatchRule(matchRule)
+    if (!parsed.ok) {
+      return err(`Invalid match rule '${matchRule}': ${parsed.error}`)
+    }
+
+    const result = grantRole({ cwd: agentDir, roleName: role, matchRule })
+    if (!result.ok) return err(result.reason)
+
+    reload()
+    return ok('match', role, matchRule, result.added, false)
+  }
+
+  function grantPermission(callerRole: string, role: string, permission: string): ToolReturn {
+    // security.bypass.* defeats guards rather than enabling a feature; never
+    // grantable through an agent tool. It stays a deliberate hand-edit gated by
+    // the rolePromotion guard + an explicit ack.
+    if (permission.startsWith('security.bypass.')) {
+      return err(
+        `grant_role refuses to grant '${permission}': security.bypass.* permissions disable security guards and ` +
+          'must be set by hand-editing typeclaw.json (gated by the rolePromotion guard), not via this tool.',
+      )
+    }
+
+    // "Grant only what you hold": the caller cannot confer a capability it does
+    // not itself possess. Owner's resolved set is the expanded wildcard, so an
+    // owner can grant any non-bypass core permission; trusted is capped at its
+    // literal set.
+    const callerPerms = permissions.describe(getOrigin()).permissions
+    if (!callerPerms.includes(permission)) {
+      return err(
+        `grant_role denied: a ${callerRole} caller cannot grant '${permission}' because it does not hold that permission.`,
+      )
+    }
+
+    const result = grantRolePermission({ cwd: agentDir, roleName: role, permission })
+    if (!result.ok) return err(result.reason)
+
+    reload()
+    return ok('permission', role, permission, result.added, true)
+  }
+
+  function reload(): void {
+    try {
+      permissions.replaceRoles(reloadRoles())
+    } catch {
+      // Best-effort hot-reload of match-grants. A failure here does not undo
+      // the on-disk write; the next config reload / restart picks it up.
+    }
+  }
+}
+
+function ok(
+  mode: 'match' | 'permission',
+  role: string,
+  value: string,
+  added: boolean,
+  restartRequired: boolean,
+): ToolReturn {
+  const details: GrantRoleToolDetails = { ok: true, mode, role, value, added, restartRequired }
+  const note = added ? '' : ' (already on file)'
+  const restart = restartRequired
+    ? ' This permission grant is restart-required; run `typeclaw restart` for it to take effect.'
+    : ''
+  const text =
+    mode === 'match'
+      ? `Granted role '${role}' the match rule '${value}'${note}.${restart}`
+      : `Granted role '${role}' the permission '${value}'${note}.${restart}`
+  return { content: [{ type: 'text', text }], details }
+}
+
+function err(message: string): ToolReturn {
+  const details: GrantRoleToolDetails = { ok: false, error: message }
+  return { content: [{ type: 'text', text: message }], details }
+}
+
+type ToolReturn = {
+  content: { type: 'text'; text: string }[]
+  details: GrantRoleToolDetails
+}

package/src/channels/router.ts

@@ -164,6 +164,19 @@ export const SESSION_FRESHNESS_TTL_MS = 5 * 60 * 1000
 // instead of awaiting the same dead promise forever.
 export const ENSURE_LIVE_TIMEOUT_MS = 30_000
 
+// Thrown by ensureLive() when a teardown (roles reload or shutdown) raced
+// ahead of an in-flight creation. route() has no special handling — it
+// propagates to the adapter's outer catch, dropping this one inbound. The
+// next inbound creates a fresh, post-reload session, which is the intended
+// outcome: a message that arrived mid-reload is cheap to drop, far cheaper
+// than answering it through a session built with the stale role.
+export class StaleLiveSessionError extends Error {
+  constructor(keyId: string) {
+    super(`[channels] ${keyId}: live session creation raced a teardown; discarded`)
+    this.name = 'StaleLiveSessionError'
+  }
+}
+
 // Per-callback ceilings inside the ensureLive chain. The outer watchdog
 // catches the worst case, but per-step timeouts give better log
 // attribution (which step hung) AND graceful degradation: a hung name
@@ -562,6 +575,7 @@ export type ChannelRouter = {
     | { kind: 'recorded-after-send'; keyId: string }
     | { kind: 'no-live-session' }
   stop: () => Promise<void>
+  tearDownAllLive: () => Promise<void>
   liveCount: () => number
   __testing?: {
     flushDebounce: (key: ChannelKey) => Promise<void>
@@ -691,6 +705,14 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const stream = options.stream
   const liveSessions = new Map<string, LiveSession>()
   const creating = new Map<string, Promise<LiveSession>>()
+  // Bumped by tearDownAllLive() and stop() before they tear sessions down. An
+  // in-flight ensureLive() captures the value at creation start and re-checks
+  // it right before installing into liveSessions; if it changed, a teardown
+  // raced ahead of this creation (e.g. a roles.match reload), so the session
+  // was built with stale role context and must self-dispose instead of
+  // installing — otherwise it would reintroduce the very staleness the
+  // teardown was meant to clear.
+  let liveGeneration = 0
   const outboundCallbacks = new Map<ChannelKey['adapter'], Set<OutboundCallback>>()
   const typingCallbacks = new Map<ChannelKey['adapter'], Set<TypingCallback>>()
   const channelNameResolvers = new Map<ChannelKey['adapter'], Set<ChannelNameResolver>>()
@@ -909,6 +931,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     const inFlight = creating.get(keyId)
     if (inFlight) return inFlight
 
+    const generation = liveGeneration
+
     const promise = (async () => {
       await ensureLoaded()
       const record = mappings ? findRecord(mappings, key) : undefined
@@ -1073,6 +1097,17 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       live.unsubTypingActivity = subscribeTypingActivity(created.session, live)
       installChannelReplyTerminalHook(live)
       installChannelOutputCap(live)
+
+      // A teardown (roles reload / shutdown) ran while this session was being
+      // built, so it carries stale role context. Dispose it instead of
+      // installing — installing here is the exact window the race exploits.
+      if (generation !== liveGeneration) {
+        logger.info(
+          `[channels] ${keyId}: discarding session created across a teardown (gen ${generation} → ${liveGeneration})`,
+        )
+        await tearDownLive(live)
+        throw new StaleLiveSessionError(keyId)
+      }
       liveSessions.set(keyId, live)
 
       if (isColdStart) {
@@ -1632,6 +1667,12 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         logger.info(`[channels] ${keyId}: ignoring unknown command /${parsedCommand.name}`)
         return
       }
+      if (isSessionControlDenied(event)) {
+        logger.info(
+          `[channels] ${keyId}: denied command /${parsedCommand.name} by permissions (session.control) author=${event.authorId}`,
+        )
+        return
+      }
       const existingLive = liveSessions.get(keyId)
       if (!existingLive || existingLive.destroyed) {
         logger.info(`[channels] ${keyId}: ignoring command /${parsedCommand.name} with no live session`)
@@ -1714,17 +1755,24 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     scheduleDebouncedDrain(live)
   }
 
-  const isChannelRespondDenied = (event: InboundMessage): boolean => {
-    const partial: SessionOrigin = {
-      kind: 'channel',
-      adapter: event.adapter,
-      workspace: event.workspace,
-      chat: event.chat,
-      thread: event.thread,
-      lastInboundAuthorId: event.authorId,
-    }
-    return !permissions.has(partial, CORE_PERMISSIONS.channelRespond)
-  }
+  const inboundAuthorOrigin = (event: InboundMessage): SessionOrigin => ({
+    kind: 'channel',
+    adapter: event.adapter,
+    workspace: event.workspace,
+    chat: event.chat,
+    thread: event.thread,
+    lastInboundAuthorId: event.authorId,
+  })
+
+  const isChannelRespondDenied = (event: InboundMessage): boolean =>
+    !permissions.has(inboundAuthorOrigin(event), CORE_PERMISSIONS.channelRespond)
+
+  // Gated separately from channelRespond so a respond-capable guest (an
+  // operator can grant guest channelRespond for masked stranger turns)
+  // cannot /stop another speaker's in-flight turn. session.control is
+  // member-and-up by default.
+  const isSessionControlDenied = (event: InboundMessage): boolean =>
+    !permissions.has(inboundAuthorOrigin(event), CORE_PERMISSIONS.sessionControl)
 
   const updateLoopGuard = (live: LiveSession, event: InboundMessage): void => {
     if (!event.authorIsBot) {
@@ -2334,6 +2382,27 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const stop = async (): Promise<void> => {
     if (gcTimer) clearInterval(gcTimer)
     gcTimer = null
+    liveGeneration++
+    const all = Array.from(liveSessions.values())
+    liveSessions.clear()
+    for (const live of all) {
+      await tearDownLive(live)
+    }
+  }
+
+  // Drops every in-memory session but KEEPS the on-disk records, so the next
+  // inbound per channel rehydrates the same transcript through a fresh
+  // createSession() — which re-renders the frozen system-prompt role block.
+  // This is how a `roles.<name>.match` reload reaches live channel sessions.
+  // Unlike stop() it leaves the GC timer running; unlike stale-rollover it
+  // keeps the sessionId, so history survives.
+  //
+  // Bumping liveGeneration BEFORE the snapshot is what makes this race-free:
+  // a session mid-creation (in `creating` but not yet in `liveSessions`) won't
+  // appear in the snapshot below, but it captured the old generation and will
+  // self-dispose at its install guard instead of resurrecting stale role state.
+  const tearDownAllLive = async (): Promise<void> => {
+    liveGeneration++
     const all = Array.from(liveSessions.values())
     liveSessions.clear()
     for (const live of all) {
@@ -2350,11 +2419,11 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     if (!commands.has(lowered)) {
       return { kind: 'unknown-command', name: lowered }
     }
-    // Permission gate runs BEFORE the live-session lookup so a guest user
-    // invoking /stop on a non-existent session gets 'permission-denied'
-    // (consistent answer regardless of session state) rather than leaking
-    // session presence via the 'no-live-session' vs 'permission-denied'
-    // distinction.
+    // Gates on session.control (not channel.respond) so a respond-capable
+    // guest cannot abort another speaker's turn. Runs BEFORE the live-session
+    // lookup so an unauthorized invoker gets 'permission-denied' regardless of
+    // session state, rather than leaking session presence via the
+    // 'no-live-session' vs 'permission-denied' distinction.
     const partial: SessionOrigin = {
       kind: 'channel',
       adapter: key.adapter,
@@ -2363,7 +2432,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       thread: key.thread,
       lastInboundAuthorId: options.invokerId,
     }
-    if (!permissions.has(partial, CORE_PERMISSIONS.channelRespond)) {
+    if (!permissions.has(partial, CORE_PERMISSIONS.sessionControl)) {
       return { kind: 'permission-denied' }
     }
     const resolved = resolveLiveSessionForCommand(liveSessions, key)
@@ -2476,6 +2545,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     injectSubagentCompletionReminder,
     markTurnSkipped,
     stop,
+    tearDownAllLive,
     liveCount: () => liveSessions.size,
     __testing: {
       flushDebounce: async (key: ChannelKey) => {

package/src/cli/role.ts

@@ -3,7 +3,7 @@ import { defineCommand } from 'citty'
 
 import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
 import { findAgentDir } from '@/init'
-import { runClaimSession } from '@/role-claim'
+import { reloadAfterClaim, runClaimSession } from '@/role-claim'
 
 import { c, errorLine } from './ui'
 
@@ -76,6 +76,15 @@ const claimSub = defineCommand({
 
     if (result.kind === 'completed') {
       s.stop(c.green(`Paired as ${result.payload.role}.`))
+      s.start('Reloading config so the new match rule takes effect...')
+      const reloaded = await reloadAfterClaim({ url })
+      if (reloaded.ok) {
+        s.stop(c.green('Config reloaded.'))
+      } else {
+        // The role is already persisted; a reload failure is non-fatal.
+        s.stop(c.yellow(`Config reload failed: ${reloaded.reason}`))
+        console.log(c.dim('Run `typeclaw reload` manually to apply the new match rule.'))
+      }
       outro(`Match rule added: ${c.bold(result.payload.matchRule)}`)
       return
     }

package/src/cli/ui.ts

@@ -252,16 +252,18 @@ export function printSlackAppManifestSetup(output: NodeJS.WritableStream = proce
 // the exact permission bitfield the adapter uses. No-ops when the token isn't
 // parseable as a Discord bot token so we never block onboarding on best-effort
 // guidance.
-export function printDiscordInviteHint(token: string): void {
+export function printDiscordInviteHint(token: string, output: NodeJS.WritableStream = process.stdout): void {
   const appId = deriveAppIdFromBotToken(token)
   if (appId === null) return
+  // URL stays OUT of note(): clack wraps long lines with a `│` gutter that
+  // corrupts copy-pasted URLs. Same fix as src/cli/oauth-callbacks.ts.
   note(
     [
-      buildDiscordInviteUrl(appId),
-      '',
-      'Open it, pick a server, click Authorize.',
+      'Open the URL below, pick a server, click Authorize.',
       "The bot won't receive messages until it's in at least one server.",
     ].join('\n'),
     'Invite the bot to a server',
   )
+  output.write(`${buildDiscordInviteUrl(appId)}\n`)
+  output.write('\n')
 }

package/src/config/reloadable.ts

@@ -11,6 +11,10 @@ export type CreateConfigReloadableOptions = {
   // hand-edits) take effect without a container restart. `roles.<name>.permissions`
   // changes still require a restart — see FIELD_EFFECTS in config.ts.
   permissions?: PermissionService
+  // Fired after replaceRoles when a `roles.<name>.match` edit is applied. The
+  // run stage wires this to the channel router so live sessions are recreated
+  // and pick up the new role in their (otherwise frozen) system prompt.
+  onRolesChanged?: () => void | Promise<void>
   // Skip the mount-path accessibility check inside validateConfig. Mount paths
   // in typeclaw.json are host paths — they don't resolve inside the container,
   // so the check would always fail on any agent that declares mounts. `mounts`
@@ -22,18 +26,20 @@ export type CreateConfigReloadableOptions = {
 export function createConfigReloadable({
   cwd,
   permissions,
+  onRolesChanged,
   skipMountValidation = false,
 }: CreateConfigReloadableOptions): Reloadable {
   return {
     scope: 'config',
     description: 'typeclaw.json runtime config',
-    reload: async () => doReload(cwd, permissions, skipMountValidation),
+    reload: async () => doReload(cwd, permissions, onRolesChanged, skipMountValidation),
   }
 }
 
 async function doReload(
   cwd: string,
   permissions: PermissionService | undefined,
+  onRolesChanged: (() => void | Promise<void>) | undefined,
   skipMountValidation: boolean,
 ): Promise<ReloadResult> {
   // Mount accessibility belongs to the validation surface, not loadConfigSync —
@@ -59,8 +65,9 @@ async function doReload(
     return { scope: 'config', ok: false, reason: message }
   }
 
-  if (permissions !== undefined && diff.applied.some((c) => c.path === 'roles.match')) {
-    permissions.replaceRoles(getConfig().roles)
+  if (diff.applied.some((c) => c.path === 'roles.match')) {
+    permissions?.replaceRoles(getConfig().roles)
+    await onRolesChanged?.()
   }
 
   return {

package/src/init/index.ts

@@ -39,14 +39,6 @@ const CONFIG_FILE = 'typeclaw.json'
 const CRON_FILE = 'cron.json'
 const PACKAGE_FILE = 'package.json'
 
-// Seeded into `typeclaw.json#roles.member.match[]` whenever a chat adapter
-// (slack-bot, discord-bot, telegram-bot, kakaotalk) is wired. The "*" rule
-// matches every channel session on every platform, so the built-in `member`
-// role (which already carries `channel.respond`) covers any inbound the
-// router sees. Without this, freshly-hatched agents silently drop every
-// chat message — see scaffold() and ensureDefaultChatMemberMatch() below.
-const DEFAULT_CHAT_MEMBER_MATCH_RULE = '*'
-
 const MARKDOWN_FILES = ['AGENTS.md', 'IDENTITY.md', 'SOUL.md', 'USER.md'] as const
 
 // `packages/` is a bun workspace root (see `workspaces` in buildPackageJson).
@@ -586,11 +578,11 @@ export async function scaffold(root: string, options: ScaffoldOptions = {}): Pro
   if (options.withTelegram) channels['telegram-bot'] = {}
   if (options.withKakaotalk) channels.kakaotalk = {}
   if (Object.keys(channels).length > 0) config.channels = channels
-  // See DEFAULT_CHAT_MEMBER_MATCH_RULE for why this is here. GitHub is wired
-  // separately (writeGithubChannelForInit) and seeds per-repo member.match
-  // entries instead of the wildcard, so a github-only init stays scoped to
-  // the repos the operator opted in to.
-  if (Object.keys(channels).length > 0) config.roles = { member: { match: [DEFAULT_CHAT_MEMBER_MATCH_RULE] } }
+  // No default `member` match is seeded. A fresh chat agent starts with every
+  // inbound author resolving to `guest` (dropped) until the operator claims
+  // `owner` (runOwnerClaim, post-hatch) and explicitly grants others. GitHub is
+  // wired separately and seeds per-repo `member.match` entries scoped to the
+  // opted-in repos. See runOwnerClaim for the mute-until-claimed warning.
   await writeFile(join(root, CONFIG_FILE), `${JSON.stringify(config, null, 2)}\n`)
 
   const cron = {
@@ -1046,8 +1038,6 @@ export async function runAddChannel(options: AddChannelOptions): Promise<void> {
   if (options.channel === 'github') {
     await appendGithubMatchRules(options.cwd, options.repos)
     await maybeInstallGithubWebhooks(options, emit)
-  } else {
-    await ensureDefaultChatMemberMatch(options.cwd)
   }
 
   // Commit the typeclaw.json change so the agent folder isn't silently
@@ -1329,24 +1319,6 @@ async function appendGithubMatchRules(cwd: string, repos: readonly string[]): Pr
   await writeFile(path, `${JSON.stringify(parsed, null, 2)}\n`)
 }
 
-// Chat-adapter counterpart of appendGithubMatchRules. See
-// DEFAULT_CHAT_MEMBER_MATCH_RULE for the rationale. Set-union semantics: re-
-// running `typeclaw channel add` for additional chat adapters is a no-op on
-// the match list, and any pre-existing rules the operator hand-authored
-// (e.g. owner-claim's per-author entry on `owner`) are left intact.
-async function ensureDefaultChatMemberMatch(cwd: string): Promise<void> {
-  const path = join(cwd, CONFIG_FILE)
-  const parsed = JSON.parse(await readFile(path, 'utf8')) as Record<string, unknown>
-  const roles = isObjectRecord(parsed.roles) ? { ...parsed.roles } : {}
-  const member = isObjectRecord(roles.member) ? { ...roles.member } : {}
-  const existing = Array.isArray(member.match) ? member.match.filter((v): v is string => typeof v === 'string') : []
-  if (existing.includes(DEFAULT_CHAT_MEMBER_MATCH_RULE)) return
-  member.match = [...existing, DEFAULT_CHAT_MEMBER_MATCH_RULE]
-  roles.member = member
-  parsed.roles = roles
-  await writeFile(path, `${JSON.stringify(parsed, null, 2)}\n`)
-}
-
 // Writes per-adapter field values into `secrets.json#channels.<adapter>`.
 // Refuses to overwrite existing fields: if the user already has e.g.
 // `botToken` recorded (from a prior `channel add` whose follow-up steps

package/src/init/run-owner-claim.ts

@@ -43,7 +43,7 @@ export async function runOwnerClaim({ url, configuredChannels }: RunOwnerClaimOp
     initialValue: true,
   })
   if (isCancel(proceed) || proceed === false) {
-    log.info(`Skipping. Run ${c.bold('typeclaw role claim')} later when you're ready.`)
+    warnMuteUntilClaimed()
     return
   }
 
@@ -78,9 +78,27 @@ export async function runOwnerClaim({ url, configuredChannels }: RunOwnerClaimOp
   }
   if (result.kind === 'error') {
     s.stop(c.red(`Claim failed: ${result.payload.reason}`))
-    log.info(`You can retry with ${c.bold('typeclaw role claim')} anytime.`)
+    warnMuteUntilClaimed()
     return
   }
   s.stop(c.yellow(`Claim timed out — no DM received within the window.`))
-  log.info(`Run ${c.bold('typeclaw role claim')} when you're ready.`)
+  warnMuteUntilClaimed()
+}
+
+// Printed on every path that finishes init WITHOUT a successful owner claim.
+// Since the scoped-by-default change removed the `member: ["*"]` seeding, an
+// unclaimed chat agent resolves every inbound to `guest` and drops it — the
+// agent answers no one. This is a footgun unless the operator is told plainly,
+// so the warning is loud and names the exact recovery command.
+function warnMuteUntilClaimed(): void {
+  note(
+    [
+      `Your agent will respond to ${c.bold('no one')} until you claim the owner role —`,
+      `every inbound message is currently dropped.`,
+      '',
+      `Run ${c.bold('typeclaw role claim')} to pair yourself, then grant others`,
+      `with the agent (ask it: "respond to <user>") or by editing typeclaw.json#roles.`,
+    ].join('\n'),
+    c.yellow('Heads up: agent is muted'),
+  )
 }

package/src/permissions/builtins.ts

@@ -10,6 +10,12 @@ export const BUILTIN_ROLE_NAMES: readonly BuiltinRoleName[] = ['owner', 'trusted
 // set at boot via expandOwnerWildcard.
 export const CORE_PERMISSIONS = {
   channelRespond: 'channel.respond',
+  // Distinct from channelRespond so a respond-capable guest cannot abort
+  // other speakers' sessions. The /stop command (both the text-prefix and
+  // native-slash paths in the router) gates on this, not on channelRespond:
+  // an operator may grant guest channelRespond to let strangers drive masked
+  // turns, but session lifecycle control stays member-and-up.
+  sessionControl: 'session.control',
   cronSchedule: 'cron.schedule',
   cronModify: 'cron.modify',
   subagentSpawn: 'subagent.spawn',
@@ -17,10 +23,11 @@ export const CORE_PERMISSIONS = {
   subagentOutput: 'subagent.output',
   subagentSpawnOperator: 'subagent.spawn.operator',
   // Phrased as capabilities to SEE, not to hide, so the role tower stays
-  // monotonic (a higher tier sees a strict superset of a lower tier) and the
-  // empty-permission guest is the fail-safe floor. resolveHiddenPaths masks
-  // whatever the resolved role lacks: fsSeePrivate gates workspace/+memory/+
-  // sessions/, fsSeeSecrets gates .env+secrets.json.
+  // monotonic (a higher tier sees a strict superset of a lower tier).
+  // resolveHiddenPaths masks whatever the resolved role lacks: fsSeePrivate
+  // gates workspace/+memory/+sessions/, fsSeeSecrets gates .env+secrets.json.
+  // The fail-safe floor is the undefined origin (see has() in
+  // permissions.ts), not the guest role, which is now grantable.
   fsSeePrivate: 'fs.see.private',
   fsSeeSecrets: 'fs.see.secrets',
 } as const
@@ -62,6 +69,7 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
     match: [{ kind: 'tui' }],
     permissions: [
       CORE_PERMISSIONS.channelRespond,
+      CORE_PERMISSIONS.sessionControl,
       CORE_PERMISSIONS.cronSchedule,
       CORE_PERMISSIONS.cronModify,
       CORE_PERMISSIONS.subagentSpawn,
@@ -80,6 +88,7 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
     match: [],
     permissions: [
       CORE_PERMISSIONS.channelRespond,
+      CORE_PERMISSIONS.sessionControl,
       CORE_PERMISSIONS.cronSchedule,
       CORE_PERMISSIONS.subagentSpawn,
       CORE_PERMISSIONS.subagentCancel,
@@ -95,6 +104,7 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
     match: [],
     permissions: [
       CORE_PERMISSIONS.channelRespond,
+      CORE_PERMISSIONS.sessionControl,
       CORE_PERMISSIONS.subagentSpawn,
       CORE_PERMISSIONS.subagentCancel,
       CORE_PERMISSIONS.subagentOutput,

package/src/permissions/grant.ts

@@ -1,6 +1,9 @@
 import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
+import { commitSystemFileSync } from '@/git/system-commit'
+
+import { BUILTIN_ROLES, isBuiltinRoleName } from './builtins'
 import { parseMatchRule } from './match-rule'
 
 // Appends `rule` to `typeclaw.json#roles.<name>.match`, creating the role
@@ -23,15 +26,97 @@ export type GrantOptions = {
   matchRule: string
 }
 
+export type GrantPermissionOptions = {
+  cwd: string
+  roleName: string
+  permission: string
+}
+
 export function grantRole(opts: GrantOptions): GrantResult {
   const validation = parseMatchRule(opts.matchRule)
   if (!validation.ok) {
     return { ok: false, reason: `invalid match rule '${opts.matchRule}': ${validation.error}` }
   }
 
-  const path = join(opts.cwd, CONFIG_FILE)
+  const loaded = loadConfigObject(opts.cwd, opts.roleName)
+  if (!loaded.ok) return loaded
+
+  const { obj, roles, role } = loaded
+  const existingMatch = Array.isArray(role.match) ? [...(role.match as unknown[])] : []
+
+  // Dedup by exact string equality — match rules canonicalize during load,
+  // and a literal duplicate in the file is a noise source the schema doesn't
+  // currently dedupe for us.
+  if (existingMatch.includes(opts.matchRule)) {
+    return { ok: true, added: false }
+  }
+
+  role.match = [...existingMatch, opts.matchRule]
+  roles[opts.roleName] = role
+  obj.roles = roles
+
+  const written = writeConfigObject(opts.cwd, obj)
+  if (!written.ok) return written
+
+  // Best-effort commit so a claimed role survives a fresh clone/rebuild — a
+  // failing commit leaves the on-disk grant intact (history, not correctness).
+  // Subject stays neutral: every grantRole caller hits this, not just claim.
+  commitSystemFileSync(opts.cwd, CONFIG_FILE, `${CONFIG_FILE}: grant ${opts.roleName} role`)
+
+  return written
+}
+
+// Appends `permission` to `typeclaw.json#roles.<name>.permissions`. For a
+// built-in role with no explicit `permissions[]`, the runtime treats the
+// field as "use built-in defaults" (see resolveOne in permissions.ts), so a
+// naive write of `[permission]` would NARROW the role to a single capability,
+// silently dropping its defaults. We materialize the current effective set
+// (explicit field if present, else the built-in default list) and append to
+// THAT, preserving every existing capability. Idempotent: a permission the
+// role already holds is a no-op.
+//
+// NOTE: `roles.permissions` is `restart-required` (FIELD_EFFECTS); the write
+// lands on disk but does not take effect until the next container restart.
+// Callers must surface that to the operator.
+export function grantRolePermission(opts: GrantPermissionOptions): GrantResult {
+  const loaded = loadConfigObject(opts.cwd, opts.roleName)
+  if (!loaded.ok) return loaded
+
+  const { obj, roles, role } = loaded
+  const effective = effectivePermissions(opts.roleName, role)
+
+  if (effective.includes(opts.permission)) {
+    return { ok: true, added: false }
+  }
+
+  role.permissions = [...effective, opts.permission]
+  roles[opts.roleName] = role
+  obj.roles = roles
+
+  return writeConfigObject(opts.cwd, obj)
+}
+
+function effectivePermissions(roleName: string, role: Record<string, unknown>): string[] {
+  if (Array.isArray(role.permissions)) {
+    return role.permissions.filter((p): p is string => typeof p === 'string')
+  }
+  if (isBuiltinRoleName(roleName)) {
+    return [...BUILTIN_ROLES[roleName].permissions]
+  }
+  return []
+}
+
+type LoadedConfig = {
+  ok: true
+  obj: Record<string, unknown>
+  roles: Record<string, unknown>
+  role: Record<string, unknown>
+}
+
+function loadConfigObject(cwd: string, roleName: string): LoadedConfig | { ok: false; reason: string } {
+  const path = join(cwd, CONFIG_FILE)
   if (!existsSync(path)) {
-    return { ok: false, reason: `${CONFIG_FILE} not found at ${opts.cwd}` }
+    return { ok: false, reason: `${CONFIG_FILE} not found at ${cwd}` }
   }
 
   let raw: string
@@ -54,26 +139,17 @@ export function grantRole(opts: GrantOptions): GrantResult {
 
   const obj = json as Record<string, unknown>
   const roles = isPlainObject(obj.roles) ? { ...obj.roles } : {}
-  const role = isPlainObject(roles[opts.roleName]) ? { ...(roles[opts.roleName] as Record<string, unknown>) } : {}
-  const existingMatch = Array.isArray(role.match) ? [...(role.match as unknown[])] : []
-
-  // Dedup by exact string equality — match rules canonicalize during load,
-  // and a literal duplicate in the file is a noise source the schema doesn't
-  // currently dedupe for us.
-  if (existingMatch.includes(opts.matchRule)) {
-    return { ok: true, added: false }
-  }
-
-  role.match = [...existingMatch, opts.matchRule]
-  roles[opts.roleName] = role
-  obj.roles = roles
+  const role = isPlainObject(roles[roleName]) ? { ...(roles[roleName] as Record<string, unknown>) } : {}
+  return { ok: true, obj, roles, role }
+}
 
+function writeConfigObject(cwd: string, obj: Record<string, unknown>): GrantResult {
+  const path = join(cwd, CONFIG_FILE)
   try {
     writeAtomic(path, `${JSON.stringify(obj, null, 2)}\n`)
   } catch (error) {
     return { ok: false, reason: `failed to write ${CONFIG_FILE}: ${describeError(error)}` }
   }
-
   return { ok: true, added: true }
 }
 

package/src/permissions/index.ts

@@ -24,6 +24,12 @@ export {
   type PermissionService,
   type UnknownPermissionWarning,
 } from './permissions'
-export { grantRole, type GrantOptions, type GrantResult } from './grant'
-export { matchesOrigin, type MatchableOrigin } from './resolve'
+export {
+  grantRole,
+  grantRolePermission,
+  type GrantOptions,
+  type GrantPermissionOptions,
+  type GrantResult,
+} from './grant'
+export { matchesOrigin, isDmChannelOrigin, type MatchableOrigin } from './resolve'
 export { MATCH_RULE_JSON_SCHEMA_PATTERN, rolesConfigSchema, type RoleConfig, type RolesConfig } from './schema'

package/src/permissions/permissions.ts

@@ -141,6 +141,15 @@ export function createPermissionService(opts: CreatePermissionServiceOptions = {
 
   return {
     has(origin, permission) {
+      // Fail-safe floor: an undefined origin holds nothing, regardless of
+      // role permissions. Previously this floor was implicit in `guest`
+      // being empty; now `guest` is grantable (an operator may grant it
+      // `channel.respond`), so the floor must live on the no-actor input
+      // instead. Keeps every downstream `has(maybeUndefined, ...)` check
+      // (bypass tiers, fs.see.*, subagent spawn) closed even after a guest
+      // grant. resolveRole/describe still report 'guest' for audit/display;
+      // only authorization is forced closed.
+      if (origin === undefined) return false
       const roleName = resolveRole(origin)
       const role = byName.get(roleName)
       if (!role) return false

package/src/permissions/resolve.ts

@@ -79,3 +79,13 @@ function matchesBucket(
   if (platform === 'telegram') return origin.workspace === 'dm' || origin.workspace.startsWith('@')
   return false
 }
+
+// True only for a 1:1 direct-message channel origin (a two-participant
+// conversation: the principal + the bot). Reuses the same per-adapter
+// workspace markers as the `dm` match-rule bucket. A DM is the only channel
+// shape with no third-party content buffered into a turn, so role-grant tools
+// treat an owner/trusted DM as injection-equivalent to the TUI; group/open
+// channels never qualify.
+export function isDmChannelOrigin(origin: { adapter: AdapterId; workspace: string }): boolean {
+  return matchesBucket('dm', { kind: 'channel', adapter: origin.adapter, workspace: origin.workspace, chat: '' })
+}

package/src/role-claim/index.ts

@@ -10,6 +10,7 @@ export {
   type CreateClaimControllerOptions,
 } from './controller'
 export { formatClaimMatchRule, type PartialChannelOrigin } from './match-rule'
+export { reloadAfterClaim, type ReloadAfterClaimOptions, type ReloadAfterClaimResult } from './reload-after-claim'
 export {
   createPendingClaimRegistry,
   type ClaimResult,

package/src/role-claim/reload-after-claim.ts

@@ -0,0 +1,34 @@
+import { requestReload, type ReloadResult } from '@/reload'
+
+export interface ReloadAfterClaimOptions {
+  url: string
+  reload?: (opts: { url: string; scope: string }) => Promise<ReloadResult[]>
+}
+
+export type ReloadAfterClaimResult = { ok: true; results: ReloadResult[] } | { ok: false; reason: string }
+
+// Best-effort by contract: the role is already persisted to typeclaw.json by
+// the time a claim completes, so a reload failure here must NOT fail the claim.
+// Callers surface the reason but keep the claim successful.
+export async function reloadAfterClaim(opts: ReloadAfterClaimOptions): Promise<ReloadAfterClaimResult> {
+  const reload = opts.reload ?? requestReload
+  let results: ReloadResult[]
+  try {
+    results = await reload({ url: opts.url, scope: 'config' })
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) }
+  }
+
+  // requestReload resolves even when the server reports a per-scope failure, so
+  // an exception-free call is not proof the config actually reloaded. Surface
+  // any failed scope (and an empty result, which means nothing reloaded) as a
+  // failure so the caller can tell the user to reload manually.
+  const failed = results.filter((r) => !r.ok)
+  if (failed.length > 0) {
+    return { ok: false, reason: failed.map((r) => `${r.scope}: ${r.reason}`).join('; ') }
+  }
+  if (results.length === 0) {
+    return { ok: false, reason: 'no reloadable config scope responded' }
+  }
+  return { ok: true, results }
+}

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

@@ -7,7 +7,7 @@ import type { CreateSessionForSubagent, SubagentRegistry } from '@/agent/subagen
 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 { PermissionService, RolesConfig } from '@/permissions'
 import type { ReloadRegistry } from '@/reload'
 import type { SessionFactory } from '@/sessions'
 import type { Stream } from '@/stream'
@@ -47,6 +47,10 @@ export type BuildChannelSessionFactoryDeps = {
   // the production wiring can plumb in pluginsLoaded.permissions while tests
   // (or stand-alone callers) keep the previous no-annotation behavior.
   permissions?: PermissionService
+  // Re-reads roles from disk for the grant_role tool's hot-reload (reload then
+  // read, not an in-memory snapshot). Forwarded to createSession; the tool only
+  // mounts when permissions is also present.
+  reloadRoles?: () => RolesConfig | undefined
   // 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.
@@ -124,6 +128,7 @@ export function buildChannelSessionFactory(deps: BuildChannelSessionFactoryDeps)
       ...(deps.containerName !== undefined ? { containerName: deps.containerName } : {}),
       ...(deps.runtimeVersion !== undefined ? { runtimeVersion: deps.runtimeVersion } : {}),
       ...(deps.permissions !== undefined ? { permissions: deps.permissions } : {}),
+      ...(deps.reloadRoles !== undefined ? { reloadRoles: deps.reloadRoles } : {}),
       ...(deps.liveSubagentRegistry !== undefined ? { liveSubagentRegistry: deps.liveSubagentRegistry } : {}),
       ...(deps.subagentRegistry !== undefined ? { subagentRegistry: deps.subagentRegistry } : {}),
       ...(deps.getCreateSessionForSubagent !== undefined

package/src/run/index.ts

@@ -24,7 +24,7 @@ import {
   type SubagentCompletionBridge,
 } from '@/channels'
 import { createTunnelBridge, type TunnelBridge } from '@/channels/tunnel-bridge'
-import { createConfigReloadable, getConfig, loadConfigSync, loadPluginConfigsSync } from '@/config'
+import { createConfigReloadable, getConfig, loadConfigSync, loadPluginConfigsSync, reloadConfig } from '@/config'
 import {
   type CronConsumer,
   type CronJob,
@@ -150,6 +150,7 @@ export async function startAgent({
     createConfigReloadable({
       cwd,
       permissions: pluginsLoaded.permissions,
+      onRolesChanged: () => channelManager.router.tearDownAllLive(),
       skipMountValidation: containerName !== undefined,
     }),
   )
@@ -244,6 +245,7 @@ export async function startAgent({
       getChannelRouter: () => channelManager.router,
       rehydrateCapOptions: resolveCapOptionsFromConfig(pluginConfigsByName['tool-result-cap']),
       permissions: pluginsLoaded.permissions,
+      reloadRoles: () => reloadRolesFromDisk(cwd),
       liveSubagentRegistry,
       liveSessionRegistry,
       subagentRegistry: pluginRuntime.get().subagents,
@@ -688,6 +690,21 @@ async function disposeMaterializedSkills(pluginRuntime: PluginRuntime): Promise<
   await Promise.allSettled(all.map((m) => m.dispose()))
 }
 
+// grant_role's hot-reload hook: reload the live config FROM DISK (grantRole
+// wrote typeclaw.json directly, bypassing the in-memory snapshot) and return
+// the fresh roles for permissions.replaceRoles. Mirrors the config reloadable's
+// reload-then-read order. Falls back to the current snapshot if the just-written
+// file fails to parse — the on-disk write still stands and the next reload picks
+// it up; replaceRoles with stale roles is no worse than not reloading.
+function reloadRolesFromDisk(cwd: string): ReturnType<typeof getConfig>['roles'] {
+  try {
+    reloadConfig(cwd)
+  } catch {
+    // keep the current pointer; see above
+  }
+  return getConfig().roles
+}
+
 async function startScheduler({
   cwd,
   loadCron,

package/src/sandbox/build.ts

@@ -65,6 +65,38 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
 
   argv.push('--ro-bind', '/usr', '/usr', '--ro-bind', '/etc', '/etc', '--dev', '/dev', '--tmpfs', '/tmp')
 
+  // Recreate the usr-merge root symlinks that --ro-bind /usr does NOT bring
+  // along. On the Debian base (oven/bun:1-slim) /bin /sbin /lib /lib64 are
+  // root-level symlinks into /usr; binding /usr exposes /usr/bin etc. but the
+  // root entries themselves are absent in the sandbox. That breaks every
+  // ABSOLUTE-path reference the kernel resolves WITHOUT consulting PATH:
+  //   - ELF interpreter (the dynamic loader) baked into PT_INTERP:
+  //     /lib/ld-linux-aarch64.so.1 (arm64) or /lib64/ld-linux-x86-64.so.2
+  //     (amd64). Missing it makes bwrap report "execvp bash: No such file or
+  //     directory" — the missing file is the loader, not bash.
+  //   - shebang lines: /bin/sh and /bin/bash are the most common interpreters
+  //     on earth; a script with "#!/bin/sh" fails "cannot execute: required
+  //     file not found" without /bin, even though /usr/bin/sh exists, because
+  //     the shebang path is literal and skips PATH.
+  // --ro-bind-try, not --ro-bind: the set is arch- and base-dependent (arm64
+  // oven/bun:1-slim ships /lib but no /lib64), and a hard bind of an absent
+  // source aborts bwrap. -try binds each only when present, keeping this
+  // builder pure (no host filesystem probe) and correct across arches/bases.
+  argv.push(
+    '--ro-bind-try',
+    '/bin',
+    '/bin',
+    '--ro-bind-try',
+    '/sbin',
+    '/sbin',
+    '--ro-bind-try',
+    '/lib',
+    '/lib',
+    '--ro-bind-try',
+    '/lib64',
+    '/lib64',
+  )
+
   if ((policy.proc ?? 'tmpfs') === 'tmpfs') {
     // --tmpfs /proc, never --proc /proc (OrbStack's kernel blocks
     // mount("proc",...) from user namespaces) and never --dev-bind /proc /proc

package/src/skills/typeclaw-channel-github/SKILL.md

@@ -63,7 +63,11 @@ Why delegate: the `reviewer` subagent runs on the `deep` model profile, loads a
    </review>
    ```
 
-4. **Translate findings into a `gh api` review payload.** Each `<finding>` with `severity` of `blocker`, `concern`, or `nit` and a `location="path:line"` becomes one entry in `comments[]`. Compose the inline `body` from the reviewer's `<issue>` + `<evidence>` + `<suggestion>` — preserve the reviewer's wording, do not paraphrase. Findings whose `location` is `general` (no file:line anchor) go into the top-level review `body` instead. **Skip `praise` findings when building `comments[]`** — they are not actionable, and inline praise comments are exactly the noise the reviewer is supposed to filter out at the source; if you want to surface them, weave them into the top-level review `body` alongside the summary. Map the reviewer's `<verdict>` to the GitHub `event`:
+4. **Translate findings into a `gh api` review payload.** Each `<finding>` with `severity` of `blocker`, `concern`, or `nit` and a `location="path:line"` becomes one entry in `comments[]`. Compose the inline `body` from the reviewer's `<issue>` + `<evidence>` + `<suggestion>` — preserve the reviewer's wording, do not paraphrase. Findings whose `location` is `general` (no file:line anchor) go into the top-level review `body` instead. **Skip `praise` findings when building `comments[]`** — they are not actionable, and inline praise comments are exactly the noise the reviewer is supposed to filter out at the source; if you want to surface them, weave them into the top-level review `body` alongside the summary.
+
+   **The verdict and the inline comments are independent. The verdict sets only the `event` field; it never decides whether you post `comments[]`.** Whenever there is at least one actionable finding (`blocker`/`concern`/`nit`) with a `location="path:line"`, you MUST submit a formal review via `POST /pulls/<N>/reviews` carrying those findings in `comments[]` — including when the verdict is `approve`. An `approve` with three nits is still a formal `APPROVE` review with three inline comments, **not** a plain approval and **not** a flattened summary posted as a top-level comment. Collapsing inline findings into a single `channel_reply` or issue comment loses the line anchors the reviewer worked to produce — that is the exact failure mode this step exists to prevent.
+
+   Map the reviewer's `<verdict>` to the GitHub `event`:
 
    | Reviewer verdict  | GitHub `event`    |
    | ----------------- | ----------------- |
@@ -88,13 +92,21 @@ Why delegate: the `reviewer` subagent runs on the `deep` model profile, loads a
 
    **Always use `--input -` with a quoted heredoc (`<<'JSON'`) for review bodies.** Do **not** use `-f body=...` or `-F 'comments[][body]=...'`: those go through shell argument parsing, so backticks (\`) trigger command substitution and have to be backslash-escaped, which leaks the literal `\` into the rendered comment. The quoted heredoc passes the JSON through untouched — backticks, newlines, and `${...}` all survive verbatim. The same applies to any other `gh api` POST whose body contains backticks, embedded newlines, or shell metacharacters.
 
-5. **Post a one-line summary with `channel_reply`** so the conversation has a human-readable trace pointing at the review (e.g., "Posted review on PR #N: <verdict>, N findings.").
+5. **Verify the review actually landed before announcing it.** The `gh api` call can fail silently from the model's perspective — a permission denial, a bad `line` anchor, or a malformed payload returns an error you must not paper over. After submitting, confirm the review exists:
+
+   ```sh
+   gh api /repos/owner/repo/pulls/<N>/reviews --jq '.[-1] | {id, state, user: .user.login}'
+   ```
+
+   The returned `id`/`state` is your proof the formal review posted. If the call errored or the review is absent, do **not** fall back to a top-level `channel_reply` that _claims_ a review was posted — fix the payload (most often a `line` that isn't part of the diff; re-anchor it or move that finding to the top-level `body`) and resubmit. A trace reply that says "Posted review" when no review exists is worse than silence.
+
+6. **End the turn with `skip_response`, not a trace reply.** The formal review from step 4 already landed _in this PR_ — it carries the summary, the verdict, and the inline comments. A `channel_reply` here does **not** go to a separate operator channel; on GitHub it posts another public comment on the same PR. A one-line "Posted review on PR #N: …" narrated into the PR thread is meta-commentary addressed to a phantom operator, and it reads absurdly next to the review it claims to point at. So once step 5 confirms the review exists, call `skip_response({ reason: "review posted via gh api" })` to close the turn silently. Only fall back to `channel_reply` when there was **no** formal review to post — the zero-actionable-findings branches in Rules below already use `channel_reply`/issue comments _as_ the substantive reply.
 
 ### Rules
 
 - **Always delegate to the `reviewer` subagent.** Do not perform the review craft yourself. The reviewer is the source of truth for severity, evidence quality, and what counts as a finding. Your job is mechanics: spawn, wait, translate, post.
 - **Trust the verdict.** Use the GitHub `event` mapped from the reviewer's `<verdict>`. Do not upgrade `comment` → `APPROVE` to seem agreeable, and do not downgrade `request-changes` → `COMMENT` to soften the tone. The reviewer chose deliberately.
-- **No actionable findings → no inline review post.** A finding is "actionable" if its severity is `blocker`, `concern`, or `nit`. If the reviewer returns zero actionable findings:
+- **No actionable findings → no inline review post.** A finding is "actionable" if its severity is `blocker`, `concern`, or `nit`. This branch applies **only when the actionable count is exactly zero** — if there is even one actionable finding with a line anchor, follow step 4 and submit a formal review with `comments[]` regardless of verdict. When the reviewer returns zero actionable findings:
   - `approve` verdict → post a plain `APPROVE` with the `<summary>` as the review body (no `comments[]` array).
   - `comment` verdict → post the summary as a top-level PR comment via `gh api -X POST /repos/.../issues/<N>/comments` instead of submitting an empty review.
   - `request-changes` verdict → submit `REQUEST_CHANGES` with the `<summary>` as the review body and no `comments[]` array. This combination is rare (the reviewer's contract says `request-changes` requires at least one blocker or load-bearing concern), so if it happens, faithfully encode the verdict and trust the reviewer's reasoning is in the summary.

package/src/skills/typeclaw-permissions/SKILL.md

@@ -42,11 +42,19 @@ When the runtime knows your permissions, it prepends a block under your `## Sess
 Role: `member`. Permissions: `channel.respond`.
 ```
 
-The block renders for cron / channel / subagent sessions. For TUI sessions, the block is omitted because TUI always resolves to `owner` under severity-then-declaration ordering (built-in `owner.match` includes `tui` and is appended-to, never replaced, by user config — and `owner` is walked first). If you don't see the block in a TUI session, treat yourself as `owner`.
+This concrete role/permissions block renders for **cron and subagent** sessions, which have a single fixed actor. For TUI sessions the block is omitted because TUI always resolves to `owner` under severity-then-declaration ordering (built-in `owner.match` includes `tui` and is appended-to, never replaced, by user config — and `owner` is walked first). If you don't see the block in a TUI session, treat yourself as `owner`.
 
-**The role line reflects the session at creation time.** For channel sessions, the speaker on subsequent turns may resolve to a different role; the runtime updates that internally for tool gating (the channel router and the security plugin re-resolve on each turn), but the system prompt is not regenerated mid-session. If the user asks "what role am I right now in this channel", read `typeclaw.json` `roles` and match their author id against `match[]` yourself — do not parrot the system-prompt line as if it always applied.
+**Channel sessions are different.** A channel session is keyed by chat/thread, not by author, so it can see many speakers with different roles. It does NOT print one concrete role; instead the block is a policy reminder:
 
-**The permission list is exhaustive at session-creation time** for the resolved role. If a permission you expect isn't listed there, the role doesn't carry it — adding it requires editing `roles.<role>.permissions[]` and restarting.
+```
+## Your role in this session
+
+This is a channel conversation that may include multiple speakers...
+```
+
+For each user turn, the current speaker's effective role is delivered in the turn context as a `<your-role authority="current-speaker">…</your-role>` tag (omitted for `owner`, the unconstrained default). **That per-turn tag is authoritative for the current message and overrides any role implied by the system prompt.** If the user asks "what role am I right now in this channel", read the `<your-role>` tag on the current turn (or, if absent, treat them as `owner`); do not consult a session-creation role line — channel sessions no longer carry one.
+
+**The permission list (cron/subagent block) is exhaustive at session-creation time** for the resolved role. If a permission you expect isn't listed there, the role doesn't carry it — adding it requires editing `roles.<role>.permissions[]` and restarting.
 
 ## The match-rule DSL
 

package/src/skills/typeclaw-skills/SKILL.md

@@ -5,7 +5,9 @@ description: Use this skill whenever the user asks you to install, find, list, u
 
 # typeclaw-skills
 
-You operate inside an agent folder. Skills — markdown files with YAML frontmatter — are how this folder teaches you new procedures, conventions, and APIs without changing your code. The runtime discovers them on session start, parses each `SKILL.md`'s frontmatter, and surfaces the `name` + `description` to you so you can decide when to read the body. **You do not import or invoke skills; you read them when their description matches the current request.**
+You operate inside an agent folder. Skills — markdown files with YAML frontmatter — are how this folder teaches you new procedures, conventions, and APIs without changing your code. The runtime discovers them on session start, parses each `SKILL.md`'s frontmatter, and surfaces the `name` + `description` (plus an absolute `<location>` path) to you in the `<available_skills>` section so you can decide when to read the body. **You do not import or invoke skills; you load one by `read`-ing the `SKILL.md` at the exact `<location>` path that section gives you.**
+
+**Never construct or guess a skill's path.** Use the `<location>` verbatim. Do not assume a layout like `node_modules/typeclaw/src/skills/<name>/SKILL.md` — bundled skills resolve through the installed package, user skills live under `.agents/skills/`, and muscle-memory skills under `memory/skills/`. If a skill you expect is not listed in `<available_skills>`, it is not a file-based skill and has no `SKILL.md` to read — stop looking on disk. (Subagent-only skills loaded via the `load_skill` tool, e.g. the `reviewer` subagent's `code-review`, are never files.)
 
 This skill exists so you (a) understand which skills you can edit and which you must not, (b) can install new skills cleanly when the user asks, and (c) can author your own skills without colliding with the rest of the system.