Something went wrong. Try again.
source dump of claude code forked from oppi.li/claude-code
Something went wrong. Try again.
12 kB · 348 lines
TypeScript
at main
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349import memoize from 'lodash-es/memoize.js'import { basename } from 'path'import { isAutoMemoryEnabled } from '../../memdir/paths.js'import type { AgentColorName } from '../../tools/AgentTool/agentColorManager.js'import { type AgentMemoryScope, loadAgentMemoryPrompt,} from '../../tools/AgentTool/agentMemory.js'import type { AgentDefinition } from '../../tools/AgentTool/loadAgentsDir.js'import { FILE_EDIT_TOOL_NAME } from '../../tools/FileEditTool/constants.js'import { FILE_READ_TOOL_NAME } from '../../tools/FileReadTool/prompt.js'import { FILE_WRITE_TOOL_NAME } from '../../tools/FileWriteTool/prompt.js'import { getPluginErrorMessage } from '../../types/plugin.js'import { logForDebugging } from '../debug.js'import { EFFORT_LEVELS, parseEffortValue } from '../effort.js'import { coerceDescriptionToString, parseFrontmatter, parsePositiveIntFromFrontmatter,} from '../frontmatterParser.js'import { getFsImplementation, isDuplicatePath } from '../fsOperations.js'import { parseAgentToolsFromFrontmatter, parseSlashCommandToolsFromFrontmatter,} from '../markdownConfigLoader.js'import { loadAllPluginsCacheOnly } from './pluginLoader.js'import { loadPluginOptions, substitutePluginVariables, substituteUserConfigInContent,} from './pluginOptionsStorage.js'import type { PluginManifest } from './schemas.js'import { walkPluginMarkdown } from './walkPluginMarkdown.js'
const VALID_MEMORY_SCOPES: AgentMemoryScope[] = ['user', 'project', 'local']
async function loadAgentsFromDirectory( agentsPath: string, pluginName: string, sourceName: string, pluginPath: string, pluginManifest: PluginManifest, loadedPaths: Set<string>,): Promise<AgentDefinition[]> { const agents: AgentDefinition[] = [] await walkPluginMarkdown( agentsPath, async (fullPath, namespace) => { const agent = await loadAgentFromFile( fullPath, pluginName, namespace, sourceName, pluginPath, pluginManifest, loadedPaths, ) if (agent) agents.push(agent) }, { logLabel: 'agents' }, ) return agents}
async function loadAgentFromFile( filePath: string, pluginName: string, namespace: string[], sourceName: string, pluginPath: string, pluginManifest: PluginManifest, loadedPaths: Set<string>,): Promise<AgentDefinition | null> { const fs = getFsImplementation() if (isDuplicatePath(fs, filePath, loadedPaths)) { return null } try { const content = await fs.readFile(filePath, { encoding: 'utf-8' }) const { frontmatter, content: markdownContent } = parseFrontmatter( content, filePath, )
const baseAgentName = (frontmatter.name as string) || basename(filePath).replace(/\.md$/, '')
// Apply namespace prefixing like we do for commands const nameParts = [pluginName, ...namespace, baseAgentName] const agentType = nameParts.join(':')
// Parse agent metadata from frontmatter const whenToUse = coerceDescriptionToString(frontmatter.description, agentType) ?? coerceDescriptionToString(frontmatter['when-to-use'], agentType) ?? `Agent from ${pluginName} plugin`
let tools = parseAgentToolsFromFrontmatter(frontmatter.tools) const skills = parseSlashCommandToolsFromFrontmatter(frontmatter.skills) const color = frontmatter.color as AgentColorName | undefined const modelRaw = frontmatter.model let model: string | undefined if (typeof modelRaw === 'string' && modelRaw.trim().length > 0) { const trimmed = modelRaw.trim() model = trimmed.toLowerCase() === 'inherit' ? 'inherit' : trimmed } const backgroundRaw = frontmatter.background const background = backgroundRaw === 'true' || backgroundRaw === true ? true : undefined // Substitute ${CLAUDE_PLUGIN_ROOT} so agents can reference bundled files, // and ${user_config.X} (non-sensitive only) so they can embed configured // usernames, endpoints, etc. Sensitive refs resolve to a placeholder. let systemPrompt = substitutePluginVariables(markdownContent.trim(), { path: pluginPath, source: sourceName, }) if (pluginManifest.userConfig) { systemPrompt = substituteUserConfigInContent( systemPrompt, loadPluginOptions(sourceName), pluginManifest.userConfig, ) }
// Parse memory scope const memoryRaw = frontmatter.memory as string | undefined let memory: AgentMemoryScope | undefined if (memoryRaw !== undefined) { if (VALID_MEMORY_SCOPES.includes(memoryRaw as AgentMemoryScope)) { memory = memoryRaw as AgentMemoryScope } else { logForDebugging( `Plugin agent file ${filePath} has invalid memory value '${memoryRaw}'. Valid options: ${VALID_MEMORY_SCOPES.join(', ')}`, ) } }
// Parse isolation mode const isolationRaw = frontmatter.isolation as string | undefined const isolation = isolationRaw === 'worktree' ? ('worktree' as const) : undefined
// Parse effort (string level or integer) const effortRaw = frontmatter.effort const effort = effortRaw !== undefined ? parseEffortValue(effortRaw) : undefined if (effortRaw !== undefined && effort === undefined) { logForDebugging( `Plugin agent file ${filePath} has invalid effort '${effortRaw}'. Valid options: ${EFFORT_LEVELS.join(', ')} or an integer`, ) }
// permissionMode, hooks, and mcpServers are intentionally NOT parsed for // plugin agents. Plugins are third-party marketplace code; these fields // escalate what the agent can do beyond what the user approved at install // time. For this level of control, define the agent in .claude/agents/ // where the user explicitly wrote the frontmatter. (Note: plugins can // still ship hooks and MCP servers at the manifest level — that's the // install-time trust boundary. Per-agent declarations would let a single // agent file buried in agents/ silently add them.) See PR #22558 review. for (const field of ['permissionMode', 'hooks', 'mcpServers'] as const) { if (frontmatter[field] !== undefined) { logForDebugging( `Plugin agent file ${filePath} sets ${field}, which is ignored for plugin agents. Use .claude/agents/ for this level of control.`, { level: 'warn' }, ) } }
// Parse maxTurns const maxTurnsRaw = frontmatter.maxTurns const maxTurns = parsePositiveIntFromFrontmatter(maxTurnsRaw) if (maxTurnsRaw !== undefined && maxTurns === undefined) { logForDebugging( `Plugin agent file ${filePath} has invalid maxTurns '${maxTurnsRaw}'. Must be a positive integer.`, ) }
// Parse disallowedTools const disallowedTools = frontmatter.disallowedTools !== undefined ? parseAgentToolsFromFrontmatter(frontmatter.disallowedTools) : undefined
// If memory is enabled, inject Write/Edit/Read tools for memory access if (isAutoMemoryEnabled() && memory && tools !== undefined) { const toolSet = new Set(tools) for (const tool of [ FILE_WRITE_TOOL_NAME, FILE_EDIT_TOOL_NAME, FILE_READ_TOOL_NAME, ]) { if (!toolSet.has(tool)) { tools = [...tools, tool] } } }
return { agentType, whenToUse, tools, ...(disallowedTools !== undefined ? { disallowedTools } : {}), ...(skills !== undefined ? { skills } : {}), getSystemPrompt: () => { if (isAutoMemoryEnabled() && memory) { const memoryPrompt = loadAgentMemoryPrompt(agentType, memory) return systemPrompt + '\n\n' + memoryPrompt } return systemPrompt }, source: 'plugin' as const, color, model, filename: baseAgentName, plugin: sourceName, ...(background ? { background } : {}), ...(memory ? { memory } : {}), ...(isolation ? { isolation } : {}), ...(effort !== undefined ? { effort } : {}), ...(maxTurns !== undefined ? { maxTurns } : {}), } as AgentDefinition } catch (error) { logForDebugging(`Failed to load agent from ${filePath}: ${error}`, { level: 'error', }) return null }}
export const loadPluginAgents = memoize( async (): Promise<AgentDefinition[]> => { // Only load agents from enabled plugins const { enabled, errors } = await loadAllPluginsCacheOnly()
if (errors.length > 0) { logForDebugging( `Plugin loading errors: ${errors.map(e => getPluginErrorMessage(e)).join(', ')}`, ) }
// Process plugins in parallel; each plugin has its own loadedPaths scope const perPluginAgents = await Promise.all( enabled.map(async (plugin): Promise<AgentDefinition[]> => { // Track loaded file paths to prevent duplicates within this plugin const loadedPaths = new Set<string>() const pluginAgents: AgentDefinition[] = []
// Load agents from default agents directory if (plugin.agentsPath) { try { const agents = await loadAgentsFromDirectory( plugin.agentsPath, plugin.name, plugin.source, plugin.path, plugin.manifest, loadedPaths, ) pluginAgents.push(...agents)
if (agents.length > 0) { logForDebugging( `Loaded ${agents.length} agents from plugin ${plugin.name} default directory`, ) } } catch (error) { logForDebugging( `Failed to load agents from plugin ${plugin.name} default directory: ${error}`, { level: 'error' }, ) } }
// Load agents from additional paths specified in manifest if (plugin.agentsPaths) { // Process all agentsPaths in parallel. isDuplicatePath is synchronous // (check-and-add), so concurrent access to loadedPaths is safe. const pathResults = await Promise.all( plugin.agentsPaths.map( async (agentPath): Promise<AgentDefinition[]> => { try { const fs = getFsImplementation() const stats = await fs.stat(agentPath)
if (stats.isDirectory()) { // Load all .md files from directory const agents = await loadAgentsFromDirectory( agentPath, plugin.name, plugin.source, plugin.path, plugin.manifest, loadedPaths, )
if (agents.length > 0) { logForDebugging( `Loaded ${agents.length} agents from plugin ${plugin.name} custom path: ${agentPath}`, ) } return agents } else if (stats.isFile() && agentPath.endsWith('.md')) { // Load single agent file const agent = await loadAgentFromFile( agentPath, plugin.name, [], plugin.source, plugin.path, plugin.manifest, loadedPaths, ) if (agent) { logForDebugging( `Loaded agent from plugin ${plugin.name} custom file: ${agentPath}`, ) return [agent] } } return [] } catch (error) { logForDebugging( `Failed to load agents from plugin ${plugin.name} custom path ${agentPath}: ${error}`, { level: 'error' }, ) return [] } }, ), ) for (const agents of pathResults) { pluginAgents.push(...agents) } } return pluginAgents }), )
const allAgents = perPluginAgents.flat() logForDebugging(`Total plugin agents loaded: ${allAgents.length}`) return allAgents },)
export function clearPluginAgentCache(): void { loadPluginAgents.cache?.clear?.()}