@swarmclawai/swarmclaw 1.5.38 → 1.5.39

package/README.md

@@ -389,6 +389,15 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.5.39 Highlights
+
+- **Agents default to scoped tool access**: new agents (and existing agents whose `tools` list is non-empty) now only see the tools they've been given in the system prompt. This trims ~3 k input tokens per turn — an observed CEO/coordinator agent with 14 tools and 4 loaded skills went from 62 k to 38 k chars of system prompt. Opt back into the old firehose by toggling **Universal tool access** in the agent sheet's new "Context & Tool Access" section. Memory, context management, and `ask_human` are always included regardless of the scoped list.
+- **Pinned skills budget hardening**: one long markdown skill was eating 24 k of a 62 k prompt. Inlined pinned-skill content is now capped at 3 k chars with a pointer to `use_skill` action="load" for the full guide, and auto-attached *learned* skills get a dedicated sub-budget (max 6 skills / 8 k chars) so they cannot dominate the main pinned-skills section.
+- **OpenClaw chat fast-fails on dangling credentials**: v1.5.38 added gateway-side fast-fail; the chat streaming path now does the same, emitting a clear `err` event naming the missing credential instead of dialing the gateway unauthenticated and waiting 120 s for the timeout.
+- **Queue: orphan-recovery auto-heals stale checkouts**: pre-1.5.38 storage could leave `queued` tasks with a stale `checkoutRunId` that `checkoutTask()` refused forever. Orphan recovery now clears the stale id in the same sweep that re-queues the task, and `reconcileFinishedRunningTasks` / agent-not-found / capability-mismatch paths also null out the checkout when they terminally fail a task.
+- **Perf ring buffer raised to 2 000 entries**: queue/task repository events fire ~20 Hz during task processing and were evicting chat-execution/prompt perf entries out of the 200-entry buffer before they could be read. The larger buffer lets the perf viewer actually show a full turn.
+- **Tests**: added regression tests for pre-1.5.38 stale-checkout orphan recovery and for the scoped-tool-access algorithm.
+
 ### v1.5.38 Highlights
 
 - **Task queue: reclaim stale checkouts**: `checkoutTask()` now reclaims a lingering `checkoutRunId` on a `queued` task instead of refusing it forever. An ungraceful server exit mid-turn (crash, SIGKILL, HMR reload) previously left tasks uncheckoutable, producing a dispatch → orphan-recovery → failed-checkout spin that logged "Recovering orphaned queued task" tens of thousands of times per session. `scheduleRetryOrDeadLetter()` also clears the prior checkout when scheduling a retry or dead-lettering.
@@ -422,12 +431,6 @@ Operational docs: https://swarmclaw.ai/docs/observability
 - **Gateway credential resolution logging**: when a gateway credential can't be resolved, the server now logs a clear warning identifying the missing credential ID.
 - **Credential decryption error logging**: when a stored credential can't be decrypted (e.g. after `CREDENTIAL_SECRET` changes), the server now logs the credential ID and provider so users know which key to re-add.
 
-### v1.5.34 Highlights
-
-- **Ollama Cloud auth fix**: SwarmClaw now normalizes `api.ollama.com` and `www.ollama.com` to `ollama.com` before making authenticated requests, avoiding the redirect that was dropping authorization headers and causing false provider-health/runtime failures.
-- **Chat execution context hardening**: tool invocation now resolves names case-insensitively, oversized tool results are truncated before they are fed back into the model, and proactive grounding/heartbeat prompts stay smaller under pressure to reduce avoidable context blowouts.
-- **API compatibility fixes**: OpenAI-compatible streaming now captures reasoning deltas from providers that emit them outside `delta.content`, and A2A endpoints are exempt from the main proxy access-key gate so they can rely on their own auth scheme.
-
 Older releases: https://swarmclaw.ai/docs/release-notes
 
 - GitHub releases: https://github.com/swarmclawai/swarmclaw/releases

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.5.38",
+  "version": "1.5.39",
   "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "main": "electron-dist/main.js",
   "license": "MIT",

package/src/components/agents/agent-sheet.tsx

@@ -210,6 +210,11 @@ export function AgentSheet() {
   const [delegationTargetMode, setDelegationTargetMode] = useState<'all' | 'selected'>('all')
   const [delegationTargetAgentIds, setDelegationTargetAgentIds] = useState<string[]>([])
   const [tools, setTools] = useState<string[]>([])
+  // Scoped tool access is the default for new agents (cuts ~3 k input tokens
+  // per turn). Existing agents with no toolAccessMode field persisted stay
+  // universal server-side for backward compat; the new-agent setup path
+  // below also explicitly writes 'scoped' so it persists on save.
+  const [toolAccessMode, setToolAccessMode] = useState<'universal' | 'scoped'>('scoped')
   const [extensions, setExtensions] = useState<string[]>([])
   const [enabledExtensionIds, setEnabledExtensionIds] = useState<Set<string> | null>(null)
   const [skills, setSkills] = useState<string[]>([])
@@ -415,6 +420,7 @@ export function AgentSheet() {
         setDelegationTargetMode(editing.delegationTargetMode === 'selected' ? 'selected' : 'all')
         setDelegationTargetAgentIds(editing.delegationTargetAgentIds || [])
         setTools(getEnabledToolIds(editing))
+        setToolAccessMode(editing.toolAccessMode === 'scoped' ? 'scoped' : 'universal')
         setExtensions(getEnabledExtensionIds(editing))
         setSkills(editing.skills || [])
         setSkillIds(editing.skillIds || [])
@@ -497,6 +503,7 @@ export function AgentSheet() {
         setDelegationTargetMode(src.delegationTargetMode === 'selected' ? 'selected' : 'all')
         setDelegationTargetAgentIds(src.delegationTargetAgentIds || [])
         setTools(getEnabledToolIds(src))
+        setToolAccessMode(src.toolAccessMode === 'scoped' ? 'scoped' : 'universal')
         setExtensions(getEnabledExtensionIds(src))
         setSkills(src.skills || [])
         setSkillIds(src.skillIds || [])
@@ -576,6 +583,7 @@ export function AgentSheet() {
         setDelegationTargetMode('all')
         setDelegationTargetAgentIds([])
         setTools(getDefaultAgentToolIds())
+        setToolAccessMode('scoped')
         setExtensions([])
         setSkills([])
         setSkillIds([])
@@ -783,6 +791,7 @@ export function AgentSheet() {
       delegationTargetMode: delegationEnabled || role === 'coordinator' ? delegationTargetMode : 'all',
       delegationTargetAgentIds: (delegationEnabled || role === 'coordinator') && delegationTargetMode === 'selected' ? delegationTargetAgentIds : [],
       tools,
+      toolAccessMode,
       extensions,
       skills,
       skillIds,
@@ -2005,6 +2014,30 @@ export function AgentSheet() {
         summary={advancedSummary}
         badges={agentAdvancedBadges}
       >
+      <SectionCard
+        title="Context & Tool Access"
+        description="Control how many tools are described in this agent's system prompt. Scoped (default) keeps the agent focused and saves ~3 k input tokens per turn; Universal gives it visibility into every built-in tool."
+        className="mb-6 border-white/[0.05] bg-white/[0.01]"
+      >
+      <div className="space-y-3">
+        <label className="flex items-center gap-3 cursor-pointer">
+          <div
+            onClick={() => setToolAccessMode((current) => current === 'universal' ? 'scoped' : 'universal')}
+            className={`w-11 h-6 rounded-full transition-all duration-200 relative cursor-pointer shrink-0 ${toolAccessMode === 'universal' ? 'bg-accent-bright' : 'bg-white/[0.08]'}`}
+          >
+            <div className={`absolute top-0.5 w-5 h-5 rounded-full bg-white transition-all duration-200 ${toolAccessMode === 'universal' ? 'left-[22px]' : 'left-0.5'}`} />
+          </div>
+          <span className="text-[13px] text-text-2">Universal tool access</span>
+          <HintTip text="Off (default, recommended): the agent only sees tools enabled in its Tools list. On: every built-in tool is described in the system prompt. Turn on only for coordinator agents that need visibility across every possible downstream tool, or temporarily for debugging." />
+        </label>
+        <p className="text-[12px] text-text-3/70 pl-[56px] -mt-1">
+          {toolAccessMode === 'universal'
+            ? 'Full tool universe is injected into the prompt. Costs ~3 k more input tokens per turn.'
+            : 'Only the tools enabled above are visible to the agent — this is the focused default.'}
+        </p>
+      </div>
+      </SectionCard>
+
       <SectionCard
         title="Voice & Autonomy"
         description="Tune voice and the detailed heartbeat behavior for this agent."

package/src/lib/providers/openclaw.ts

@@ -422,6 +422,21 @@ export function streamOpenClawChat({ session, message, imagePath, apiKey, write,
 
   const wsUrl = session.apiEndpoint ? deriveOpenClawWsUrl(session.apiEndpoint) : 'ws://127.0.0.1:18789'
   const token = apiKey || session.apiKey || undefined
+  // If the session references a credential but nothing resolved, the credential
+  // was deleted or corrupted. Fail fast with a clear error instead of dialing
+  // the gateway unauthenticated and timing out 120 s later (the original symptom
+  // behind the "OpenClaw gateway timed out after 120 s" report).
+  const credentialIdSet = typeof session.credentialId === 'string' && session.credentialId.trim().length > 0
+  if (credentialIdSet && !token) {
+    return Promise.resolve().then(() => {
+      active.delete(session.id)
+      write(`data: ${JSON.stringify({
+        t: 'err',
+        text: `OpenClaw credential "${session.credentialId}" is missing from the credential store. Reattach an existing credential or create a new one in Settings → Credentials.`,
+      })}\n\n`)
+      return ''
+    })
+  }
   return new Promise((resolve) => {
     let fullResponse = ''
     let settled = false

package/src/lib/server/chat-execution/chat-turn-preparation.ts

@@ -15,7 +15,7 @@ import { loadSettings } from '@/lib/server/settings/settings-repository'
 import { loadSkills } from '@/lib/server/skills/skill-repository'
 import { resolveImagePath } from '@/lib/server/resolve-image'
 import { resolveSessionToolPolicy } from '@/lib/server/tool-capability-policy'
-import { listUniversalToolAccessExtensionIds } from '@/lib/server/universal-tool-access'
+import { listUniversalToolAccessExtensionIds, listScopedToolAccessExtensionIds } from '@/lib/server/universal-tool-access'
 import {
   buildAgentDisabledMessage,
   isAgentDisabled,
@@ -332,9 +332,17 @@ function buildAgentSystemPrompt(
   const allowSilentReplies = isDirectConnectorSession(session)
   const lightweightDirectChat = options?.lightweightDirectChat === true
   const parts: string[] = []
-  const enabledExtensions = listUniversalToolAccessExtensionIds(
-    getEnabledCapabilityIds(session).length > 0 ? getEnabledCapabilityIds(session) : getEnabledCapabilityIds(agent),
-  )
+  const capabilityIds = getEnabledCapabilityIds(session).length > 0
+    ? getEnabledCapabilityIds(session)
+    : getEnabledCapabilityIds(agent)
+  // Scoped tool access is the new default: if the agent declares a non-empty
+  // `tools` list, the system prompt only describes those tools. Explicit
+  // `toolAccessMode: 'universal'` opts into the full firehose (for coordinators
+  // or debugging). Agents with no declared tools fall back to universal so
+  // empty-config agents aren't crippled.
+  const enabledExtensions = agent.toolAccessMode !== 'universal' && Array.isArray(agent.tools) && agent.tools.length > 0
+    ? listScopedToolAccessExtensionIds(agent.tools, capabilityIds)
+    : listUniversalToolAccessExtensionIds(capabilityIds)
 
   const identityLines = ['## My Identity']
   identityLines.push(`Name: ${agent.name}`)
@@ -547,8 +555,16 @@ export async function prepareChatTurn(input: ExecuteChatTurnInput): Promise<Prep
   const runtimeCapabilityIds = filterRuntimeCapabilityIds(getEnabledCapabilityIds(session), {
     delegationEnabled: agentForSession?.delegationEnabled === true,
   })
+  // Match the resolver in buildAgentSystemPrompt: default to scoped whenever
+  // the agent declares a non-empty tools list, unless explicitly set to
+  // 'universal'. Agents with no declared tools stay universal.
+  const scopedAccess = agentForSession?.toolAccessMode !== 'universal'
+    && Array.isArray(agentForSession?.tools)
+    && (agentForSession!.tools!.length > 0)
   const requestedCapabilityIds = runtimeCapabilityIds.length > 0
-    ? listUniversalToolAccessExtensionIds(runtimeCapabilityIds)
+    ? (scopedAccess
+      ? listScopedToolAccessExtensionIds(agentForSession!.tools!, runtimeCapabilityIds)
+      : listUniversalToolAccessExtensionIds(runtimeCapabilityIds))
     : []
   const toolPolicy = resolveSessionToolPolicy(requestedCapabilityIds, appSettings)
   const isHeartbeatRun = input.internal === true && source === 'heartbeat'

package/src/lib/server/runtime/perf.ts

@@ -34,7 +34,11 @@ const perfState = hmrSingleton('__swarmclaw_perf__', () => ({
   recentEntries: [] as PerfEntry[],
 }))
 
-const MAX_RECENT = 200
+// Keep a generous ring buffer so perf entries from a chat turn survive the
+// flurry of repository/queue events that fire between them. 200 was too small
+// — queue.get/tasks.list fire ~20/s during task processing and would evict
+// chat-execution/prompt entries before they could be read.
+const MAX_RECENT = 2000
 
 function emitEntry(entry: PerfEntry): void {
   perfState.recentEntries.push(entry)

package/src/lib/server/runtime/queue/core.ts

@@ -700,6 +700,7 @@ export function reconcileFinishedRunningTasks(): { reconciled: number; deadLette
     if (!fallbackText && !task.result) {
       task.status = 'failed'
       task.result = 'Agent session finished without producing output.'
+      task.checkoutRunId = null
       task.updatedAt = now
       tasksDirty = true
       continue
@@ -1105,13 +1106,23 @@ export async function processNext() {
       const currentQueue = loadQueue()
       const queueSet = new Set(currentQueue)
       let recovered = false
+      let tasksDirty = false
       for (const [id, t] of Object.entries(allTasks) as [string, BoardTask][]) {
         if (t.status === 'queued' && !queueSet.has(id)) {
           log.info(TAG, `[queue] Recovering orphaned queued task: "${t.title}" (${id})`)
+          // Defence in depth: a queued task must not carry a stale checkoutRunId
+          // (left over from pre-1.5.38 retries). If it does, checkoutTask() will
+          // reject every attempt and this orphan-recovery loop will spin at 100%
+          // CPU re-queueing a task that can never run.
+          if (t.checkoutRunId) {
+            t.checkoutRunId = null
+            tasksDirty = true
+          }
           pushQueueUnique(currentQueue, id)
           recovered = true
         }
       }
+      if (tasksDirty) saveTasks(allTasks)
       if (recovered) saveQueue(currentQueue)
     }
 
@@ -1152,6 +1163,7 @@ export async function processNext() {
       if (!agent) {
         task.status = 'failed'
         task.deadLetteredAt = Date.now()
+        task.checkoutRunId = null
         task.error = `Agent ${task.agentId} not found`
         task.updatedAt = Date.now()
         saveTasks(latestTasks)
@@ -1182,6 +1194,7 @@ export async function processNext() {
         } else {
           task.status = 'failed'
           task.deadLetteredAt = Date.now()
+          task.checkoutRunId = null
           task.error = `No agent matches required capabilities: [${reqCaps.join(', ')}]`
           task.updatedAt = Date.now()
           saveTasks(latestTasks)

package/src/lib/server/runtime/queue-recovery.test.ts

@@ -309,6 +309,67 @@ describe('queue recovery', () => {
     assert.equal(output.attempts, 1)
   })
 
+  it('processNext orphan recovery clears stale checkoutRunId on queued tasks', () => {
+    // Regression: tasks written before the 1.5.38 fix could land in storage with
+    // status='queued' + a set checkoutRunId (because the old scheduleRetryOrDeadLetter
+    // forgot to release the checkout). Orphan recovery must repair this invalid combo
+    // so the next checkoutTask() can succeed — otherwise the loop spins forever.
+    const output = runWithTempDataDir<{
+      status: string | null
+      checkoutRunId: string | null
+      queued: string[]
+    }>(`
+      const storageMod = await import('@/lib/server/storage')
+      const queueMod = await import('@/lib/server/runtime/queue')
+      const storage = storageMod.default || storageMod
+      const queue = queueMod.default || queueMod
+
+      const now = Date.now()
+      storage.saveAgents({
+        'agent-a': {
+          id: 'agent-a',
+          name: 'Agent A',
+          provider: 'openai',
+          model: 'gpt-test',
+          createdAt: now,
+          updatedAt: now,
+        },
+      })
+      storage.saveTasks({
+        stale: {
+          id: 'stale',
+          title: 'Pre-1.5.38 stuck task',
+          description: 'Queued but still holds a stale checkoutRunId from a prior failed run',
+          status: 'queued',
+          agentId: 'agent-a',
+          checkoutRunId: 'stale-run-id',
+          createdAt: now - 10_000,
+          updatedAt: now - 10_000,
+        },
+      })
+      // Intentionally NOT in the queue array — simulates the orphan condition.
+      storage.saveQueue([])
+
+      await queue.processNext()
+
+      const task = storage.loadTasks().stale
+      console.log(JSON.stringify({
+        status: task?.status ?? null,
+        checkoutRunId: task?.checkoutRunId ?? null,
+        queued: storage.loadQueue(),
+      }))
+    `)
+
+    // Orphan recovery should have put the task back in the queue AND cleared the stale id.
+    assert.equal(output.checkoutRunId, null, 'orphan recovery must clear stale checkoutRunId')
+    // After recovery the task either stayed queued or moved to running (depending on concurrency).
+    // Either way it must not still be stuck in an orphan state.
+    assert.ok(
+      output.status === 'queued' || output.status === 'running' || output.status === 'failed',
+      `unexpected status after recovery: ${output.status}`,
+    )
+  })
+
   it('dead-letter path clears checkoutRunId so terminal tasks do not appear checked-out', () => {
     const output = runWithTempDataDir<{
       status: string | null

package/src/lib/server/skills/runtime-skill-resolver.ts

@@ -654,6 +654,16 @@ export function resolveRuntimeSkills(options: ResolveRuntimeSkillsOptions = {}):
   }
 }
 
+// Dedicated sub-budget for auto-attached learned skills. buildSeedFromLearned
+// marks every learned skill as `attached`, which means a single coordinator
+// agent with 100+ historical learnings could flood the whole 30 k pinned-skill
+// block every turn (observed: 178 learned skills / 176 k chars candidate pool
+// → 24 k-char Pinned Skills section on every CEO turn). We cap learned-skill
+// injection well below the full budget so explicitly-pinned/always-on skills
+// still fit afterward.
+const MAX_LEARNED_SKILLS_PROMPT_CHARS = 8000
+const MAX_LEARNED_SKILLS_IN_PROMPT = 6
+
 function selectPromptSkills(skills: ResolvedRuntimeSkill[]): ResolvedRuntimeSkill[] {
   const ordered = [...skills]
     .filter((skill) =>
@@ -670,16 +680,39 @@ function selectPromptSkills(skills: ResolvedRuntimeSkill[]): ResolvedRuntimeSkil
 
   const selected: ResolvedRuntimeSkill[] = []
   let totalChars = 0
+  let learnedChars = 0
+  let learnedCount = 0
   for (const skill of ordered) {
     if (selected.length >= MAX_SKILLS_IN_PROMPT) break
     const contentLen = skill.name.length + skill.content.length + 12
     if (totalChars + contentLen > MAX_SKILLS_PROMPT_CHARS) continue
+    const isLearned = skill.source === 'learned'
+    if (isLearned) {
+      if (learnedCount >= MAX_LEARNED_SKILLS_IN_PROMPT) continue
+      if (learnedChars + contentLen > MAX_LEARNED_SKILLS_PROMPT_CHARS) continue
+      learnedChars += contentLen
+      learnedCount += 1
+    }
     totalChars += contentLen
     selected.push(skill)
   }
   return selected
 }
 
+// Hard cap on how much skill content we inline per pinned skill. Long skill
+// files (multi-page markdown guides) were dominating the system prompt — one
+// coordinator agent had 24,402 chars (39% of its 62 k budget) from a single
+// pinned skill. When content exceeds the cap we truncate and instruct the
+// agent to pull the rest on demand via `use_skill` action="load".
+const INLINED_SKILL_CHAR_CAP = 3000
+
+function truncateInlinedSkillContent(content: string, skillName: string): string {
+  const trimmed = content.trim()
+  if (trimmed.length <= INLINED_SKILL_CHAR_CAP) return trimmed
+  const head = trimmed.slice(0, INLINED_SKILL_CHAR_CAP)
+  return `${head}\n\n[Skill content truncated at ${INLINED_SKILL_CHAR_CAP} chars to save context. Call \`use_skill\` with action="load" and skillId for "${skillName}" to load the full guide when you need it.]`
+}
+
 function sectionFromSkills(params: {
   title: string
   preface: string
@@ -688,7 +721,7 @@ function sectionFromSkills(params: {
   const usable = params.skills.filter((skill) => skill.content.trim())
   if (usable.length === 0) return ''
   const body = usable
-    .map((skill) => `### ${skill.name}\n${skill.content}`)
+    .map((skill) => `### ${skill.name}\n${truncateInlinedSkillContent(skill.content, skill.name)}`)
     .join('\n\n')
   return [params.title, params.preface, '', body].join('\n')
 }

package/src/lib/server/universal-tool-access.test.ts

@@ -0,0 +1,71 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+// NOTE: we intentionally avoid importing the real universal-tool-access
+// module here — it pulls in the extension manager which transitively loads
+// the whole plugin system and OOMs in test workers. We re-declare the pure
+// logic and verify the algorithmic behavior. Integration coverage for the
+// extension-manager branch happens via live-chat profiling instead.
+
+const SCOPED_TOOL_BASELINE = ['memory', 'context_mgmt', 'ask_human'] as const
+const UNIVERSAL_SAMPLE = new Set([
+  'shell', 'files', 'edit_file', 'delegate', 'web', 'browser', 'memory',
+  'manage_platform', 'manage_tasks', 'context_mgmt', 'ask_human',
+  'schedule_wake', 'email', 'image_gen',
+])
+
+function normalize(value: string[] | undefined | null): string[] {
+  if (!Array.isArray(value)) return []
+  return value.map((entry) => (typeof entry === 'string' ? entry.trim() : '')).filter(Boolean)
+}
+
+function scoped(declared: string[] | null | undefined, universe: Set<string> = UNIVERSAL_SAMPLE): string[] {
+  const picks = normalize(declared).filter((t) => universe.has(t))
+  return Array.from(new Set([...SCOPED_TOOL_BASELINE, ...picks]))
+}
+
+describe('scoped tool access algorithm', () => {
+  it('intersects declared tools with the universe and keeps the baseline', () => {
+    const out = scoped(['shell', 'files', 'edit_file', 'web'])
+    assert.ok(out.includes('memory'))
+    assert.ok(out.includes('context_mgmt'))
+    assert.ok(out.includes('ask_human'))
+    assert.ok(out.includes('shell'))
+    assert.ok(out.includes('files'))
+    assert.ok(out.includes('edit_file'))
+    assert.ok(out.includes('web'))
+    assert.ok(!out.includes('browser'))
+    assert.ok(!out.includes('manage_platform'))
+    assert.ok(!out.includes('delegate'))
+  })
+
+  it('drops declared tools that are not in the universe', () => {
+    const out = scoped(['shell', 'not_a_real_tool'])
+    assert.ok(out.includes('shell'))
+    assert.ok(!out.includes('not_a_real_tool'))
+  })
+
+  it('returns only the baseline when declared tools is empty', () => {
+    assert.deepEqual(scoped([]).sort(), ['ask_human', 'context_mgmt', 'memory'])
+  })
+
+  it('produces a strictly smaller set than the universe for a focused agent', () => {
+    assert.ok(scoped(['shell', 'files', 'web']).length < UNIVERSAL_SAMPLE.size)
+  })
+
+  it('deduplicates when baseline overlaps with declared tools', () => {
+    const out = scoped(['memory', 'shell'])
+    assert.equal(out.filter((t) => t === 'memory').length, 1)
+  })
+
+  it('treats null / undefined / non-array declared tools as empty', () => {
+    assert.deepEqual(scoped(null).sort(), ['ask_human', 'context_mgmt', 'memory'])
+    assert.deepEqual(scoped(undefined).sort(), ['ask_human', 'context_mgmt', 'memory'])
+  })
+
+  it('trims whitespace in declared tool names', () => {
+    const out = scoped(['  shell  ', '\tfiles\n'])
+    assert.ok(out.includes('shell'))
+    assert.ok(out.includes('files'))
+  })
+})

package/src/lib/server/universal-tool-access.ts

@@ -57,3 +57,26 @@ export function listUniversalToolAccessExtensionIds(extraExtensions?: string[] |
     ...normalizeExtensionList(extraExtensions),
   ])
 }
+
+// Minimum extensions that a 'scoped' agent always gets regardless of its
+// declared tool list. Memory + context management are required for the agent
+// to function (remembering things, noticing when it's out of context), and
+// ask_human lets it escalate to the user when stuck. Everything else is
+// filterable through agent.tools.
+const SCOPED_TOOL_BASELINE = ['memory', 'context_mgmt', 'ask_human'] as const
+
+/**
+ * Returns the set of enabled extension IDs for a scoped-access agent: the
+ * intersection of `listUniversalToolAccessExtensionIds()` with the agent's
+ * declared tools, plus the non-negotiable baseline. Use this when an agent
+ * has opted into `toolAccessMode: 'scoped'` to shrink per-turn context.
+ */
+export function listScopedToolAccessExtensionIds(
+  declaredTools: string[] | null | undefined,
+  extraExtensions?: string[] | null,
+): string[] {
+  const universe = new Set(listUniversalToolAccessExtensionIds(extraExtensions))
+  const declared = normalizeExtensionList(declaredTools)
+  const scoped = declared.filter((tool) => universe.has(tool))
+  return dedup([...SCOPED_TOOL_BASELINE, ...scoped])
+}

package/src/types/agent.ts

@@ -68,6 +68,13 @@ export interface Agent {
   delegationTargetMode?: DelegationTargetMode
   delegationTargetAgentIds?: string[]
   tools?: string[]
+  // When 'scoped', the chat turn restricts enabled extensions to the
+  // intersection of the universal core list and agent.tools (plus a small
+  // non-negotiable baseline for memory + context management). Default
+  // 'universal' preserves existing behavior. Opt in to cut per-turn tool
+  // guidance dramatically — a focused agent with 5 tools drops ~15 k chars
+  // of tool-related prompt text vs. the full 33-tool universe.
+  toolAccessMode?: 'universal' | 'scoped'
   extensions?: string[]
   skills?: string[]             // e.g. ['frontend-design'] — pinned Claude Code skills to mention explicitly
   skillIds?: string[]           // IDs of pinned managed skills to keep always-on for this agent