switchroom 0.15.18 → 0.15.20

package/telegram-plugin/gateway/effort-command.ts

@@ -0,0 +1,272 @@
+/**
+ * Telegram `/effort` command — show or switch the Claude reasoning effort
+ * for this agent's live session. The effort sibling of `/model`.
+ *
+ * `/effort` (bare) renders the effort menu: the configured default plus an
+ * inline keyboard of the five levels the CLI offers
+ * (`low · medium · high · xhigh · max`, faster→smarter), the live level
+ * marked ✅. A tap types claude's own `/effort <level>` into the agent's
+ * tmux pane via the allowlisted inject primitive (`/effort` is on the
+ * inject allowlist) — the Claude-native mechanism: the unmodified CLI's
+ * REPL command, no API, no SDK, no config mutation.
+ *
+ * `/effort <level>` does the same non-interactively.
+ *
+ * The switch is session-scoped. It lasts until the agent restarts, because
+ * `start.sh` always relaunches claude with `--effort <thinking_effort>`
+ * (the cascade-resolved default, "low" out of the box) which re-pins the
+ * session effort on boot. Persisting a new default is a `thinking_effort:`
+ * change in switchroom.yaml + restart, which the reply spells out.
+ *
+ * Split parser/handler shape mirrors `model-command.ts` so the logic is
+ * unit-testable without booting the bot.
+ */
+
+import type { InjectResult } from '../../src/agents/inject.js'
+
+/**
+ * The effort levels the installed CLI accepts (`claude --help`:
+ * "--effort <level> … (low, medium, high, xhigh, max)"). Fixed and
+ * ordered faster→smarter. Unlike model ids these don't churn, so they're
+ * listed here rather than discovered live — a new level needs a one-line
+ * edit, surfaced by the regression test.
+ */
+export const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'] as const
+export type EffortLevel = (typeof EFFORT_LEVELS)[number]
+
+/** Strict allowlist gate — the arg is typed verbatim into the agent pane. */
+export function isValidEffortArg(arg: string): boolean {
+  return (EFFORT_LEVELS as readonly string[]).includes(arg.toLowerCase())
+}
+
+export type ParsedEffortCommand =
+  | { kind: 'show' }
+  | { kind: 'set'; level: EffortLevel }
+  | { kind: 'help'; reason?: string }
+
+/**
+ * Parse an `/effort` message. Returns null when the text isn't an /effort
+ * command at all (caller bug — bot.command should pre-filter).
+ */
+export function parseEffortCommand(text: string): ParsedEffortCommand | null {
+  const m = text.match(/^\/effort(?:@[A-Za-z0-9_]+)?(?:\s+([\s\S]*))?$/)
+  if (!m) return null
+  const rest = (m[1] ?? '').trim()
+  if (rest.length === 0) return { kind: 'show' }
+  const parts = rest.split(/\s+/)
+  if (parts.length > 1) {
+    return { kind: 'help', reason: 'effort takes a single level' }
+  }
+  const arg = parts[0]
+  if (arg.toLowerCase() === 'help') return { kind: 'help' }
+  if (!isValidEffortArg(arg)) {
+    return { kind: 'help', reason: `not a valid effort level: ${arg}` }
+  }
+  return { kind: 'set', level: arg.toLowerCase() as EffortLevel }
+}
+
+export interface EffortCommandDeps {
+  /** Inject primitive — wired to injectSlashCommand in the gateway. */
+  inject: (agent: string, command: string) => Promise<InjectResult>
+  getAgentName: () => string
+  /**
+   * The agent's cascade-resolved `thinking_effort` from
+   * `switchroom agent list` (the value start.sh bakes into `--effort`).
+   * Null when unreadable — rendered as the built-in default.
+   */
+  getConfiguredEffort: () => string | null
+  escapeHtml: (s: string) => string
+  preBlock: (s: string) => string
+}
+
+export interface EffortCommandReply {
+  text: string
+  html: true
+}
+
+const PERSIST_NOTE =
+  '<i>Session-only — reverts to the configured default on restart. To change the default, set <code>thinking_effort:</code> in switchroom.yaml and restart.</i>'
+
+const LEVELS_INLINE = EFFORT_LEVELS.map(l => `<code>${l}</code>`).join(' · ')
+
+function helpText(deps: EffortCommandDeps, reason?: string): EffortCommandReply {
+  const lines: string[] = []
+  if (reason) lines.push(`⚠️ ${deps.escapeHtml(reason)}`)
+  lines.push(
+    '<b>/effort</b> — show or switch the reasoning effort (faster→smarter)',
+    '<code>/effort</code> — show the configured effort + a tap menu',
+    `<code>/effort &lt;level&gt;</code> — switch the live session (${LEVELS_INLINE})`,
+    PERSIST_NOTE,
+  )
+  return { text: lines.join('\n'), html: true }
+}
+
+export async function handleEffortCommand(
+  parsed: ParsedEffortCommand,
+  deps: EffortCommandDeps,
+): Promise<EffortCommandReply> {
+  if (parsed.kind === 'help') return helpText(deps, parsed.reason)
+
+  if (parsed.kind === 'show') {
+    const configured = deps.getConfiguredEffort()
+    const shown = configured && configured.length > 0 ? configured : 'low'
+    return {
+      text: [
+        `<b>Effort — ${deps.escapeHtml(deps.getAgentName())}</b>`,
+        `Configured default: <code>${deps.escapeHtml(shown)}</code>`,
+        `Switch the live session: ${EFFORT_LEVELS.map(l => `<code>/effort ${l}</code>`).join(' · ')}`,
+        PERSIST_NOTE,
+      ].join('\n'),
+      html: true,
+    }
+  }
+
+  // kind === 'set' — re-gate at the seam so a caller that skipped the
+  // parser can't type arbitrary keys into the pane.
+  if (!isValidEffortArg(parsed.level)) {
+    return helpText(deps, `not a valid effort level: ${parsed.level}`)
+  }
+  const verbHtml = `<code>/effort ${deps.escapeHtml(parsed.level)}</code>`
+  let result: InjectResult
+  try {
+    result = await deps.inject(deps.getAgentName(), `/effort ${parsed.level}`)
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    return { text: `❌ ${verbHtml} — inject failed: ${deps.escapeHtml(msg)}`, html: true }
+  }
+
+  if (result.outcome === 'ok') {
+    return {
+      text: [
+        `${verbHtml}`,
+        deps.preBlock(result.output),
+        ...(result.truncated ? ['<i>truncated</i>'] : []),
+        PERSIST_NOTE,
+      ].join('\n'),
+      html: true,
+    }
+  }
+  if (result.outcome === 'ok_no_output') {
+    return {
+      text: [
+        `${verbHtml} — sent, but no response captured. The agent may be mid-turn; check <code>/inject /status</code> to confirm the active effort.`,
+        PERSIST_NOTE,
+      ].join('\n'),
+      html: true,
+    }
+  }
+  // outcome === 'failed'
+  if (result.errorCode === 'session_missing') {
+    return {
+      text:
+        '❌ tmux session not found — the agent must be running under the tmux supervisor (the default). Remove <code>experimental.legacy_pty: true</code> if set.',
+      html: true,
+    }
+  }
+  return {
+    text: `❌ ${verbHtml} — ${deps.escapeHtml(result.errorMessage ?? 'inject failed')}`,
+    html: true,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Button menu — five fixed levels, the live one marked ✅. No live discovery
+// (the levels don't churn) and no picker-driving (the inline `/effort <level>`
+// form sets it directly), so this is far simpler than the /model menu.
+// ---------------------------------------------------------------------------
+
+export interface EffortMenuKeyboardButton {
+  text: string
+  callback_data: string
+}
+
+export interface EffortMenuReply {
+  text: string
+  html: true
+  keyboard?: EffortMenuKeyboardButton[][]
+}
+
+export const EFFORT_CALLBACK_PREFIX = 'eff:'
+const EFFORT_CALLBACK_SELECT = 'eff:s:'
+
+export function effortSelectCallbackData(level: string): string {
+  return `${EFFORT_CALLBACK_SELECT}${level}`
+}
+
+function menuKeyboard(highlight: string): EffortMenuKeyboardButton[][] {
+  // Five short labels fit one row (Telegram allows up to 8/row). ✅ marks
+  // the level we believe is live.
+  return [
+    EFFORT_LEVELS.map(l => ({
+      text: l === highlight ? `✅ ${l}` : l,
+      callback_data: effortSelectCallbackData(l),
+    })),
+  ]
+}
+
+/**
+ * Build the `/effort` menu: configured default + a tap row of the five
+ * levels. `highlight` marks the level shown as live (defaults to the
+ * configured value; the callback path passes the just-selected level).
+ */
+export function buildEffortMenu(deps: EffortCommandDeps, highlight?: string): EffortMenuReply {
+  const configured = deps.getConfiguredEffort() || 'low'
+  const live = highlight ?? configured
+  return {
+    text: [
+      `<b>Effort — ${deps.escapeHtml(deps.getAgentName())}</b>`,
+      `Default: <code>${deps.escapeHtml(configured)}</code> · faster → smarter: ${LEVELS_INLINE}`,
+      'Tap to switch the live session:',
+      PERSIST_NOTE,
+    ].join('\n'),
+    html: true,
+    keyboard: menuKeyboard(live),
+  }
+}
+
+export interface EffortCallbackOutcome {
+  reply: EffortMenuReply
+  /** The level applied to the live session, if any (gateway records it). */
+  selectedEffort?: string
+}
+
+/**
+ * Handle an `eff:*` callback tap. `eff:s:<level>` injects claude's
+ * `/effort <level>` and re-renders the menu with a one-line banner and the
+ * new level checked. Never throws — failures render as a banner.
+ */
+export async function handleEffortMenuCallback(
+  data: string,
+  deps: EffortCommandDeps,
+): Promise<EffortCallbackOutcome> {
+  if (!data.startsWith(EFFORT_CALLBACK_SELECT)) {
+    return { reply: buildEffortMenu(deps) }
+  }
+  const level = data.slice(EFFORT_CALLBACK_SELECT.length)
+  if (!isValidEffortArg(level)) {
+    return { reply: buildEffortMenu(deps) }
+  }
+  let banner: string
+  let selected: string | undefined
+  try {
+    const result = await deps.inject(deps.getAgentName(), `/effort ${level}`)
+    if (result.outcome === 'ok' || result.outcome === 'ok_no_output') {
+      banner = `✅ Effort → <code>${deps.escapeHtml(level)}</code> for this session`
+      selected = level
+    } else if (result.errorCode === 'session_missing') {
+      banner = '❌ tmux session not found — is the agent running under the supervisor?'
+    } else {
+      banner = `❌ couldn't set effort: ${deps.escapeHtml(result.errorMessage ?? 'inject failed')}`
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    banner = `❌ inject failed: ${deps.escapeHtml(msg)}`
+  }
+  // Re-render with the just-selected level checked (or the configured
+  // default if the inject failed) and the banner on top.
+  const menu = buildEffortMenu(deps, selected)
+  return {
+    reply: { ...menu, text: `${banner}\n${menu.text}` },
+    selectedEffort: selected,
+  }
+}

package/telegram-plugin/gateway/gateway.ts

@@ -271,6 +271,15 @@ import {
   type ModelMenuReply,
 } from './model-command.js'
 import { discoverModels, selectModel } from '../../src/agents/model-picker.js'
+import {
+  parseEffortCommand,
+  handleEffortCommand,
+  buildEffortMenu,
+  handleEffortMenuCallback,
+  EFFORT_CALLBACK_PREFIX,
+  type EffortCommandDeps,
+  type EffortMenuReply,
+} from './effort-command.js'
 import { type BannerState } from '../slot-banner.js'
 import { refreshBanner } from '../slot-banner-driver.js'
 import { loadConfig as loadSwitchroomConfig, findConfigFile as findSwitchroomConfigFile } from '../../src/config/loader.js'; import { resolveAgentConfig } from '../../src/config/merge.js'
@@ -429,6 +438,7 @@ import {
   lookupScopedGrant,
   sweepScopedGrants,
 } from '../scoped-approval.js'
+import { grantRestartDecision, type GrantRestartDecision } from './grant-restart.js'
 import { synthesizeAllowRuleDiff, extractAddedAllowRule } from '../permission-diff.js'
 import {
   readClaudeJsonOverage,
@@ -13392,6 +13402,54 @@ async function sweepBeforeSelfRestart(): Promise<void> {
   }
 }
 
+/**
+ * Schedule a marker-safe, turn-deferred SELF-restart so a just-persisted
+ * config change ACTUALLY takes effect. claude loads tools / MCP servers /
+ * settings at process start, so a durable "Always allow" write is inert in
+ * the running session until the next restart — the old "restart agent for
+ * full effect" text asked the operator to do this by hand, and most never
+ * did (so the grant didn't stick and the same prompt reappeared). This
+ * completes the flow the operator already approved.
+ *
+ * CALLER-AGENT ONLY (an "Always allow" edits the calling agent's own
+ * `agents.<self>.tools.allow`, a provably single-agent blast radius). The
+ * restart fires when the CURRENT turn completes (via `pendingRestarts`),
+ * never mid-turn — so the operator-approved action finishes first. If no
+ * turn is in flight, it fires immediately after a short drain delay. A
+ * marker is written first so the post-restart greeting lands in the chat
+ * the operator tapped. Kill-switch: `SWITCHROOM_AUTORESTART_ON_GRANT=0`.
+ *
+ * Returns 'disabled' | 'deferred' | 'now'.
+ */
+function scheduleGrantRestart(
+  agentName: string,
+  chatId: string | number | undefined,
+  threadId: number | undefined,
+  reason: string,
+): GrantRestartDecision {
+  const decision = grantRestartDecision({
+    killSwitch: process.env.SWITCHROOM_AUTORESTART_ON_GRANT,
+    selfAgent: process.env.SWITCHROOM_AGENT_NAME,
+    agentName,
+    turnInFlight: turnInFlightForGate(),
+  })
+  if (decision === "disabled") return decision
+  // Marker first → the post-restart greeting lands in the chat the operator
+  // tapped, not the default operator DM.
+  if (chatId != null) {
+    writeRestartMarker({ chat_id: String(chatId), thread_id: threadId ?? null, ack_message_id: null, ts: Date.now() })
+  }
+  stampUserRestartReason(reason)
+  if (decision === "deferred") {
+    pendingRestarts.set(agentName, Date.now()) // fires at turn-complete (marker-safe)
+  } else {
+    // No turn to drain — restart now, after a short delay so this callback's
+    // card edit flushes first.
+    void sweepBeforeSelfRestart().finally(() => triggerSelfRestart(agentName, reason, 1500))
+  }
+  return decision
+}
+
 /**
  * Shape the `switchroom auth ...` CLI stdout into a Telegram-friendly
  * HTML block. Returns the body text AND the OAuth authorize URL (if
@@ -14219,6 +14277,51 @@ bot.command('model', async ctx => {
   await switchroomReply(ctx, reply.text, { html: reply.html })
 })
 
+// `/effort` — show or switch the reasoning effort for the live session.
+// The effort sibling of `/model`: bare form renders a five-button menu
+// (low/medium/high/xhigh/max, the live level ✅), a typed form
+// `/effort <level>` sets it directly. Both ride the allowlisted inject
+// primitive (claude's own `/effort` REPL command), session-scoped — boot
+// re-pins the configured default via start.sh's `--effort`. Implementation
+// in effort-command.ts so it's unit-testable without booting the bot.
+function buildEffortDeps(): EffortCommandDeps {
+  return {
+    inject: injectSlashCommandImpl,
+    getAgentName: getMyAgentName,
+    getConfiguredEffort: () => {
+      type AgentListResp = { agents: Array<{ name: string; thinking_effort?: string | null }> }
+      const data = switchroomExecJson<AgentListResp>(['agent', 'list'])
+      return data?.agents?.find(a => a.name === getMyAgentName())?.thinking_effort ?? null
+    },
+    escapeHtml: escapeHtmlForTg,
+    preBlock,
+  }
+}
+
+function effortMenuReplyMarkup(reply: EffortMenuReply): InlineKeyboard | undefined {
+  if (!reply.keyboard) return undefined
+  const kb = new InlineKeyboard()
+  for (const row of reply.keyboard) {
+    for (const btn of row) kb.text(btn.text, btn.callback_data)
+    kb.row()
+  }
+  return kb
+}
+
+bot.command('effort', async ctx => {
+  if (!isAuthorizedSender(ctx)) return
+  const text = ctx.message?.text ?? ctx.channelPost?.text ?? ''
+  const parsed = parseEffortCommand(text) ?? { kind: 'show' as const }
+  const deps = buildEffortDeps()
+  if (parsed.kind === 'show') {
+    const menu = buildEffortMenu(deps)
+    await switchroomReply(ctx, menu.text, { html: true, reply_markup: effortMenuReplyMarkup(menu) })
+    return
+  }
+  const reply = await handleEffortCommand(parsed, deps)
+  await switchroomReply(ctx, reply.text, { html: reply.html })
+})
+
 bot.command('agentstart', async ctx => {
   if (!isAuthorizedSender(ctx)) return
   const name = ctx.match?.trim() || getMyAgentName()
@@ -18568,6 +18671,55 @@ bot.command('version', async ctx => {
 })
 
 
+// /whoami — the operator's view of THIS agent's sandbox (the same
+// `config whoami` the agent itself can call as an MCP tool, and the host CLI
+// exposes). Read-only, isAuthorizedSender-gated like /version — surfaces
+// tools / MCP / vault key-NAMES (never values) / powers so the operator can
+// see at a glance what this agent is authorized for.
+bot.command('whoami', async ctx => {
+  if (!isAuthorizedSender(ctx)) return
+  try {
+    let raw: string
+    try { raw = switchroomExecCombined(['config', 'whoami'], 10000) }
+    catch (err: unknown) { raw = (err as any).stdout ?? (err as any).message ?? 'whoami failed' }
+    const trimmed = stripAnsi(raw).trim()
+    let card: string
+    try { card = formatWhoamiCard(JSON.parse(trimmed.split('\n').pop() ?? trimmed)) }
+    catch { card = preBlock(formatSwitchroomOutput(trimmed || 'whoami: no output')) }
+    await switchroomReply(ctx, card, { html: true })
+  } catch (err: unknown) {
+    await switchroomReply(ctx, `<b>whoami failed:</b>\n${preBlock(formatSwitchroomOutput((err as any).message ?? 'unknown error'))}`, { html: true })
+  }
+})
+
+/** Compact HTML card from the `config whoami` JSON view. Names/booleans only. */
+function formatWhoamiCard(v: {
+  name?: string; persona?: string | null; model?: string | null; tier?: string;
+  tools?: { allow?: string[]; deny?: string[] }; mcpServers?: string[]; skills?: string[];
+  vault?: { key: string; readable: boolean }[];
+  powers?: { admin?: boolean; root?: boolean; configEdit?: boolean; crossAgentHostVerbs?: boolean };
+  scheduleCount?: number; memoryBackend?: string | null;
+}): string {
+  const esc = escapeHtmlForTg
+  const yn = (b?: boolean) => (b ? '✓' : '✗')
+  const lines: string[] = []
+  lines.push(`👤 <b>${esc(v.name ?? '?')}</b> · ${esc(v.tier ?? 'standard')}`)
+  if (v.persona) lines.push(esc(v.persona))
+  if (v.model) lines.push(`Model: ${esc(v.model)}`)
+  const allow = v.tools?.allow ?? []
+  lines.push(`Tools: ${allow.length ? esc(allow.slice(0, 8).join(', ')) + (allow.length > 8 ? ` …(+${allow.length - 8})` : '') : '—'}`)
+  if ((v.tools?.deny ?? []).length) lines.push(`Denied: ${esc((v.tools!.deny!).join(', '))}`)
+  if ((v.mcpServers ?? []).length) lines.push(`MCP: ${esc(v.mcpServers!.join(', '))}`)
+  if ((v.skills ?? []).length) lines.push(`Skills: ${esc(v.skills!.join(', '))}`)
+  if ((v.vault ?? []).length) {
+    lines.push(`Vault keys (names only): ${v.vault!.map(k => `${esc(k.key)} ${yn(k.readable)}`).join(', ')}`)
+  }
+  const p = v.powers ?? {}
+  lines.push(`Powers: admin ${yn(p.admin)} · root ${yn(p.root)} · config-edit ${yn(p.configEdit)} · cross-agent verbs ${yn(p.crossAgentHostVerbs)}`)
+  lines.push(`Schedule: ${v.scheduleCount ?? 0} cron · Memory: ${esc(v.memoryBackend ?? 'none')}`)
+  return lines.join('\n')
+}
+
 bot.command('commands', async ctx => {
   if (!isAuthorizedSender(ctx)) return
   await switchroomReply(ctx, buildSwitchroomHelpText(getMyAgentName()), { html: true })
@@ -18608,6 +18760,33 @@ bot.on('callback_query:data', async ctx => {
   // a stale index); `mdl:r` re-renders. Strict allowFrom gate like
   // every other mutating callback family — a model switch changes the
   // fleet's quota burn profile.
+  if (data.startsWith(EFFORT_CALLBACK_PREFIX)) {
+    const access = loadAccess()
+    const senderId = String(ctx.from?.id ?? '')
+    if (!access.allowFrom.includes(senderId)) {
+      await ctx.answerCallbackQuery({ text: 'Not authorized.' })
+      return
+    }
+    // No picker-driving (the inline `/effort <level>` form sets it
+    // directly via the inject primitive), so no mid-turn guard is needed
+    // here — just ack and apply.
+    await ctx.answerCallbackQuery({ text: 'Setting effort…' }).catch(() => {})
+    try {
+      const outcome = await handleEffortMenuCallback(data, buildEffortDeps())
+      await ctx
+        .editMessageText(outcome.reply.text, {
+          parse_mode: 'HTML',
+          reply_markup: effortMenuReplyMarkup(outcome.reply) ?? { inline_keyboard: [] },
+        })
+        .catch(() => {})
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: effort-menu callback failed: ${(err as Error)?.message ?? String(err)}\n`,
+      )
+    }
+    return
+  }
+
   if (data.startsWith(MODEL_CALLBACK_PREFIX)) {
     const access = loadAccess()
     const senderId = String(ctx.from?.id ?? '')
@@ -19275,10 +19454,26 @@ bot.on('callback_query:data', async ctx => {
 
     const ok = durable
     const legacyNote = legacy && durable
+    // Make the durable grant LIVE: config_propose_edit's apply already
+    // regenerated the scaffold (settings.json with the new tools.allow), so a
+    // marker-safe, turn-deferred self-restart loads it — no more "restart by
+    // hand" hint that the operator ignores (leaving the grant inert until the
+    // next bounce). Only on the hostd-durable path (scaffold currency assured);
+    // legacy path keeps the manual hint. Self-agent only; kill-switch
+    // SWITCHROOM_AUTORESTART_ON_GRANT=0.
+    const restartScheduled =
+      ok && !legacy &&
+      scheduleGrantRestart(
+        agentName,
+        ctx.chat?.id,
+        (ctx.callbackQuery?.message as { message_thread_id?: number } | undefined)?.message_thread_id,
+        `always-allow: ${grantPhrase}`,
+      ) !== "disabled"
+    const liveSuffix = restartScheduled ? " — applying now (restarting to take effect)" : ""
     const ackText = ok
       ? (legacyNote
           ? `✅ Saved. ${agentName} can now ${grantPhrase} without asking (legacy path).`
-          : `✅ Saved. ${agentName} can now ${grantPhrase} without asking.`)
+          : `✅ Saved. ${agentName} can now ${grantPhrase} without asking.${liveSuffix}`)
       : (editLockHint
           ? `⚠️ Allowed for now — config edits are locked. Enable hostd.config_edit_enabled.`
           : `⚠️ Allowed for now, but "always" did NOT save — it will ask again after restart. Check gateway log.`)
@@ -19295,7 +19490,9 @@ bot.on('callback_query:data', async ctx => {
     const editLabel = ok
       ? (legacyNote
           ? `✅ <b>${escapeHtmlForTg(agentName)} can now ${escapeHtmlForTg(grantPhrase)}</b> without asking (legacy path); restart agent for full effect`
-          : `✅ <b>${escapeHtmlForTg(agentName)} can now ${escapeHtmlForTg(grantPhrase)}</b> without asking; restart agent for full effect`)
+          : restartScheduled
+            ? `✅ <b>${escapeHtmlForTg(agentName)} can now ${escapeHtmlForTg(grantPhrase)}</b> without asking — applying now (restarting to take effect).`
+            : `✅ <b>${escapeHtmlForTg(agentName)} can now ${escapeHtmlForTg(grantPhrase)}</b> without asking; restart agent for full effect`)
       : (editLockHint
           ? `⚠️ <b>Allowed for now — "always" did NOT save.</b> Config edits are locked; enable <code>hostd.config_edit_enabled</code>.`
           : `⚠️ <b>Allowed for now — "always" did NOT save.</b> It will ask again after restart. Check gateway log.`)

package/telegram-plugin/gateway/grant-restart.ts

@@ -0,0 +1,30 @@
+/**
+ * Pure decision for the "make a just-persisted grant LIVE" self-restart
+ * (the side-effecting `scheduleGrantRestart` in gateway.ts wraps this).
+ *
+ * Extracted so the gating — kill-switch, self-agent-only, and
+ * turn-deferred-vs-now — unit-tests without gateway.ts's boot side-effects
+ * (same pattern as scoped-approval.ts / admin-commands/index.ts).
+ *
+ * Contract (reference/access-model.md): the restart only ever follows an
+ * operator-approved, single-agent, additive `tools.allow` edit, and only
+ * ever bounces the CALLER's own agent — never a peer, never fleet-wide.
+ */
+export type GrantRestartDecision = "disabled" | "deferred" | "now";
+
+export function grantRestartDecision(opts: {
+  /** SWITCHROOM_AUTORESTART_ON_GRANT value ("0" disables; default on). */
+  killSwitch: string | undefined;
+  /** The gateway's own agent identity ($SWITCHROOM_AGENT_NAME). */
+  selfAgent: string | undefined;
+  /** The agent whose config was edited (must equal selfAgent — self only). */
+  agentName: string;
+  /** Whether a turn is currently in flight (defer the restart to its end). */
+  turnInFlight: boolean;
+}): GrantRestartDecision {
+  if ((opts.killSwitch ?? "") === "0") return "disabled";
+  // Self-only: an "Always allow" edits agents.<self>.tools.allow. We never
+  // bounce a peer or the fleet from this path.
+  if (!opts.selfAgent || opts.selfAgent !== opts.agentName) return "disabled";
+  return opts.turnInFlight ? "deferred" : "now";
+}