fix: 修复 agent 终端工具审查问题（terminal_list 输出契约、跨会话归属、UTF-8 截断边界等），工具注入改为设置面板开关（默认关闭）

src/agent-pty.ts

@@ -27,17 +27,29 @@ export type AgentTerminalSignal = (typeof ALLOWED_SIGNALS)[number]
 /** Default read page size (lines) when the caller omits `count`. */
 export const DEFAULT_READ_COUNT = 500
 
+/** Smallest pty dimension the registry accepts (mirrors the tool contract). */
+export const TERMINAL_DIM_MIN = 2
+/** Largest pty dimension the registry accepts (mirrors the tool contract). */
+export const TERMINAL_DIM_MAX = 1024
+
+/** Clamp one cols×rows pair into the supported pty range (flooring decimals). */
+export function clampDims(cols: number, rows: number): { cols: number; rows: number } {
+  const clamp = (value: number): number =>
+    Math.min(TERMINAL_DIM_MAX, Math.max(TERMINAL_DIM_MIN, Math.floor(value)))
+  return { cols: clamp(cols), rows: clamp(rows) }
+}
+
 /**
  * Serializable snapshot of one agent terminal — the shape the model sees
  * through `terminal_list` and the sidebar sees through the push endpoint.
  * Carries no pty reference and no transcript (those are reached through
- * dedicated read/attach paths).
+ * dedicated read/attach paths), and no sessionId: ownership is registry
+ * internals, scoped by the caller (list filters by session, the push
+ * endpoint scopes by its query param), never part of the serialized view.
  */
 export interface AgentTerminalSnapshot {
   /** Stable opaque handle the model passes back to other terminal_* tools. */
   uuid: string
-  /** The conversation id this terminal belongs to (scope filter for list). */
-  sessionId: string
   /** Display title the model chose at create time. */
   title: string
   /** The command the model asked to run at create time (verbatim). */
@@ -115,8 +127,6 @@ export interface AgentTerminalReadResult {
   lineBegin: number
   /** 0-based index of the last line in `text` (exclusive). */
   lineEnd: number
-  /** Whether `text` was truncated to fit the read cap. */
-  truncated: boolean
 }
 
 /** Outcome of {@link AgentPtyRegistry.waitFor}. */
@@ -158,7 +168,6 @@ export type AgentTerminalWaitResult =
 export function snapshotOf(handle: AgentTerminalHandle): AgentTerminalSnapshot {
   const out: AgentTerminalSnapshot = {
     uuid: handle.uuid,
-    sessionId: handle.sessionId,
     title: handle.title,
     command: handle.command,
     exited: handle.exited,
@@ -201,10 +210,11 @@ export class AgentPtyRegistry {
     rows = 24,
   ): string {
     const uuid = randomUUID()
+    const dims = clampDims(cols, rows)
     const pty = nodePty.spawn(this.shell, [], {
       name: 'xterm-256color',
-      cols: Math.max(2, Math.floor(cols)),
-      rows: Math.max(2, Math.floor(rows)),
+      cols: dims.cols,
+      rows: dims.rows,
       cwd,
       env: { ...process.env },
     })
@@ -267,6 +277,20 @@ export class AgentPtyRegistry {
     return handle
   }
 
+  /**
+   * Resolve a live handle that belongs to `sessionId`, or throw `not-found`.
+   * The model-facing tools call this before every uuid-keyed operation: a
+   * uuid from another session is indistinguishable from an unknown one, so a
+   * model can never reach (or probe) a terminal it does not own.
+   */
+  assertOwned(uuid: string, sessionId: string): AgentTerminalHandle {
+    const handle = this.expect(uuid)
+    if (handle.sessionId !== sessionId) {
+      throw new SidebarError('not-found', `agent terminal "${uuid}" not found`, 404)
+    }
+    return handle
+  }
+
   /** Resolve a handle's snapshot, or undefined if it does not exist. */
   snapshot(uuid: string): AgentTerminalSnapshot | undefined {
     const handle = this.sessions.get(uuid)
@@ -310,15 +334,19 @@ export class AgentPtyRegistry {
       totalLines,
       lineBegin: start,
       lineEnd: end,
-      truncated: false,
     }
   }
 
-  /** Resize a terminal's pty (clamped to a 2..1024 sane range). */
-  resize(uuid: string, cols: number, rows: number): void {
+  /**
+   * Resize a terminal's pty, clamped to the 2..1024 sane range.
+   * @returns the dimensions actually applied (the caller echoes these, so the
+   * reported value always matches the pty).
+   */
+  resize(uuid: string, cols: number, rows: number): { cols: number; rows: number } {
     const handle = this.expect(uuid)
-    if (handle.exited) return
-    handle.pty.resize(Math.max(2, Math.floor(cols)), Math.max(2, Math.floor(rows)))
+    const dims = clampDims(cols, rows)
+    if (!handle.exited) handle.pty.resize(dims.cols, dims.rows)
+    return dims
   }
 
   /**

src/client/SideCardSection.tsx

@@ -128,6 +128,13 @@ export function SideCardSection({ store }: SideCardSectionProps) {
     void commit({ autoOpenSubagent: next }).then(outcome => applyOutcome(previous, outcome))
   }
 
+  const onToggleTools = (next: boolean): void => {
+    const previous = prefs
+    setPrefs({ ...previous, agentTerminalTools: next })
+    setError(null)
+    void commit({ agentTerminalTools: next }).then(outcome => applyOutcome(previous, outcome))
+  }
+
   const commitWidth = (): void => {
     const parsed = Number(widthDraft)
     if (!Number.isFinite(parsed)) {
@@ -193,6 +200,19 @@ export function SideCardSection({ store }: SideCardSectionProps) {
           onChange={event => { onToggleSubagent(event.currentTarget.checked) }}
         />
       </label>
+      <label className={css.row}>
+        <span className={css.rowText}>
+          <span className={css.title}>{t('settingsToolsTitle')}</span>
+          <span className={css.desc}>{t('settingsToolsDesc')}</span>
+        </span>
+        <input
+          type="checkbox"
+          className={css.toggle}
+          checked={prefs.agentTerminalTools}
+          aria-label={t('settingsToolsTitle')}
+          onChange={event => { onToggleTools(event.currentTarget.checked) }}
+        />
+      </label>
       {error !== null && (
         <div className={css.error} role="alert">
           {error}

src/client/Sidebar.tsx

@@ -15,7 +15,7 @@ import clsx from 'clsx'
 import { IconChevronRightOutline14, IconFullscreenOutline16, IconPanelLeftOutline16, Tooltip } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { Context, SidebarConversation, SidebarSessionList } from '../context-types.ts'
 import {
-  allLeaves, closeTab, leafWithTab, mapLeaf, moveTab, moveTabToEdge, openTab,
+  agentUuidOf, allLeaves, closeTab, isAgentTabId, leafWithTab, mapLeaf, moveTab, moveTabToEdge, openTab,
   reconcileAgentTerminals,
   resizeSplit, setWidth, toggleExpanded, togglePanel,
   TERMINAL_LIMIT, type DropZone, type SidebarState, type SidebarStore, type SidebarTab, type SplitNode,
@@ -36,6 +36,10 @@ import { api } from './api.ts'
 import { openSidebarFile } from './intercept.tsx'
 import css from './sidebar.module.css'
 
+/** How many consecutive reconnect failures stop the agent-terminals push loop
+ * (mirror of the terminal view's own cap; the loop restarts on session switch). */
+const FAILURE_LIMIT = 3
+
 /** Render the content of one tab (dispatched by type). */
 function TabContent(props: {
   tab: SidebarTab
@@ -83,19 +87,21 @@ function TabContent(props: {
   }
 }
 
-/** The + menu options for the current state (terminal cap applied). */
+/** The + menu options for the current state (UI-tab terminal cap applied).
+ * Agent-owned terminals (`agent:` tabs) are the model's, not the user's:
+ * they never count toward the per-session UI cap. */
 function buildNewTabOptions(state: SidebarState): NewTabOption[] {
-  const terminalCount = allLeaves(state.splits)
+  const uiTerminalCount = allLeaves(state.splits)
     .flatMap(leaf => leaf.tabs)
-    .filter(tab => tab.type === 'terminal').length
+    .filter(tab => tab.type === 'terminal' && !isAgentTabId(tab.id)).length
   return [
     { id: 'explorer', label: t('openExplorer'), icon: tabTypeIcon('explorer', 16) },
     { id: 'git', label: t('openGit'), icon: tabTypeIcon('git', 16) },
     { id: 'subagent', label: t('openSubagent'), icon: tabTypeIcon('subagent', 16) },
     {
       id: 'terminal',
-      label: terminalCount >= TERMINAL_LIMIT ? `${t('newTerminal')} (${t('terminalLimit')})` : t('newTerminal'),
-      disabled: terminalCount >= TERMINAL_LIMIT,
+      label: uiTerminalCount >= TERMINAL_LIMIT ? `${t('newTerminal')} (${t('terminalLimit')})` : t('newTerminal'),
+      disabled: uiTerminalCount >= TERMINAL_LIMIT,
       icon: tabTypeIcon('terminal', 16),
     },
   ]
@@ -145,13 +151,16 @@ export function Sidebar(props: { ctx: Context; store: SidebarStore }) {
    * create / close / exit; the sidebar reconciles the list into tabs
    * (id `agent:<uuid>`, title from the agent). A disconnected socket
    * retries with a short backoff so a refresh or transient drop reattaches
-   * the same shell without losing the agent's work.
+   * the same shell without losing the agent's work — capped like the
+   * terminal view's own reconnect loop, so a refused endpoint never spins
+   * forever (the next session switch restarts the loop).
    */
   useEffect(() => {
     if (sessionId === undefined) return
     let socket: WebSocket | null = null
     let retry: number | undefined
     let closed = false
+    let failures = 0
     const connect = (): void => {
       if (closed) return
       const url = new URL('/sidebar/ws/agent-terminals', location.origin)
@@ -169,7 +178,13 @@ export function Sidebar(props: { ctx: Context; store: SidebarStore }) {
         }
       }
       socket.onclose = () => {
-        if (!closed) retry = window.setTimeout(connect, 2000)
+        if (closed) return
+        failures += 1
+        if (failures >= FAILURE_LIMIT) {
+          console.error('[dsh-better-sidebar] agent-terminals connection failed; stopping reconnect loop', sessionId)
+          return
+        }
+        retry = window.setTimeout(connect, 2000)
       }
       socket.onerror = () => { socket?.close() }
     }
@@ -265,8 +280,8 @@ export function Sidebar(props: { ctx: Context; store: SidebarStore }) {
       const tab = leaf?.tabs.find(candidate => candidate.id === tabId)
       store.reduce(s => closeTab(s, paneId, tabId))
       if (tab?.type === 'terminal') {
-        if (tabId.startsWith('agent:')) {
-          const uuid = tabId.slice('agent:'.length)
+        if (isAgentTabId(tabId)) {
+          const uuid = agentUuidOf(tabId)
           void api.agentPtyClose(uuid).catch(() => { /* the host may already have released it */ })
         } else if (sessionId !== undefined) {
           void api.ptyClose({ sessionId, cwd }, tabId).catch(() => { /* the host may already have released it */ })
@@ -350,7 +365,9 @@ export function Sidebar(props: { ctx: Context; store: SidebarStore }) {
         return openTab(s, { id: 'subagent', type: 'subagent', title: t('subagent') })
       }
       if (optionId === 'terminal') {
-        const count = allLeaves(s.splits).flatMap(leaf => leaf.tabs).filter(tab => tab.type === 'terminal').length
+        const count = allLeaves(s.splits)
+          .flatMap(leaf => leaf.tabs)
+          .filter(tab => tab.type === 'terminal' && !isAgentTabId(tab.id)).length
         if (count >= TERMINAL_LIMIT) return s
         const tab: SidebarTab = {
           id: `terminal:${s.nextTerminal}`,

src/client/TerminalView.tsx

@@ -25,26 +25,13 @@ import { FitAddon } from '@xterm/addon-fit'
 import 'xterm/css/xterm.css'
 import { t } from './locales.ts'
 import type { SessionScope } from './api.ts'
-import type { SidebarStore } from './state.ts'
+import { agentUuidOf, isAgentTabId, type SidebarStore } from './state.ts'
 import { isDarkScheme, subscribeColorScheme, tokenValue } from './theme.ts'
 import css from './sidebar.module.css'
 
 /** How many consecutive unreasoned failures before showing the error banner. */
 const FAILURE_LIMIT = 3
 
-/** Prefix marking a tab id as an agent-owned terminal (suffix is the uuid). */
-const AGENT_TAB_PREFIX = 'agent:'
-
-/** Whether a tab id refers to an agent-owned terminal. */
-function isAgentTab(tabId: string): boolean {
-  return tabId.startsWith(AGENT_TAB_PREFIX)
-}
-
-/** Extract the agent terminal uuid from an `agent:<uuid>` tab id. */
-function agentUuidOf(tabId: string): string {
-  return tabId.slice(AGENT_TAB_PREFIX.length)
-}
-
 /**
  * Curated ANSI palettes for the terminal. The surface colors (background,
  * foreground, cursor, selection) ride the theme tokens so the terminal
@@ -126,7 +113,7 @@ export function TerminalView(props: { scope: SessionScope; tabId: string; store:
       // Agent terminals attach by uuid (the host looks them up in the agent
       // pty registry); UI-tab terminals attach by sessionId+tab (the host
       // uses the UI-tab pty manager). Same upgrade endpoint, different query.
-      if (isAgentTab(tabId)) {
+      if (isAgentTabId(tabId)) {
         url.search = new URLSearchParams({ uuid: agentUuidOf(tabId) }).toString()
       } else {
         const params = new URLSearchParams({ sessionId: scope.sessionId, tab: tabId })

src/client/locales.ts

@@ -90,6 +90,8 @@ const zh = {
   zoomHint: 'Alt + 滚轮',
   settingsSubagentTitle: '检测到子代理时自动展开子代理页面',
   settingsSubagentDesc: '当前会话产生新的子代理时，自动展开侧边栏并打开子代理页面；关闭后需手动打开',
+  settingsToolsTitle: '为模型注入终端工具',
+  settingsToolsDesc: '开启后，模型可通过 terminal_create 等 8 个工具创建并操作侧边栏终端（默认关闭）',
   subagent: '子代理',
   openSubagent: '子代理',
   subagentMainAgent: '主代理',
@@ -192,6 +194,8 @@ const en: Record<keyof typeof zh, string> = {
   zoomHint: 'Alt + wheel',
   settingsSubagentTitle: 'Auto-open the Subagent page when a subagent appears',
   settingsSubagentDesc: 'Expand the side card and open the Subagent page when the current conversation spawns a new subagent; turn off to open it manually',
+  settingsToolsTitle: 'Inject terminal tools for the model',
+  settingsToolsDesc: 'When enabled, the model can create and drive sidebar terminals through the 8 terminal_* tools (off by default)',
   subagent: 'Subagents',
   openSubagent: 'Subagents',
   subagentMainAgent: 'Main agent',

src/client/prefs.ts

@@ -41,6 +41,9 @@ export function parsePrefs(value: unknown): SidebarPrefs {
     autoOpenSubagent: typeof record.autoOpenSubagent === 'boolean'
       ? record.autoOpenSubagent
       : SIDEBAR_PREFS_DEFAULTS.autoOpenSubagent,
+    agentTerminalTools: typeof record.agentTerminalTools === 'boolean'
+      ? record.agentTerminalTools
+      : SIDEBAR_PREFS_DEFAULTS.agentTerminalTools,
   }
 }
 

src/client/state.ts

@@ -399,6 +399,21 @@ export function resizeSplit(node: SplitNode, splitId: string, index: number, del
 /** Prefix marking a tab id as an agent-owned terminal (suffix is the uuid). */
 export const AGENT_TAB_PREFIX = 'agent:'
 
+/** Whether a tab id refers to an agent-owned terminal. */
+export function isAgentTabId(tabId: string): boolean {
+  return tabId.startsWith(AGENT_TAB_PREFIX)
+}
+
+/** Extract the agent terminal uuid from an `agent:<uuid>` tab id. */
+export function agentUuidOf(tabId: string): string {
+  return tabId.slice(AGENT_TAB_PREFIX.length)
+}
+
+/** Build the sidebar tab id for one agent terminal uuid. */
+export function agentTabId(uuid: string): string {
+  return `${AGENT_TAB_PREFIX}${uuid}`
+}
+
 /**
  * Reconcile the sidebar's agent-terminal tabs with the host's live list.
  * The host pushes the current list of agent terminals (created by the model
@@ -416,11 +431,11 @@ export function reconcileAgentTerminals(
   agentTerminals: ReadonlyArray<{ uuid: string; title: string }>,
 ): SidebarState {
   const existingTabs = allLeaves(state.splits).flatMap(leaf => leaf.tabs)
-  const existingAgentTabs = existingTabs.filter(tab => tab.id.startsWith(AGENT_TAB_PREFIX))
-  const existingUuids = new Set(existingAgentTabs.map(tab => tab.id.slice(AGENT_TAB_PREFIX.length)))
+  const existingAgentTabs = existingTabs.filter(tab => isAgentTabId(tab.id))
+  const existingUuids = new Set(existingAgentTabs.map(tab => agentUuidOf(tab.id)))
   const serverUuids = new Set(agentTerminals.map(t => t.uuid))
   const toAdd = agentTerminals.filter(t => !existingUuids.has(t.uuid))
-  const toRemove = existingAgentTabs.filter(tab => !serverUuids.has(tab.id.slice(AGENT_TAB_PREFIX.length)))
+  const toRemove = existingAgentTabs.filter(tab => !serverUuids.has(agentUuidOf(tab.id)))
   if (toAdd.length === 0 && toRemove.length === 0) return state
   // Remove tabs whose uuids vanished from the server list (the agent closed
   // them, or the pty exited and was reaped). Reuse closeTab's leaf cleanup.
@@ -436,7 +451,7 @@ export function reconcileAgentTerminals(
   let next: SidebarState = { ...state, splits }
   for (const terminal of toAdd) {
     const tab: SidebarTab = {
-      id: `${AGENT_TAB_PREFIX}${terminal.uuid}`,
+      id: agentTabId(terminal.uuid),
       type: 'terminal',
       title: terminal.title,
     }

src/config.ts

@@ -79,4 +79,5 @@ export const PrefsSchema: z<SidebarPrefs> = z.object({
   openByDefault: z.boolean().default(true),
   defaultWidthPercent: z.number().step(1).min(WIDTH_PERCENT_MIN).max(WIDTH_PERCENT_MAX).default(WIDTH_PERCENT_DEFAULT),
   autoOpenSubagent: z.boolean().default(true),
+  agentTerminalTools: z.boolean().default(false),
 })

src/index.ts

@@ -23,13 +23,14 @@ import {
   SIDEBAR_PREFS_NS,
   type ResolvedSidebarConfig,
   type SidebarConfig,
+  type SidebarPrefs,
 } from './config.ts'
 import { isWithin, parentOf, requireAbsolute, listDirectory, rootLabel } from './fs-tree.ts'
 import { isTrustedApiRequest } from './trust-fence.ts'
 import * as git from './git.ts'
 import { SettingsConflictError, settingsNamespace, type SettingsNamespace } from '@deepseek-ai/dsh-settings'
 import { defaultShell, ensureSpawnHelper, PtyManager } from './pty-manager.ts'
-import { AgentPtyRegistry, type AgentTerminalHandle } from './agent-pty.ts'
+import { AgentPtyRegistry, clampDims, type AgentTerminalHandle } from './agent-pty.ts'
 import { registerTools } from './tools.ts'
 import { readJsonBody, requireString, SidebarError, writeError, writeJson, writeOk } from './wire.ts'
 
@@ -315,9 +316,34 @@ export function apply(ctx: Context, config?: SidebarConfig): void {
   // which call the seam in-process. Deployments without a settings service
   // simply never fill the face and the client falls back to the defaults.
   let settingsFace: SidebarSettingsFace | undefined
+  // The model-facing terminal tools are gated on the side-card setting
+  // `agentTerminalTools` (default off): nothing is injected until the user
+  // turns the feature on, and turning it off mid-session unregisters the
+  // tools and releases the agent terminals they created.
+  let toolsDisposers: (() => void) | null = null
+  const syncToolsGate = (scope: { get(): SidebarPrefs }): void => {
+    if (scope.get().agentTerminalTools) {
+      if (toolsDisposers === null) {
+        toolsDisposers = registerTools(ctx, agentPtyRegistry, (sessionId) => sessionCwdOf(ctx, sessionId))
+      }
+    } else if (toolsDisposers !== null) {
+      toolsDisposers()
+      toolsDisposers = null
+      // The feature is off: release every agent terminal the model created
+      // while it was on (they are only reachable through the tools). The
+      // registry change fires the push, so the sidebar reconciles them away.
+      agentPtyRegistry.disposeAll()
+    }
+  }
   ctx.inject(['settings'], (sctx) => {
     const ns: SettingsNamespace = settingsNamespace(SIDEBAR_PREFS_NS)
-    sctx.settings.register(ns, PrefsSchema)
+    // The structural settings mirror types `schema` as unknown, so the
+    // generic is not inferred here; the real service resolves it from the
+    // schemastery schema (PrefsSchema) — narrow the owner scope explicitly.
+    const scope = sctx.settings.register(ns, PrefsSchema) as {
+      get(): SidebarPrefs
+      watch(callback: (next: SidebarPrefs, prev: SidebarPrefs) => void): () => void
+    }
     const viewOf = (): { value?: unknown; revision?: number } => {
       const descriptor = sctx.settings.describe({ redactSecrets: true }).find(candidate => candidate.ns === ns)
       return descriptor === undefined
@@ -331,15 +357,12 @@ export function apply(ctx: Context, config?: SidebarConfig): void {
         return viewOf()
       },
     }
+    // Register (or unregister) the terminal tools from the current setting,
+    // and keep them in sync with every settings commit.
+    syncToolsGate(scope)
+    scope.watch(() => { syncToolsGate(scope) })
   })
 
-  // ── Model-facing tools (terminal_create / list / send / read / wait_for / resize / signal / close) ─
-  // Registered once at activation; the disposer is attached to the plugin
-  // fiber by the tools registry, so unloading unregisters them. The cwd
-  // resolver threads the live session cwd (authoritative from the session
-  // store, falling back to the process cwd) so the model never passes it.
-  registerTools(ctx, agentPtyRegistry, (sessionId) => sessionCwdOf(ctx, sessionId))
-
   // ── JSON API ────────────────────────────────────────────────────────────
   const api = buildApi(ctx, ptyManager, agentPtyRegistry, resolved, () => settingsFace)
   ctx.effect(() => ctx.httpServer.register({
@@ -467,6 +490,7 @@ export function apply(ctx: Context, config?: SidebarConfig): void {
   }), 'dsh-better-sidebar: agent-terminals push WebSocket')
 
   ctx.effect(() => () => {
+    toolsDisposers?.()
     ptyManager.disposeAll()
     agentPtyRegistry.disposeAll()
     wss.close()
@@ -530,7 +554,7 @@ async function attachTerminal(
         ws.close(1011, `agent terminal "${uuid}" not found`)
         return
       }
-      pumpAgentTerminal(agentPtyRegistry, handle, ws, resolved)
+      pumpAgentTerminal(agentPtyRegistry, handle, ws)
       return
     }
     const sessionId = url.searchParams.get('sessionId')
@@ -577,7 +601,8 @@ async function attachTerminal(
         && control.type === 'resize'
         && typeof control.cols === 'number' && typeof control.rows === 'number'
       ) {
-        handle.pty.resize(Math.max(2, Math.floor(control.cols)), Math.max(2, Math.floor(control.rows)))
+        const dims = clampDims(control.cols, control.rows)
+        handle.pty.resize(dims.cols, dims.rows)
       } else {
         handle.pty.write(text)
       }
@@ -606,7 +631,6 @@ function pumpAgentTerminal(
   registry: AgentPtyRegistry,
   handle: AgentTerminalHandle,
   ws: WebSocket,
-  _resolved: ResolvedSidebarConfig,
 ): void {
   if (handle.transcript !== '') ws.send(handle.transcript)
   const onData = (data: string): void => {
@@ -642,7 +666,8 @@ function pumpAgentTerminal(
       && control.type === 'resize'
       && typeof control.cols === 'number' && typeof control.rows === 'number'
     ) {
-      handle.pty.resize(Math.max(2, Math.floor(control.cols)), Math.max(2, Math.floor(control.rows)))
+      const dims = clampDims(control.cols, control.rows)
+      handle.pty.resize(dims.cols, dims.rows)
     } else if (control === null) {
       // Raw text input (a JSON-looking string the pty would have received
       // verbatim is reachable in theory but is exotic for an agent terminal;

src/prefs-shared.ts

@@ -20,6 +20,13 @@ export interface SidebarPrefs {
    * Subagent page when the current conversation spawns a new subagent.
    */
   autoOpenSubagent: boolean
+  /**
+   * Whether the model-facing agent terminal tools (terminal_create / list /
+   * send / read / wait_for / resize / signal / close) are injected into the
+   * model's toolset. Off by default: the feature stays dormant until the
+   * user explicitly enables it in the side card settings.
+   */
+  agentTerminalTools: boolean
 }
 
 /** Range contract of {@link SidebarPrefs.defaultWidthPercent}. */
@@ -32,6 +39,7 @@ export const SIDEBAR_PREFS_DEFAULTS: SidebarPrefs = {
   openByDefault: true,
   defaultWidthPercent: WIDTH_PERCENT_DEFAULT,
   autoOpenSubagent: true,
+  agentTerminalTools: false,
 }
 
 /** Clamp one width percent into the contract range (shared by schema and client reads). */

src/tools.ts

@@ -27,17 +27,22 @@ import {
 /** Maximum UTF-8 bytes of one `terminal_read` result text. */
 const READ_BYTE_LIMIT = 256 * 1024
 
-/** Bound a string to a byte limit, marking truncation. */
-function boundBytes(text: string, maxBytes: number): { text: string; truncated: boolean } {
-  const bytes = Buffer.byteLength(text, 'utf8')
-  if (bytes <= maxBytes) return { text, truncated: false }
-  // Trim by character count proportional to the overage, then walk back to a
-  // valid UTF-8 boundary (Buffer.subarray with garbage on a trailing multibyte
-  // sequence would decode to U+FFFD).
-  const ratio = maxBytes / bytes
-  const cut = Math.floor(text.length * ratio)
-  const buf = Buffer.from(text, 'utf8').subarray(0, maxBytes)
-  return { text: buf.toString('utf8').slice(0, cut), truncated: true }
+/**
+ * Bound a string to a byte limit, marking truncation. Truncation never
+ * splits a multi-byte UTF-8 sequence: when the byte cap lands inside one,
+ * the walk-back retreats to the sequence's leading byte so the retained
+ * prefix decodes cleanly (a split would decode to U+FFFD).
+ * @internal exported for the unit tests, like {@link snapshotOf}.
+ */
+export function boundBytes(text: string, maxBytes: number): { text: string; truncated: boolean } {
+  const buf = Buffer.from(text, 'utf8')
+  if (buf.byteLength <= maxBytes) return { text, truncated: false }
+  // The byte at `end` is a continuation byte (10xxxxxx) exactly when the
+  // character that started before `end` spills past the cap. Stop at the
+  // first non-continuation byte — the retained prefix is then intact.
+  let end = maxBytes
+  while (end > 0 && ((buf[end] ?? 0) & 0xc0) === 0x80) end -= 1
+  return { text: buf.subarray(0, end).toString('utf8'), truncated: true }
 }
 
 /** Pure text projection helper (the canonical value is already structured). */
@@ -53,27 +58,36 @@ function requireAgent(agent: Agent | undefined): Agent {
   return agent
 }
 
-/** Resolve the calling agent's session id (the registry scope filter). */
-function sessionOf(exec: ToolRunContext): { agent: Agent; sessionId: string } {
-  const agent = requireAgent(exec.agent)
-  return { agent, sessionId: agent.session.id }
+/** Resolve the calling agent's session id (the registry scope + ownership key). */
+function sessionIdOf(exec: ToolRunContext): string {
+  return requireAgent(exec.agent).session.id
 }
 
 /**
- * Register the seven terminal tools against the host tool registry. The
+ * Register the eight terminal tools against the host tool registry. The
  * `resolveCwd` callback threads the live session cwd (authoritative from the
  * session store, falling back to the process cwd) so a freshly-created
  * terminal lands in the right directory without the model passing it.
+ * Every uuid-keyed tool first asserts the terminal belongs to the calling
+ * session (`registry.assertOwned`), so one agent can never reach another
+ * session's terminals.
  * @param ctx - host plugin context (carries the tools service).
  * @param registry - the agent-owned terminal registry.
  * @param resolveCwd - live cwd resolver for one session id.
+ * @returns a disposer that unregisters all eight tools (the caller gates
+ * registration on the side-card setting and calls this to turn them off).
  */
 export function registerTools(
   ctx: Context,
   registry: AgentPtyRegistry,
   resolveCwd: (sessionId: string) => string,
-): void {
-  ctx.tools.register(defineTool({
+): () => void {
+  const disposers: Array<() => void> = []
+  const register = (tool: ReturnType<typeof defineTool>): void => {
+    disposers.push(ctx.tools.register(tool))
+  }
+
+  register(defineTool({
     name: 'terminal_create',
     description:
       'Open a persistent terminal in the sidebar and run a command in it. '
@@ -111,14 +125,14 @@ export function registerTools(
     },
     execute: (args: { title: string; command: string }, exec) => {
       exec.signal.throwIfAborted()
-      const { sessionId } = sessionOf(exec)
+      const sessionId = sessionIdOf(exec)
       const cwd = resolveCwd(sessionId)
       const uuid = registry.create(sessionId, args.title, args.command, cwd, 80, 24)
       return Promise.resolve({ uuid, title: args.title })
     },
   }))
 
-  ctx.tools.register(defineTool({
+  register(defineTool({
     name: 'terminal_list',
     description:
       'List every terminal the current agent has opened in this session. Returns each terminal\'s uuid, title, '
@@ -154,19 +168,19 @@ export function registerTools(
       },
     },
     execute: (_args, exec) => {
-      const { sessionId } = sessionOf(exec)
+      const sessionId = sessionIdOf(exec)
       return Promise.resolve(registry.list(sessionId))
     },
   }))
 
-  ctx.tools.register(defineTool({
+  register(defineTool({
     name: 'terminal_send',
     description:
       'Send raw text (keystrokes) to a terminal opened with terminal_create — tmux send-keys semantics. '
       + 'The text is written verbatim to the pty stdin. '
       + 'To submit a command, set submit=true (appends an Enter key); do NOT put "\\n" or "\\r" in the text yourself. '
       + 'To send Ctrl+C (interrupt the running command), use the terminal_signal tool with signal="SIGINT" — do NOT try to send the control character "\\u0003" as text. '
-      + 'Similarly use terminal_signal for Ctrl+D (EOF), Ctrl+Z (suspend), etc. '
+      + 'Use terminal_signal with signal="SIGTSTP" for Ctrl+Z (suspend) as well. '
       + 'This tool does NOT wait for the command to finish or for output to settle — pair with terminal_read to observe the result. '
       + 'Throws if the terminal has exited.',
     parameters: {
@@ -200,13 +214,15 @@ export function registerTools(
     },
     execute: (args: { uuid: string; text: string; submit?: boolean }, exec) => {
       exec.signal.throwIfAborted()
+      const sessionId = sessionIdOf(exec)
+      registry.assertOwned(args.uuid, sessionId)
       const payload = args.submit === true ? `${args.text}\r` : args.text
       registry.send(args.uuid, payload)
       return Promise.resolve({ uuid: args.uuid, bytes: Buffer.byteLength(payload, 'utf8') })
     },
   }))
 
-  ctx.tools.register(defineTool({
+  register(defineTool({
     name: 'terminal_read',
     description:
       'Read a bounded page of retained output from an agent terminal without sending input. '
@@ -249,6 +265,8 @@ export function registerTools(
     },
     execute: (args: { uuid: string; offset?: number; count?: number }, exec) => {
       exec.signal.throwIfAborted()
+      const sessionId = sessionIdOf(exec)
+      registry.assertOwned(args.uuid, sessionId)
       const result = registry.read(args.uuid, args.offset, args.count)
       const bounded = boundBytes(result.text, READ_BYTE_LIMIT)
       return Promise.resolve({
@@ -261,7 +279,7 @@ export function registerTools(
     },
   }))
 
-  ctx.tools.register(defineTool({
+  register(defineTool({
     name: 'terminal_wait_for',
     description:
       'Block until a substring appears in a terminal\'s retained transcript, or until the timeout elapses, or until the terminal exits — whichever happens first. '
@@ -298,7 +316,7 @@ export function registerTools(
               needle: { type: 'string', required: true },
               line: { type: 'integer', required: true, description: '0-based line index in the retained transcript where the needle first appeared.' },
               column: { type: 'integer', required: true, description: '0-based column index within that line where the match starts.' },
-              elapsed_ms: { type: 'integer', required: true, description: 'Wall-clock milliseconds from wait start to match.' },
+              elapsedMs: { type: 'integer', required: true, description: 'Wall-clock milliseconds from wait start to match.' },
             },
           },
           {
@@ -307,8 +325,8 @@ export function registerTools(
             properties: {
               kind: { type: 'string', required: true, const: 'timeout' },
               needle: { type: 'string', required: true },
-              timeout_ms: { type: 'integer', required: true, description: 'The configured timeout that elapsed.' },
-              total_lines: { type: 'integer', required: true, description: 'Total lines retained when the timeout fired. Call terminal_read to inspect the tail.' },
+              timeoutMs: { type: 'integer', required: true, description: 'The configured timeout that elapsed.' },
+              totalLines: { type: 'integer', required: true, description: 'Total lines retained when the timeout fired. Call terminal_read to inspect the tail.' },
             },
           },
           {
@@ -317,55 +335,42 @@ export function registerTools(
             properties: {
               kind: { type: 'string', required: true, const: 'exited' },
               needle: { type: 'string', required: true },
-              exit_code: { type: 'integer', description: 'Exit code, if known.' },
-              exit_signal: { type: 'string', description: 'Exit signal name, if killed by a signal.' },
+              exitCode: { oneOf: [{ type: 'integer' }, { type: 'null' }], description: 'Exit code, if known.' },
+              exitSignal: { oneOf: [{ type: 'string' }, { type: 'null' }], description: 'Exit signal name, if killed by a signal.' },
             },
           },
         ],
       },
       render: (_args, value) => {
-        const v = value as { kind: 'found' | 'timeout' | 'exited'; needle: string; elapsed_ms?: number; timeout_ms?: number; line?: number; column?: number; exit_code?: number | null; exit_signal?: string | null }
+        const v = value as { kind: 'found' | 'timeout' | 'exited'; needle: string; elapsedMs?: number; timeoutMs?: number; line?: number; column?: number; exitCode?: number | null; exitSignal?: string | null }
         if (v.kind === 'found') {
-          return [{ type: 'text', text: `Found "${v.needle}" at line ${v.line}, column ${v.column} (after ${v.elapsed_ms}ms).` }]
+          return [{ type: 'text', text: `Found "${v.needle}" at line ${v.line}, column ${v.column} (after ${v.elapsedMs}ms).` }]
         }
         if (v.kind === 'timeout') {
-          return [{ type: 'text', text: `Timed out after ${v.timeout_ms}ms waiting for "${v.needle}". Call terminal_read to inspect the transcript.` }]
+          return [{ type: 'text', text: `Timed out after ${v.timeoutMs}ms waiting for "${v.needle}". Call terminal_read to inspect the transcript.` }]
         }
-        const exitInfo = v.exit_code !== undefined ? ` (exit code ${v.exit_code})` : ''
+        const exitInfo = v.exitCode !== undefined && v.exitCode !== null ? ` (exit code ${v.exitCode})` : ''
         return [{ type: 'text', text: `Terminal exited before "${v.needle}" appeared${exitInfo}.` }]
       },
     },
     async execute(args: { uuid: string; needle: string; timeout_ms?: number }, exec) {
       exec.signal.throwIfAborted()
-      if (args.needle === '') {
-        throw new Error('needle must be a non-empty string')
-      }
+      const sessionId = sessionIdOf(exec)
+      registry.assertOwned(args.uuid, sessionId)
+      // The registry validates the needle (empty → bad-request) and returns
+      // the camelCase result the schema above declares directly — no
+      // field-by-field projection.
       const timeoutMs = args.timeout_ms ?? 10_000
-      const result = await registry.waitFor(args.uuid, args.needle, timeoutMs, exec.signal)
-      // Project the registry's camelCase result into the snake_case canonical
-      // value declared by the output schema (the model sees snake_case).
-      if (result.kind === 'found') {
-        return { kind: 'found' as const, needle: result.needle, line: result.line, column: result.column, elapsed_ms: result.elapsedMs }
-      }
-      if (result.kind === 'timeout') {
-        return { kind: 'timeout' as const, needle: result.needle, timeout_ms: result.timeoutMs, total_lines: result.totalLines }
-      }
-      const out: { kind: 'exited'; needle: string; exit_code?: number; exit_signal?: string } = {
-        kind: 'exited',
-        needle: result.needle,
-      }
-      if (result.exitCode !== null && result.exitCode !== undefined) out.exit_code = result.exitCode
-      if (result.exitSignal !== null && result.exitSignal !== undefined) out.exit_signal = result.exitSignal
-      return out
+      return await registry.waitFor(args.uuid, args.needle, timeoutMs, exec.signal)
     },
   }))
 
-  ctx.tools.register(defineTool({
+  register(defineTool({
     name: 'terminal_resize',
     description:
       'Resize an agent terminal\'s pty ( cols × rows ). The host clamps both to a 2..1024 sane range. '
       + 'Most shells redraw their prompt and any full-screen TUI on the next output frame. '
-      + 'No-op if the terminal has exited.',
+      + 'No-op if the terminal has exited. Returns the dimensions actually applied.',
     parameters: {
       uuid: { type: 'string', required: true, description: 'Terminal uuid from terminal_create or terminal_list.' },
       cols: { type: 'integer', required: true, description: 'New column count ( clamped to 2..1024 ).' },
@@ -387,15 +392,17 @@ export function registerTools(
     },
     execute: (args: { uuid: string; cols: number; rows: number }, exec) => {
       exec.signal.throwIfAborted()
-      registry.resize(args.uuid, args.cols, args.rows)
-      return Promise.resolve({ uuid: args.uuid, cols: args.cols, rows: args.rows })
+      const sessionId = sessionIdOf(exec)
+      registry.assertOwned(args.uuid, sessionId)
+      const dims = registry.resize(args.uuid, args.cols, args.rows)
+      return Promise.resolve({ uuid: args.uuid, ...dims })
     },
   }))
 
-  ctx.tools.register(defineTool({
+  register(defineTool({
     name: 'terminal_signal',
     description:
-      'Send a POSIX signal to an agent terminal\'s foreground process — this is how you send Ctrl+C, Ctrl+D, Ctrl+Z, etc. '
+      'Send a POSIX signal to an agent terminal\'s foreground process — this is how you send Ctrl+C, Ctrl+Z, etc. '
       + 'Use signal="SIGINT" for Ctrl+C (interrupt the running command), signal="SIGTERM" to request termination, '
       + 'signal="SIGKILL" to force-kill the pty, signal="SIGHUP" to hang up (many shells exit), signal="SIGTSTP" for Ctrl+Z (suspend). '
       + 'Do NOT try to send control characters (like "\\u0003") through terminal_send — use this tool instead. '
@@ -425,12 +432,14 @@ export function registerTools(
     },
     execute: (args: { uuid: string; signal: AgentTerminalSignal }, exec) => {
       exec.signal.throwIfAborted()
+      const sessionId = sessionIdOf(exec)
+      registry.assertOwned(args.uuid, sessionId)
       registry.signal(args.uuid, args.signal)
       return Promise.resolve({ uuid: args.uuid, signal: args.signal })
     },
   }))
 
-  ctx.tools.register(defineTool({
+  register(defineTool({
     name: 'terminal_close',
     description:
       'Close an agent terminal and release its process. The uuid becomes invalid for all subsequent tool calls. '
@@ -455,8 +464,14 @@ export function registerTools(
     },
     execute: (args: { uuid: string }, exec) => {
       exec.signal.throwIfAborted()
+      const sessionId = sessionIdOf(exec)
+      registry.assertOwned(args.uuid, sessionId)
       const closed = registry.close(args.uuid)
       return Promise.resolve({ uuid: args.uuid, closed })
     },
   }))
+
+  return () => {
+    for (const dispose of disposers) dispose()
+  }
 }