typeclaw 0.15.2 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.15.2",
+  "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'
@@ -63,7 +64,7 @@ export type { SessionOrigin } from './session-origin'
 
 export type { AgentSession }
 
-export { renderTurnTimeAnchor } from './system-prompt'
+export { renderTurnRoleAnchor, renderTurnTimeAnchor } from './system-prompt'
 
 type AgentSessionTools = NonNullable<Parameters<typeof createAgentSession>[0]>['tools']
 
@@ -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
@@ -335,6 +347,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
           sessionId: options.plugins.sessionId,
           hooks: options.plugins.hooks,
           getOrigin,
+          ...(options.permissions ? { permissions: options.permissions } : {}),
         })
       : []
   const wrappedCustomSystemTools = wrapSystemTools(customSystemTools, options.plugins, getOrigin)
@@ -576,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,
@@ -711,6 +743,7 @@ export function deriveSystemPromptMode(origin: SessionOrigin | undefined): Syste
       return 'full'
     case 'cron':
     case 'subagent':
+    case 'system':
       return 'slim'
     default: {
       const _exhaustive: never = origin

package/src/agent/plugin-tools.ts

@@ -20,6 +20,7 @@ import {
   checkNonWorkspaceWriteGuard,
   checkSkillAuthoringGuard,
 } from '@/bundled-plugins/guard/policy'
+import type { PermissionService } from '@/permissions/permissions'
 import type {
   BuiltinToolRef,
   ContentPart,
@@ -30,6 +31,7 @@ import type {
   ToolContext,
   ToolResult,
 } from '@/plugin'
+import { buildSandboxedCommand, ensureBwrapAvailable, resolveHiddenPaths } from '@/sandbox'
 
 import { createLoopGuard, type LoopGuard } from './loop-guard'
 import { checkImageReadRedirect } from './multimodal/read-redirect'
@@ -134,6 +136,11 @@ export type WrapSystemToolOptions = {
   sessionId: string
   hooks: HookBus
   getOrigin?: () => SessionOrigin | undefined
+  // When present, the bash builtin is rewritten through the per-tool bwrap
+  // sandbox with role-derived path masks. Absent (or no masks for the role)
+  // runs bash unchanged — preserving today's behavior for trusted+ and for
+  // sessions wired without a permission service (e.g. tests).
+  permissions?: PermissionService
 }
 
 // Zod 4 emits a top-level `"$schema": "https://json-schema.org/draft/2020-12/schema"`
@@ -393,6 +400,10 @@ export function wrapAgentToolAsCustomToolDefinition<TParams extends TSchema, TDe
       }
       stripGuardAcknowledgements(mutableArgs)
 
+      if (tool.name === 'bash' && opts.permissions !== undefined) {
+        await applyBashSandbox(mutableArgs, opts.permissions, liveOrigin, opts.agentDir)
+      }
+
       const result = await tool.execute(toolCallId, mutableArgs as Static<TParams>, signal, onUpdate)
       const hookResult: ToolResult = {
         content: result.content as ContentPart[],
@@ -425,6 +436,33 @@ export function buildBuiltinPiToolOverrides(opts: WrapSystemToolOptions): ToolDe
   return defaultBuiltinPiAgentTools().map((tool) => wrapAgentToolAsCustomToolDefinition(tool, opts))
 }
 
+// Rewrites mutableArgs.command in place so the bash builtin runs inside bwrap
+// with role-derived path masks. A role that sees everything (trusted+) yields
+// no masks and runs unchanged. When masks ARE needed but bwrap is unavailable
+// we throw rather than run unsandboxed — fail closed, never leak the masked
+// surface. Runs after the tool.before guards have inspected the raw command.
+async function applyBashSandbox(
+  mutableArgs: Record<string, unknown>,
+  permissions: PermissionService,
+  origin: SessionOrigin | undefined,
+  agentDir: string,
+): Promise<void> {
+  const command = mutableArgs.command
+  if (typeof command !== 'string') return
+
+  const { dirs, files } = resolveHiddenPaths(permissions, origin, agentDir)
+  if (dirs.length === 0 && files.length === 0) return
+
+  await ensureBwrapAvailable()
+  const { commandString } = buildSandboxedCommand(command, {
+    mounts: [{ type: 'bind', source: agentDir, dest: agentDir }],
+    masks: { dirs, files },
+    network: 'inherit',
+    cwd: agentDir,
+  })
+  mutableArgs.command = commandString
+}
+
 function appendLoopWarning(result: ToolResult, message: string): ToolResult {
   const content: ContentPart[] = [...(result.content as ContentPart[]), { type: 'text', text: message }]
   return { content, details: result.details }

package/src/agent/session-meta.ts

@@ -28,10 +28,12 @@ export type MinimalSessionOrigin =
       thread: string | null
     }
   | { kind: 'subagent'; subagent: string; parentSessionId: string }
+  | { kind: 'system'; component: string }
 
 // Reduce a full SessionOrigin to the minimum projection persisted to disk.
-// Drops participant lists, membership counts, recursive provenance, and
-// author identifiers — none of which `typeclaw usage` reads, and all of
+// Drops participant lists, membership counts, recursive provenance (including
+// the system origin's `triggeredBy`, which can carry channel author identity),
+// and author identifiers — none of which `typeclaw usage` reads, and all of
 // which would otherwise land in git history when sessions/ is auto-backed-up.
 // Kept as a separate function so the boundary between "data the LLM sees in
 // the system prompt" (full origin) and "data persisted for usage reporting"
@@ -58,5 +60,7 @@ function minimalOrigin(origin: SessionOrigin): MinimalSessionOrigin {
       }
     case 'subagent':
       return { kind: 'subagent', subagent: origin.subagent, parentSessionId: origin.parentSessionId }
+    case 'system':
+      return { kind: 'system', component: origin.component }
   }
 }

package/src/agent/session-origin.ts

@@ -48,6 +48,23 @@ export type SessionOrigin =
       spawnedByRole?: string
       spawnedByOrigin?: SessionOrigin
     }
+  // Runtime-owned infrastructure operating over TypeClaw's own state (memory
+  // logging/retrieval, backup), NOT user-delegated work. It resolves to `owner`
+  // because it acts on the operator's behalf over operator-owned files, with no
+  // single user session to inherit authority from — inheriting the triggering
+  // turn's role (e.g. a guest channel turn) would wrongly classify TypeClaw
+  // infrastructure as the guest actor and block its legitimate sessions//memory/
+  // access. `triggeredBy` keeps honest provenance — "a guest turn triggered the
+  // memory-logger" — without the synthetic-TUI lie. This kind is only ever
+  // constructed by runtime/bundled code; inbound channel/cron content can never
+  // produce it (those origins come from the runtime, not from message text), so
+  // it is not a role-laundering vector.
+  | {
+      kind: 'system'
+      component: string
+      reason?: string
+      triggeredBy?: SessionOrigin
+    }
 
 export const PARTICIPANTS_TOP_K = 10
 export const PARTICIPANTS_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
@@ -94,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[]
@@ -111,19 +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, 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 {
@@ -141,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',
@@ -167,6 +212,34 @@ function renderCronOrigin(origin: { jobId: string; jobKind: 'prompt' | 'exec' |
   ].join('\n')
 }
 
+function renderSystemOrigin(origin: { component: string; reason?: string; triggeredBy?: SessionOrigin }): string {
+  const lines = [
+    '## Session origin',
+    '',
+    `You are the \`${origin.component}\` system process — TypeClaw-owned`,
+    "infrastructure operating over the agent folder on the operator's behalf,",
+    'not a user-delegated task. Do exactly the job described and exit.',
+  ]
+  if (origin.reason !== undefined) lines.push('', `Reason: ${origin.reason}`)
+  if (origin.triggeredBy !== undefined) lines.push('', `Triggered by: ${describeTrigger(origin.triggeredBy)}`)
+  return lines.join('\n')
+}
+
+function describeTrigger(origin: SessionOrigin): string {
+  switch (origin.kind) {
+    case 'tui':
+      return 'a TUI session'
+    case 'cron':
+      return `cron job \`${origin.jobId}\``
+    case 'channel':
+      return `a ${getPlatformInfo(origin.adapter).displayName} channel turn`
+    case 'subagent':
+      return `the \`${origin.subagent}\` subagent`
+    case 'system':
+      return `the \`${origin.component}\` system process`
+  }
+}
+
 function renderSubagentOrigin(origin: { subagent: string; parentSessionId: string }): string {
   return [
     '## Session origin',
@@ -215,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)
 
@@ -244,10 +333,18 @@ function renderChannelOrigin(
     '  have no reason worth recording. Any other visible text without a',
     '  channel tool call is blocked.',
     '',
+    '**Every user-facing sentence goes through `channel_reply`.** Narrating in',
+    'plain text — "bumping to 16x now", "let me check that" — does NOT reach the',
+    'user; it is invisible. If you want the user to see it, it is a',
+    '`channel_reply` call, not narration. This includes acks.',
+    '',
     '**One substantive reply per inbound.** If the answer needs more than one',
-    'tool call, send a one-line ack first ("On it."), keep working, then send',
-    'the answer — both in the same turn. The ack is not your reply; the answer',
-    'is. Once the answer lands, end your turn.',
+    'tool call, send a one-line ack first via `channel_reply({ text: "On it.",',
+    'continue: true })`, keep working, then send the answer with a final',
+    '`channel_reply`. The ack is not your reply; the answer is. Once the answer',
+    'lands, end your turn. The `continue: true` is not optional on that ack:',
+    'without it the turn ends the instant the ack lands and the rest of your',
+    'work — the fetch, the subagent, the actual answer — is silently dropped.',
     '',
     '**Backgrounded work does not end the obligation.** If you spawn a',
     'subagent with `run_in_background: true` to answer the current inbound,',

package/src/agent/subagents.ts

@@ -455,7 +455,12 @@ function parseSpawnedByOriginJson(
   return parsed
 }
 
-const SESSION_ORIGIN_KINDS = new Set(['tui', 'cron', 'channel', 'subagent'])
+// Must list EVERY SessionOrigin discriminator. `system` is included so a
+// streamed memory/backup spawn (whose spawnedByOrigin is serialized to JSON
+// and re-parsed here) keeps its owner-resolving origin instead of being
+// dropped and silently demoted to guest — the exact regression the system
+// origin exists to prevent. Keep in sync with the SessionOrigin union.
+const SESSION_ORIGIN_KINDS = new Set(['tui', 'cron', 'channel', 'subagent', 'system'])
 function isSessionOriginShape(value: unknown): value is SessionOrigin {
   if (value === null || typeof value !== 'object') return false
   const kind = (value as { kind?: unknown }).kind

package/src/agent/system-prompt.ts

@@ -27,6 +27,7 @@ When in doubt between SOUL.md and AGENTS.md: if it describes *how you sound*, it
 ## Your workspace
 
 - **\`workspace/\`** — your free-write zone for drafts, scratch work, generated artifacts. Do not create files at the agent-folder root unless the user explicitly asks.
+- **\`public/\`** — the guest-visible zone. Untrusted callers (the \`guest\` role) cannot see \`workspace/\`, but they can read and write \`public/\`. Put anything meant to be shared with an untrusted caller here. If a \`<your-role>\` tag on the turn names a non-trusted role, or a write to \`workspace/\` comes back \`denied by permissions\`, the caller is untrusted — write to \`public/\` instead.
 - **\`sessions/\`** — transcripts of past conversations. Runtime-managed; don't write here.
 - **\`memory/streams/\`** *(not injected — reach via \`memory_search\`)* — dated streams written by the memory-logger between sessions. Runtime-owned. Undreamed observations are searchable on demand instead of injected into every prompt.
 - **\`memory/skills/\`** — muscle-memory skills written by the dreaming subagent. Auto-loaded; don't write here directly.
@@ -45,6 +46,17 @@ When the user gives you work, start doing it in the same turn — a real action,
 
 Do not narrate routine, low-risk tool calls. Just call the tool. Narrate only when it helps: multi-step work, risky actions (deletions, external sends, irreversible changes), or when the user asks.
 
+## Long-running and interactive shell work
+
+Foreground \`bash\` blocks your turn until exit, so a command that runs for minutes or waits for input (dev server, REPL, watcher, \`docker compose up\`, interactive installer) freezes the conversation. \`tmux\` is in the container — run such programs detached so your turn stays free:
+
+- Start: \`tmux new-session -d -s <name> "<cmd>"\`
+- Observe: \`tmux capture-pane -t <name> -p\` (poll across turns, don't block)
+- Drive: \`tmux send-keys -t <name> "<input>" Enter\` (control keys too, e.g. \`C-c\`)
+- Stop: \`tmux kill-session -t <name>\`
+
+Use this only when the work belongs in *your* session. For self-contained long work (build, test suite, install, batch) whose result is all you need, delegate to \`operator\` instead.
+
 ## Version control
 
 Your agent folder is a git repository.
@@ -64,35 +76,17 @@ Your agent folder is a git repository.
 
 ## Subagent orchestration
 
-You can delegate focused work to subagents via three tools: \`spawn_subagent\`, \`subagent_output\`, \`subagent_cancel\`. Subagents run with their own context window and their own (often smaller, cheaper, or more constrained) tool set. The list of available subagents and what each one is for is rendered in the \`spawn_subagent\` tool description — re-read it before delegating.
-
-There are two delegation modes. Pick deliberately.
-
-**Mode A — Research fan-out** (in service of the current question)
-
-When you need information to answer the user and the search is broad, fire 2-5 subagents in parallel with \`run_in_background: true\` covering different angles. End your response after spawning. The system will deliver a \`<system-reminder>\` for each completion; then call \`subagent_output\` once per task_id to fetch the result and answer the user. \`subagent_output\` always returns immediately with a snapshot — it does not block.
-
-The bundled \`explorer\` subagent is the right tool for **local** reconnaissance — anything reachable on the agent's filesystem: code, past sessions (\`sessions/*.jsonl\`), memory topic shards and daily memory streams, skills, cron jobs, config, git history, mounts, channels state. It is read-only and runs on a fast/cheap model, so fire liberally. Do NOT ask it to plan, decide, or write code — it finds and reports.
-
-The bundled \`scout\` subagent is its external counterpart — web research only. Use it when you need information from public sources (docs, library references, vendor changelogs, news, anything not already in this agent's folder). Scout runs \`websearch\` and \`webfetch\` in a fresh context window so the search churn does not pollute yours; it returns a citation-backed answer with a confidence rating. Prefer scout over running \`websearch\`/\`webfetch\` yourself when the research is non-trivial (more than 1-2 queries) or when you want to save your context for the synthesis step.
+Delegate focused work to subagents via \`spawn_subagent\`, \`subagent_output\`, \`subagent_cancel\`. Each runs in its own context window with its own tool set. The available subagents and their purpose are listed in the \`spawn_subagent\` tool description — re-read it before delegating. Briefly: \`explorer\` (read-only local recon — code, sessions, memory, git, config; fire liberally), \`scout\` (web research in a fresh context), \`reviewer\` (deep read-only code/PR/plan review, returns a structured verdict; it does NOT post), \`operator\` (write-capable: bash-with-side-effects, write, edit — for browser sessions, refactors, deploys, batch ops, and Claude Code / Codex CLI driving; gated by \`subagent.spawn.operator\`, owner/trusted only — on denial, do the work yourself).
 
-The bundled \`reviewer\` subagent is for **deep read-only analysis** — code review, PR review, plan review, design review, docs review. It runs on the \`deep\` profile (falls back to \`default\` if \`models.deep\` is unconfigured) so it can spend tokens on careful reasoning. It has the read-only filesystem tools, \`bash\` (for \`gh pr diff\`, \`git log\`, \`git diff\`, \`gh api -X GET\`, etc.), and the web tools (for verifying claims against OWASP, RFCs, library docs). It returns a structured \`<review>\` block with findings (severity \`blocker\`/\`concern\`/\`nit\`/\`praise\`, evidence quotes, suggestions) and a verdict (\`approve\`/\`request-changes\`/\`comment\`). Reviewer does NOT post — when reviewing a PR for a channel that wants comments posted, YOU translate its findings into \`gh api\` review-comment payloads and post them yourself. Use reviewer instead of doing review work in your own session whenever the target is non-trivial: a single-file lookup or a one-paragraph sanity check stays with you; a real PR, a multi-page design doc, a non-trivial plan — delegate.
+There are three delegation modes. Pick deliberately.
 
-**Mode B — Delegate-and-converse** (the user asked you to DO something long-running)
+**Mode A — Research fan-out.** Need information and the search is broad? Fire 2-5 subagents (usually \`explorer\`/\`scout\`) in parallel with \`run_in_background: true\`, then end your response. A \`<system-reminder>\` lands per completion; call \`subagent_output\` once per task_id to collect (it never blocks) and answer.
 
-When the user hands you a task that will take minutes (a multi-step browser session, a long build, a complex external operation), acknowledge in plain language ("Alright, running that in the background — I'll let you know when it's done"), spawn one subagent with \`run_in_background: true\`, then KEEP TALKING. Stay available for follow-ups, related questions, parallel small tasks. When the completion reminder lands, weave the result into your next reply naturally. If the conversation has gone idle, proactively message the user with the result rather than waiting.
+**Mode B — Delegate-and-converse.** Asked to DO something long-running (>~30s: installs, builds, \`docker\`, scrapes, long test suites, multi-host loops, any noisy "fetch N and synthesize" chain)? Don't run it inline — blocking your own \`bash\` freezes the conversation and stalls the channel typing heartbeat (\`MAX_TYPING_HEARTBEAT_MS\`). Spawn one subagent (\`operator\` for side effects, \`scout\` for research) with \`run_in_background: true\`, acknowledge, and KEEP TALKING. Single fast calls (\`git status\`, one known-endpoint \`curl\`) stay inline. When the completion reminder lands, weave the result in; in a channel session, the completion \`<system-reminder>\` is NOT a user message but plain text is still invisible — Surface the result via \`channel_reply\` (or \`channel_send\`). If you already posted the substantive answer in the spawn turn, prefer \`skip_response({ reason: "result confirms prior reply" })\` over going silent.
 
-**Concrete threshold: ~30 seconds.** If you expect a tool call to take longer than that, delegate. While your own \`bash\` is blocked, you cannot reply, the channel typing indicator cannot heartbeat past silent stretches (it caps after a couple of minutes of no tool activity by design — see \`MAX_TYPING_HEARTBEAT_MS\`), and the user sees a frozen-looking conversation. Specifically: do NOT run \`npm install\`, \`bun install\`, \`docker build\`, \`docker compose up\`, multi-target \`curl\` probes, headed-browser scrapes, WebSocket/CDP captures, long \`pytest\`/\`npm test\` suites, or any "do N requests across hosts" loop in your own session — delegate every one of those to \`operator\`. Single fast \`bash\` calls (a \`git status\`, a \`ls\`, a one-shot \`curl\` against a known endpoint) stay in your session; that's not what this rule is targeting.
+**Mode C — Troubleshooting.** Stuck in a fix-it loop — ~3 non-converging attempts at the same failure, cycling kill/re-run/\`sleep\`/capture/retry? Stop (the trigger is non-convergence, not elapsed time — this overrides the ~30s rule). Hand the whole debugging loop to \`operator\` with \`run_in_background: true\` — symptom, what you tried, success condition — and stay responsive. Read the \`typeclaw-troubleshooting\` skill for the mechanics before you spawn.
 
-In a channel session, the completion \`<system-reminder>\` is NOT a user message — the channel origin's "you MUST call \`channel_reply\` for every user message" rule does not literally apply, but the underlying constraint does: plain-text output is invisible in a channel. Surface the result via \`channel_reply\` (or \`channel_send\`) so the user actually sees it. Failures need surfacing too: when a delegated task didn't complete, the user needs the outcome and whatever partial progress you got. Skipping the reply is legal only when the user has already seen the substantive answer — typically because you posted it via \`channel_reply\` in the same turn that spawned the subagent, and the reminder is purely confirming completion of a step the user is already tracking. In that case, prefer \`skip_response({ reason: "result confirms prior reply" })\` over the \`NO_REPLY\` text sentinel — the structured tool records why, so the operator can audit silent post-completion turns. Otherwise, post the result.
-
-Before you run a tool chain that returns bulky intermediate output you won't need again — multiple \`webfetch\` calls, a \`websearch\` round you'll iterate on, a \`bash\` command that scrapes a site or dumps a large response, an \`agent-browser\` session, a \`claude\` (Claude Code) or \`codex\` (OpenAI Codex CLI) delegation driven through tmux, any "fetch N things and synthesize" loop — delegate it to a subagent. \`scout\` (for research) or \`operator\` (for actions with side effects) runs the noisy work in its own context window and returns a distilled summary; your session carries the *answer*, not the raw material you derived it from. This is about context economy, not latency: even a fast operation belongs in a subagent when the byproducts are large and disposable (three quick news searches across different outlets still dumps three SERPs and three article bodies into your context forever). The exception is exactly one call whose result you'll cite directly — one \`webfetch\` of a known URL, one \`websearch\` query whose top result is the answer. Two of either, or any "across multiple sources" framing, is delegation territory.
-
-The bundled \`operator\` subagent is the right tool for this mode. It is write-capable (read, write, edit, bash with side effects) and runs on the default model. Use it for: browser sessions, multi-file refactors, deploys, batch API calls, Claude Code or Codex CLI delegations (the tmux driving loop, the multi-turn polling, the worktree teardown — all of it inside operator), anything that involves taking action on behalf of the user over multiple steps. The operator returns a structured final report (outcome, what changed, what was observed); surface it naturally rather than copy-pasting. Operator is gated by a separate permission (\`subagent.spawn.operator\`) so write-capable spawns are restricted to owner-tier and trusted-tier callers — if the gate denies, fall back to doing the work in your own session rather than reporting failure to the user.
-
-**Status queries**
-
-If the user asks "how's it going?" or "status?" on a running subagent, call \`subagent_output({ task_id })\` and report the \`status_summary\` in your own words. Don't pretend to know the status without checking.
+**Status queries.** If the user asks "status?" on a running subagent, call \`subagent_output({ task_id })\` and report its \`status_summary\` — don't guess.
 
 **Prompt structure for spawns** (mandatory — the subagent does not see this conversation)
 
@@ -102,13 +96,7 @@ If the user asks "how's it going?" or "status?" on a running subagent, call \`su
 [REQUEST]: Concrete instructions — what to find/do/produce, what format, what to SKIP.
 \`\`\`
 
-**Anti-patterns**
-
-- Don't fire more than 5 subagents in a single turn.
-- Don't spawn for a known answer or single-file lookup — do it yourself.
-- Don't call \`subagent_output\` in a loop waiting for completion; end your response and the reminder will wake you, then fetch the result once.
-- Don't ask a research subagent to make architectural decisions for you — they find and report; you decide.
-- Subagents cannot recursively spawn other subagents.
+**Anti-patterns.** Don't fire more than 5 subagents per turn, spawn for a known answer or single-file lookup, poll \`subagent_output\` in a loop (end your turn; the reminder wakes you), or ask a research subagent to make decisions — they find and report, you decide. Subagents cannot recursively spawn subagents.
 
 ## Safety
 
@@ -167,6 +155,27 @@ export function renderTurnTimeAnchor(now: Date = new Date()): string {
   return `<current-time>${iso} (${zone}, ${weekday})</current-time>`
 }
 
+// Live role anchor injected into the **user turn**, not the system prompt —
+// same rationale and cache properties as renderTurnTimeAnchor above.
+//
+// The "## Your role in this session" block in the system prompt is a
+// session-CREATION snapshot: in a channel where speakers change turn to turn,
+// it reports the role of whoever first opened the session, not whoever is
+// speaking now. Tool gating already re-resolves the live role per turn (the
+// router updates `originRef` before each prompt), but the model never saw that
+// value — so it could not, for example, route output to `public/` for a guest.
+// This anchor surfaces the per-turn resolved role in the one place that costs
+// zero cached bytes (the non-cacheable user-turn suffix).
+//
+// Omitted for `owner`: owner is the unconstrained default, an absent tag means
+// "no special handling", and emitting it on every interactive turn would be
+// pure token overhead. This mirrors resolveRoleContext skipping the session
+// block for a TUI owner.
+export function renderTurnRoleAnchor(role: string): string | undefined {
+  if (role === 'owner') return undefined
+  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
 // sessions (cron jobs, and default subagents that don't supply their own
 // `systemPromptOverride`). The full prompt is ~2155 tokens of operator-facing
@@ -207,6 +216,6 @@ Never suppress errors to make things "work", and never fabricate results. If som
 
 Do not narrate routine, low-risk tool calls — just call the tool. Do not over-explain what you did unless asked.
 
-Your free-write zone is \`workspace/\`. Do not create files at the root of the agent folder unless the prompt names another path. Do not edit \`memory/topics/\` directly — the dreaming subagent owns it; to capture something memorable, surface it in your reply or let the memory-logger append to \`memory/streams/\`. Never stage or commit \`secrets.json\`, \`.env\`, \`sessions/\`, \`memory/\`, or \`workspace/\` — those are runtime- or user-managed.
+Your free-write zone is \`workspace/\`. Do not create files at the root of the agent folder unless the prompt names another path. \`public/\` is the guest-visible zone — write there anything meant to be shared with an untrusted caller (a \`guest\`-role turn cannot read \`workspace/\` but can read \`public/\`). Do not edit \`memory/topics/\` directly — the dreaming subagent owns it; to capture something memorable, surface it in your reply or let the memory-logger append to \`memory/streams/\`. Never stage or commit \`secrets.json\`, \`.env\`, \`sessions/\`, \`memory/\`, or \`workspace/\` — those are runtime- or user-managed.
 
 See the session-origin block below for what kind of session this is and what's expected of you.`

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

@@ -74,8 +74,9 @@ export function createChannelReplyTool({
       continue: Type.Optional(
         Type.Boolean({
           description:
-            'Set `true` ONLY when this reply is a mid-turn status update (e.g. "working on it…") and you still have work to do THIS turn — fetching data, running a tool, spawning a subagent, then replying again. ' +
-            'A normal reply omits this: by default a successful reply ends the turn (no wasted follow-up LLM call). ' +
+            'Set `true` when this reply is a mid-turn status update (e.g. "working on it…") and you still have work to do THIS turn — fetching data, running a tool, spawning a subagent, then replying again. ' +
+            'Omitting it on such an ack silently truncates the turn: a successful reply ends the turn by default, so the fetch/subagent/answer you intended to do next never runs. ' +
+            'A normal final reply omits this (no wasted follow-up LLM call). ' +
             'Do not set it just to seem responsive; only when genuine multi-step work follows in the same turn.',
         }),
       ),