typeclaw 0.21.0 → 0.22.0

package/src/channels/adapters/github/inbound.ts

@@ -19,6 +19,10 @@ export type GithubWebhookHandlerOptions = {
   // Defaults to 'pat' when omitted. In 'app' mode classifyReviewRequest also
   // matches the App's decoy reviewer login; see resolveDecoyReviewerLogin.
   authType?: () => 'pat' | 'app'
+  // Defaults to true when omitted. When it returns false, every inbound carries
+  // an appended operator-policy note telling the agent not to submit an APPROVE
+  // review; the github skill keys off that note to downgrade approve→COMMENT.
+  allowApprove?: () => boolean
   route: (message: InboundMessage) => void
   logger: GithubInboundLogger
   // Optional: resolves whether the bot is a member of the given team. When
@@ -75,11 +79,29 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
     if (classified === null) return ok()
 
     if (delivery !== '') options.dedup.add(delivery)
-    options.route(classified)
+    options.route(withApprovalPolicy(classified, options.allowApprove?.() ?? true))
     return ok()
   }
 }
 
+export const PR_APPROVAL_DISABLED_NOTE =
+  'Operator policy: PR approval is disabled for this agent ' +
+  '(`channels.github.review.approve: false`). If you review a PR and the ' +
+  'verdict is `approve`, submit a `COMMENT` review instead of `APPROVE` — post ' +
+  'the findings, but never formally approve.'
+
+// Gating PR approval lives here (inbound text), not at the bash layer: the
+// review is posted via `gh api --input <file>`, so the `event: APPROVE` value
+// sits in a temp file the gh-cli-auth command interceptor never inspects. The
+// note rides on every inbound (cheap: one line, only when an operator has
+// opted out) so it reaches the agent for both webhook review requests and
+// plain-language "@bot review this" asks, which arrive on arbitrary inbounds.
+function withApprovalPolicy(message: InboundMessage, allowApprove: boolean): InboundMessage {
+  if (allowApprove) return message
+  const text = message.text === '' ? PR_APPROVAL_DISABLED_NOTE : `${message.text}\n\n${PR_APPROVAL_DISABLED_NOTE}`
+  return { ...message, text }
+}
+
 // GitHub auto-records the App as a reviewer the moment its review posts, but
 // leaves the decoy user pinned as a perpetual "review requested". When the bot
 // drops its own review (the self-authored event we're about to discard), fire a

package/src/channels/adapters/github/index.ts

@@ -149,6 +149,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     selfId: () => selfId,
     selfLogin: () => selfLogin,
     authType: () => options.secrets.auth.type,
+    allowApprove: () => options.configRef().review.approve,
     isBotInTeam,
     authToken,
     fetchImpl,

package/src/channels/adapters/slack-bot.ts

@@ -6,6 +6,8 @@ import {
 } from 'agent-messenger/slackbot'
 
 import {
+  MEMBERSHIP_CACHE_TRANSIENT_TTL_MS,
+  MEMBERSHIP_CACHE_TTL_MS,
   MEMBERSHIP_ENUMERATION_CAP,
   type MembershipResolver,
   type MembershipResolverFailure,
@@ -58,7 +60,7 @@ import { slackTsToMillis } from './slack-bot-time'
 // slash_commands events we route vs drop. The ui.test.ts manifest-drift
 // test asserts equality between this set and SLACK_APP_MANIFEST.features.
 // slash_commands so the two can never silently diverge.
-export const SLACK_SLASH_COMMAND_NAMES: ReadonlySet<string> = new Set(['help', 'stop'])
+export const SLACK_SLASH_COMMAND_NAMES: ReadonlySet<string> = new Set(['help', 'stop', 'reload', 'restart'])
 
 // Resolvers fall back to the raw id on failure, so a name equal to the id
 // means resolution failed; we render the bare id rather than `id(id)`. The
@@ -404,6 +406,16 @@ type SlackUserInfoResponse = {
   user?: { is_bot?: boolean; deleted?: boolean }
 }
 
+type SlackUsersListResponse = {
+  ok: boolean
+  error?: string
+  members?: Array<{ id?: string; is_bot?: boolean }>
+  response_metadata?: { next_cursor?: string }
+}
+
+const USERS_LIST_PAGE_LIMIT = 200
+const USERS_LIST_MAX_PAGES = 50
+
 export function createSlackMembershipResolver(deps: {
   token: string
   logger: SlackBotAdapterLogger
@@ -414,6 +426,43 @@ export function createSlackMembershipResolver(deps: {
   const fetchFn = deps.fetchImpl ?? fetch
   const now = deps.now ?? Date.now
   const userBotCache = new Map<string, boolean>()
+
+  // Keyed by workspace. One resolver instance is bound to a single token/team
+  // today, but the router dispatches by adapter (not by adapter+workspace), so
+  // scoping the warm set by `key.workspace` keeps a set built for one workspace
+  // from ever classifying another's members if a multi-workspace mode is added.
+  const botSetCache = new Map<string, { ids: ReadonlySet<string>; fetchedAt: number }>()
+  const botSetFailedAt = new Map<string, number>()
+  const botSetInFlight = new Map<string, Promise<ReadonlySet<string> | null>>()
+
+  const warmBotSet = async (workspace: string): Promise<ReadonlySet<string> | null> => {
+    const cached = botSetCache.get(workspace)
+    if (cached !== undefined && now() - cached.fetchedAt < MEMBERSHIP_CACHE_TTL_MS) return cached.ids
+    // Negative-cache a failed warm so a rate-limited workspace doesn't re-run
+    // the full paginated `users.list` crawl on every membership read — that
+    // would keep the hot path expensive under the exact failure this PR fixes.
+    // Members fall back to per-id `users.info` during the cooldown.
+    const failedAt = botSetFailedAt.get(workspace)
+    if (failedAt !== undefined && now() - failedAt < MEMBERSHIP_CACHE_TRANSIENT_TTL_MS) return null
+    const inFlight = botSetInFlight.get(workspace)
+    if (inFlight !== undefined) return await inFlight
+    const promise = fetchWorkspaceBotIds(fetchFn, deps.token, deps.logger)
+      .then((ids) => {
+        if (ids !== null) {
+          botSetCache.set(workspace, { ids, fetchedAt: now() })
+          botSetFailedAt.delete(workspace)
+        } else {
+          botSetFailedAt.set(workspace, now())
+        }
+        return ids
+      })
+      .finally(() => {
+        botSetInFlight.delete(workspace)
+      })
+    botSetInFlight.set(workspace, promise)
+    return await promise
+  }
+
   return async (key): Promise<MembershipResolverResult> => {
     if (key.workspace === '@dm') return { humans: 1, bots: 1, fetchedAt: now(), truncated: false }
 
@@ -466,11 +515,22 @@ export function createSlackMembershipResolver(deps: {
       return members.failure
     }
 
+    // Reached only for channels at or under the cap (larger ones returned
+    // `truncated` above). `conversations.members` gives ids with no bot/human
+    // flag and Slack has no bulk-classify-ids call, so per-member `users.info`
+    // is an N+1 that exceeds the router cold-fetch timeout near the cap; the
+    // read then returns null and engagement misreads the busy channel as solo.
+    // Classify against a workspace bot-id set from one paginated `users.list`
+    // (bots are a small set, shared across channels). `users.info` stays as a
+    // per-id fallback for ids minted after the last warm, keeping `bots` and
+    // `humanMemberIds` exact for `grant_role`'s "no peer bot present" proof.
+    const memberIds = members.value.members ?? []
+    const botSet = await warmBotSet(key.workspace)
     let bots = 0
     const humanMemberIds: string[] = []
-    for (const userId of members.value.members ?? []) {
-      const cached = userBotCache.get(userId)
-      const isBot = cached ?? (await resolveSlackUserIsBot(fetchFn, deps.token, userId, deps.logger, userBotCache))
+    for (const userId of memberIds) {
+      const isBot =
+        botSet?.has(userId) ?? (await resolveSlackUserIsBot(fetchFn, deps.token, userId, deps.logger, userBotCache))
       if (isBot) bots++
       else humanMemberIds.push(userId)
     }
@@ -512,10 +572,17 @@ async function resolveSlackUserIsBot(
   logger: SlackBotAdapterLogger,
   cache: Map<string, boolean>,
 ): Promise<boolean> {
+  const cached = cache.get(userId)
+  if (cached !== undefined) return cached
   const info = await slackApi<SlackUserInfoResponse>(fetchFn, token, 'users.info', { user: userId })
   if (!info.ok) {
     logger.warn(`[slack-bot] membership users.info user=${userId} failed: ${info.reason}`)
-    cache.set(userId, false)
+    // Only a definitive answer is cached. A transient failure (429/network)
+    // must not be memoized as "human" — that would poison classification until
+    // restart and let a peer bot read as human, skewing engagement and
+    // `grant_role`'s "no peer bot" proof. Default this read to human (the
+    // safe, count-conservative direction) but let the next read retry.
+    if (info.failure.kind === 'permanent') cache.set(userId, false)
     return false
   }
   const isBot = info.value.user?.is_bot === true
@@ -523,6 +590,38 @@ async function resolveSlackUserIsBot(
   return isBot
 }
 
+// Enumerates the workspace and returns the set of bot user ids. Slack has no
+// server-side `is_bot` filter, so we page the full `users.list` and keep only
+// bots — a complete pass is required so silent lurking bots (never seen in
+// history) are still counted, which `grant_role`'s "no peer bot" proof relies
+// on. Returns null on any failure so the caller can fall back to per-id
+// `users.info` rather than trusting an incomplete set. Page count is bounded so
+// a pathologically large workspace cannot stall the read indefinitely.
+async function fetchWorkspaceBotIds(
+  fetchFn: typeof fetch,
+  token: string,
+  logger: SlackBotAdapterLogger,
+): Promise<ReadonlySet<string> | null> {
+  const botIds = new Set<string>()
+  let cursor: string | undefined
+  for (let page = 0; page < USERS_LIST_MAX_PAGES; page++) {
+    const fields: Record<string, string> = { limit: String(USERS_LIST_PAGE_LIMIT) }
+    if (cursor !== undefined && cursor !== '') fields.cursor = cursor
+    const res = await slackApi<SlackUsersListResponse>(fetchFn, token, 'users.list', fields)
+    if (!res.ok) {
+      logger.warn(`[slack-bot] users.list failed: ${res.reason}; falling back to per-member classification`)
+      return null
+    }
+    for (const member of res.value.members ?? []) {
+      if (member.is_bot === true && typeof member.id === 'string') botIds.add(member.id)
+    }
+    cursor = res.value.response_metadata?.next_cursor
+    if (cursor === undefined || cursor === '') return botIds
+  }
+  logger.warn(`[slack-bot] users.list exceeded ${USERS_LIST_MAX_PAGES} pages; bot set may be incomplete`)
+  return null
+}
+
 function slackFailureForError(error: string): MembershipResolverFailure {
   if (['invalid_auth', 'not_authed', 'not_in_channel', 'channel_not_found', 'missing_scope'].includes(error)) {
     return { kind: 'permanent' }

package/src/channels/manager.ts

@@ -89,6 +89,12 @@ export type ChannelManagerOptions = {
   // per-repo App token minter here on start (App auth only) so plugin hooks
   // can resolve a token for ad-hoc `gh` commands. Tests omit it.
   githubTokenBridge?: GithubTokenBridge
+  // Forwarded to the router as the /reload and /restart command handlers.
+  // Production wiring (src/run/index.ts) supplies the reload-registry and
+  // container-restart bindings; tests omit them so the commands stay
+  // unregistered. See CreateChannelRouterOptions.onReload/onRestart.
+  onReload?: () => Promise<string>
+  onRestart?: () => Promise<string>
 }
 
 export type ChannelManager = {
@@ -125,6 +131,8 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
     ...(options.permissions ? { permissions: options.permissions } : {}),
     ...(options.claimHandler ? { claimHandler: options.claimHandler } : {}),
     ...(options.stream ? { stream: options.stream } : {}),
+    ...(options.onReload ? { onReload: options.onReload } : {}),
+    ...(options.onRestart ? { onRestart: options.onRestart } : {}),
   })
   const createDiscordAdapter = options.createDiscordAdapter ?? createDiscordBotAdapter
   const createGithub = options.createGithubAdapter ?? createGithubAdapter

package/src/channels/router.ts

@@ -7,7 +7,7 @@ import { createSession, renderTurnRoleAnchor, renderTurnTimeAnchor, type AgentSe
 import { subscribeProviderErrors } from '@/agent/provider-error'
 import type { ChannelParticipant, SessionOrigin } from '@/agent/session-origin'
 import { renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
-import { type Command, type CommandResult, createCommandRegistry } from '@/commands'
+import { type Command, type CommandPermission, type CommandResult, createCommandRegistry } from '@/commands'
 import { CORE_PERMISSIONS, type PermissionService } from '@/permissions'
 import type { HookBus } from '@/plugin'
 import { extractClaimCode } from '@/role-claim'
@@ -720,6 +720,17 @@ export type CreateChannelRouterOptions = {
   // can diagnose silent drops from `typeclaw inspect` alone. Omitted in
   // tests that don't care about inspect surfacing.
   stream?: Stream
+  // Operate-the-agent command handlers. When set, the router registers the
+  // matching channel command (/reload, /restart) gated on session.admin
+  // (owner+trusted). Omitted means the command is not registered at all — it
+  // won't appear in /help and a text-prefix or native-slash invocation is
+  // treated as unknown. Production wiring (src/run/index.ts via the channel
+  // manager) supplies both; tests opt in per-case. `onReload` returns a short
+  // human-readable summary posted back to the channel; `onRestart` returns a
+  // confirmation string (the container exits shortly after, so the reply is
+  // best-effort).
+  onReload?: () => Promise<string>
+  onRestart?: () => Promise<string>
 }
 
 export type ClaimHandlerInput = {
@@ -756,6 +767,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const permissions = options.permissions ?? GRANT_ALL_PERMISSIONS
   const claimHandler = options.claimHandler
   const stream = options.stream
+  const onReload = options.onReload
+  const onRestart = options.onRestart
   const liveSessions = new Map<string, LiveSession>()
   const creating = new Map<string, Promise<LiveSession>>()
   // Bumped by tearDownAllLive() and stop() before they tear sessions down. An
@@ -779,7 +792,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   // The /help handler reads the live registry to enumerate commands, so it
   // forward-references `commands`. Safe at runtime — the handler only runs on
   // invocation, long after the assignment below completes.
-  const channelCommands: readonly Command<ChannelCommandContext>[] = [
+  const channelCommands: Command<ChannelCommandContext>[] = [
     {
       name: 'help',
       description: 'List available commands.',
@@ -800,6 +813,28 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       },
     },
   ]
+  // /reload and /restart are registered only when the operate-the-agent
+  // callbacks are wired (production via the channel manager). Without them the
+  // capability doesn't exist for this router, so the commands stay absent from
+  // /help and resolve as unknown — never a silent no-op.
+  if (onReload !== undefined) {
+    channelCommands.push({
+      name: 'reload',
+      description: 'Reload typeclaw config and subsystems from disk.',
+      permission: 'session.admin',
+      requiresLiveSession: false,
+      handler: async () => ({ reply: await onReload() }),
+    })
+  }
+  if (onRestart !== undefined) {
+    channelCommands.push({
+      name: 'restart',
+      description: 'Restart the typeclaw container.',
+      permission: 'session.admin',
+      requiresLiveSession: false,
+      handler: async () => ({ reply: await onRestart() }),
+    })
+  }
   const commands = createCommandRegistry<ChannelCommandContext>(channelCommands)
 
   // Implicit dir-name alias: agent folder basename matches Docker
@@ -1800,9 +1835,10 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         logger.info(`[channels] ${keyId}: ignoring unknown command /${parsedCommand.name}`)
         return
       }
-      if (commandInfo.permission === 'session.control' && isSessionControlDenied(event)) {
+      const requiredPermission = commandPermissionString(commandInfo.permission)
+      if (requiredPermission !== null && !permissions.has(inboundAuthorOrigin(event), requiredPermission)) {
         logger.info(
-          `[channels] ${keyId}: denied command /${parsedCommand.name} by permissions (session.control) author=${event.authorId}`,
+          `[channels] ${keyId}: denied command /${parsedCommand.name} by permissions (${requiredPermission}) author=${event.authorId}`,
         )
         return
       }
@@ -1913,8 +1949,22 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   // 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)
+  // Maps a command's declared permission tier to the concrete permission
+  // string gated on both the text-prefix path (route) and the native-slash
+  // path (executeCommand). 'none' is never gated. session.admin (owner+trusted,
+  // not member) covers /reload and /restart, which mutate global agent state
+  // and drop every in-flight session. Centralized so a new tier can't be
+  // honored on one path and silently skipped on the other.
+  const commandPermissionString = (permission: CommandPermission): string | null => {
+    switch (permission) {
+      case 'none':
+        return null
+      case 'session.control':
+        return CORE_PERMISSIONS.sessionControl
+      case 'session.admin':
+        return CORE_PERMISSIONS.sessionAdmin
+    }
+  }
 
   const updateLoopGuard = (live: LiveSession, event: InboundMessage): void => {
     if (!event.authorIsBot) {
@@ -2702,14 +2752,17 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     if (commandInfo === undefined) {
       return { kind: 'unknown-command', name: lowered }
     }
-    // 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. Session-less
-    // informational commands (e.g. /help) declare permission:'none' and skip
-    // both the gate and the lookup so they work in channels with no live turn.
-    if (commandInfo.permission === 'session.control') {
+    // Gates on the command's declared tier (session.control for /stop,
+    // session.admin for /reload and /restart) — never channel.respond — so a
+    // respond-capable guest cannot abort another speaker's turn or bounce the
+    // container. 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. Session-less informational commands (e.g. /help) declare
+    // permission:'none' and skip both the gate and the lookup so they work in
+    // channels with no live turn.
+    const requiredPermission = commandPermissionString(commandInfo.permission)
+    if (requiredPermission !== null) {
       const partial: SessionOrigin = {
         kind: 'channel',
         adapter: key.adapter,
@@ -2718,7 +2771,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         thread: key.thread,
         lastInboundAuthorId: options.invokerId,
       }
-      if (!permissions.has(partial, CORE_PERMISSIONS.sessionControl)) {
+      if (!permissions.has(partial, requiredPermission)) {
         return { kind: 'permission-denied' }
       }
     }

package/src/channels/schema.ts

@@ -131,6 +131,23 @@ export const DEFAULT_GITHUB_EVENT_ALLOWLIST = [
   'pull_request_review.submitted',
 ] as const
 
+// PR-review policy knobs. Grouped under `review` so future toggles
+// (`requestChanges`, auto-review-on-request, severity thresholds) cluster
+// here instead of flattening onto the channel root.
+//
+// `approve` gates whether the agent may submit a formal review with
+// `event: APPROVE`. When `false`, the adapter appends an operator-policy note
+// to inbounds and the `typeclaw-channel-github` skill downgrades an `approve`
+// verdict to a `COMMENT` review (findings still posted, no formal approval).
+// Enforced in the inbound text rather than at the bash layer because the
+// review posts via `gh api --input <file>`, so the `event` value lives in a
+// temp file the command interceptor never sees.
+const githubReviewSchema = z
+  .object({
+    approve: z.boolean().default(true),
+  })
+  .default({ approve: true })
+
 const githubChannelSchema = adapterSchema.extend({
   // Optional now (PR 2): when omitted and a `tunnels[]` entry with
   // `for: { kind: 'channel', name: 'github' }` exists, the runtime resolves
@@ -146,6 +163,7 @@ const githubChannelSchema = adapterSchema.extend({
   // this session is deleted so a restart with a different webhookUrl (e.g.
   // a tunnel reassigning a URL) doesn't leave orphaned hooks on GitHub.
   repos: z.array(z.string()).default([]),
+  review: githubReviewSchema,
 })
 
 // KakaoTalk uses the same shape as every other adapter. There used to be an

package/src/cli/dreams.ts

@@ -4,7 +4,7 @@ import { type DreamEntry, renderListRow, runDreams, type ViewAction } from '@/dr
 import { findAgentDir } from '@/init'
 
 import { createEscController } from './inspect-controller'
-import { c, cancel, errorLine, isCancel } from './ui'
+import { c, cancel, errorLine, isCancel, prepareStdinForClack } from './ui'
 
 const ESC_DEBOUNCE_MS = 50
 const QUIT_KEY = 0x71
@@ -123,6 +123,7 @@ async function clackSelect(
   initialSha: string | undefined,
 ): Promise<DreamEntry | null> {
   const { select } = await import('@clack/prompts')
+  prepareStdinForClack()
   const preferred = initialSha !== undefined && entries.some((e) => e.sha === initialSha) ? initialSha : entries[0]?.sha
   const picked = await select<string>({
     message: `Pick a dream to open (${entries.length} total)`,

package/src/cli/inspect.ts

@@ -6,7 +6,7 @@ import { runInspectLoop, streamLive, type LiveSourceFactory, type SessionSummary
 import { originLabel, shortSessionId } from '@/inspect/label'
 
 import { createEscController } from './inspect-controller'
-import { cancel, c, errorLine, isCancel } from './ui'
+import { cancel, c, errorLine, isCancel, prepareStdinForClack } from './ui'
 
 const ESC_LISTEN_DELAY_MS = 50
 
@@ -212,6 +212,7 @@ async function clackSelect(
   initialSessionId: string | undefined,
 ): Promise<SessionSummary | null> {
   const { select } = await import('@clack/prompts')
+  prepareStdinForClack()
   const preferred =
     initialSessionId !== undefined && sessions.some((s) => s.sessionId === initialSessionId)
       ? initialSessionId

package/src/cli/ui.ts

@@ -7,6 +7,28 @@ import { type AutoUpgradeOutcome, describeAutoUpgrade } from '@/init/auto-upgrad
 
 export { cancel, intro, isCancel, log, note, outro }
 
+type ClackInput = Pick<NodeJS.ReadStream, 'isTTY' | 'setRawMode' | 'resume'>
+
+// Hand stdin to a clack picker in a state it can own. Over an SSH pseudo-TTY,
+// Bun's readline keypress wiring only transitions stdin into flowing raw mode
+// reliably once the stream has already been resumed; on a never-resumed stdin
+// the picker renders but arrow keys echo as raw `^[[B` and never advance it.
+// Local terminals dodge this because stdin was already flowing. So before every
+// picker: clear any stale raw mode for a clean baseline, then resume the stream.
+// Never pause() here — a previously-paused process.stdin does not reliably
+// re-flow under Bun, which is the same failure this resume() is fixing.
+export function prepareStdinForClack(input: ClackInput = process.stdin): void {
+  if (!input.isTTY) return
+  if (typeof input.setRawMode === 'function') {
+    try {
+      input.setRawMode(false)
+    } catch {
+      /* terminal already torn down */
+    }
+  }
+  input.resume()
+}
+
 function colorize(modifier: Parameters<typeof styleText>[0], s: string): string {
   if (!colorsEnabled()) return s
   return styleText(modifier, s)
@@ -169,6 +191,18 @@ export const SLACK_APP_MANIFEST = {
         url: 'https://example.invalid/typeclaw-uses-socket-mode',
         should_escape: false,
       },
+      {
+        command: '/reload',
+        description: 'Reload typeclaw config and subsystems from disk',
+        url: 'https://example.invalid/typeclaw-uses-socket-mode',
+        should_escape: false,
+      },
+      {
+        command: '/restart',
+        description: 'Restart the typeclaw container',
+        url: 'https://example.invalid/typeclaw-uses-socket-mode',
+        should_escape: false,
+      },
     ],
   },
   oauth_config: {

package/src/commands/index.ts

@@ -13,8 +13,11 @@ export type CommandHandler<Context> = (
 // dispatcher, so a new command declares its own requirements in one place:
 // 'session.control' + requiresLiveSession:true is the control-command default
 // (/stop); 'none' + requiresLiveSession:false is the informational default
-// (/help). Both are optional so plain registries (tests, TUI) need not care.
-export type CommandPermission = 'none' | 'session.control'
+// (/help). 'session.admin' + requiresLiveSession:false is the operate-the-agent
+// tier (/reload, /restart) — owner+trusted only, no live session required since
+// it acts on the container, not a channel turn. Both are optional so plain
+// registries (tests, TUI) need not care.
+export type CommandPermission = 'none' | 'session.control' | 'session.admin'
 
 export type Command<Context> = {
   name: string

package/src/config/config.ts

@@ -8,6 +8,7 @@ import { z } from 'zod'
 import { channelsSchema } from '@/channels/schema'
 import { commitSystemFileSync } from '@/git/system-commit'
 import { rolesConfigSchema } from '@/permissions/schema'
+import { secretFieldSchema } from '@/secrets/resolve'
 
 import {
   DEFAULT_MODEL_REF,
@@ -30,6 +31,30 @@ const DEFAULT_PORT = 8973
 // of files like `mounts/.git` or `mounts/Hello`.
 const MOUNT_NAME_PATTERN = /^[a-z0-9][a-z0-9-_]*$/
 
+// Shell-portable env var identifier: a leading letter or underscore followed by
+// letters, digits, or underscores. MCP `env` keys are passed verbatim to a child
+// process environment, so an invalid identifier (spaces, `=`, leading digit)
+// would be silently dropped or corrupt the spawned server's env.
+const ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+// Upper bound for a per-server MCP request timeout: 10 minutes. Long-running
+// MCP tools (large crawls, builds) can legitimately take minutes, but a ceiling
+// guards against fat-finger values that would re-introduce the unbounded-hang
+// failure mode the explicit timeouts exist to prevent.
+const MCP_MAX_TIMEOUT_MS = 600_000
+
+// URL schemes are case-insensitive (RFC 3986), and the WHATWG parser normalizes
+// `.protocol` to lowercase. Checking the parsed protocol instead of a raw
+// `startsWith` keeps `HTTPS://…` valid, which `z.string().url()` already accepts.
+function isHttpProtocol(value: string): boolean {
+  try {
+    const protocol = new URL(value).protocol
+    return protocol === 'http:' || protocol === 'https:'
+  } catch {
+    return false
+  }
+}
+
 export const mountSchema = z.object({
   name: z.string().regex(MOUNT_NAME_PATTERN, 'mount name must be lowercase alphanumeric with - or _'),
   path: z.string().min(1),
@@ -39,6 +64,66 @@ export const mountSchema = z.object({
 
 export type Mount = z.infer<typeof mountSchema>
 
+// MCP servers are keyed by the same shell/disk-safe namespace as mounts because
+// the name becomes the tool namespace exposed to the agent. The transport is an
+// XOR on purpose: stdio servers are child processes (`command` + `args` + env),
+// while Streamable HTTP servers are remote endpoints (`url`); accepting both
+// would make ownership, lifetime, and credential injection ambiguous at boot.
+export const mcpServerSchema = z
+  .object({
+    name: z
+      .string()
+      .regex(MOUNT_NAME_PATTERN, 'MCP server name must be lowercase alphanumeric with - or _')
+      .refine((name) => !name.includes('__'), {
+        message: "MCP server name must not contain '__' (reserved as the tool-namespace separator)",
+      }),
+    description: z.string().optional(),
+    // Default true so omitting the field keeps the server on; set false to keep config but skip connecting.
+    enabled: z.boolean().default(true),
+    timeoutMs: z.number().int().positive().max(MCP_MAX_TIMEOUT_MS).optional(),
+    command: z.string().trim().min(1).optional(),
+    args: z.array(z.string()).default([]),
+    url: z
+      .string()
+      .url()
+      .refine((u) => isHttpProtocol(u), {
+        message: 'MCP server url must use http:// or https://',
+      })
+      .optional(),
+    env: z
+      .record(z.string().regex(ENV_NAME_PATTERN, 'env var name must be a valid identifier'), secretFieldSchema)
+      .default({}),
+  })
+  .refine((server) => (server.command !== undefined) !== (server.url !== undefined), {
+    message: 'MCP server must be either stdio (command) or http (url), not both or neither',
+  })
+
+export type McpServer = z.infer<typeof mcpServerSchema>
+
+// The name becomes the `<server>__<tool>` namespace at dispatch, so duplicates
+// would make tool lookup ambiguous and silently shadow one server behind
+// another. Reject them with an indexed path so the error points at the
+// offending entry instead of the whole array.
+const mcpServersArraySchema = z
+  .array(mcpServerSchema)
+  .default([])
+  .superRefine((entries, ctx) => {
+    const seen = new Map<string, number>()
+    for (let i = 0; i < entries.length; i++) {
+      const name = entries[i]!.name
+      const prev = seen.get(name)
+      if (prev !== undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [i, 'name'],
+          message: `mcpServers[${i}].name duplicates mcpServers[${prev}].name ('${name}')`,
+        })
+      } else {
+        seen.set(name, i)
+      }
+    }
+  })
+
 const portNumber = z.number().int().min(1).max(65535)
 
 // `allow` is the discriminator between "forward everything" ('*') and a fixed
@@ -391,6 +476,7 @@ export const configSchema = z
     // host paths exposed) without failing the whole config load. `typeclaw
     // init` omits this field so users don't see noise for the empty case.
     mounts: z.array(mountSchema).default([]),
+    mcpServers: mcpServersArraySchema,
     plugins: z.array(z.string().min(1)).default([]),
     // Additional names the agent answers to in channel engagement, on top
     // of `basename(agentDir)` which is always implicit. Each entry is a
@@ -538,6 +624,7 @@ export const FIELD_EFFECTS: Record<string, FieldEffect> = {
   models: 'applied',
   port: 'restart-required',
   mounts: 'restart-required',
+  mcpServers: 'restart-required',
   plugins: 'restart-required',
   alias: 'applied',
   channels: 'applied',
@@ -638,6 +725,8 @@ export function extractPluginConfigs(raw: unknown): Record<string, unknown> {
     'git',
     'roles',
     'permissions',
+    'tunnels',
+    'mcpServers',
   ])
   const result: Record<string, unknown> = {}
   for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {