typeclaw 0.18.0 → 0.20.0

package/package.json

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

package/src/agent/index.ts

@@ -26,6 +26,7 @@ import { getAuthFor } from './auth'
 import { createCompactionSettingsManager } from './compaction'
 import { renderGitNudge } from './git-nudge'
 import type { LiveSubagentRegistry } from './live-subagents'
+import { applyModelRuntimeOverrides } from './model-overrides'
 import { createChannelLookAtTool, lookAtTool } from './multimodal'
 import {
   buildBuiltinPiToolOverrides,
@@ -48,6 +49,7 @@ import {
 } from './tool-result-budget'
 import { createChannelFetchAttachmentTool } from './tools/channel-fetch-attachment'
 import { createChannelHistoryTool } from './tools/channel-history'
+import { createChannelReactTool } from './tools/channel-react'
 import { createChannelReplyTool } from './tools/channel-reply'
 import { createChannelSendTool } from './tools/channel-send'
 import { createGrantRoleTool } from './tools/grant-role'
@@ -357,7 +359,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
       ? customToolsPreBudget.map((t) => wrapToolDefinitionWithBudget(t, sessionBudget, sessionBudgetState))
       : customToolsPreBudget
 
-  const model = resolveModel(activeRef)
+  const model = applyModelRuntimeOverrides(resolveModel(activeRef), activeRef)
   const thinkingLevel = defaultThinkingLevelForRef(activeRef)
   const { session } = await createAgentSession({
     model,
@@ -531,6 +533,12 @@ export function buildChannelTools(
     tools.push(createChannelReplyTool({ router: channelRouter, origin: channelOrigin }))
     tools.push(createChannelHistoryTool({ router: channelRouter, origin: channelOrigin }))
     tools.push(createChannelSendTool({ router: channelRouter, origin: channelOrigin }))
+    tools.push(
+      createChannelReactTool({
+        router: channelRouter,
+        origin: { ...channelOrigin, ...(origin.reactionRef !== undefined ? { reactionRef: origin.reactionRef } : {}) },
+      }),
+    )
     tools.push(
       createChannelFetchAttachmentTool({
         router: channelRouter,

package/src/agent/live-subagents.ts

@@ -19,6 +19,10 @@ export type LiveSubagent = {
   sessionId: string
   subagentName: string
   parentSessionId?: string
+  // Role that resolved at spawn time, captured for the provenance cap on
+  // subagent_output/subagent_cancel. Absent when no permission service was
+  // active at spawn, in which case the cap fails closed.
+  spawnedByRole?: string
   startedAt: number
   status: SubagentStatus
   completion?: SubagentCompletion

package/src/agent/model-overrides.ts

@@ -0,0 +1,77 @@
+import type { Api, Model } from '@mariozechner/pi-ai'
+
+import { providerForModelRef, type KnownModelRef, type KnownProviderId } from '@/config/providers'
+
+// Providers whose base URL can be swapped to an upstream-compatible gateway at
+// runtime. Each env var mirrors the upstream SDK's own name so a credential /
+// endpoint pair that works with the official CLI carries over:
+//   * ANTHROPIC_BASE_URL — native Anthropic Messages protocol (`/v1/messages`,
+//     `x-api-key` / OAuth Bearer). NOT raw AWS Bedrock (SigV4, different
+//     transport) — that needs a distinct transport, not a base-URL swap.
+//   * OPENAI_BASE_URL — OpenAI-compatible endpoints (LiteLLM, Azure-style
+//     gateways, corporate proxies) speaking the same request shape as
+//     api.openai.com. Targets the `openai` provider only; `openai-codex` is
+//     an OAuth-only ChatGPT backend, not an API-key endpoint, so it is out of
+//     scope here.
+export const PROVIDER_BASE_URL_ENV = {
+  anthropic: 'ANTHROPIC_BASE_URL',
+  openai: 'OPENAI_BASE_URL',
+} as const satisfies Partial<Record<KnownProviderId, string>>
+
+type OverridableProviderId = keyof typeof PROVIDER_BASE_URL_ENV
+
+// Separate from `resolveModel` so resolution stays a pure table lookup; this
+// is the per-process "prepare the model" seam run just before pi-coding-agent
+// receives it. Clones because the `KNOWN_PROVIDERS` literals are shared static
+// data that must never be mutated.
+export function applyModelRuntimeOverrides<TApi extends Api>(
+  model: Model<TApi>,
+  ref: KnownModelRef,
+  env: NodeJS.ProcessEnv = process.env,
+): Model<TApi> {
+  const providerId = providerForModelRef(ref)
+  if (!isOverridable(providerId)) return model
+
+  const baseUrl = normalizeBaseUrl(PROVIDER_BASE_URL_ENV[providerId], env[PROVIDER_BASE_URL_ENV[providerId]])
+  if (baseUrl === undefined) return model
+
+  return { ...model, baseUrl }
+}
+
+// Resolves the effective base URL for a provider, falling back to the provider
+// default when the override is unset. Returns `undefined` for providers without
+// a base-URL override so callers can keep their hardcoded probe URL. Used by
+// callers outside the session path (e.g. the init-time API-key probe) that need
+// to hit the same endpoint the runtime will use.
+export function effectiveBaseUrl(
+  providerId: KnownProviderId,
+  fallback: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  if (!isOverridable(providerId)) return undefined
+  const envVar = PROVIDER_BASE_URL_ENV[providerId]
+  return normalizeBaseUrl(envVar, env[envVar]) ?? fallback
+}
+
+function isOverridable(providerId: KnownProviderId): providerId is OverridableProviderId {
+  return providerId in PROVIDER_BASE_URL_ENV
+}
+
+// `undefined` for unset/blank (caller keeps the default); throws on a value
+// that isn't a parseable http(s) URL so a typo fails loudly at boot rather
+// than silently falling back to the public API with the wrong credential.
+function normalizeBaseUrl(envVar: string, value: string | undefined): string | undefined {
+  const trimmed = value?.trim()
+  if (trimmed === undefined || trimmed === '') return undefined
+
+  let url: URL
+  try {
+    url = new URL(trimmed)
+  } catch {
+    throw new Error(`${envVar} is not a valid URL: ${trimmed}`)
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error(`${envVar} must use http:// or https://, got: ${trimmed}`)
+  }
+  return url.toString().replace(/\/+$/, '')
+}

package/src/agent/plugin-tools.ts

@@ -1,6 +1,8 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
 import type { AgentTool } from '@mariozechner/pi-agent-core'
 import {
-  bashTool as piBashTool,
+  createBashTool as piCreateBashTool,
   defineTool as piDefineTool,
   editTool as piEditTool,
   findTool as piFindTool,
@@ -9,7 +11,7 @@ import {
   readTool as piReadTool,
   writeTool as piWriteTool,
 } from '@mariozechner/pi-coding-agent'
-import type { ToolDefinition } from '@mariozechner/pi-coding-agent'
+import type { BashSpawnContext, ToolDefinition } from '@mariozechner/pi-coding-agent'
 import type { Static, TSchema } from '@sinclair/typebox'
 import { Type } from '@sinclair/typebox'
 import { z } from 'zod'
@@ -46,6 +48,38 @@ import { websearchTool } from './tools/websearch'
 // and pi-coding-agent builtins — through one chokepoint.
 let sharedLoopGuard: LoopGuard = createLoopGuard()
 
+// Internal, non-model-facing contract: a tool.before hook may set this key on
+// a bash call's args to inject env vars into the spawned process WITHOUT
+// putting them in the command string (where they would leak through logs and
+// later hooks). The wrapper extracts and deletes it before the bash tool runs,
+// then threads it to the spawn (non-sandboxed) and to bwrap --setenv
+// (sandboxed). Used by github-cli-auth to inject a per-repo GH_TOKEN. The key
+// is stripped from client-supplied args before tool.before so only trusted
+// hooks can set it.
+export const TYPECLAW_INTERNAL_BASH_ENV = '__typeclawBashEnv'
+
+type BashEnvOverlay = Record<string, string>
+
+const bashEnvStore = new AsyncLocalStorage<BashEnvOverlay | undefined>()
+
+function readBashEnvOverlay(args: Record<string, unknown>): BashEnvOverlay | undefined {
+  const raw = args[TYPECLAW_INTERNAL_BASH_ENV]
+  if (raw === null || typeof raw !== 'object') return undefined
+  const overlay: BashEnvOverlay = {}
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (typeof value === 'string') overlay[key] = value
+  }
+  return Object.keys(overlay).length > 0 ? overlay : undefined
+}
+
+function bashSpawnHookWithOverlay(context: BashSpawnContext): BashSpawnContext {
+  const overlay = bashEnvStore.getStore()
+  if (overlay === undefined) return context
+  return { ...context, env: { ...context.env, ...overlay } }
+}
+
+const piBashTool = piCreateBashTool(process.cwd(), { spawnHook: bashSpawnHookWithOverlay })
+
 const ACKNOWLEDGE_GUARDS_SCHEMA = Type.Optional(
   Type.Object(
     {
@@ -372,6 +406,9 @@ export function wrapAgentToolAsCustomToolDefinition<TParams extends TSchema, TDe
     async execute(toolCallId, params, signal, onUpdate) {
       const mutableArgs = params as Record<string, unknown>
       const liveOrigin = opts.getOrigin?.()
+      // Defense-in-depth: strip any pre-existing internal env-overlay key
+      // before hooks run so only trusted tool.before hooks can set it.
+      delete mutableArgs[TYPECLAW_INTERNAL_BASH_ENV]
       const blockResult = await opts.hooks.runToolBefore({
         tool: tool.name,
         sessionId: opts.sessionId,
@@ -382,6 +419,11 @@ export function wrapAgentToolAsCustomToolDefinition<TParams extends TSchema, TDe
       if (blockResult !== undefined) {
         throw new Error(`blocked: ${blockResult.reason}`)
       }
+      // Extract and delete before the loop guard serializes args and before
+      // the bash tool destructures them, so the overlay never reaches logs,
+      // loop-detection state, or pi's execute.
+      const bashEnvOverlay = readBashEnvOverlay(mutableArgs)
+      delete mutableArgs[TYPECLAW_INTERNAL_BASH_ENV]
       const loopDecision = sharedLoopGuard.check(opts.sessionId, tool.name, mutableArgs)
       if (loopDecision.kind === 'block') {
         throw new Error(loopDecision.message)
@@ -401,10 +443,12 @@ export function wrapAgentToolAsCustomToolDefinition<TParams extends TSchema, TDe
       stripGuardAcknowledgements(mutableArgs)
 
       if (tool.name === 'bash' && opts.permissions !== undefined) {
-        await applyBashSandbox(mutableArgs, opts.permissions, liveOrigin, opts.agentDir)
+        await applyBashSandbox(mutableArgs, opts.permissions, liveOrigin, opts.agentDir, bashEnvOverlay)
       }
 
-      const result = await tool.execute(toolCallId, mutableArgs as Static<TParams>, signal, onUpdate)
+      const result = await bashEnvStore.run(bashEnvOverlay, () =>
+        tool.execute(toolCallId, mutableArgs as Static<TParams>, signal, onUpdate),
+      )
       const hookResult: ToolResult = {
         content: result.content as ContentPart[],
         details: result.details,
@@ -446,6 +490,7 @@ async function applyBashSandbox(
   permissions: PermissionService,
   origin: SessionOrigin | undefined,
   agentDir: string,
+  envOverlay: BashEnvOverlay | undefined,
 ): Promise<void> {
   const command = mutableArgs.command
   if (typeof command !== 'string') return
@@ -454,11 +499,15 @@ async function applyBashSandbox(
   if (dirs.length === 0 && files.length === 0) return
 
   await ensureBwrapAvailable()
+  // bwrap does --clearenv, so the overlay must be re-introduced via env.set or
+  // it would never reach the sandboxed process (the non-sandboxed spawnHook
+  // path does not run when the command is rewritten to a bwrap invocation).
   const { commandString } = buildSandboxedCommand(command, {
     mounts: [{ type: 'bind', source: agentDir, dest: agentDir }],
     masks: { dirs, files },
     network: 'inherit',
     cwd: agentDir,
+    ...(envOverlay !== undefined ? { env: { set: envOverlay } } : {}),
   })
   mutableArgs.command = commandString
 }

package/src/agent/session-origin.ts

@@ -1,5 +1,6 @@
 import { MEMBERSHIP_FRESHNESS_MS, type MembershipCount } from '@/channels/membership'
 import type { AdapterId } from '@/channels/schema'
+import type { ReactionRef } from '@/channels/types'
 
 export type ChannelParticipant = {
   authorId: string
@@ -38,6 +39,7 @@ export type SessionOrigin =
       chatName?: string
       thread: string | null
       lastInboundAuthorId?: string
+      reactionRef?: ReactionRef
       participants?: readonly ChannelParticipant[]
       membership?: MembershipCount
     }
@@ -301,6 +303,13 @@ function renderChannelOrigin(
       '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.',
+      '',
+      '**Do not post an "On it" acknowledgment comment.** The runtime already',
+      'adds an :eyes: reaction to the triggering item the moment it engages, so a',
+      'separate "looking into this" comment is redundant noise on the PR. If you',
+      'want to signal acknowledgment explicitly, use `channel_react({ emoji })`',
+      '(it reacts, it does not comment) — never a text ack. Reserve `channel_reply`',
+      'for the actual substantive answer.',
     )
   }
 
@@ -339,12 +348,21 @@ function renderChannelOrigin(
     '`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 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.',
+    ...(origin.adapter === 'github'
+      ? [
+          'tool call, keep working and post the answer with a single final',
+          '`channel_reply`. Do not post an "On it" ack comment first — the runtime',
+          'already added an :eyes: reaction on engage; use `channel_react` if you',
+          'want to acknowledge explicitly. The answer is your reply.',
+        ]
+      : [
+          '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,',
@@ -400,15 +418,19 @@ function renderMembershipSummary(
   if (membership === undefined) return null
 
   const total = membership.humans + membership.bots
+  // Exact Discord counts are channel-scoped (filtered by who can VIEW_CHANNEL),
+  // so the count is the channel's room, not the guild. The truncated branch is
+  // history-derived recent speakers, which is not a channel-membership claim,
+  // so the caveat would mislead there.
+  const isExact = !membership.truncated && now - membership.fetchedAt < MEMBERSHIP_FRESHNESS_MS
   const caveat =
-    origin.adapter === 'discord-bot' && origin.workspace !== '@dm'
-      ? ' (Note: this is the count of guild members; private channels with permission overwrites may have fewer actual viewers.)'
+    isExact && origin.adapter === 'discord-bot' && origin.workspace !== '@dm'
+      ? ' (This counts only members who can view this channel, not the whole guild.)'
       : ''
-  const isExact = !membership.truncated && now - membership.fetchedAt < MEMBERSHIP_FRESHNESS_MS
   if (isExact) {
     return `This channel has ${total} members: ${membership.humans} humans, ${membership.bots} bots.${caveat} The 10 most recent speakers are listed below.`
   }
-  return `This channel has approximately ${total} members (about ${membership.humans} humans, ${membership.bots} bots — the bot count is approximate, the full member list was not enumerated because it exceeds the 50-member cap).${caveat} The 10 most recent speakers are listed below.`
+  return `This channel has approximately ${total} members (about ${membership.humans} humans, ${membership.bots} bots — the bot count is approximate, the full member list was not enumerated because it exceeds the 50-member cap). The 10 most recent speakers are listed below.`
 }
 
 function renderMentionGuidance(

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

@@ -0,0 +1,79 @@
+import { Type } from '@mariozechner/pi-ai'
+import { defineTool } from '@mariozechner/pi-coding-agent'
+
+import type { ChannelRouter } from '@/channels/router'
+import type { AdapterId } from '@/channels/schema'
+import type { ReactionRef } from '@/channels/types'
+
+import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
+import { TOOL_RESULT_PREFIX } from './channel-reply'
+
+export type ChannelReactOrigin = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  thread: string | null
+  reactionRef?: ReactionRef
+}
+
+export type CreateChannelReactToolOptions = {
+  router: ChannelRouter
+  origin: ChannelReactOrigin
+  logger?: ChannelToolLogger
+}
+
+export function createChannelReactTool({
+  router,
+  origin,
+  logger = consoleChannelLogger,
+}: CreateChannelReactToolOptions) {
+  return defineTool({
+    name: 'channel_react',
+    label: 'Channel React',
+    description:
+      'Add an emoji reaction to the message that triggered this turn — a lightweight acknowledgment that does not post a comment. ' +
+      'On GitHub this reacts to the triggering issue/PR/comment (e.g. :eyes: to signal "I am looking at this"). ' +
+      'Use this instead of a textual "on it" reply when a reaction is enough. Pass the bare emoji name, no colons.',
+    parameters: Type.Object({
+      emoji: Type.String({
+        description: 'Bare emoji name, no surrounding colons. e.g. "eyes", "+1", "rocket", "heart".',
+        minLength: 1,
+      }),
+    }),
+
+    async execute(_toolCallId, params) {
+      const deny = (error: string) => {
+        logger.warn(formatChannelToolFailure('channel_react', error))
+        const details: { ok: boolean; error?: string } = { ok: false, error }
+        return {
+          content: [{ type: 'text' as const, text: `${TOOL_RESULT_PREFIX}channel_react denied: ${error}` }],
+          details,
+        }
+      }
+
+      if (origin.reactionRef === undefined) return deny('this conversation has no message to react to')
+
+      const result = await router.react({
+        adapter: origin.adapter,
+        workspace: origin.workspace,
+        chat: origin.chat,
+        thread: origin.thread,
+        reactionRef: origin.reactionRef,
+        emoji: params.emoji,
+      })
+
+      if (!result.ok) return deny(`${origin.adapter}:${origin.workspace}/${origin.chat}: ${result.error}`)
+
+      const details: { ok: boolean; error?: string } = { ok: true }
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `${TOOL_RESULT_PREFIX}reacted with :${params.emoji}: on ${origin.adapter}:${origin.workspace}/${origin.chat}`,
+          },
+        ],
+        details,
+      }
+    },
+  })
+}

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

@@ -1,6 +1,7 @@
 import { Type } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
+import { MEMBERSHIP_FRESHNESS_MS, type MembershipCount } from '@/channels/membership'
 import {
   grantRole,
   grantRolePermission,
@@ -48,11 +49,10 @@ function isTierRole(role: string): role is TierRole {
 
 // 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
+// third-party messages buffered in). A group/open channel turn normally 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.
+// Role grants are confined to turns where that surface does not exist.
 function isSinglePrincipalOrigin(origin: SessionOrigin | undefined): boolean {
   if (origin === undefined) return false
   if (origin.kind === 'tui') return true
@@ -60,6 +60,91 @@ function isSinglePrincipalOrigin(origin: SessionOrigin | undefined): boolean {
   return false
 }
 
+// Shared precondition for treating a non-DM channel as injection-equivalent to
+// a 1:1 DM. A DM is safe because it is "principal + the agent's OWN bot, no
+// third-party content". For a group channel we must independently prove the
+// same room shape from a membership read:
+//   - fresh and NOT truncated, so the count is the complete current membership
+//     (`participants` is speaker-only and cannot see silent lurkers — never
+//     used for authorization here);
+//   - `bots === 1`, i.e. the only non-human is the agent itself. The agent's
+//     own bot is always a member of a chat channel and is never an inbound
+//     author (adapters drop self-authored messages), so a complete read with
+//     exactly one bot proves there are NO peer bots whose buffered messages
+//     could prompt-inject the turn. A peer bot would push the count to >= 2
+//     (or, if misclassified as human, trip the human checks) — fail-closed
+//     either way.
+// GitHub is excluded: its membership is the repo COLLABORATOR list, a different
+// population from the authors that can comment into a PR/issue turn (and the
+// agent App is typically not a collaborator), so `bots === 1` is not a valid
+// "no peer bot" proof there. GitHub grants stay confined to the TUI/DM path.
+function provesOnlyAgentBotPresent(
+  origin: Extract<SessionOrigin, { kind: 'channel' }>,
+  now: number,
+): origin is Extract<SessionOrigin, { kind: 'channel' }> & { membership: MembershipCount } {
+  if (origin.adapter === 'github') return false
+  const membership = origin.membership
+  if (membership === undefined) return false
+  if (membership.truncated) return false
+  if (now - membership.fetchedAt >= MEMBERSHIP_FRESHNESS_MS) return false
+  return membership.bots === 1
+}
+
+// A group/open channel that the platform proves contains exactly one human AND
+// no peer bots is injection-equivalent to a 1:1 DM: there is no third-party
+// author (human or bot) whose buffered messages could prompt-inject the turn.
+// The lone human is the caller, and the per-turn caller-role check below still
+// requires them to resolve to owner/trusted.
+function isSingleHumanGroupChannelOrigin(origin: SessionOrigin | undefined, now: number): boolean {
+  if (origin?.kind !== 'channel') return false
+  if (isDmChannelOrigin(origin)) return false
+  if (!provesOnlyAgentBotPresent(origin, now)) return false
+
+  return origin.membership.humans === 1
+}
+
+// Caps the per-member role resolution this check performs so it can never do
+// unbounded work on a large room. resolveRole is in-memory (a match-rule walk,
+// no I/O), so the real cost is small, but a trusted-only operational channel is
+// small by nature and past this many humans we refuse rather than iterate an
+// arbitrarily long list on a tool call. Adapters already stop enumerating past
+// their own cap; this is the guard-local ceiling.
+const MAX_TRUSTED_GROUP_HUMANS = 20
+
+// Generalises the single-human case: a group channel where the platform proves
+// EVERY human member resolves to trusted/owner AND no peer bots are present is
+// also injection-equivalent to a DM, because no untrusted author (human or bot)
+// can buffer a message into the turn. The human proof requires an authoritative,
+// complete identity enumeration — only a fresh, non-truncated membership read
+// that carries `humanMemberIds` (the adapter listed and classified every member
+// in one pass). `humanMemberIds` length must equal `humans` so an unaccounted
+// member cannot slip past; the resolvers construct it that way and we re-check
+// defensively. The no-peer-bot proof is shared with the single-human branch via
+// provesOnlyAgentBotPresent (also enforces fresh/non-truncated and excludes
+// GitHub). The room must be at most MAX_TRUSTED_GROUP_HUMANS humans. Each id is
+// resolved through the same per-author path the turn anchor uses.
+function isAllHumansTrustedGroupChannelOrigin(
+  origin: SessionOrigin | undefined,
+  permissions: PermissionService,
+  now: number,
+): boolean {
+  if (origin?.kind !== 'channel') return false
+  if (isDmChannelOrigin(origin)) return false
+  if (!provesOnlyAgentBotPresent(origin, now)) return false
+
+  const membership = origin.membership
+  const humanMemberIds = membership.humanMemberIds
+  if (humanMemberIds === undefined) return false
+  if (humanMemberIds.length !== membership.humans) return false
+  if (humanMemberIds.length === 0) return false
+  if (humanMemberIds.length > MAX_TRUSTED_GROUP_HUMANS) return false
+
+  return humanMemberIds.every((authorId) => {
+    const role = permissions.resolveRole({ ...origin, lastInboundAuthorId: authorId })
+    return role === 'owner' || role === 'trusted'
+  })
+}
+
 export function createGrantRoleTool(options: CreateGrantRoleToolOptions) {
   const { agentDir, getOrigin, permissions, reloadRoles } = options
 
@@ -70,7 +155,9 @@ export function createGrantRoleTool(options: CreateGrantRoleToolOptions) {
       '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. ' +
+      'Only callable by an owner or trusted user from the TUI, a 1:1 DM, or a group channel with no peer bots whose ' +
+      'human members are all trusted (or which has a single human member) — channels that admit untrusted humans or ' +
+      'other bots 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(
@@ -98,10 +185,17 @@ export function createGrantRoleTool(options: CreateGrantRoleToolOptions) {
     async execute(_toolCallId, params): Promise<ToolReturn> {
       const origin = getOrigin()
 
-      if (!isSinglePrincipalOrigin(origin)) {
+      const now = Date.now()
+      if (
+        !isSinglePrincipalOrigin(origin) &&
+        !isSingleHumanGroupChannelOrigin(origin, now) &&
+        !isAllHumansTrustedGroupChannelOrigin(origin, permissions, now)
+      ) {
         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).',
+          'grant_role is only available from the TUI, a 1:1 DM, or a group channel that has no peer bots and whose ' +
+            'human members are all trusted (or which currently has a single human member). A channel that admits any ' +
+            'untrusted human or another bot cannot change roles, because it mixes in other participants\u2019 messages ' +
+            '(prompt-injection surface).',
         )
       }
 

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

@@ -129,6 +129,7 @@ export function createSpawnSubagentTool(options: CreateSpawnSubagentToolOptions)
         sessionId: resolvedHandle.sessionId ?? '<pending>',
         subagentName,
         parentSessionId,
+        ...(spawnedByRole !== undefined ? { spawnedByRole } : {}),
         startedAt,
         status: 'running' as const,
         abort: resolvedHandle.abort,

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

@@ -0,0 +1,67 @@
+import type { PermissionService } from '@/permissions'
+
+import type { LiveSubagent, LiveSubagentRegistry } from '../live-subagents'
+import type { SessionOrigin } from '../session-origin'
+
+export type SubagentAccessPermission = 'subagent.output' | 'subagent.cancel'
+
+export type SubagentAccessResult = { ok: true; live: LiveSubagent } | { ok: false; message: string }
+
+export type AuthorizeLiveSubagentAccessArgs = {
+  permissions: PermissionService | undefined
+  origin: SessionOrigin | undefined
+  liveRegistry: LiveSubagentRegistry
+  taskId: string
+  permission: SubagentAccessPermission
+}
+
+// Authorizes a single subagent_output/subagent_cancel call and resolves the
+// live entry in one place so the two tools cannot drift. Caps access to the
+// requester's role: the caller must hold the permission AND resolve to a role
+// at least as high as the role that spawned the subagent.
+//
+// The ordering closes an existence oracle: the task-independent base-permission
+// check runs BEFORE any registry lookup, and for non-owner callers an absent
+// task, a capped task, and a task with missing provenance all collapse to one
+// identical denial — so a lower-role caller cannot probe which task IDs are
+// live. Only `owner` (the trust root, which outranks every spawner) learns the
+// truthful `Unknown task_id` for a genuine miss. The cap fails closed.
+export function authorizeLiveSubagentAccess(args: AuthorizeLiveSubagentAccessArgs): SubagentAccessResult {
+  const { permissions, origin, liveRegistry, taskId, permission } = args
+
+  if (permissions === undefined) {
+    const live = liveRegistry.get(taskId)
+    if (live === undefined) {
+      return { ok: false, message: `Unknown task_id: ${taskId}.` }
+    }
+    return { ok: true, live }
+  }
+
+  if (!permissions.has(origin, permission)) {
+    return { ok: false, message: `${permission} denied: insufficient permissions` }
+  }
+
+  const requesterRole = permissions.resolveRole(origin)
+  const accessAll = requesterRole === 'owner'
+  const opaqueDenial = `${permission} denied: unknown task_id or insufficient role`
+
+  const live = liveRegistry.get(taskId)
+  if (live === undefined) {
+    return { ok: false, message: accessAll ? `Unknown task_id: ${taskId}.` : opaqueDenial }
+  }
+  if (accessAll) {
+    return { ok: true, live }
+  }
+
+  const spawnedByRole = live.spawnedByRole
+  if (spawnedByRole === undefined) {
+    return { ok: false, message: opaqueDenial }
+  }
+
+  const cmp = permissions.compareRoleSeverity(requesterRole, spawnedByRole)
+  if (cmp === undefined || cmp < 0) {
+    return { ok: false, message: opaqueDenial }
+  }
+
+  return { ok: true, live }
+}