You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Status: Draft Created: 2025-11-21 Last Updated: 2025-11-21
Abstract
This RFC proposes the design and implementation of a specialized subagent system for NeovateCode, inspired by Claude Code's subagent architecture. The system will enable delegation of specific tasks to specialized AI assistants that operate in isolated context windows, improving task specialization while preserving the main conversation's focus and efficiency.
Claude Code implements a sophisticated subagent system that provides task-specific AI delegation with isolated contexts. According to their documentation: "Each subagent operates in its own context, preventing pollution of the main conversation." This section provides a deep analysis of the existing implementation to inform our design decisions.
Core Value Proposition
Primary Benefits Observed:
Context Preservation
Quote from docs: "Each subagent operates in its own context, preventing pollution of the main conversation"
Enables longer overall sessions by isolating specialized work
Main conversation remains focused and relevant
Specialized Expertise
Task-specific system prompts improve output quality
Fine-tuned for specific domains with higher success rates
Each agent can have deep, focused instructions
Reusability & Collaboration
Can be used across projects
Shareable with teams via version control
Standardizes workflows and best practices
Flexible Security
Customizable tool access levels per agent
Principle of least privilege enforcement
Reduces risk of unintended actions
Feature Analysis
Core Capabilities
1. Isolated Context Windows
Each subagent operates in a completely separate conversation context
No access to main conversation history (except the passed task prompt)
No cross-agent state sharing
Prevents context pollution in main thread
Clean-slate execution ensures predictability
Trade-off: "Clean-slate invocations may add latency as subagents gather required context"
2. Multi-Level Configuration System
Storage Locations & Priority:
Project-level (highest priority) - .claude/agents/*.md for team-shared agents
CLI-defined - --agents JSON flag for session-specific configs
User-level - ~/.claude/agents/*.md for personal agents
Plugin-provided (lowest priority) - Integrated via plugin manifests
3. Configuration Format
---name: identifier-namedescription: Purpose and invocation criteriatools: tool1, tool2 (optional)model: sonnet/opus/haiku/inherit (optional)---
System prompt defining role and behavior
Field Specifications:
Field
Required
Details
name
✅ Yes
Lowercase with hyphens, unique identifier
description
✅ Yes
Natural language purpose statement, triggers invocation
tools
❌ No
Comma-separated list; inherits all if omitted
model
❌ No
Defaults to configured subagent model setting
4. Tool Access Control
Two Configuration Options:
Option 1: Inherit All Tools (Default)
Omit the tools field entirely
Agent receives all tools from main thread
Includes MCP (Model Context Protocol) server tools
Best for general-purpose agents
Option 2: Granular Control
Specify tools as comma-separated list
Only listed tools available to agent
Best for security-sensitive agents
MCP Integration: Full support for Model Context Protocol tools, inherited by default
MCP Tool Details:
Tool name format: mcp__server__tool (double underscore separators)
Validation timing: Tool names validated at configuration load time, not runtime
Error handling: Unknown tool names rejected with clear error messages
Discovery: /agents command displays all available MCP tools during agent creation
Inheritance: MCP tools automatically included when using "Inherit All Tools" option
5. Model Selection
Model Options:
sonnet, opus, haiku - Specific models for cost/performance tuning
inherit - Matches main conversation model
Omit field - Uses default subagent model configuration
6. Agent Nesting Prevention
Critical safety mechanism - Subagents cannot spawn other subagents
Prevents infinite recursion and uncontrolled resource usage
Exception: Special Plan agent for plan mode
Essential for: System stability, cost control, predictable execution
Implementation: Disable Task, TodoWrite, and TodoRead tools in subagent contexts
Security benefit: Limits attack surface for prompt injection exploits
7. Invocation Methods
Four Invocation Methods:
Automatic - Claude matches tasks to agents based on descriptions
Explicit - User mentions agent by name ("use the code-reviewer subagent")
@ Mention - User types @agent-name in chat to invoke specific agent
Provides autocomplete/selection UI
Clear visual indicator of agent invocation
Familiar UX pattern from chat applications
CLI - Dynamic definition via --agents flag for testing/automation
Advanced Features
1. Resumable Agent Execution
Each execution gets unique agentId
Transcript stored as agent-{agentId}.jsonl in project directory
Resume via resume parameter to continue previous sessions
Recording behavior: Recording is disabled during resume to avoid duplicating messages
Agent types: Both synchronous and asynchronous subagents can be resumed
Context restoration: Full context from previous conversation is restored when resuming
Use case: Long-running research, iterative refinement, particularly useful for analysis tasks that span multiple sessions
2. Subagent Chaining
Sequence multiple subagents for complex workflows
Results inform subsequent agent invocations
3. Dynamic Selection
AI matches tasks to agents based on description similarity and context
Documentation: "Claude intelligently matches tasks to subagents based on context and description specificity"
Management Interface
/agents Command - Interactive interface for managing subagents:
✅ Implement @ mention surface for agent selection in chat
Non-Goals (Future Features)
⏳ Resumable agent execution - Transcript storage and resume capabilities
⏳ Agent chaining - Sequential composition of multiple agents
⏳ Persistent agent state - Agents maintaining state across invocations
⏳ Config file watching - Watch project-level config files for automatic reload on changes
Detailed Design
Architecture Overview
The NeovateCode subagent system follows a hierarchical architecture with clear separation between configuration loading, task delegation, and execution. The system ensures isolated execution contexts while maintaining centralized control over agent lifecycle and security.
{
"agents": {
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer specializing in code quality, security, and best practices.\n\nWhen invoked, review code changes and provide constructive feedback...",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "inherit"
},
"test-runner": {
"description": "Runs tests and analyzes failures",
"prompt": "You are a test automation expert...",
"tools": ["Read", "Bash", "Grep"],
"model": "haiku"
}
},
"defaultModel": "sonnet",
"otherSettings": "..."
}
Agent Definition Example
---name: code-reviewerdescription: Expert code reviewer. Use proactively after code changes to review quality, security, and best practices.tools: Read, Grep, Glob, Bash---
You are a senior code reviewer specializing in code quality, security, and best practices.
...
Security Considerations
Tool Permission Enforcement
Risk: Agents could access tools they shouldn't have Mitigation:
Validate tool permissions before each tool call
Deny-by-default for unspecified tools
Audit log of tool usage per agent
Configuration Injection
Risk: Malicious YAML could execute code Mitigation:
Use safe YAML parser (no custom tags)
Validate all configuration values
Sanitize file paths
Prompt Injection via Agent Descriptions
Risk: Crafted descriptions could manipulate delegation Mitigation:
Treat descriptions as data, not instructions
Use structured matching, not prompt concatenation
Rate matching algorithm's reasoning
Performance Considerations
Latency Concerns
Cold Start Overhead:
Each agent invocation starts with empty context
No warm state to leverage
Fresh LLM conversation initialization
Mitigation Strategies:
Use faster models (Haiku) for simple agents
Optimize prompt length in system prompt
Cache parsed configurations
Parallel agent discovery on startup
Context Window Management
Main Conversation Preservation:
Agents help preserve main context by isolating work
Enables longer overall sessions
Reduces need for conversation resets
Trade-off:
Agent results returned to main → still consumes main context
Need concise result summarization
Storage Concerns
Transcript Accumulation:
Each agent execution creates transcript file
Can accumulate over time
Mitigation:
Implement transcript TTL and auto-cleanup
Add transcript compression
Provide cleanup command
Configuration Loading
Startup Performance:
Must scan multiple directories
Parse YAML + Markdown for each agent
Can be slow with many agents
Optimization:
Lazy loading (load on first use)
Cache parsed configurations
Watch files for changes (hot reload)
Parallel parsing
Open Questions
Technical Questions
How do we handle agent execution timeouts?
Should we set max execution time per agent?
How do we gracefully terminate long-running agents?
Should users be able to configure timeouts?
Should we treat the main conversation as a first-class agent?
Main conversation could be an agent with its own configuration
Would unify the architecture (all conversations are agents)
Enables features like: main agent model selection, tool restrictions, custom system prompts
Trade-off: Added complexity vs architectural consistency
---
name: simple-agentdescription: A minimal agent for testing
---
You are a helpful assistant.
Full-Featured Agent:
---
name: advanced-agentdescription: Advanced agent with all options. Use for complex analysis tasks.tools: Read, Write, Grep, Glob, Bashmodel: sonnet
---
# Advanced Agent System PromptYou are a senior software architect with expertise in system design.## Your Capabilities
- Analyze complex codebases
- Design scalable architectures
- Review technical designs## Your Process1. Understand the requirements thoroughly2. Analyze existing code and patterns3. Propose solutions with trade-offs4. Provide implementation guidance## Output FormatAlways structure your responses with:
- Executive Summary
- Detailed Analysis
- Recommendations
- Implementation Steps
- Risks & Mitigation
Appendix B: Configuration Examples
Define agents in .neovate/config.json:
{
"agents": {
"reviewer": {
"description": "Code reviewer for quality and security",
"prompt": "You are an expert code reviewer. Review code for quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob"],
"model": "haiku"
},
"test-analyst": {
"description": "Analyzes test failures and suggests fixes",
"prompt": "You are a test debugging expert. Analyze test failures and provide actionable fixes.",
"tools": ["Read", "Bash", "Grep"],
"model": "sonnet"
}
}
}
Define agents in ~/.neovate/config.json (personal):
{
"agents": {
"my-helper": {
"description": "My personal coding assistant",
"prompt": "You are my personal assistant. Help with tasks using my preferred coding style.",
"model": "inherit"
}
}
}
Appendix C: Comparison Matrix
Feature
Claude Code
NeovateCode (Proposed)
Notes
Isolated contexts
✅
✅
Core feature
Multi-level config
✅
✅
Project/User (files + config.json)
CLI config
✅
⏳ Future
Not supported in NeovateCode
Plugin agents
✅
⏳ Future
Not supported in NeovateCode
config.json agents
❌
✅
NeovateCode addition
Tool permissions
✅
✅
Inherit or specify
Resumable agents
✅
⏳ Future
Planned, not MVP
Nesting prevention
✅
✅
Core security feature
MCP integration
✅
✅
Full support
/agents command
✅
✅
CRUD interface
Visual builder
❌
❌
Not planned
Cloud marketplace
❌
❌
Local-first
Document Version: 1.0 Next Review Date: 2025-12-01
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
-
Status: Draft
Created: 2025-11-21
Last Updated: 2025-11-21
Abstract
This RFC proposes the design and implementation of a specialized subagent system for NeovateCode, inspired by Claude Code's subagent architecture. The system will enable delegation of specific tasks to specialized AI assistants that operate in isolated context windows, improving task specialization while preserving the main conversation's focus and efficiency.
Table of Contents
Product Research: Claude Code Subagents
Overview
Claude Code implements a sophisticated subagent system that provides task-specific AI delegation with isolated contexts. According to their documentation: "Each subagent operates in its own context, preventing pollution of the main conversation." This section provides a deep analysis of the existing implementation to inform our design decisions.
Core Value Proposition
Primary Benefits Observed:
Context Preservation
Specialized Expertise
Reusability & Collaboration
Flexible Security
Feature Analysis
Core Capabilities
1. Isolated Context Windows
2. Multi-Level Configuration System
Storage Locations & Priority:
.claude/agents/*.mdfor team-shared agents--agentsJSON flag for session-specific configs~/.claude/agents/*.mdfor personal agents3. Configuration Format
Field Specifications:
namedescriptiontoolsmodel4. Tool Access Control
Two Configuration Options:
Option 1: Inherit All Tools (Default)
toolsfield entirelyOption 2: Granular Control
MCP Integration: Full support for Model Context Protocol tools, inherited by default
MCP Tool Details:
mcp__server__tool(double underscore separators)/agentscommand displays all available MCP tools during agent creation5. Model Selection
Model Options:
sonnet,opus,haiku- Specific models for cost/performance tuninginherit- Matches main conversation model6. Agent Nesting Prevention
7. Invocation Methods
Four Invocation Methods:
@agent-namein chat to invoke specific agent--agentsflag for testing/automationAdvanced Features
1. Resumable Agent Execution
agentIdagent-{agentId}.jsonlin project directoryresumeparameter to continue previous sessions2. Subagent Chaining
3. Dynamic Selection
Management Interface
/agentsCommand - Interactive interface for managing subagents:@ Mention in Chat - Quick agent invocation surface:
@to trigger agent autocomplete dropdownAlternative: Direct file editing in
.claude/agents/*.mdor~/.claude/agents/*.mdBuilt-in Subagents
Claude Code ships with 4 built-in subagents:
1. general-purpose (Sonnet)
2. statusline-setup (Sonnet)
3. Explore (Haiku)
4. Plan (Sonnet)
Best Practices
Performance Characteristics
Benefit: "Subagents preserve main context for longer overall sessions"
Cost: "Clean-slate invocations may add latency as subagents gather required context"
Optimizations: Use Haiku for simple tasks, provide context in task description, use resumable agents for iterative work
Key Design Patterns
1. Hierarchical Configuration with Priority Override
2. Context Isolation by Default
3. Secure by Default, Flexible When Needed
4. Automatic with Manual Override
5. File-Based Configuration
.claude/agents/Trade-offs Analysis
Benefits:
Costs:
/agentsUI, AI-assisted creation)Implementation Insights & Lessons
Motivation
NeovateCode needs a subagent system to enable task delegation with isolated contexts and specialized expertise. Key benefits include:
This follows the proven pattern established by Claude Code's subagent architecture.
Goals & Non-Goals
Goals
MVP: Task Tools with Built-in Subagents
general-proposalandexplorePhase 1: Custom Subagent Support
Phase 2: Interactive Agent Management
/agentscommand interfaceNon-Goals (Future Features)
Detailed Design
Architecture Overview
The NeovateCode subagent system follows a hierarchical architecture with clear separation between configuration loading, task delegation, and execution. The system ensures isolated execution contexts while maintaining centralized control over agent lifecycle and security.
High-Level System Architecture
Configuration Loading Architecture
Agent Invocation Flow
Nesting Prevention Mechanism
Data Flow Diagram
Core Components
1. Task Tool Implementation
System Prompt Integration
Task Tool Parameters
Execution Flow
Return Result
Delegation Logic
Main agent delegates when:
2. Agent Executor & Context Isolation
Isolated Context
Message History
Context Cleanup
Intermediate Messages
Error Handling
Model Selection
Priority: param > config > inherit > default
3. Tool Permission System
Tool Resolver
tools→ use explicit subsettools→ inherit all from main (default)Tool Filtering for Subagents (Nesting Prevention)
CRITICAL: When
isSubagent = true, automatically remove:Why This Works:
Why Essential:
Permission Approval
Tool Validation
MCP Tool Support
mcp__server__tool4. Agent Configuration System
Configuration Schema
Configuration Sources
~/.neovate/agents/*.mdor.neovate/agents/*.mdagentsfield~/.neovate/config.jsonor.neovate/config.jsonPriority & Merge Strategy
Agent Registry
Map<name, AgentConfig>Validation
5. Management Interface
/agentsCommandCRUD Operations
External Editor
File Structure
Priority Rules:
Example Scenario:
Example .neovate/config.json with agents:
{ "agents": { "code-reviewer": { "description": "Expert code reviewer. Use proactively after code changes.", "prompt": "You are a senior code reviewer specializing in code quality, security, and best practices.\n\nWhen invoked, review code changes and provide constructive feedback...", "tools": ["Read", "Grep", "Glob", "Bash"], "model": "inherit" }, "test-runner": { "description": "Runs tests and analyzes failures", "prompt": "You are a test automation expert...", "tools": ["Read", "Bash", "Grep"], "model": "haiku" } }, "defaultModel": "sonnet", "otherSettings": "..." }Agent Definition Example
Security Considerations
Tool Permission Enforcement
Risk: Agents could access tools they shouldn't have
Mitigation:
Configuration Injection
Risk: Malicious YAML could execute code
Mitigation:
Prompt Injection via Agent Descriptions
Risk: Crafted descriptions could manipulate delegation
Mitigation:
Performance Considerations
Latency Concerns
Cold Start Overhead:
Mitigation Strategies:
Context Window Management
Main Conversation Preservation:
Trade-off:
Storage Concerns
Transcript Accumulation:
Mitigation:
Configuration Loading
Startup Performance:
Optimization:
Open Questions
Technical Questions
How do we handle agent execution timeouts?
Should we treat the main conversation as a first-class agent?
Product Questions
How do we measure agent effectiveness?
How do we handle breaking changes?
User Experience Questions
How do users discover which agents are available?
/agentslist?How do we communicate agent activity to users?
Should users approve agent invocations?
How do we handle agent failures gracefully?
References
External References
Claude Code Documentation
Appendix
Appendix A: Configuration Examples
Minimal Agent:
Full-Featured Agent:
Appendix B: Configuration Examples
Define agents in .neovate/config.json:
{ "agents": { "reviewer": { "description": "Code reviewer for quality and security", "prompt": "You are an expert code reviewer. Review code for quality, security, and best practices.", "tools": ["Read", "Grep", "Glob"], "model": "haiku" }, "test-analyst": { "description": "Analyzes test failures and suggests fixes", "prompt": "You are a test debugging expert. Analyze test failures and provide actionable fixes.", "tools": ["Read", "Bash", "Grep"], "model": "sonnet" } } }Define agents in ~/.neovate/config.json (personal):
{ "agents": { "my-helper": { "description": "My personal coding assistant", "prompt": "You are my personal assistant. Help with tasks using my preferred coding style.", "model": "inherit" } } }Appendix C: Comparison Matrix
/agentscommandDocument Version: 1.0
Next Review Date: 2025-12-01
Beta Was this translation helpful? Give feedback.
All reactions