mixdog 0.9.1 → 0.9.3

package/scripts/tool-smoke.mjs

@@ -3,15 +3,16 @@ import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'nod
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { __renderToolSearchForTest, compactToolSearchDescription, defaultDeferredToolNames, SKILL_TOOL, TOOL_SEARCH_TOOL } from '../src/mixdog-session-runtime.mjs';
+import { __applyStandaloneToolDefaultsForTest, __renderToolSearchForTest, compactToolSearchDescription, defaultDeferredToolNames, SKILL_TOOL, TOOL_SEARCH_TOOL } from '../src/mixdog-session-runtime.mjs';
 import { buildExplorerPrompt, EXPLORE_TOOL, MAX_FANOUT_QUERIES, normalizeExploreQueries } from '../src/standalone/explore-tool.mjs';
 import { AGENT_TOOL, createStandaloneAgent } from '../src/standalone/agent-tool.mjs';
 import { parseHeadlessRoleCommand } from '../src/app.mjs';
 import { buildHeadlessSpawnArgs } from '../src/headless-role.mjs';
 import { createStandaloneChannelWorker } from '../src/standalone/channel-worker.mjs';
 import { OpenAIOAuthProvider, buildRequestBody, sendViaHttpSse } from '../src/runtime/agent/orchestrator/providers/openai-oauth.mjs';
+import { _test as _anthropicOAuthTest } from '../src/runtime/agent/orchestrator/providers/anthropic-oauth.mjs';
 import { _logicalResponseItemMatch, _resolveOpenAiPromptCacheRatePolicy } from '../src/runtime/agent/orchestrator/providers/openai-oauth-ws.mjs';
-import { _mergePendingMessageEntries, closeSession, createSession, drainPendingMessages, enqueuePendingMessage, resumeSession } from '../src/runtime/agent/orchestrator/session/manager.mjs';
+import { _mergePendingMessageEntries, applyAskTerminalUsageTotals, closeSession, createSession, drainPendingMessages, enqueuePendingMessage, resumeSession } from '../src/runtime/agent/orchestrator/session/manager.mjs';
 import {
   contentHasImage,
   normalizeContentForAnthropic,
@@ -28,7 +29,8 @@ import {
   shouldRecordObservedForProvider,
 } from '../src/runtime/agent/orchestrator/agent-runtime/cache-strategy.mjs';
 import { executeBuiltinTool } from '../src/runtime/agent/orchestrator/tools/builtin.mjs';
-import { validateBuiltinArgs } from '../src/runtime/agent/orchestrator/tools/builtin/arg-guard.mjs';
+import { applyGrepContextLeadPolicy, GREP_CONTEXT_MAX, validateBuiltinArgs } from '../src/runtime/agent/orchestrator/tools/builtin/arg-guard.mjs';
+import { normaliseReadLineWindowArgs } from '../src/runtime/agent/orchestrator/tools/builtin/read-args.mjs';
 import { BUILTIN_TOOLS } from '../src/runtime/agent/orchestrator/tools/builtin/builtin-tools.mjs';
 import { runResultCacheInFlight } from '../src/runtime/agent/orchestrator/tools/builtin/cache-layers.mjs';
 import { executeCodeGraphTool } from '../src/runtime/agent/orchestrator/tools/code-graph.mjs';
@@ -44,7 +46,7 @@ import { composeSystemPrompt } from '../src/runtime/agent/orchestrator/context/c
 import { setInternalToolsProvider } from '../src/runtime/agent/orchestrator/internal-tools.mjs';
 import { prepareAgentSession } from '../src/runtime/agent/orchestrator/agent-runtime/session-builder.mjs';
 import { resolveHiddenRoleSchemaAllowedTools } from '../src/runtime/agent/orchestrator/agent-runtime/agent-dispatch.mjs';
-import { getHiddenRole, resolveAgentSessionPermission } from '../src/runtime/agent/orchestrator/internal-roles.mjs';
+import { getHiddenAgent, resolveAgentSessionPermission } from '../src/runtime/agent/orchestrator/internal-agents.mjs';
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -63,6 +65,27 @@ function assertOk(name, result, pattern = null) {
   return text;
 }
 
+{
+  const session = { provider: 'openai-oauth' };
+  applyAskTerminalUsageTotals(session, {
+    usage: { inputTokens: 100_000, outputTokens: 10, cachedTokens: 98_000, cacheWriteTokens: 0 },
+  });
+  assert(session.lastInputTokens === 100_000, `inclusive last input should retain provider total: ${JSON.stringify(session)}`);
+  assert(session.lastUncachedInputTokens === 2_000, `inclusive last uncached input should subtract cache reads: ${JSON.stringify(session)}`);
+  assert(session.totalUncachedInputTokens === 2_000, `inclusive total uncached input should be tracked: ${JSON.stringify(session)}`);
+}
+
+{
+  const session = { provider: 'anthropic-oauth' };
+  applyAskTerminalUsageTotals(session, {
+    usage: { inputTokens: 2_000, outputTokens: 10, cachedTokens: 90_000, cacheWriteTokens: 8_000 },
+  });
+  assert(session.lastInputTokens === 2_000, `additive last input should retain provider input field: ${JSON.stringify(session)}`);
+  assert(session.lastUncachedInputTokens === 10_000, `additive uncached input should include cache writes: ${JSON.stringify(session)}`);
+  assert(session.lastContextTokens === 100_000, `additive context should include input+cache read+cache write: ${JSON.stringify(session)}`);
+  assert(session.totalUncachedInputTokens === 10_000, `additive total uncached input should include cache writes: ${JSON.stringify(session)}`);
+}
+
 {
   const sid = `tool-smoke-rich-pending-${process.pid}-${Date.now()}`.replace(/[^A-Za-z0-9_-]/g, '_');
   const richContent = [
@@ -193,7 +216,9 @@ function assertOk(name, result, pattern = null) {
 {
   const publicStrategy = resolveCacheStrategy('worker');
   assert(publicStrategy.tools === 'none', `Anthropic tools must not spend a cache_control BP: ${JSON.stringify(publicStrategy)}`);
-  assert(publicStrategy.system === '1h' && publicStrategy.tier3 === '1h' && publicStrategy.messages === '1h', `public cache tiers changed unexpectedly: ${JSON.stringify(publicStrategy)}`);
+  // BP1~3 stay 1h (pool-stable prefix); volatile message tail is 5m for all
+  // sessions — see resolveCacheStrategy docs (trace p99 gap ≈ 4.5min).
+  assert(publicStrategy.system === '1h' && publicStrategy.tier3 === '1h' && publicStrategy.messages === '5m', `public cache tiers changed unexpectedly: ${JSON.stringify(publicStrategy)}`);
   assert(cacheCapabilityForProvider('anthropic-oauth') === 'explicit-breakpoint', 'Anthropic OAuth should remain explicit-breakpoint');
   assert(cacheCapabilityForProvider('openai-oauth') === 'key-prefix', 'OpenAI OAuth should remain key-prefix');
   assert(cacheCapabilityForProvider('xai') === 'key-prefix', 'xAI should remain key-prefix');
@@ -355,6 +380,7 @@ const grepOut = await executeBuiltinTool('grep', {
   pattern: ['standalone mixdog CLI/TUI coding agent', 'smoke passed'],
   path: 'scripts',
   glob: '*.mjs',
+  output_mode: 'content_with_context',
   head_limit: 10,
 }, root);
 assertOk('grep', grepOut, /smoke\.mjs/);
@@ -390,8 +416,8 @@ assertOk('find', findOut, /scripts[\\/]tool-smoke\.mjs/i);
 
 const readOut = await executeBuiltinTool('read', {
   path: 'scripts/smoke.mjs',
-  line: 1,
-  context: 3,
+  offset: 0,
+  limit: 4,
 }, root);
 assertOk('read', readOut, /spawnSync/);
 
@@ -402,12 +428,71 @@ if (!/^Error[\s:[]/.test(String(readDirOut)) || !/read expects a file/i.test(Str
   throw new Error(`read directory must be classified as Error:\n${readDirOut}`);
 }
 
+const readRegionBatchOut = await executeBuiltinTool('read', {
+  path: [
+    { path: 'scripts/smoke.mjs', offset: 0, limit: 2 },
+    { path: 'scripts/smoke.mjs', offset: 2, limit: 2 },
+  ],
+}, root);
+if (!/^read 2\b/m.test(String(readRegionBatchOut))
+  || (String(readRegionBatchOut).match(/scripts\/smoke\.mjs \[full\] \[ok\]/g) || []).length < 2
+  || !/1→import \{ spawnSync \}/.test(String(readRegionBatchOut))
+  || !/3→import \{ fileURLToPath \}/.test(String(readRegionBatchOut))
+  || !/pass offset:2 to continue/.test(String(readRegionBatchOut))
+  || !/pass offset:4 to continue/.test(String(readRegionBatchOut))) {
+  throw new Error(`read region batch must preserve both requested spans:\n${readRegionBatchOut}`);
+}
+
+const readStringifiedRegionArgs = {
+  path: JSON.stringify([{ path: 'scripts/smoke.mjs', offset: 0, limit: 2 }]),
+};
+const readStringifiedRegionErr = validateBuiltinArgs('read', readStringifiedRegionArgs);
+if (readStringifiedRegionErr || !Array.isArray(readStringifiedRegionArgs.path)) {
+  throw new Error(`read guard must losslessly coerce stringified path arrays: err=${readStringifiedRegionErr} args=${JSON.stringify(readStringifiedRegionArgs)}`);
+}
+const readStringifiedRegionOut = await executeBuiltinTool('read', {
+  path: JSON.stringify([{ path: 'scripts/smoke.mjs', offset: 0, limit: 2 }]),
+}, root);
+if (!/^read 1\b/m.test(String(readStringifiedRegionOut)) || !/scripts\/smoke\.mjs \[full\] \[ok\]/.test(String(readStringifiedRegionOut)) || !/1→import \{ spawnSync \}/.test(String(readStringifiedRegionOut))) {
+  throw new Error(`read stringified region batch must execute after guard coercion:\n${readStringifiedRegionOut}`);
+}
+const readStringifiedLineArgs = {
+  path: JSON.stringify([{ path: 'scripts/smoke.mjs', line: 10, context: 2 }]),
+};
+const readStringifiedLineErr = validateBuiltinArgs('read', readStringifiedLineArgs);
+if (readStringifiedLineErr || readStringifiedLineArgs.path[0].offset !== 7 || readStringifiedLineArgs.path[0].limit !== 5) {
+  throw new Error(`read guard must losslessly convert legacy line/context inside stringified arrays to offset/limit: err=${readStringifiedLineErr} args=${JSON.stringify(readStringifiedLineArgs)}`);
+}
+
 const graphOut = await executeCodeGraphTool('code_graph', {
   mode: 'symbols',
   file: 'scripts/smoke.mjs',
 }, root);
 assertOk('code_graph', graphOut, /binding|spawnSync|symbol/i);
 
+const graphSymbolBatchOut = await executeCodeGraphTool('code_graph', {
+  mode: 'symbol_search',
+  symbols: ['executeBuiltinTool', 'validateBuiltinArgs'],
+  limit: 2,
+}, root);
+if (!/# symbol_search executeBuiltinTool\b/.test(String(graphSymbolBatchOut)) || !/# symbol_search validateBuiltinArgs\b/.test(String(graphSymbolBatchOut))) {
+  throw new Error(`code_graph symbol_search symbols[] batch execution failed:\n${graphSymbolBatchOut}`);
+}
+
+const graphMissingFileOut = await executeCodeGraphTool('code_graph', {
+  mode: 'symbols',
+  file: 'src/runtime/loop.mjs',
+}, root);
+if (!/^Error: code_graph: file not found: src\/runtime\/loop\.mjs/.test(String(graphMissingFileOut))) {
+  throw new Error(`code_graph missing-file fast path failed:\n${graphMissingFileOut}`);
+}
+
+const graphDotDirOut = await executeCodeGraphTool('code_graph', {
+  mode: 'overview',
+  file: '.',
+}, root);
+assertOk('code_graph dot directory anchor', graphDotDirOut, /files\s+\d+|edges\s+\d+/i);
+
 const patchOut = await executePatchTool('apply_patch', {
   base_path: root,
   dry_run: true,
@@ -498,6 +583,12 @@ if (literalBackslashPipeArray) {
   throw new Error(`grep array literal \\| should be allowed: ${literalBackslashPipeArray}`);
 }
 
+const grepContextPolicyArgs = { pattern: 'smoke', path: root, context: GREP_CONTEXT_MAX + 999 };
+applyGrepContextLeadPolicy(grepContextPolicyArgs);
+if (grepContextPolicyArgs['-C'] !== GREP_CONTEXT_MAX || Object.prototype.hasOwnProperty.call(grepContextPolicyArgs, 'context')) {
+  throw new Error(`grep context policy must canonicalize and clamp explicit context: ${JSON.stringify(grepContextPolicyArgs)}`);
+}
+
 const invalidGrepPath = validateBuiltinArgs('grep', {
   pattern: 'providerStatus',
   path: 'C:\\Project\\mixdog\\src\\tui C:\\Project\\mixdog\\src\\mixdog-session-runtime.mjs',
@@ -514,11 +605,20 @@ if (!/lookaround\/backrefs/i.test(invalidGrepLookaround || '')) {
   throw new Error(`grep unsupported-regex guard failed: ${invalidGrepLookaround}`);
 }
 
-const invalidShellPath = validateBuiltinArgs('shell', {
+// Windows drive path + no explicit shell used to be rejected with a retry hint;
+// the guard now auto-coerces to shell:'powershell' (drive paths are a definitive
+// powershell signal — they can never work under Git Bash unconverted).
+const shellDrivePathArgs = {
   command: 'cd C:\\Project\\mixdog && node scripts/build-tui.mjs',
-});
-if (process.platform === 'win32' && !/shell:'powershell'/i.test(invalidShellPath || '')) {
-  throw new Error(`shell Windows-path guard failed: ${invalidShellPath}`);
+};
+const shellDrivePathErr = validateBuiltinArgs('shell', shellDrivePathArgs);
+if (process.platform === 'win32') {
+  if (shellDrivePathErr !== null) {
+    throw new Error(`shell Windows-path auto-coercion failed: ${shellDrivePathErr}`);
+  }
+  if (shellDrivePathArgs.shell !== 'powershell') {
+    throw new Error(`shell Windows-path auto-coercion did not set shell:'powershell' (got ${JSON.stringify(shellDrivePathArgs.shell)})`);
+  }
 }
 
 const invalidShellCwdAliasConflict = validateBuiltinArgs('shell', {
@@ -534,16 +634,28 @@ if (!/cwd.*workdir.*conflict/i.test(invalidShellCwdAliasConflict || '')) {
 const shellWorkdirOut = await shellWorkdirOutPromise;
 assertOk('shell workdir alias', shellWorkdirOut, /scripts\s*$/i);
 
-const mixedReadWindow = {
+const offsetReadWindow = {
   path: 'scripts/smoke.mjs',
-  line: 1,
-  context: 3,
-  offset: 1,
+  offset: 0,
   limit: 20,
 };
-const readWindowErr = validateBuiltinArgs('read', mixedReadWindow);
-if (!/exactly one window family/i.test(readWindowErr || '')) {
-  throw new Error(`read mixed-window guard failed: err=${readWindowErr} args=${JSON.stringify(mixedReadWindow)}`);
+const readWindowErr = validateBuiltinArgs('read', offsetReadWindow);
+if (readWindowErr) {
+  throw new Error(`read offset/limit window guard failed: err=${readWindowErr} args=${JSON.stringify(offsetReadWindow)}`);
+}
+const readLineArgs = { path: 'scripts/smoke.mjs', line: 10, context: 2 };
+const readLineErr = validateBuiltinArgs('read', readLineArgs);
+if (readLineErr || readLineArgs.offset !== 7 || readLineArgs.limit !== 5 || 'line' in readLineArgs || 'context' in readLineArgs) {
+  throw new Error(`read guard must losslessly convert top-level legacy line/context args to offset/limit: err=${readLineErr} args=${JSON.stringify(readLineArgs)}`);
+}
+const batchedReadLineArgs = { path: [{ path: 'scripts/smoke.mjs', line: 10, context: 2 }] };
+const batchedReadLineErr = validateBuiltinArgs('read', batchedReadLineArgs);
+if (batchedReadLineErr || batchedReadLineArgs.path[0].offset !== 7 || batchedReadLineArgs.path[0].limit !== 5) {
+  throw new Error(`read guard must losslessly convert batched legacy line/context args to offset/limit: err=${batchedReadLineErr} args=${JSON.stringify(batchedReadLineArgs)}`);
+}
+const pathLineWithLimit = normaliseReadLineWindowArgs({ path: 'scripts/smoke.mjs#L10', limit: 5 }, root);
+if (pathLineWithLimit.offset !== 9 || pathLineWithLimit.limit !== 5) {
+  throw new Error(`read path#line compatibility must anchor offset when limit is explicit: ${JSON.stringify(pathLineWithLimit)}`);
 }
 
 function assertHas(set, name) {
@@ -630,27 +742,27 @@ const agentProps = AGENT_TOOL.inputSchema?.properties || {};
 if (agentProps.mode || agentProps.wait) throw new Error('agent schema should not expose execution mode controls');
 {
   const heavyPrompt = composeSystemPrompt({
-    role: 'heavy-worker',
+    agent: 'heavy-worker',
     provider: 'anthropic-oauth',
     agentRules: '# Tool Use',
     skillManifest: '',
   });
-  if (!heavyPrompt.stableSystemContext.includes('## heavy-worker') || !heavyPrompt.stableSystemContext.includes('Complex implementation agent')) {
+  if (!heavyPrompt.stableSystemContext.includes('## heavy-worker')) {
     throw new Error(`heavy-worker AGENT.md must be included in scoped role instructions: ${heavyPrompt.stableSystemContext}`);
   }
   const workerPrompt = composeSystemPrompt({
-    role: 'worker',
+    agent: 'worker',
     provider: 'anthropic-oauth',
     agentRules: '# Tool Use',
     skillManifest: '',
   });
-  if (!workerPrompt.stableSystemContext.includes('## worker') || !workerPrompt.stableSystemContext.includes('Basic implementation agent')) {
+  if (!workerPrompt.stableSystemContext.includes('## worker')) {
     throw new Error(`worker AGENT.md must be included in scoped role instructions: ${workerPrompt.stableSystemContext}`);
   }
 }
 {
   const shorthand = parseHeadlessRoleCommand(['reviewer', 'check', 'this']);
-  if (shorthand?.role !== 'reviewer' || shorthand?.message !== 'check this') {
+  if (shorthand?.agent !== 'reviewer' || shorthand?.message !== 'check this') {
     throw new Error(`headless shorthand command parse failed: ${JSON.stringify(shorthand)}`);
   }
   const explicit = parseHeadlessRoleCommand(['role', 'debug', 'trace', 'failure']);
@@ -662,7 +774,7 @@ if (agentProps.mode || agentProps.wait) throw new Error('agent schema should not
     throw new Error(`empty argv must keep TUI default: ${JSON.stringify(tuiDefault)}`);
   }
   const modelOnlySpawn = buildHeadlessSpawnArgs({
-    role: 'reviewer',
+    agent: 'reviewer',
     tag: 'headless-smoke',
     cwd: root,
     message: 'check this',
@@ -672,7 +784,7 @@ if (agentProps.mode || agentProps.wait) throw new Error('agent schema should not
     throw new Error(`headless model-only route must preserve --model without forcing provider: ${JSON.stringify(modelOnlySpawn)}`);
   }
 }
-if (!/always start background tasks/i.test(AGENT_TOOL.description || '') || !/distinct tags/i.test(AGENT_TOOL.description || '') || !/completion notification/i.test(AGENT_TOOL.description || '') || !/do not (?:call|poll) status\/read/i.test(AGENT_TOOL.description || '')) {
+if (!/always start background tasks/i.test(AGENT_TOOL.description || '') || !/distinct tags/i.test(AGENT_TOOL.description || '') || !/same scope/i.test(AGENT_TOOL.description || '') || !/send/i.test(AGENT_TOOL.description || '') || !/completion notification/i.test(AGENT_TOOL.description || '') || !/do not (?:call|poll) status\/read/i.test(AGENT_TOOL.description || '')) {
   throw new Error('agent description must preserve async tagged delegation contract');
 }
 const agentSmoke = createStandaloneAgent({
@@ -846,6 +958,15 @@ if (EXPLORE_TOOL.annotations?.readOnlyHint !== true || EXPLORE_TOOL.annotations?
 if (EXPLORE_TOOL.annotations?.agentHidden === true) {
   throw new Error('explore must stay visible to agent sessions');
 }
+{
+  const runtimeSearchTool = __applyStandaloneToolDefaultsForTest(SEARCH_TOOL_DEFS.find((tool) => tool?.name === 'search'));
+  if (runtimeSearchTool?.annotations?.agentHidden === true) {
+    throw new Error('production search tool must stay visible to agent sessions');
+  }
+  if (TOOL_SEARCH_TOOL.annotations?.agentHidden !== true) {
+    throw new Error('deferred tool_search wrapper must stay hidden from agent sessions');
+  }
+}
 const exploreProps = EXPLORE_TOOL.inputSchema?.properties || {};
 if (!/Repo anchor locator/i.test(EXPLORE_TOOL.description || '') || !/broad\/uncertain/i.test(EXPLORE_TOOL.description || '') || !/independent targets/i.test(EXPLORE_TOOL.description || '') || (EXPLORE_TOOL.description || '').length > 90) {
   throw new Error('explore description must stay compact and anchor-oriented');
@@ -897,7 +1018,7 @@ setInternalToolsProvider({
       provider: 'openai-oauth',
       model: 'tool-smoke-model',
       owner: 'cli',
-      role: 'lead',
+      agent: 'lead',
       cwd: skillManifestTmp,
       permission: 'read-write',
     });
@@ -917,7 +1038,7 @@ setInternalToolsProvider({
       provider: 'openai-oauth',
       model: 'tool-smoke-model',
       owner: AGENT_OWNER,
-      role: 'worker',
+      agent: 'worker',
       cwd: skillManifestTmp,
       permission: 'read-write',
     });
@@ -938,8 +1059,8 @@ setInternalToolsProvider({
         throw new Error(`agent system layers must carry BP1 tool policy and BP2 role rules: ${systemVisible.slice(0, 1200)}`);
       }
       const agentSkillToolNames = (agentSkillSession.tools || []).map((tool) => tool?.name).filter(Boolean);
-      if (agentSkillToolNames.includes('Skill')) {
-        throw new Error(`read-write agent schema must omit Skill loader: ${agentSkillToolNames.join(', ')}`);
+      if (!agentSkillToolNames.includes('Skill')) {
+        throw new Error(`read-write agent schema must expose Skill loader with the manifest: ${agentSkillToolNames.join(', ')}`);
       }
     } finally {
       closeSession(agentSkillSession.id, 'tool-smoke');
@@ -951,7 +1072,7 @@ setInternalToolsProvider({
     provider: 'openai-oauth',
     model: 'tool-smoke-model',
     owner: AGENT_OWNER,
-    role: 'explorer',
+    agent: 'explorer',
     cwd: root,
     permission: 'read',
     skipSkills: true,
@@ -970,7 +1091,7 @@ setInternalToolsProvider({
     if (!/Read-only retrieval role/i.test(visible) || /# environment/i.test(visible) || /git operations deferred to Lead/i.test(visible)) {
       throw new Error(`explorer hidden retrieval context should stay slim: ${visible.slice(0, 1200)}`);
     }
-    if (!/# Role: explorer/i.test(systemVisible) || /# Role: explorer/i.test(userReminderVisible) || !/Locator only/i.test(systemVisible)) {
+    if (!/# Role: explorer/i.test(systemVisible) || /# Role: explorer/i.test(userReminderVisible) || !/one-shot locator/i.test(systemVisible)) {
       throw new Error(`explorer role md must ride BP2 system, not BP3 user reminder: system=${systemVisible.slice(0, 600)} user=${userReminderVisible.slice(0, 600)}`);
     }
     const visibleBytes = Buffer.byteLength(visible, 'utf8');
@@ -984,7 +1105,7 @@ setInternalToolsProvider({
     provider: 'openai-oauth',
     model: 'tool-smoke-model',
     owner: AGENT_OWNER,
-    role: 'worker',
+    agent: 'worker',
     cwd: root,
     permission: 'read-write',
     taskBrief: 'Implement a scoped smoke check.',
@@ -1029,7 +1150,7 @@ setInternalToolsProvider({
     provider: 'openai-oauth',
     model: 'tool-smoke-model',
     owner: AGENT_OWNER,
-    role: 'worker',
+    agent: 'worker',
     cwd: root,
     permission: 'read',
   });
@@ -1037,7 +1158,7 @@ setInternalToolsProvider({
     provider: 'openai-oauth',
     model: 'tool-smoke-model',
     owner: AGENT_OWNER,
-    role: 'worker',
+    agent: 'worker',
     cwd: root,
     permission: 'read-write',
   });
@@ -1045,7 +1166,7 @@ setInternalToolsProvider({
     provider: 'openai-oauth',
     model: 'tool-smoke-model',
     owner: AGENT_OWNER,
-    role: 'worker',
+    agent: 'worker',
     cwd: root,
     permission: 'full',
   });
@@ -1062,8 +1183,8 @@ setInternalToolsProvider({
     const writeTools = (writeAgentSession.tools || []).map((tool) => tool?.name).filter(Boolean);
     const fullTools = (fullAgentSession.tools || []).map((tool) => tool?.name).filter(Boolean);
     const publicExploreTools = (publicExploreSession.tools || []).map((tool) => tool?.name).filter(Boolean);
-    const expectedReadTools = ['code_graph', 'find', 'glob', 'list', 'grep', 'read', 'explore', 'search', 'web_fetch'];
-    const expectedWriteTools = ['code_graph', 'find', 'glob', 'list', 'grep', 'read', 'apply_patch', 'explore', 'search', 'web_fetch'];
+    const expectedReadTools = ['code_graph', 'find', 'glob', 'list', 'grep', 'read', 'explore', 'search', 'web_fetch', 'Skill'];
+    const expectedWriteTools = ['code_graph', 'find', 'glob', 'list', 'grep', 'read', 'apply_patch', 'explore', 'search', 'web_fetch', 'Skill'];
     if (JSON.stringify(readTools) !== JSON.stringify(expectedReadTools)) {
       throw new Error(`read agent schema must be fixed allow-list: expected=${expectedReadTools.join(', ')} actual=${readTools.join(', ')}`);
     }
@@ -1076,7 +1197,7 @@ setInternalToolsProvider({
     if (readTools.includes('shell') || writeTools.includes('shell')) {
       throw new Error(`read/read-write agent schemas must omit shell: read=${readTools.join(', ')} write=${writeTools.join(', ')}`);
     }
-    for (const name of ['shell', 'apply_patch', 'task', 'diagnostics', 'open_config', 'Skill']) {
+    for (const name of ['shell', 'apply_patch', 'task', 'diagnostics', 'open_config']) {
       if (readTools.includes(name)) {
         throw new Error(`read agent schema must omit non-read tool ${name}: read=${readTools.join(', ')}`);
       }
@@ -1089,7 +1210,7 @@ setInternalToolsProvider({
         throw new Error(`read-write agent schema must omit non-edit tool ${name}: write=${writeTools.join(', ')}`);
       }
     }
-    for (const name of ['open_config', 'Skill']) {
+    for (const name of ['open_config']) {
       if (writeTools.includes(name)) {
         throw new Error(`read-write agent schema must omit config/skill tool ${name}: write=${writeTools.join(', ')}`);
       }
@@ -1121,14 +1242,14 @@ setInternalToolsProvider({
     provider: 'openai-oauth',
     model: 'tool-smoke-model',
     owner: AGENT_OWNER,
-    role: 'worker',
+    agent: 'worker',
     cwd: root,
     permission: 'read-write',
   });
   try {
     const resumed = await resumeSession(resumeAgentSession.id, 'full');
     const resumedTools = (resumed?.tools || []).map((tool) => tool?.name).filter(Boolean);
-    const expectedWriteTools = ['code_graph', 'find', 'glob', 'list', 'grep', 'read', 'apply_patch', 'explore', 'search', 'web_fetch'];
+    const expectedWriteTools = ['code_graph', 'find', 'glob', 'list', 'grep', 'read', 'apply_patch', 'explore', 'search', 'web_fetch', 'Skill'];
     if (JSON.stringify(resumedTools) !== JSON.stringify(expectedWriteTools)) {
       throw new Error(`resumed read-write agent schema must keep fixed allow-list: expected=${expectedWriteTools.join(', ')} actual=${resumedTools.join(', ')}`);
     }
@@ -1139,7 +1260,7 @@ setInternalToolsProvider({
     provider: 'openai-oauth',
     model: 'tool-smoke-model',
     owner: AGENT_OWNER,
-    role: 'worker',
+    agent: 'worker',
     cwd: root,
     permission: 'none',
   });
@@ -1156,7 +1277,7 @@ setInternalToolsProvider({
     provider: 'openai-oauth',
     model: 'tool-smoke-model',
     owner: AGENT_OWNER,
-    role: 'worker',
+    agent: 'worker',
     cwd: root,
     permission: { allow: ['read', 'grep'], deny: ['grep'] },
   });
@@ -1169,55 +1290,55 @@ setInternalToolsProvider({
   } finally {
     closeSession(objectPermissionSession.id, 'tool-smoke');
   }
-  const hiddenRoles = JSON.parse(readFileSync(join(root, 'src', 'defaults', 'hidden-roles.json'), 'utf8')).roles || [];
+  const hiddenAgents = JSON.parse(readFileSync(join(root, 'src', 'defaults', 'agents.json'), 'utf8')).agents || [];
   const hiddenPreset = { id: 'hidden-smoke', name: 'hidden-smoke', type: 'agent', provider: 'openai-oauth', model: 'tool-smoke-model', tools: 'full' };
   const hiddenRuntimeSpec = { scopeKey: 'hidden-role-smoke', lane: 'agent' };
   const hiddenBadTools = new Set(['shell', 'task', 'diagnostics', 'open_config', 'Skill', 'memory', 'reply', 'edit_message', 'recall', 'reload_config', 'inject_command']);
-  const expectedForHiddenRole = (permission, schemaAllowedTools) => {
+  const expectedForHiddenAgent = (permission, schemaAllowedTools) => {
     if (Array.isArray(schemaAllowedTools)) return schemaAllowedTools.slice();
     if (permission === 'none') return [];
     if (permission === 'read') return ['code_graph', 'find', 'glob', 'list', 'grep', 'read', 'explore', 'search', 'web_fetch'];
     if (permission === 'read-write') return ['code_graph', 'find', 'glob', 'list', 'grep', 'read', 'apply_patch', 'explore', 'search', 'web_fetch'];
     return null;
   };
-  for (const entry of hiddenRoles) {
-    const role = String(entry?.name || '').trim();
-    if (!role) continue;
-    const hidden = getHiddenRole(role);
-    const permission = resolveAgentSessionPermission(role, hidden?.permission || null);
+  for (const entry of hiddenAgents) {
+    const agent = String(entry?.agent || '').trim();
+    if (!agent) continue;
+    const hidden = getHiddenAgent(agent);
+    const permission = resolveAgentSessionPermission(agent, hidden?.permission || null);
     const schemaAllowedTools = resolveHiddenRoleSchemaAllowedTools(hidden);
     const { session } = prepareAgentSession({
-      role,
+      agent,
       presetName: 'hidden-smoke',
       preset: hiddenPreset,
       runtimeSpec: hiddenRuntimeSpec,
       permission,
       cwd: root,
       sourceType: 'hidden-role-smoke',
-      sourceName: role,
+      sourceName: agent,
       schemaAllowedTools,
     });
     try {
       const tools = (session.tools || []).map((tool) => tool?.name).filter(Boolean);
       const resumed = await resumeSession(session.id, 'full');
       const resumedTools = (resumed?.tools || []).map((tool) => tool?.name).filter(Boolean);
-      const expected = expectedForHiddenRole(permission, schemaAllowedTools);
+      const expected = expectedForHiddenAgent(permission, schemaAllowedTools);
       if (expected && (JSON.stringify(tools) !== JSON.stringify(expected) || JSON.stringify(resumedTools) !== JSON.stringify(expected))) {
-        throw new Error(`hidden role ${role} schema mismatch: expected=${expected.join(', ')} tools=${tools.join(', ')} resumed=${resumedTools.join(', ')}`);
+        throw new Error(`hidden agent ${agent} schema mismatch: expected=${expected.join(', ')} tools=${tools.join(', ')} resumed=${resumedTools.join(', ')}`);
       }
       const leaked = tools.filter((name) => hiddenBadTools.has(name) && !(expected || []).includes(name));
       if (leaked.length) {
-        throw new Error(`hidden role ${role} leaked forbidden full-runtime tools: ${leaked.join(', ')} from ${tools.join(', ')}`);
+        throw new Error(`hidden agent ${agent} leaked forbidden full-runtime tools: ${leaked.join(', ')} from ${tools.join(', ')}`);
       }
       const systemVisible = (session.messages || [])
         .filter((m) => m?.role === 'system')
         .map((m) => String(m.content || ''))
         .join('\n');
       if (/available-skills|Skill\(/i.test(systemVisible)) {
-        throw new Error(`hidden role ${role} must not carry Skill manifest without Skill tool`);
+        throw new Error(`hidden agent ${agent} must not carry Skill manifest without Skill tool`);
       }
       if (/effective-cwd|Override cwd|# environment|# task-brief/i.test(systemVisible)) {
-        throw new Error(`hidden role ${role} must not carry cwd/environment/task-brief injection`);
+        throw new Error(`hidden agent ${agent} must not carry cwd/environment/task-brief injection`);
       }
     } finally {
       closeSession(session.id, 'tool-smoke');
@@ -1311,21 +1432,93 @@ for (const requiredGrammarLine of [
     throw new Error(`custom apply_patch SSE parser must eager-emit patch args: ${JSON.stringify(emitted)}`);
   }
 }
-const readPathDescription = BUILTIN_TOOLS.find((tool) => tool.name === 'read')?.inputSchema?.properties?.path?.description || '';
-if (!/File path or array/i.test(readPathDescription) || !/Dirs use list/i.test(readPathDescription)) {
+const readPathSchema = BUILTIN_TOOLS.find((tool) => tool.name === 'read')?.inputSchema?.properties?.path || {};
+const readPathDescription = readPathSchema.description || '';
+if (!/File path/i.test(readPathDescription) || !/\{path,offset,limit\}\[\]/i.test(readPathDescription) || !/Pass arrays directly/i.test(readPathDescription) || !/legacy recovery only/i.test(readPathDescription)) {
   throw new Error('read schema must keep directory-vs-file guidance');
 }
-const readDescription = BUILTIN_TOOLS.find((tool) => tool.name === 'read')?.description || '';
-if (!/known file path\(s\)/i.test(readDescription) || !/line\+context/i.test(readDescription)) {
-  throw new Error('read description must stay narrow-target oriented');
+if (!/Dirs use list/i.test((BUILTIN_TOOLS.find((tool) => tool.name === 'read')?.description) || '')) {
+  throw new Error('read description must keep directory-vs-file guidance');
+}
+const readTool = BUILTIN_TOOLS.find((tool) => tool.name === 'read');
+const readDescription = readTool?.description || '';
+const readProps = readTool?.inputSchema?.properties || {};
+const readArraySchema = readPathSchema.anyOf?.find((entry) => entry?.type === 'array');
+const readArrayItemAnyOf = readArraySchema?.items?.anyOf || [];
+if (!readArrayItemAnyOf.some((entry) => entry?.type === 'object' && entry?.properties?.offset && entry?.properties?.limit)) {
+  throw new Error('read schema must expose array-of-region objects for batched spans');
+}
+if (/line\+context/i.test(readDescription) || !/numeric offset\+limit/i.test(readDescription) || !/Batch paths\/regions as real arrays/i.test(readDescription) || !/grep content_with_context or code_graph anchors/i.test(readDescription)) {
+  throw new Error('read description must expose offset/limit as the single window form');
+}
+if (readProps.line || readProps.context) {
+  throw new Error('read schema must not expose legacy line/context window fields');
+}
+if (readProps.offset?.minimum !== 0 || !/Numeric lines to skip/i.test(readProps.offset?.description || '') || !/offset:N/i.test(readProps.offset?.description || '') || !/Numeric max lines/i.test(readProps.limit?.description || '')) {
+  throw new Error('read offset schema must describe Mixdog paging cursor semantics');
+}
+if (/line\/context/i.test(JSON.stringify(readTool?.inputSchema || {}))) {
+  throw new Error('read schema surface must not mention legacy line/context');
+}
+{
+  const benchRunSrc = readFileSync(resolve(root, 'scripts/bench-run.mjs'), 'utf8');
+  if (!/task_complete:\s*results\.length > 0 && completed === results\.length/.test(benchRunSrc)) {
+    throw new Error('bench-run must require every task to complete before saving a round');
+  }
+  if (!/score_complete:\s*results\.length > 0 && taskErrors\.length === 0 && scoreErrors\.length === 0 && \(score\?\.cards\?\.length \|\| 0\) === results\.length/.test(benchRunSrc)) {
+    throw new Error('bench-run must require a scorecard for every task before saving a round');
+  }
+  if (!/not saving incomplete round/.test(benchRunSrc) || !/process\.exit\(1\)/.test(benchRunSrc)) {
+    throw new Error('bench-run must not save incomplete rounds and must exit non-zero');
+  }
+  const taskBenchSrc = readFileSync(resolve(root, 'scripts/task-bench.mjs'), 'utf8');
+  if (!/const allowPartial = hasFlag\('--allow-partial'\)/.test(taskBenchSrc) || !/skipped\.length && !allowPartial/.test(taskBenchSrc) || !/process\.exit\(1\)/.test(taskBenchSrc)) {
+    throw new Error('task-bench must fail partial scoring unless --allow-partial is explicit');
+  }
+}
+{
+  // setRoute must default to "next session only": a bare
+  // runtime.setRoute({model}) call (no options) must NOT rewrite a live
+  // session's provider/model in place, or a mid-conversation model/provider
+  // switch silently forces a full prompt-cache rewrite (seen as a
+  // promptΔ spike + cache_ratio=0% turn in session-bench).
+  const runtimeSrc = readFileSync(resolve(root, 'src/mixdog-session-runtime.mjs'), 'utf8');
+  const setRouteBlock = runtimeSrc.match(/async setRoute\(next, options = \{\}\) \{[\s\S]*?\n    \},\n/)?.[0] || '';
+  if (!/applyToCurrentSession = options\?\.applyToCurrentSession === true/.test(setRouteBlock)) {
+    throw new Error('setRoute must default applyToCurrentSession to false (model changes apply to the next session only)');
+  }
+  if (!/if \(!applyToCurrentSession\)/.test(setRouteBlock) || !/return route;/.test(setRouteBlock)) {
+    throw new Error('setRoute must early-return before touching the live session when applyToCurrentSession is false');
+  }
+  const engineSrc = readFileSync(resolve(root, 'src/tui/engine.mjs'), 'utf8');
+  if (/setRoute\(\{ model: m \}, \{ applyToCurrentSession: true \}\)/.test(engineSrc)) {
+    throw new Error('TUI setModel must not force applyToCurrentSession:true (model changes must apply to the next session only)');
+  }
+  if (!/routeOpts\.applyToCurrentSession === true/.test(engineSrc)) {
+    throw new Error('TUI setRoute wrapper must default applyToCurrentSession to false');
+  }
 }
 const codeGraphDescription = CODE_GRAPH_TOOL_DEFS[0]?.description || '';
 const codeGraphProps = CODE_GRAPH_TOOL_DEFS[0]?.inputSchema?.properties || {};
-if (!/Code structure/i.test(codeGraphDescription) || !/symbols/i.test(codeGraphDescription) || codeGraphDescription.length > 90) {
-  throw new Error('code_graph description must stay compact and structure-oriented');
+const codeGraphSymbolSearchErr = validateBuiltinArgs('code_graph', { mode: 'symbol_search', symbols: ['hook', 'deny'], limit: 5 });
+if (codeGraphSymbolSearchErr) {
+  throw new Error(`code_graph guard must accept symbol_search with symbols[] batching: ${codeGraphSymbolSearchErr}`);
+}
+// code_graph description stays structure-oriented and must actively route
+// symbol/definition/caller lookups AWAY from repeated grep (the grep_retry +
+// find_symbol_noscope anti-patterns). It is allowed to be verbose enough to
+// enumerate modes, but must not drift into web-search territory.
+if (!/code structure\/flow/i.test(codeGraphDescription) || !/symbols\/references\/calls\/deps/i.test(codeGraphDescription)) {
+  throw new Error('code_graph description must stay structure-oriented and name its symbol modes');
+}
+if (!/before text grep/i.test(codeGraphDescription)) {
+  throw new Error('code_graph description must steer symbol/caller lookups to structure lookup before grep');
 }
-if (!/^Operation\.$/i.test(codeGraphProps.mode?.description || '') || !/^Source file\.$/i.test(codeGraphProps.file?.description || '')) {
-  throw new Error('code_graph schema must keep compact field descriptions');
+if (!/repo-local/i.test(codeGraphDescription) || !/NOT web search|not web/i.test(codeGraphDescription)) {
+  throw new Error('code_graph description must mark itself repo-local (not web search)');
+}
+if (!/repo-local|not web/i.test(codeGraphProps.mode?.description || '') || !/source file/i.test(codeGraphProps.file?.description || '')) {
+  throw new Error('code_graph schema must keep compact, repo-local field descriptions');
 }
 const recallTool = MEMORY_TOOL_DEFS.find((tool) => tool.name === 'recall');
 const recallProps = recallTool?.inputSchema?.properties || {};
@@ -1572,13 +1765,63 @@ if (!/NOT for URLs/i.test(fetchTool?.description || '') || !/web_fetch/i.test(fe
 const grepTool = BUILTIN_TOOLS.find((tool) => tool.name === 'grep');
 const grepPatternDescription = grepTool?.inputSchema?.properties?.pattern?.description || '';
 const grepPathDescription = grepTool?.inputSchema?.properties?.path?.description || '';
-if (!/Array = OR/i.test(grepPatternDescription) || !/^File or directory\.$/i.test(grepPathDescription)) {
+const grepGlobDescription = grepTool?.inputSchema?.properties?.glob?.description || '';
+const grepOutputModeDescription = grepTool?.inputSchema?.properties?.output_mode?.description || '';
+const grepHeadLimitDescription = grepTool?.inputSchema?.properties?.head_limit?.description || '';
+if (!/synonyms in pattern\[\]/i.test(grepPatternDescription) || !/OR in ONE grep/i.test(grepPatternDescription) || !/serial rewording/i.test(grepPatternDescription) || !/equivalent repeats/i.test(grepPatternDescription) || !/Narrowest file\/dir/i.test(grepPathDescription) || !/broad scopes return paths first/i.test(grepPathDescription) || !/refine from returned paths/i.test(grepPathDescription)) {
   throw new Error('grep schema must keep compact pattern/path guidance');
 }
+if (!/same grep/i.test(grepGlobDescription) || !/no follow-up grep/i.test(grepGlobDescription) || !/equivalent scope changes/i.test(grepGlobDescription)) {
+  throw new Error('grep glob schema must steer narrowing into the same grep call');
+}
+if (!/Broad scope: files_with_matches\/count/i.test(grepOutputModeDescription) || !/Narrow scope: content_with_context/i.test(grepOutputModeDescription) || !/answer from/i.test(grepOutputModeDescription) || !/skip read/i.test(grepOutputModeDescription) || !/span is not shown/i.test(grepOutputModeDescription)) {
+  throw new Error('grep output_mode schema must steer content_with_context away from follow-up reads');
+}
+if (grepTool?.inputSchema?.properties?.head_limit?.minimum !== 0 || !/keep small/i.test(grepHeadLimitDescription)) {
+  throw new Error('grep head_limit schema must keep locator caps explicit');
+}
+if (grepTool?.inputSchema?.properties?.type) {
+  throw new Error('grep type schema must stay hidden; prefer glob for extension narrowing');
+}
+if (!/code flow before text search/i.test(codeGraphProps.mode?.description || '') || !/one anchor is enough/i.test(codeGraphProps.symbol?.description || '') || !/one call/i.test(codeGraphProps.symbols?.description || '')) {
+  throw new Error('code_graph schema fields must steer away from repeated lookup loops');
+}
 
 const longToolSearchText = compactToolSearchDescription(`${patchDescription}\n${patchDescription}`);
 if (longToolSearchText.length > 220 || /\n/.test(longToolSearchText)) {
   throw new Error(`tool_search descriptions must be compact single-line snippets, got ${longToolSearchText.length} chars`);
 }
 
+{
+  // Regression guard for the sonnet-5 16384 cap bug (thinking exhausted the
+  // whole output budget). Both the catalog path (outputTokens=128000 → capped
+  // 65536) and the catalog-miss heuristic (sonnet 5+ → 65536) must yield
+  // 65536, so assert the exact value with the env override cleared.
+  const _prevMaxOut = process.env.MIXDOG_ANTHROPIC_MAX_OUTPUT_TOKENS;
+  delete process.env.MIXDOG_ANTHROPIC_MAX_OUTPUT_TOKENS;
+  try {
+    const sonnet5MaxTokens = _anthropicOAuthTest.resolveMaxTokens('claude-sonnet-5');
+    if (sonnet5MaxTokens !== 65536) {
+      throw new Error(`resolveMaxTokens('claude-sonnet-5') must be 65536 (catalog-capped or sonnet-5+ fallback), got ${sonnet5MaxTokens}`);
+    }
+    const sonnet46MaxTokens = _anthropicOAuthTest.resolveMaxTokens('claude-sonnet-4-6');
+    if (!(sonnet46MaxTokens >= 16384)) {
+      throw new Error(`resolveMaxTokens('claude-sonnet-4-6') must be >= 16384, got ${sonnet46MaxTokens}`);
+    }
+    process.env.MIXDOG_ANTHROPIC_MAX_OUTPUT_TOKENS = 'garbage';
+    const garbageOverride = _anthropicOAuthTest.resolveMaxTokens('claude-sonnet-5');
+    if (garbageOverride !== 65536) {
+      throw new Error(`invalid MIXDOG_ANTHROPIC_MAX_OUTPUT_TOKENS must be ignored (catalog/fallback path), got ${garbageOverride}`);
+    }
+    process.env.MIXDOG_ANTHROPIC_MAX_OUTPUT_TOKENS = '32768';
+    const validOverride = _anthropicOAuthTest.resolveMaxTokens('claude-sonnet-5');
+    if (validOverride !== 32768) {
+      throw new Error(`valid MIXDOG_ANTHROPIC_MAX_OUTPUT_TOKENS=32768 must win, got ${validOverride}`);
+    }
+  } finally {
+    if (_prevMaxOut === undefined) delete process.env.MIXDOG_ANTHROPIC_MAX_OUTPUT_TOKENS;
+    else process.env.MIXDOG_ANTHROPIC_MAX_OUTPUT_TOKENS = _prevMaxOut;
+  }
+}
+
 process.stdout.write(`tool smoke passed surface_chars=${surfaceSize}\n`);