@shawnstack/quickforge 1.4.1 → 1.5.0

package/server/agent-manager.mjs

@@ -11,7 +11,7 @@ import {
   formatSubagentTask,
 } from './subagents.mjs'
 import { agentProfileSnapshot, getAgentProfile } from './agent-profiles.mjs'
-import { projectContextFromId, readProjectConfig } from './project-config.mjs'
+import { projectContextFromId, defaultGlobalWorkspaceContext, readProjectConfig } from './project-config.mjs'
 import { readStore, atomicUpdate, atomicSessionMetadataUpdate, readSessionValue, writeSessionValue, deleteSessionValue } from './storage.mjs'
 import { logger } from './utils/logger.mjs'
 import { buildSystemPrompt, generateAiTitle, generateTitle } from './session-utils.mjs'
@@ -23,8 +23,11 @@ import {
 } from './conversation-compaction.mjs'
 import {
   buildAutoCompactLoopMessages,
+  compactSessionInPlace,
+  DEFAULT_AUTO_COMPACT_SETTINGS,
   estimateSessionContextUsage,
   maybeAutoCompactSession,
+  readAutoCompactSettings,
 } from './auto-compaction.mjs'
 import {
   handleInternalCommand,
@@ -92,7 +95,7 @@ async function createServerTools(projectId, projectContext, skillsContext, inclu
     .filter(isAllowed)
     .map((definition) => wrapToolDefinition(definition, toolContext, toolPermissions))
 
-  if (includeWorkspaceTools && projectId && projectContext) {
+  if (includeWorkspaceTools && projectContext) {
     const definitions = workspaceTools.filter((definition) => includeSubagentTool || definition.name !== 'run_subagent')
     tools.push(...definitions
       .filter(isAllowed)
@@ -117,7 +120,7 @@ async function rebuildSessionTools(session) {
     session.projectId,
     session.projectContext,
     sessionSkillsContext(session),
-    !!(session.projectId && session.projectContext),
+    !!session.projectContext,
     createCommandToolPermissions(session),
     { parentSessionId: session.sessionId },
   )
@@ -129,7 +132,26 @@ async function rebuildSessionTools(session) {
 
 const agentSessions = new Map()
 
-/** @typedef {{ agent: Agent, projectContext: object|null, projectId: string|null, yoloMode: boolean, model: object, thinkingLevel: string, scope: string, title: string, createdAt: string, status: string, startedAt: string|null, finishedAt: string|null, listeners: Set<function>, idleTimer: NodeJS.Timeout|null, eventBus: EventEmitter }} AgentSession */
+const AGENT_ACCESS_MODE_DEFAULT = 'default'
+const AGENT_ACCESS_MODE_FULL_ACCESS = 'full-access'
+
+function normalizeAccessMode(value, fallback = AGENT_ACCESS_MODE_DEFAULT) {
+  if (value === AGENT_ACCESS_MODE_DEFAULT || value === AGENT_ACCESS_MODE_FULL_ACCESS) return value
+  if (value === true || value === 'true') return AGENT_ACCESS_MODE_FULL_ACCESS
+  if (value === false || value === 'false') return AGENT_ACCESS_MODE_DEFAULT
+  if (fallback !== value) return normalizeAccessMode(fallback, AGENT_ACCESS_MODE_DEFAULT)
+  return AGENT_ACCESS_MODE_DEFAULT
+}
+
+function yoloModeFromAccessMode(accessMode) {
+  return normalizeAccessMode(accessMode) === AGENT_ACCESS_MODE_FULL_ACCESS
+}
+
+function hasFullAccess(session) {
+  return normalizeAccessMode(session?.accessMode, session?.yoloMode) === AGENT_ACCESS_MODE_FULL_ACCESS
+}
+
+/** @typedef {{ agent: Agent, projectContext: object|null, projectId: string|null, accessMode: string, yoloMode: boolean, model: object, thinkingLevel: string, scope: string, title: string, createdAt: string, status: string, startedAt: string|null, finishedAt: string|null, listeners: Set<function>, idleTimer: NodeJS.Timeout|null, eventBus: EventEmitter }} AgentSession */
 
 const IDLE_TIMEOUT_MS = 30 * 60 * 1000 // 30 minutes
 const SUBAGENT_DEFAULT_TIMEOUT_MS = 30 * 60 * 1000
@@ -370,12 +392,12 @@ function finishManualSessionRun(session, status, errorMessage) {
   session.agent.state.errorMessage = errorMessage
 }
 
-async function compactSession(session, initialUserMessage, compactOptions) {
+async function summarySession(session, initialUserMessage, summaryOptions) {
   if (session.agent.state.isStreaming) {
     session.agent.state.messages = [
       ...session.agent.state.messages,
       initialUserMessage,
-      assistantTextMessage('Cannot compact while a generation is still running. Stop it or wait until it finishes, then run /compact again.', session.model),
+      assistantTextMessage('Cannot summarize while a generation is still running. Stop it or wait until it finishes, then run /summary again.', session.model),
     ]
     await persistSession(session)
     const messages = session.agent.state.messages
@@ -399,13 +421,13 @@ async function compactSession(session, initialUserMessage, compactOptions) {
 
   try {
     const originalMessages = session.agent.state.messages.slice()
-    const options = parseCompactArgs(compactOptions?.args || '')
+    const options = parseCompactArgs(summaryOptions?.args || '')
 
     if (options.unsupported?.length) {
       session.agent.state.messages = [
         ...originalMessages,
         initialUserMessage,
-        assistantTextMessage(`Unsupported /compact option(s): ${options.unsupported.join(', ')}\n\nSupported usage: /compact or /compact keep=0`, session.model),
+        assistantTextMessage(`Unsupported /summary option(s): ${options.unsupported.join(', ')}\n\nSupported usage: /summary or /summary keep=0`, session.model),
       ]
       finishManualSessionRun(session, 'idle')
       await persistSession(session)
@@ -427,7 +449,7 @@ async function compactSession(session, initialUserMessage, compactOptions) {
       session.agent.state.messages = [
         ...originalMessages,
         initialUserMessage,
-        assistantTextMessage('Not enough earlier history to compact. Continue chatting and run /compact again later.', session.model),
+        assistantTextMessage('Not enough earlier history to summarize. Continue chatting and run /summary again later.', session.model),
       ]
       finishManualSessionRun(session, 'idle')
       await persistSession(session)
@@ -463,6 +485,7 @@ async function compactSession(session, initialUserMessage, compactOptions) {
     const compactedSession = await createAgent(compactedSessionId, {
       scope: session.scope,
       projectId: session.projectId,
+      accessMode: session.accessMode,
       yoloMode: session.yoloMode,
       model: session.model,
       thinkingLevel: session.thinkingLevel,
@@ -512,6 +535,97 @@ async function compactSession(session, initialUserMessage, compactOptions) {
   }
 }
 
+async function compactSession(session, initialUserMessage, compactOptions) {
+  if (session.agent.state.isStreaming) {
+    session.agent.state.messages = [
+      ...session.agent.state.messages,
+      initialUserMessage,
+      assistantTextMessage('Cannot compact while a generation is still running. Stop it or wait until it finishes, then run /compact again.', session.model),
+    ]
+    await persistSession(session)
+    const messages = session.agent.state.messages
+    emitSessionEvent(session, { type: 'message_end', messages })
+    emitSessionEvent(session, { type: 'agent_end', messages })
+    return { sessionId: session.sessionId, status: session.status }
+  }
+
+  const args = String(compactOptions?.args || '').trim()
+  if (args) {
+    session.agent.state.messages = [
+      ...session.agent.state.messages,
+      initialUserMessage,
+      assistantTextMessage('Unsupported /compact option(s). Supported usage: /compact', session.model),
+    ]
+    session.status = 'idle'
+    session.finishedAt = new Date().toISOString()
+    await persistSession(session)
+    const messages = session.agent.state.messages
+    emitSessionEvent(session, { type: 'message_end', messages })
+    emitSessionEvent(session, { type: 'agent_end', messages })
+    return { sessionId: session.sessionId, status: session.status }
+  }
+
+  resetIdleTimer(session)
+  session.status = 'running'
+  session.startedAt = session.startedAt ?? new Date().toISOString()
+  session.finishedAt = null
+  session.agent.state.isStreaming = true
+  session.agent.state.errorMessage = undefined
+  emitSessionEvent(session, { type: 'agent_start' })
+
+  try {
+    const messages = session.agent.state.messages.slice()
+    const settings = await readAutoCompactSettings().catch(() => DEFAULT_AUTO_COMPACT_SETTINGS)
+    const usage = getSessionContextUsage(session)
+    const result = await compactSessionInPlace({
+      session,
+      messages,
+      keepRecentTurns: settings.keepRecentTurns,
+      minSourceChars: settings.minSourceChars,
+      usage,
+      thresholdPercent: settings.thresholdPercent,
+      emitSessionEvent,
+      persistSession,
+      reason: 'manual_compact',
+      onBeforePersist: () => {
+        finishManualSessionRun(session, 'idle')
+      },
+    })
+
+    if (!result.compacted) {
+      session.agent.state.messages = [
+        ...messages,
+        initialUserMessage,
+        assistantTextMessage('Not enough earlier history to compact. Continue chatting and run /compact again later.', session.model),
+      ]
+      finishManualSessionRun(session, 'idle')
+      await persistSession(session)
+      const nextMessages = session.agent.state.messages
+      emitSessionEvent(session, { type: 'message_end', messages: nextMessages })
+      emitSessionEvent(session, { type: 'agent_end', messages: nextMessages })
+      return { sessionId: session.sessionId, status: session.status }
+    }
+
+    const nextMessages = session.agent.state.messages
+    emitSessionEvent(session, { type: 'message_end', messages: nextMessages })
+    emitSessionEvent(session, { type: 'agent_end', messages: nextMessages })
+    return { sessionId: session.sessionId, status: session.status }
+  } catch (err) {
+    const errorMessage = err?.message || 'Conversation compaction failed'
+    session.agent.state.messages = [
+      ...session.agent.state.messages,
+      initialUserMessage,
+      assistantTextMessage(`Conversation compaction failed: ${errorMessage}`, session.model),
+    ]
+    finishManualSessionRun(session, 'error', errorMessage)
+    await persistSession(session)
+    const messages = session.agent.state.messages
+    emitSessionEvent(session, { type: 'error', error: errorMessage })
+    emitSessionEvent(session, { type: 'agent_end', messages, errorMessage })
+    return { sessionId: session.sessionId, status: session.status }
+  }
+}
+
 async function clearSession(session) {
   if (session.agent.state.isStreaming) {
     session.agent.state.messages = [
@@ -602,6 +716,7 @@ async function resolveCommandState(session, userMessage, promptCommand = null) {
   )
   if (typeof internalResponse === 'string') return { textResponse: internalResponse }
   if (internalResponse?.clear) return { clear: internalResponse }
+  if (internalResponse?.summary) return { summary: internalResponse }
   if (internalResponse?.compact) return { compact: internalResponse }
   if (internalResponse?.plan) {
     return planCommandState(userMessage, internalResponse.args)
@@ -704,7 +819,7 @@ ${scopeText}
 }
 
 async function runSubagent(parentSession, params, parentSignal, onUpdate) {
-  const profile = await getAgentProfile(params?.subagent)
+  const profile = await getAgentProfile(params?.subagent, { workspaceRoot: parentSession.projectContext?.workspaceRoot })
   if (!profile || !profile.enabledAsSubagent) {
     const error = new Error(`Unknown or disabled subagent: ${params?.subagent || ''}`)
     error.statusCode = 400
@@ -828,7 +943,7 @@ async function runSubagent(parentSession, params, parentSignal, onUpdate) {
       }
       const commandPermissionError = commandToolPermissionError(parentSession, toolName)
       if (commandPermissionError) return { block: true, reason: commandPermissionError }
-      if (!parentSession.yoloMode) {
+      if (!hasFullAccess(parentSession)) {
         if (safeReadTools.has(toolName)) return undefined
         return createApprovalPromise(parentSession, context.toolCall?.id, toolName, context.args, {
           type: 'subagent',
@@ -1009,8 +1124,15 @@ async function transformSessionContext(session, messages, signal) {
 export const agentEvents = new EventEmitter()
 agentEvents.setMaxListeners(100)
 
+function isIdleRetainedSession(session) {
+  return session?.idleRetention === 'always'
+}
+
 function resetIdleTimer(session) {
   if (session.idleTimer) clearTimeout(session.idleTimer)
+  session.idleTimer = null
+  if (isIdleRetainedSession(session)) return
+
   session.idleTimer = setTimeout(() => {
     if (session.status === 'running') {
       logger.info(`Session ${session.sessionId} idle timer fired but still running, resetting...`, { sessionId: session.sessionId, status: session.status })
@@ -1045,6 +1167,7 @@ export function touchSession(sessionId) {
 export async function createAgent(sessionId, config = {}) {
   const existing = agentSessions.get(sessionId)
   if (existing) {
+    if (config.idleRetention !== undefined) existing.idleRetention = config.idleRetention
     resetIdleTimer(existing)
     return existing
   }
@@ -1052,6 +1175,7 @@ export async function createAgent(sessionId, config = {}) {
   const {
     scope = 'global',
     projectId = null,
+    accessMode: rawAccessMode,
     yoloMode = false,
     model = null,
     thinkingLevel = 'off',
@@ -1062,17 +1186,23 @@ export async function createAgent(sessionId, config = {}) {
     lastModified = null,
     contextCompaction = null,
     agentProfile = null,
+    idleRetention = null,
   } = config
+  const accessMode = normalizeAccessMode(rawAccessMode, yoloMode)
+  const resolvedYoloMode = yoloModeFromAccessMode(accessMode)
 
-  // Resolve project context for tool calls
+  // Resolve project context for tool calls. Project conversations resolve to
+  // their directory; global conversations (no projectId) and any fallback fall
+  // back to a synthetic default workspace context so file tools stay available.
   let projectContext = null
   if (projectId) {
     try {
       projectContext = await projectContextFromId(projectId)
     } catch {
-      // project not found — run without tools
+      // project not found — fall back to the default workspace below
     }
   }
+  projectContext ??= defaultGlobalWorkspaceContext()
 
   // Build system prompt
   const projectConfig = await readProjectConfig()
@@ -1105,7 +1235,7 @@ export async function createAgent(sessionId, config = {}) {
     projectId,
     projectContext,
     skillsContext,
-    !!(projectId && projectContext),
+    !!projectContext,
     (toolName) => {
       if (profileToolNames && !profileToolNames.includes(toolName)) return `Agent profile ${agentProfile.name} is not allowed to use ${toolName}.`
       const session = agentSessions.get(sessionId)
@@ -1159,14 +1289,14 @@ export async function createAgent(sessionId, config = {}) {
       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 (isMcpToolName(toolName) || isPluginToolName(toolName)) {
-        if (!currentSession?.yoloMode) return createApprovalPromise(currentSession, toolCallId, toolName, context.args)
+        if (!hasFullAccess(currentSession)) return createApprovalPromise(currentSession, toolCallId, toolName, context.args)
         return undefined
       }
-      if (!projectContext) {
+      if (!projectContext?.workspaceRoot) {
         return { block: true, reason: 'No active project. Select a project to use tools.' }
       }
-      if (!currentSession?.yoloMode) {
-        // YOLO OFF: safe reads auto-pass, dangerous writes require approval
+      if (!hasFullAccess(currentSession)) {
+        // Default access: safe reads auto-pass, state-changing or external tools require approval
         if (safeReadTools.has(toolName)) return undefined
         return createApprovalPromise(currentSession, toolCallId, toolName, context.args)
       }
@@ -1182,7 +1312,8 @@ export async function createAgent(sessionId, config = {}) {
     agent,
     projectContext,
     projectId,
-    yoloMode,
+    accessMode,
+    yoloMode: resolvedYoloMode,
     model: resolvedModel,
     thinkingLevel,
     scope,
@@ -1205,6 +1336,7 @@ export async function createAgent(sessionId, config = {}) {
     getApiKey,
     contextCompaction,
     agentProfile: agentProfile ? agentProfileSnapshot(agentProfile) : null,
+    idleRetention,
     lastTransformedContextMessages: null,
     autoCompacting: false,
     stateVersion: 0,
@@ -1216,7 +1348,7 @@ export async function createAgent(sessionId, config = {}) {
   }
 
   // Subscribe to agent lifecycle events and forward to eventBus
-  agent.subscribe((event) => {
+  agent.subscribe(async (event) => {
     // The pi-agent-core agent loop emits agent_end with `messages` that only
     // contains messages generated during THIS run (newMessages), not the
     // complete session history.  Replace with the authoritative full state
@@ -1246,10 +1378,14 @@ export async function createAgent(sessionId, config = {}) {
       session.status = 'running'
       session.startedAt = session.startedAt ?? new Date().toISOString()
       session.finishedAt = null
-      // Persist running state immediately so a browser refresh still shows the green dot
-      persistSession(session).catch((err) =>
-        logger.error(`Failed to persist session on start ${sessionId}:`, err, { sessionId }),
-      )
+      // Persist running state immediately so a browser refresh still shows the green dot.
+      // Brand-new runs have no messages until the first user message_end; persisting
+      // here would only trigger the empty-session cleanup path.
+      if (session.agent.state.messages.length > 0) {
+        persistSession(session).catch((err) =>
+          logger.error(`Failed to persist session on start ${sessionId}:`, err, { sessionId }),
+        )
+      }
     }
 
     if (event.type === 'agent_end') {
@@ -1265,15 +1401,28 @@ export async function createAgent(sessionId, config = {}) {
     }
 
     if (event.type === 'message_end') {
-      // Debounced persist for crash recovery; coalesces the many message_end
-      // events within a single run into infrequent full-session writes.
-      scheduleSessionPersist(session)
+      const isInitialUserMessage = (event.message?.role === 'user' || event.message?.role === 'user-with-attachments')
+        && session.agent.state.messages.length === 1
+      if (isInitialUserMessage) {
+        // External ACP channels run in a separate process from the web UI. Persist
+        // the first user message immediately so the session becomes visible on
+        // disk before a long/failed agent run can exit or be restarted.
+        try {
+          await flushSessionPersist(session)
+        } catch (err) {
+          logger.error(`Failed to persist initial user message for session ${sessionId}:`, err, { sessionId })
+        }
+      } else {
+        // Debounced persist for crash recovery; coalesces the many message_end
+        // events within a single run into infrequent full-session writes.
+        scheduleSessionPersist(session)
+      }
     }
   })
 
   agentSessions.set(sessionId, session)
   resetIdleTimer(session)
-  logger.info(`Created session ${sessionId} (scope: ${scope}, project: ${projectId || 'none'}, yolo: ${yoloMode})`, { sessionId, scope, projectId: projectId || undefined, yoloMode })
+  logger.info(`Created session ${sessionId} (scope: ${scope}, project: ${projectId || 'none'}, access: ${accessMode})`, { sessionId, scope, projectId: projectId || undefined, accessMode, yoloMode: resolvedYoloMode, idleRetention: idleRetention || undefined })
   return session
 }
 
@@ -1305,7 +1454,7 @@ function sessionLastModifiedFromMessages(messages, fallback) {
  * Persist session data to storage.
  */
 async function persistSession(session) {
-  const { sessionId, agent, scope, projectId, title, createdAt, lastModified: storedLastModified, status, startedAt, finishedAt, model, thinkingLevel, yoloMode, contextCompaction } = session
+  const { sessionId, agent, scope, projectId, title, createdAt, lastModified: storedLastModified, status, startedAt, finishedAt, model, thinkingLevel, accessMode, yoloMode, contextCompaction } = session
   const messages = agent.state.messages
 
   if (messages.length === 0) {
@@ -1328,6 +1477,7 @@ async function persistSession(session) {
     title,
     model,
     thinkingLevel,
+    accessMode,
     yoloMode,
     messages,
     createdAt: createdAt || now,
@@ -1338,6 +1488,7 @@ async function persistSession(session) {
     taskStartedAt: startedAt,
     taskFinishedAt: finishedAt,
     contextCompaction: contextCompaction || undefined,
+    idleRetention: session.idleRetention || undefined,
   }
   session.lastModified = lastModified
 
@@ -1379,6 +1530,7 @@ async function persistSession(session) {
     messageCount: messages.length,
     usage,
     thinkingLevel,
+    accessMode,
     yoloMode,
     preview,
     scope,
@@ -1393,6 +1545,7 @@ async function persistSession(session) {
       thresholdPercent: contextCompaction.thresholdPercent,
       usageBefore: contextCompaction.usageBefore,
     } : undefined,
+    idleRetention: session.idleRetention || undefined,
   }
 
   // Write to storage atomically (read-modify-write within queue)
@@ -1550,6 +1703,10 @@ export async function runPrompt(sessionId, message, selectedCapabilities = [], p
     return clearSession(session)
   }
 
+  if (commandState.summary) {
+    return summarySession(session, initialUserMessage, commandState.summary)
+  }
+
   if (commandState.compact) {
     return compactSession(session, initialUserMessage, commandState.compact)
   }
@@ -1750,6 +1907,7 @@ export function getSessionState(sessionId) {
     sessionId: session.sessionId,
     scope: session.scope,
     projectId: session.projectId,
+    accessMode: session.accessMode,
     yoloMode: session.yoloMode,
     systemPrompt: session.agent.state.systemPrompt,
     model: session.model,
@@ -1894,6 +2052,7 @@ export async function restoreAgent(sessionId) {
     return await createAgent(sessionId, {
       scope: sessionData.scope || 'global',
       projectId: sessionData.projectId || null,
+      accessMode: normalizeAccessMode(sessionData.accessMode, sessionData.yoloMode),
       yoloMode: sessionData.yoloMode || false,
       model: sessionData.model,
       thinkingLevel: sessionData.thinkingLevel || 'off',
@@ -1902,6 +2061,7 @@ export async function restoreAgent(sessionId) {
       createdAt: sessionData.createdAt,
       lastModified: sessionData.lastModified,
       contextCompaction: sessionData.contextCompaction || null,
+      idleRetention: sessionData.idleRetention || null,
     })
   } catch (err) {
     logger.error(`Failed to restore agent ${sessionId}:`, err, { sessionId })
@@ -1974,6 +2134,7 @@ export function listSessions() {
       scope: session.scope,
       status: session.status,
       title: session.title,
+      idleRetention: session.idleRetention || undefined,
     })
   }
   return result
@@ -1995,20 +2156,25 @@ export async function refreshAllSessionTools() {
   return result
 }
 
-export async function updateSessionYoloMode(sessionId, yoloMode) {
+export async function updateSessionAccessMode(sessionId, accessMode) {
   const session = agentSessions.get(sessionId)
   if (!session) {
     throw Object.assign(new Error('Session not found'), { statusCode: 404 })
   }
 
-  session.yoloMode = Boolean(yoloMode)
+  session.accessMode = normalizeAccessMode(accessMode, session.accessMode)
+  session.yoloMode = yoloModeFromAccessMode(session.accessMode)
   await rebuildSessionTools(session)
   await persistSession(session)
 
   const state = getSessionState(sessionId)
   emitSessionEvent(session, { type: 'state', ...state })
 
-  return { sessionId, yoloMode: session.yoloMode }
+  return { sessionId, accessMode: session.accessMode, yoloMode: session.yoloMode }
+}
+
+export async function updateSessionYoloMode(sessionId, yoloMode) {
+  return updateSessionAccessMode(sessionId, yoloMode ? AGENT_ACCESS_MODE_FULL_ACCESS : AGENT_ACCESS_MODE_DEFAULT)
 }
 
 /**

package/server/agent-profile-files.mjs

@@ -0,0 +1,179 @@
+import { existsSync, promises as fs } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { dataDir } from './storage.mjs'
+import { firstOptionalBoolean, firstString, parseFrontmatter, splitDelimitedList } from './frontmatter.mjs'
+
+const DEFAULT_MAX_RUNTIME_MS = 30 * 60 * 1000
+const DEFAULT_MAX_TOOL_CALLS = 300
+const nameRegex = /^[a-z][a-z0-9_-]{1,39}$/
+const allowedToolNames = new Set(['read_file', 'grep_files', 'write_file', 'edit_file', 'run_command'])
+
+const toolAliases = new Map([
+  ['Read', 'read_file'],
+  ['Grep', 'grep_files'],
+  ['Bash', 'run_command'],
+  ['Write', 'write_file'],
+  ['Edit', 'edit_file'],
+])
+
+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
+}
+
+function normalizeName(value) {
+  const name = normalizeString(value)?.toLowerCase()
+  return name && nameRegex.test(name) ? name : null
+}
+
+function normalizeRuntime(value) {
+  if (value === undefined || value === null || value === '') return DEFAULT_MAX_RUNTIME_MS
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_MAX_RUNTIME_MS
+  return Math.min(Math.max(Math.round(parsed), 1000), DEFAULT_MAX_RUNTIME_MS)
+}
+
+function normalizeToolCalls(value) {
+  if (value === undefined || value === null || value === '') return DEFAULT_MAX_TOOL_CALLS
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed <= 0) return DEFAULT_MAX_TOOL_CALLS
+  return Math.min(parsed, DEFAULT_MAX_TOOL_CALLS)
+}
+
+function normalizeTools(value) {
+  const tools = []
+  const seen = new Set()
+  for (const item of splitDelimitedList(value)) {
+    const mapped = toolAliases.get(item) || item
+    if (!allowedToolNames.has(mapped) || seen.has(mapped)) continue
+    seen.add(mapped)
+    tools.push(mapped)
+  }
+  return tools.length ? tools : ['read_file', 'grep_files']
+}
+
+function hasMutationTool(allowedTools) {
+  return allowedTools.some((toolName) => toolName === 'write_file' || toolName === 'edit_file')
+}
+
+export function agentProfileFromMarkdown(file, text, options = {}) {
+  const parsed = parseFrontmatter(text)
+  if (!parsed.body) return null
+
+  const metadata = parsed.metadata || {}
+  const name = normalizeName(metadata.name) || normalizeName(path.basename(file, '.md'))
+  if (!name) return null
+  if (options.reservedNames?.has(name)) return null
+
+  const allowedTools = normalizeTools(
+    metadata.tools ?? metadata['allowed-tools'] ?? metadata.allowedTools,
+  )
+  const label = firstString(metadata.label, metadata.displayName, metadata.title) || name
+  const enabledAsSubagent = firstOptionalBoolean(
+    metadata['enabled-as-subagent'],
+    metadata.enabled_as_subagent,
+    metadata.enabledAsSubagent,
+  )
+
+  return {
+    id: `${options.idPrefix || 'file'}:${name}`,
+    name,
+    label: label.slice(0, 80),
+    description: String(firstString(metadata.description) || '').slice(0, 500),
+    systemPrompt: parsed.body,
+    allowedTools,
+    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,
+    filePath: file,
+    relativePath: options.relativePath || path.basename(file),
+    allowFileMutations: hasMutationTool(allowedTools),
+    createdAt: 'file',
+    updatedAt: 'file',
+  }
+}
+
+async function listAgentFilesFromDirectory(dir, options = {}) {
+  if (!dir || !existsSync(dir)) return []
+  let entries
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true })
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR' || error?.code === 'EACCES' || error?.code === 'EPERM') return []
+    throw error
+  }
+
+  const profiles = []
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.toLowerCase().endsWith('.md')) continue
+    const file = path.join(dir, entry.name)
+    try {
+      const relativePath = options.relativeRoot
+        ? `${options.relativeRoot}/${entry.name}`.replace(/\\/g, '/')
+        : entry.name
+      const profile = agentProfileFromMarkdown(file, await fs.readFile(file, 'utf8'), {
+        ...options,
+        relativePath,
+      })
+      if (profile) profiles.push(profile)
+    } catch (error) {
+      console.warn(`Failed to load agent profile ${file}:`, error.message || error)
+    }
+  }
+  return profiles
+}
+
+function projectClaudeAgentsDir(workspaceRoot) {
+  return workspaceRoot ? path.join(path.resolve(workspaceRoot), '.claude', 'agents') : ''
+}
+
+function projectQuickForgeAgentsDir(workspaceRoot) {
+  return workspaceRoot ? path.join(path.resolve(workspaceRoot), '.quickforge', 'agents') : ''
+}
+
+export async function loadUserAgentProfiles(options = {}) {
+  const byName = new Map()
+  const sources = [
+    { dir: claudeUserAgentsDir, source: 'user-claude', relativeRoot: '~/.claude/agents', idPrefix: 'user-claude' },
+    { dir: userAgentsDir, source: 'user', relativeRoot: '~/.quickforge/agents', idPrefix: 'user' },
+  ]
+  for (const source of sources) {
+    for (const profile of await listAgentFilesFromDirectory(source.dir, { ...options, ...source })) {
+      byName.set(profile.name, profile)
+    }
+  }
+  return [...byName.values()]
+}
+
+export async function loadProjectAgentProfiles(workspaceRoot, options = {}) {
+  if (!workspaceRoot) return []
+  const byName = new Map()
+  const sources = [
+    { dir: projectClaudeAgentsDir(workspaceRoot), source: 'project-claude', relativeRoot: '.claude/agents', idPrefix: 'project-claude' },
+    { dir: projectQuickForgeAgentsDir(workspaceRoot), source: 'project', relativeRoot: '.quickforge/agents', idPrefix: 'project' },
+  ]
+  for (const source of sources) {
+    for (const profile of await listAgentFilesFromDirectory(source.dir, { ...options, ...source })) {
+      byName.set(profile.name, profile)
+    }
+  }
+  return [...byName.values()]
+}
+
+export async function loadFileAgentProfiles(workspaceRoot, options = {}) {
+  const byName = new Map()
+  for (const profile of await loadUserAgentProfiles(options)) byName.set(profile.name, profile)
+  for (const profile of await loadProjectAgentProfiles(workspaceRoot, options)) byName.set(profile.name, profile)
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name))
+}
+
+export const agentProfileSearchPaths = {
+  global: ['~/.claude/agents', '~/.quickforge/agents'],
+  project: ['<project>/.claude/agents', '<project>/.quickforge/agents'],
+}