#16247: feat(agents): declarative agent definitions for sessions_spawn

## Summary Adds support for **declarative agent definitions** - markdown files with YAML frontmatter that define specialized sub-agent types with scoped tools, models, and system prompts, spawnable by name via `sessions_spawn`. Fixes #16128 ## Changes ### New: Agent Definition Module (`src/agents/agent-definitions/`) - **types.ts** - `AgentDefinition`, `AgentDefinitionFrontmatter`, `AgentDefinitionToolPolicy` types - **loader.ts** - Parses markdown files with YAML frontmatter into structured agent definitions - **workspace.ts** - Discovers definitions from `agents/` and `.agents/agents/` directories with precedence (workspace > .agents > bundled) - **index.ts** - Barrel export ### Modified: `sessions_spawn` tool - New optional `agent` parameter to reference an agent definition by name - Definition model serves as fallback (explicit `model` override takes precedence over definition) - Returns `agentDefinition` field in response when an agent definition is used - Returns clear error when a referenced definition is not found ### Modified: `agents_list` tool - Response now includes `definitions` array listing available agent definitions (name, description, source) ### Modified: `buildSubagentSystemPrompt` - Accepts optional `agentDefinition` parameter - When present, prepends the definition's custom system prompt to the subagent context - Adds agent type to session context section ### Example Usage Place a file at `agents/explorer.md`: ```markdown --- name: explorer description: "Read-only codebase exploration" model: google/gemini-2.5-flash tools: allow: - read - web_search --- You are a code explorer. Find and summarize relevant code patterns. ``` Then spawn it: ``` sessions_spawn({ agent: "explorer", task: "Find error handling patterns in src/" }) ``` ## Test Plan - [x] 22 unit tests for loader and workspace discovery (parsing, precedence, edge cases) - [x] 3 e2e tests for sessions_spawn with agent definitions (resolution, error handling, model precedence) - [x] 4 existing agents_list e2e tests still pass - [x] 15 existing sessions_spawn e2e tests still pass - [x] Full test suite: 644 files, 4413 tests passed - [x] Lint: 0 warnings, 0 errors - [x] Format: all files pass - [x] Type check: passes - [x] Build: succeeds --- 🤖 Generated with Claude Code (issue-hunter-pro) <!-- greptile_comment --> <h3>Greptile Summary</h3> This PR adds declarative agent definitions - markdown files with YAML frontmatter that define specialized sub-agent types with scoped tools, models, and system prompts. The implementation includes a complete loader/parser module, workspace directory discovery with precedence rules (workspace > .agents > bundled), and integration with `sessions_spawn` and `agents_list` tools. **Key Changes:** - New `agent-definitions/` module with types, loader, and workspace discovery logic - `sessions_spawn` tool accepts optional `agent` parameter to reference agent definitions by name - Agent definition model serves as fallback (explicit `model` parameter takes precedence) - `agents_list` tool now returns available agent definitions in response - `buildSubagentSystemPrompt` prepends custom system prompts from agent definitions - 22 unit tests for loader/workspace discovery, 3 e2e tests for sessions_spawn integration **Implementation Quality:** - Well-structured with proper separation of concerns (types, loader, workspace) - Comprehensive test coverage including edge cases (invalid YAML, missing files, precedence) - Proper error handling for missing agent definitions - Follows existing patterns for tool parameter handling and model resolution - Case-insensitive name resolution for better UX <h3>Confidence Score: 5/5</h3> - This PR is safe to merge with very low risk - The implementation is well-designed with comprehensive test coverage (25 total tests across unit and e2e), proper error handling, and follows established codebase patterns. The feature is additive and opt-in - existing functionality remains unchanged. All tests pass (644 files, 4413 tests) with no lint/format/type errors. - No files require special attention _{Last reviewed commit: aa2f037} <!-- greptile_other_comments_section --> <!-- /greptile_comment -->