@shawnstack/quickforge 1.6.7 → 1.6.9

package/server/agent-manager.mjs

@@ -1,5 +1,7 @@
 import { EventEmitter } from 'node:events'
 import { randomUUID } from 'node:crypto'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
 import { Agent } from '@earendil-works/pi-agent-core'
 import { streamSimpleWithAiHttpLogging } from './ai-http-logger.mjs'
 import { loadSkillToolContext, abortRunningCommand } from './tools/index.mjs'
@@ -11,8 +13,20 @@ import {
   formatSubagentTask,
 } from './subagents.mjs'
 import { agentProfileSnapshot, getAgentProfile } from './agent-profiles.mjs'
+import { agentProfileFromMarkdown } from './agent-profile-files.mjs'
+import {
+  applyCapabilityPolicy,
+  inferCapabilityPolicy,
+  modelReferenceSnapshot,
+  normalizeCapabilityPolicy,
+  normalizeModelReference,
+  resolveAgentProfileModel,
+  resolveAgentProfileThinkingLevel,
+  validateAgentProfileTools,
+  validateModelReference,
+} from './agent-profile-schema.mjs'
 import { projectContextFromId, defaultGlobalWorkspaceContext, readProjectConfig } from './project-config.mjs'
-import { readStore, atomicUpdate, atomicSessionMetadataUpdate, readSessionValue, writeSessionValue, deleteSessionValue } from './storage.mjs'
+import { ensureStorage, readStore, atomicUpdate, atomicSessionMetadataUpdate, readSessionValue, writeSessionValue, deleteSessionValue, tempAgentsDir } from './storage.mjs'
 import { logger } from './utils/logger.mjs'
 import { buildSystemPrompt, generateAiTitle, generateTitle } from './session-utils.mjs'
 import { restoreReasoningContentInPayload } from './reasoning-cache.mjs'
@@ -385,6 +399,21 @@ function addToolTimingToEvent(session, event) {
   return event
 }
 
+export function markLatestAssistantProcessFinished(messages, finishedAt = Date.now()) {
+  if (!Array.isArray(messages)) return false
+  for (let index = messages.length - 1; index >= 0; index--) {
+    const message = messages[index]
+    if (!message || message.role !== 'assistant') continue
+    const details = message.details && typeof message.details === 'object' && !Array.isArray(message.details)
+      ? message.details
+      : {}
+    if (details.quickforgeProcessFinishedAt !== undefined) return false
+    messages[index] = { ...message, details: { ...details, quickforgeProcessFinishedAt: finishedAt } }
+    return true
+  }
+  return false
+}
+
 function updateSessionMessages(session, messages) {
   session.agent.state.messages = messages
 }
@@ -831,10 +860,109 @@ ${scopeText}
 </review_command_invocation>`
 }
 
+const tempSubagentNameRegex = /^[a-z][a-z0-9_-]{1,39}$/
+
+function frontmatterString(value) {
+  return String(value ?? '').replace(/\r?\n/g, ' ').replace(/"/g, '\\"')
+}
+
+function normalizeTemporarySubagentSpec(input) {
+  const spec = input && typeof input === 'object' && !Array.isArray(input) ? input : null
+  if (!spec || spec.type !== 'temporary') return null
+  const name = String(spec.name || '').trim().toLowerCase()
+  if (!tempSubagentNameRegex.test(name)) {
+    const error = new Error('Temporary subagent name must start with a letter and contain only lowercase letters, numbers, underscores, or hyphens')
+    error.statusCode = 400
+    throw error
+  }
+  const instructions = String(spec.instructions || '').trim()
+  if (!instructions) {
+    const error = new Error('Temporary subagent instructions are required')
+    error.statusCode = 400
+    throw error
+  }
+  const requestedTools = Array.isArray(spec.tools)
+    ? [...new Set(spec.tools.map((toolName) => String(toolName || '').trim()).filter(Boolean))]
+    : ['read_file', 'grep_files', 'run_command']
+  const capabilityPolicy = normalizeCapabilityPolicy(spec.capabilityPolicy || 'readonly-research', requestedTools)
+  validateAgentProfileTools(requestedTools, capabilityPolicy)
+  const allowedTools = applyCapabilityPolicy(requestedTools, capabilityPolicy)
+  const model = validateModelReference(normalizeModelReference(spec.model))
+  return {
+    name,
+    label: String(spec.label || spec.description || name).trim().slice(0, 80) || name,
+    description: String(spec.description || '').trim().slice(0, 500),
+    systemPrompt: instructions,
+    allowedTools,
+    capabilityPolicy,
+    model,
+    maxRuntimeMs: spec.maxRuntimeMs,
+    maxToolCalls: spec.maxToolCalls,
+  }
+}
+
+function safeTempPathSegment(value, fallback) {
+  const text = String(value || '').replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 80)
+  return text || fallback
+}
+
+function temporarySubagentMarkdown(spec, parentSession, runId, expiresAt) {
+  return `---
+name: ${spec.name}
+label: "${frontmatterString(spec.label)}"
+description: "${frontmatterString(spec.description)}"
+source: temporary
+lifecycle: temporary
+createdBy: ai
+createdAt: ${new Date().toISOString()}
+parentSessionId: ${frontmatterString(parentSession.sessionId)}
+runId: ${runId}
+expiresAt: ${expiresAt}
+enabled-as-subagent: true
+capabilityPolicy: ${spec.capabilityPolicy}
+tools: ${spec.allowedTools.join(', ')}
+model:
+  mode: ${spec.model?.mode === 'fixed' ? 'fixed' : 'inherit'}${spec.model?.mode === 'fixed' ? `
+  provider: ${frontmatterString(spec.model.provider)}
+  modelId: ${frontmatterString(spec.model.modelId)}${spec.model.api ? `
+  api: ${frontmatterString(spec.model.api)}` : ''}${spec.model.baseUrl ? `
+  baseUrl: ${frontmatterString(spec.model.baseUrl)}` : ''}` : ''}
+max-runtime-ms: ${Math.max(1000, Math.min(Number(spec.maxRuntimeMs || SUBAGENT_DEFAULT_TIMEOUT_MS), 30 * 60 * 1000))}
+max-tool-calls: ${Math.max(1, Math.min(Number(spec.maxToolCalls || 300), 300))}
+---
+${spec.systemPrompt}
+`
+}
+
+async function createTemporarySubagentProfile(parentSession, spec) {
+  await ensureStorage()
+  const runId = `run_${Date.now()}_${randomUUID().slice(0, 8)}`
+  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString()
+  const dir = path.join(tempAgentsDir, safeTempPathSegment(parentSession.sessionId, 'session'), runId)
+  await fs.mkdir(dir, { recursive: true })
+  const file = path.join(dir, `${spec.name}.md`)
+  const markdown = temporarySubagentMarkdown(spec, parentSession, runId, expiresAt)
+  await fs.writeFile(file, markdown, 'utf8')
+  const profile = agentProfileFromMarkdown(file, markdown, {
+    source: 'temporary',
+    idPrefix: `temporary:${safeTempPathSegment(parentSession.sessionId, 'session')}:${runId}`,
+    relativePath: path.relative(tempAgentsDir, file).replace(/\\/g, '/'),
+  })
+  if (!profile) throw new Error('Failed to create temporary subagent profile')
+  profile.readonly = true
+  return profile
+}
+
+async function resolveSubagentProfile(parentSession, requestedSubagent) {
+  const temporarySpec = normalizeTemporarySubagentSpec(requestedSubagent)
+  if (temporarySpec) return createTemporarySubagentProfile(parentSession, temporarySpec)
+  return getAgentProfile(requestedSubagent, { workspaceRoot: parentSession.projectContext?.workspaceRoot })
+}
+
 async function runSubagent(parentSession, params, parentSignal, onUpdate) {
-  const profile = await getAgentProfile(params?.subagent, { workspaceRoot: parentSession.projectContext?.workspaceRoot })
+  const profile = await resolveSubagentProfile(parentSession, params?.subagent)
   if (!profile || !profile.enabledAsSubagent) {
-    const error = new Error(`Unknown or disabled subagent: ${params?.subagent || ''}`)
+    const error = new Error(`Unknown or disabled subagent: ${typeof params?.subagent === 'string' ? params.subagent : params?.subagent?.name || ''}`)
     error.statusCode = 400
     throw error
   }
@@ -854,6 +982,10 @@ async function runSubagent(parentSession, params, parentSignal, onUpdate) {
   }
 
   const timeoutMs = Math.max(1000, Math.min(Number(definition.maxRuntimeMs || SUBAGENT_DEFAULT_TIMEOUT_MS), 30 * 60 * 1000))
+  definition.capabilityPolicy ||= inferCapabilityPolicy(definition.allowedTools || [])
+  definition.allowedTools = applyCapabilityPolicy(definition.allowedTools || [], definition.capabilityPolicy)
+  const { model: subagentModel, info: subagentModelInfo } = await resolveAgentProfileModel(definition, parentSession.model, readStore)
+  const subagentThinkingLevel = resolveAgentProfileThinkingLevel(definition, parentSession.thinkingLevel, subagentModel)
   const subagentSessionId = `${parentSession.sessionId}:subagent:${definition.name}:${randomUUID()}`
   const startedAt = Date.now()
   let toolCalls = 0
@@ -898,6 +1030,11 @@ async function runSubagent(parentSession, params, parentSignal, onUpdate) {
         toolCalls,
         allowedTools: definition.allowedTools,
         timeoutMs,
+        source: definition.source,
+        lifecycle: definition.lifecycle,
+        profilePath: definition.filePath,
+        capabilityPolicy: definition.capabilityPolicy,
+        model: subagentModelInfo,
         durationMs: Date.now() - startedAt,
         messages: latestMessages,
         tools: toolsForClient,
@@ -932,8 +1069,8 @@ async function runSubagent(parentSession, params, parentSignal, onUpdate) {
   const subagent = new Agent({
     initialState: {
       systemPrompt,
-      model: parentSession.model,
-      thinkingLevel: parentSession.thinkingLevel,
+      model: subagentModel,
+      thinkingLevel: subagentThinkingLevel,
       messages: [],
       tools,
     },
@@ -1013,6 +1150,11 @@ async function runSubagent(parentSession, params, parentSignal, onUpdate) {
       toolCalls,
       allowedTools: definition.allowedTools,
       timeoutMs,
+      source: definition.source,
+      lifecycle: definition.lifecycle,
+      profilePath: definition.filePath,
+      capabilityPolicy: definition.capabilityPolicy,
+      model: subagentModelInfo,
       durationMs: Date.now() - startedAt,
       messages: latestMessages,
       tools: toolsForClient,
@@ -1229,6 +1371,8 @@ export async function createAgent(sessionId, config = {}) {
   const profileSystemPrompt = agentProfile?.systemPrompt ? `\n\n<agent_profile_instructions>\nAgent Profile: ${agentProfile.label || agentProfile.name}\n${agentProfile.systemPrompt}\n</agent_profile_instructions>` : ''
   const resolvedSystemPrompt = systemPrompt ?? `${await buildSystemPrompt(projectId)}${profileSystemPrompt}`
 
+  let resolvedAgentProfile = agentProfile
+
   // Resolve model
   let resolvedModel = model
   if (!resolvedModel) {
@@ -1241,6 +1385,17 @@ export async function createAgent(sessionId, config = {}) {
       // ignore
     }
   }
+  if (agentProfile?.model?.mode === 'fixed') {
+    resolvedModel = (await resolveAgentProfileModel(agentProfile, resolvedModel, readStore)).model
+    resolvedAgentProfile = {
+      ...agentProfile,
+      model: modelReferenceSnapshot(agentProfile.model),
+    }
+  }
+  if (resolvedAgentProfile && !resolvedModel) throw new Error('No active model is configured for the agent session.')
+  const resolvedThinkingLevel = agentProfile
+    ? resolveAgentProfileThinkingLevel(agentProfile, thinkingLevel, resolvedModel)
+    : thinkingLevel
 
   // Build skills tools for enabled skills, plus workspace tools when a project is available.
   const profileToolNames = Array.isArray(agentProfile?.allowedTools) ? agentProfile.allowedTools : null
@@ -1279,7 +1434,7 @@ export async function createAgent(sessionId, config = {}) {
     initialState: {
       systemPrompt: resolvedSystemPrompt,
       model: resolvedModel,
-      thinkingLevel,
+      thinkingLevel: resolvedThinkingLevel,
       messages,
       tools,
     },
@@ -1300,7 +1455,14 @@ export async function createAgent(sessionId, config = {}) {
       const isSkillTool = toolName === 'activate_skill' || toolName === 'read_skill_resource'
       if (isSkillTool) return undefined
       if (profileToolNames && !profileToolNames.includes(toolName)) return { block: true, reason: `Agent profile ${agentProfile.name} is not allowed to use ${toolName}.` }
-      if (toolName === 'run_subagent') return undefined
+      if (toolName === 'run_subagent') {
+        const requested = context.args?.subagent
+        const policy = requested && typeof requested === 'object' ? normalizeCapabilityPolicy(requested.capabilityPolicy || 'readonly-research', Array.isArray(requested.tools) ? requested.tools : []) : null
+        if (policy && ['code-edit', 'docs-edit'].includes(policy) && !hasFullAccess(currentSession)) {
+          return { block: true, reason: `Temporary subagent capability policy ${policy} requires full access or approval.` }
+        }
+        return undefined
+      }
       if (isMcpToolName(toolName) || isPluginToolName(toolName)) {
         if (!hasFullAccess(currentSession)) return createApprovalPromise(currentSession, toolCallId, toolName, context.args)
         return undefined
@@ -1328,7 +1490,7 @@ export async function createAgent(sessionId, config = {}) {
     accessMode,
     yoloMode: resolvedYoloMode,
     model: resolvedModel,
-    thinkingLevel,
+    thinkingLevel: resolvedThinkingLevel,
     scope,
     title,
     createdAt,
@@ -1348,7 +1510,7 @@ export async function createAgent(sessionId, config = {}) {
     toolTimings: new Map(),
     getApiKey,
     contextCompaction,
-    agentProfile: agentProfile ? agentProfileSnapshot(agentProfile) : null,
+    agentProfile: resolvedAgentProfile ? agentProfileSnapshot(resolvedAgentProfile) : null,
     idleRetention,
     lastTransformedContextMessages: null,
     autoCompacting: false,
@@ -1374,6 +1536,9 @@ export async function createAgent(sessionId, config = {}) {
           ? 'error'
           : 'idle'
       : undefined
+    if (timedEvent.type === 'agent_end') {
+      markLatestAssistantProcessFinished(agent.state.messages)
+    }
     const forwardEvent = timedEvent.type === 'agent_end'
       ? {
           ...timedEvent,

package/server/agent-profile-files.mjs

@@ -1,9 +1,10 @@
 import { existsSync, promises as fs } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
-import { dataDir } from './storage.mjs'
+import { userAgentsDir } from './storage.mjs'
 import { logger } from './utils/logger.mjs'
 import { firstOptionalBoolean, firstString, parseFrontmatter, splitDelimitedList } from './frontmatter.mjs'
+import { normalizeAgentProfileThinkingLevel, normalizeCapabilityPolicy, normalizeModelReference, validateAgentProfileTools, validateModelReference } from './agent-profile-schema.mjs'
 
 const DEFAULT_MAX_RUNTIME_MS = 30 * 60 * 1000
 const DEFAULT_MAX_TOOL_CALLS = 300
@@ -19,7 +20,6 @@ const toolAliases = new Map([
 ])
 
 const claudeUserAgentsDir = path.join(os.homedir(), '.claude', 'agents')
-const userAgentsDir = path.join(dataDir, 'agents')
 
 function normalizeString(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : undefined
@@ -60,6 +60,64 @@ function hasMutationTool(allowedTools) {
   return allowedTools.some((toolName) => toolName === 'write_file' || toolName === 'edit_file')
 }
 
+function quoteFrontmatter(value) {
+  return `"${String(value ?? '').replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\r?\n/g, ' ')}"`
+}
+
+function formatModelFrontmatter(model) {
+  if (!model || model.mode !== 'fixed') return 'model:\n  mode: inherit'
+  return [
+    'model:',
+    '  mode: fixed',
+    `  provider: ${quoteFrontmatter(model.provider)}`,
+    `  modelId: ${quoteFrontmatter(model.modelId)}`,
+    model.api ? `  api: ${quoteFrontmatter(model.api)}` : '',
+    model.baseUrl ? `  baseUrl: ${quoteFrontmatter(model.baseUrl)}` : '',
+  ].filter(Boolean).join('\n')
+}
+
+export function userAgentProfileFilePath(name) {
+  const normalized = normalizeName(name)
+  if (!normalized) throw new Error('Invalid agent profile name')
+  return path.join(userAgentsDir, `${normalized}.md`)
+}
+
+export function agentProfileToMarkdown(profile) {
+  return `---
+id: ${quoteFrontmatter(profile.id)}
+name: ${profile.name}
+label: ${quoteFrontmatter(profile.label || profile.name)}
+description: ${quoteFrontmatter(profile.description || '')}
+source: user
+lifecycle: persistent
+managed: true
+managedBy: quickforge
+readonly: false
+enabled-as-subagent: ${profile.enabledAsSubagent === true ? 'true' : 'false'}
+capabilityPolicy: ${profile.capabilityPolicy || 'review-only'}
+tools: ${(profile.allowedTools || []).join(', ')}
+${formatModelFrontmatter(profile.model)}
+thinking-level: ${normalizeAgentProfileThinkingLevel(profile.thinkingLevel)}
+max-runtime-ms: ${profile.maxRuntimeMs || DEFAULT_MAX_RUNTIME_MS}
+max-tool-calls: ${profile.maxToolCalls || DEFAULT_MAX_TOOL_CALLS}
+created-at: ${quoteFrontmatter(profile.createdAt || new Date().toISOString())}
+updated-at: ${quoteFrontmatter(profile.updatedAt || new Date().toISOString())}
+---
+${String(profile.systemPrompt || '').trim()}
+`
+}
+
+export async function writeUserAgentProfileMarkdown(profile) {
+  await fs.mkdir(userAgentsDir, { recursive: true })
+  const file = userAgentProfileFilePath(profile.name)
+  await fs.writeFile(file, agentProfileToMarkdown(profile), 'utf8')
+  return file
+}
+
+export async function deleteUserAgentProfileMarkdown(profile) {
+  await fs.rm(userAgentProfileFilePath(profile.name), { force: true })
+}
+
 export function agentProfileFromMarkdown(file, text, options = {}) {
   const parsed = parseFrontmatter(text)
   if (!parsed.body) return null
@@ -72,30 +130,52 @@ export function agentProfileFromMarkdown(file, text, options = {}) {
   const allowedTools = normalizeTools(
     metadata.tools ?? metadata['allowed-tools'] ?? metadata.allowedTools,
   )
+  const capabilityPolicy = normalizeCapabilityPolicy(
+    metadata.capabilityPolicy ?? metadata['capability-policy'] ?? metadata.capability_policy,
+    allowedTools,
+  )
+  validateAgentProfileTools(allowedTools, capabilityPolicy)
+  const model = validateModelReference(normalizeModelReference(metadata.model, metadata))
   const label = firstString(metadata.label, metadata.displayName, metadata.title) || name
   const enabledAsSubagent = firstOptionalBoolean(
     metadata['enabled-as-subagent'],
     metadata.enabled_as_subagent,
     metadata.enabledAsSubagent,
   )
+  const source = firstString(metadata.source) || options.source || 'file'
+  const lifecycle = firstString(metadata.lifecycle) || (source === 'temporary' ? 'temporary' : 'persistent')
+  const explicitReadonly = firstOptionalBoolean(metadata.readonly, metadata['read-only'])
+  const managedBy = firstString(metadata.managedBy, metadata['managed-by'])
+  const profileId = firstString(metadata.id) || `${options.idPrefix || source || 'file'}:${name}`
 
   return {
-    id: `${options.idPrefix || 'file'}:${name}`,
+    id: profileId,
     name,
     label: label.slice(0, 80),
     description: String(firstString(metadata.description) || '').slice(0, 500),
     systemPrompt: parsed.body,
     allowedTools,
+    capabilityPolicy,
+    model,
+    thinkingLevel: normalizeAgentProfileThinkingLevel(
+      metadata['thinking-level'] ?? metadata.thinking_level ?? metadata.thinkingLevel,
+    ),
+    lifecycle,
+    managed: firstOptionalBoolean(metadata.managed) === true,
+    managedBy,
+    expiresAt: firstString(metadata.expiresAt, metadata['expires-at']),
+    parentSessionId: firstString(metadata.parentSessionId, metadata['parent-session-id']),
+    runId: firstString(metadata.runId, metadata['run-id']),
     maxRuntimeMs: normalizeRuntime(metadata['max-runtime-ms'] ?? metadata.max_runtime_ms ?? metadata.maxRuntimeMs),
     maxToolCalls: normalizeToolCalls(metadata['max-tool-calls'] ?? metadata.max_tool_calls ?? metadata.maxToolCalls),
     enabledAsSubagent: enabledAsSubagent === undefined ? true : enabledAsSubagent,
     builtin: false,
-    source: options.source || 'file',
-    readonly: true,
+    source,
+    readonly: explicitReadonly === undefined ? true : explicitReadonly,
     filePath: file,
     relativePath: options.relativePath || path.basename(file),
     allowFileMutations: hasMutationTool(allowedTools),
-    createdAt: 'file',
+    createdAt: firstString(metadata.createdAt, metadata['created-at']) || 'file',
     updatedAt: 'file',
   }
 }

package/server/agent-profile-schema.mjs

@@ -0,0 +1,197 @@
+export const AGENT_PROFILE_TOOL_NAMES = ['read_file', 'grep_files', 'write_file', 'edit_file', 'run_command']
+export const AGENT_PROFILE_MODEL_INHERIT = { mode: 'inherit' }
+export const AGENT_PROFILE_THINKING_LEVELS = ['inherit', 'off', 'low', 'medium', 'high', 'xhigh']
+
+const agentProfileThinkingLevels = new Set(AGENT_PROFILE_THINKING_LEVELS)
+
+export const CAPABILITY_POLICIES = {
+  'readonly-research': {
+    readonly: true,
+    allowedTools: ['read_file', 'grep_files', 'run_command'],
+  },
+  'safe-validation': {
+    readonly: true,
+    allowedTools: ['read_file', 'grep_files', 'run_command'],
+  },
+  'review-only': {
+    readonly: true,
+    allowedTools: ['read_file', 'grep_files'],
+  },
+  'docs-edit': {
+    readonly: false,
+    allowedTools: ['read_file', 'grep_files', 'write_file', 'edit_file'],
+    pathScope: ['docs/**', 'README.md', 'CHANGELOG.md'],
+  },
+  'code-edit': {
+    readonly: false,
+    allowedTools: ['read_file', 'grep_files', 'write_file', 'edit_file', 'run_command'],
+  },
+}
+
+const policyNames = new Set(Object.keys(CAPABILITY_POLICIES))
+const allowedToolNames = new Set(AGENT_PROFILE_TOOL_NAMES)
+
+function requestError(message, statusCode = 400) {
+  const error = new Error(message)
+  error.statusCode = statusCode
+  return error
+}
+
+function normalizeString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+function sameBaseUrl(a, b) {
+  return String(a || '').trim().replace(/\/$/, '') === String(b || '').trim().replace(/\/$/, '')
+}
+
+function readModelField(value, ...keys) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
+  for (const key of keys) {
+    const text = normalizeString(value[key])
+    if (text) return text
+  }
+  return undefined
+}
+
+export function inferCapabilityPolicy(allowedTools = []) {
+  if (allowedTools.some((toolName) => toolName === 'write_file' || toolName === 'edit_file')) return 'code-edit'
+  if (allowedTools.includes('run_command')) return 'readonly-research'
+  return 'review-only'
+}
+
+export function normalizeCapabilityPolicy(value, allowedTools = []) {
+  const policy = normalizeString(value)?.toLowerCase()
+  if (policy && policyNames.has(policy)) return policy
+  return inferCapabilityPolicy(allowedTools)
+}
+
+export function validateAgentProfileTools(allowedTools = [], capabilityPolicy = inferCapabilityPolicy(allowedTools)) {
+  const policy = CAPABILITY_POLICIES[capabilityPolicy]
+  if (!policy) throw requestError(`Unsupported capability policy: ${capabilityPolicy}`)
+  const allowedByPolicy = new Set(policy.allowedTools)
+  for (const toolName of allowedTools) {
+    if (!allowedToolNames.has(toolName)) throw requestError(`Unsupported tool for custom agent: ${toolName}`)
+    if (!allowedByPolicy.has(toolName)) throw requestError(`Tool ${toolName} is not allowed by capability policy ${capabilityPolicy}`)
+  }
+  return true
+}
+
+export function applyCapabilityPolicy(allowedTools = [], capabilityPolicy = inferCapabilityPolicy(allowedTools)) {
+  const policy = CAPABILITY_POLICIES[capabilityPolicy] || CAPABILITY_POLICIES['review-only']
+  const allowedByPolicy = new Set(policy.allowedTools)
+  return allowedTools.filter((toolName) => allowedByPolicy.has(toolName))
+}
+
+export function normalizeModelReference(input, metadata = {}) {
+  const modelValue = input === undefined ? metadata.model : input
+  const flatMode = normalizeString(metadata['model-mode'] ?? metadata.modelMode)?.toLowerCase()
+  const flatProvider = normalizeString(metadata['model-provider'] ?? metadata.modelProvider ?? metadata.provider)
+  const flatModelId = normalizeString(metadata['model-id'] ?? metadata.model_id ?? metadata.modelId)
+  const flatApi = normalizeString(metadata['model-api'] ?? metadata.modelApi ?? metadata.api)
+  const flatBaseUrl = normalizeString(metadata['model-base-url'] ?? metadata.modelBaseUrl ?? metadata.baseUrl)
+
+  if (flatMode === 'fixed' || flatProvider || flatModelId) {
+    return {
+      mode: 'fixed',
+      provider: flatProvider,
+      modelId: flatModelId,
+      api: flatApi,
+      baseUrl: flatBaseUrl,
+    }
+  }
+
+  if (modelValue === undefined || modelValue === null || modelValue === '') return { ...AGENT_PROFILE_MODEL_INHERIT }
+  if (typeof modelValue === 'string') {
+    const normalized = modelValue.trim().toLowerCase()
+    if (!normalized || normalized === 'inherit' || normalized === 'parent' || normalized === 'default') return { ...AGENT_PROFILE_MODEL_INHERIT }
+    const colon = modelValue.indexOf(':')
+    if (colon > 0) {
+      return {
+        mode: 'fixed',
+        provider: modelValue.slice(0, colon).trim(),
+        modelId: modelValue.slice(colon + 1).trim(),
+      }
+    }
+    return { ...AGENT_PROFILE_MODEL_INHERIT }
+  }
+  if (!modelValue || typeof modelValue !== 'object' || Array.isArray(modelValue)) return { ...AGENT_PROFILE_MODEL_INHERIT }
+
+  const mode = normalizeString(modelValue.mode)?.toLowerCase()
+  if (!mode || mode === 'inherit' || mode === 'parent' || mode === 'default') return { ...AGENT_PROFILE_MODEL_INHERIT }
+  if (mode !== 'fixed') return { ...AGENT_PROFILE_MODEL_INHERIT }
+
+  return {
+    mode: 'fixed',
+    provider: readModelField(modelValue, 'provider'),
+    modelId: readModelField(modelValue, 'modelId', 'model-id', 'model_id', 'id', 'model'),
+    api: readModelField(modelValue, 'api'),
+    baseUrl: readModelField(modelValue, 'baseUrl', 'base-url', 'base_url'),
+  }
+}
+
+export function validateModelReference(modelRef) {
+  const ref = modelRef || AGENT_PROFILE_MODEL_INHERIT
+  if (ref.mode !== 'fixed') return { ...AGENT_PROFILE_MODEL_INHERIT }
+  if (!ref.provider || !ref.modelId) throw requestError('Fixed agent model requires provider and modelId')
+  return {
+    mode: 'fixed',
+    provider: ref.provider,
+    modelId: ref.modelId,
+    api: ref.api,
+    baseUrl: ref.baseUrl,
+  }
+}
+
+export function normalizeAgentProfileThinkingLevel(value, fallback = 'inherit') {
+  const normalized = normalizeString(value)?.toLowerCase() || fallback
+  if (!agentProfileThinkingLevels.has(normalized)) {
+    throw requestError(`Unsupported agent thinking level: ${normalized}`)
+  }
+  return normalized
+}
+
+export function resolveAgentProfileThinkingLevel(profile, inheritedThinkingLevel, model) {
+  const configured = normalizeAgentProfileThinkingLevel(profile?.thinkingLevel)
+  const requested = configured === 'inherit'
+    ? normalizeAgentProfileThinkingLevel(inheritedThinkingLevel || 'off', 'off')
+    : configured
+  return model?.reasoning === true ? requested : 'off'
+}
+
+export function modelReferenceSnapshot(modelRef) {
+  const ref = modelRef || AGENT_PROFILE_MODEL_INHERIT
+  if (ref.mode !== 'fixed') return { ...AGENT_PROFILE_MODEL_INHERIT }
+  return {
+    mode: 'fixed',
+    provider: ref.provider,
+    modelId: ref.modelId,
+    ...(ref.api ? { api: ref.api } : {}),
+    ...(ref.baseUrl ? { baseUrl: ref.baseUrl } : {}),
+  }
+}
+
+export async function resolveAgentProfileModel(profile, parentModel, readStore) {
+  const ref = profile?.model || AGENT_PROFILE_MODEL_INHERIT
+  if (!ref || ref.mode !== 'fixed') {
+    if (!parentModel) throw requestError('No active model is configured for the parent session.')
+    return { model: parentModel, info: { ...modelReferenceSnapshot(ref), inherited: true } }
+  }
+
+  const validRef = validateModelReference(ref)
+  const store = await readStore('custom-providers').catch(() => ({}))
+  const providers = Array.isArray(store) ? store : Object.values(store || {})
+  const configuredModels = providers
+    .flatMap((provider) => Array.isArray(provider?.models) ? provider.models : [])
+    .filter((model) => model && typeof model === 'object')
+  const model = configuredModels.find((candidate) => (
+    candidate.provider === validRef.provider &&
+    candidate.id === validRef.modelId &&
+    (!validRef.api || candidate.api === validRef.api) &&
+    (!validRef.baseUrl || sameBaseUrl(candidate.baseUrl, validRef.baseUrl))
+  ))
+  if (!model) {
+    throw requestError(`Agent profile ${profile?.name || ''} requested model ${validRef.provider}/${validRef.modelId}, but it is not configured.`)
+  }
+  return { model, info: { ...modelReferenceSnapshot(validRef), inherited: false } }
+}