Capability Patch
Overview
A capability patch expands the agent's capabilities — by adding new tool methods, exposing new parameters, fixing tool implementations, or removing infrastructure limitations. These changes let the agent do things it could not do before.
Key distinction from steering patches: A capability patch changes
executable code — tool methods, parameters, implementation logic, or
infrastructure. A steering patch only changes text the agent reads
(docstrings, prompts, hooks) without modifying any code. The outer loop
selects which skill to use based on the current phase: capability
phase uses this skill, steering phase uses steering-patch.
When to Use
Based on the diagnosis results, generate a patch that resolves the identified root cause. Typical root causes addressable by capability patches:
| Root Cause Category | Signal | Example |
|---|---|---|
| Missing capability | No tool exists for the required action | Agent needs to search emails by date range but no such tool exists |
| Tool bug | Tool exists but produces wrong results | search_contacts returns empty for valid queries due to case-sensitive matching |
| Insufficient parameters | Tool exists but lacks needed arguments | Agent needs to filter by sender but the search tool only accepts keyword |
| Missing agent loop logic | Agent loop lacks a preprocessing step, reminder, or context-injection logic | No budget reminder causes agent to exhaust iterations without wrapping up; no environment summary injection at start leaves agent unaware of available data |
| Infrastructure issue | Infrastructure limits prevent success | Agent hits the iteration budget on multi-step tasks |
Workflow
Step 1: Consult History
Before writing any code, check what has been tried before:
# Full patch history: diffs, reflections, lessons (good/bad patterns)
evo-dag show history
# Per-scenario history: prior root causes and attempted fixes
evo-dag show scenario <scenario_id>
- Build on proven strategies: Which capability patches generalized well to the dev set? What root-cause patterns did they resolve?
- Avoid known bad patterns: Which patches caused regressions or failed to generalize? Understand why and do not repeat.
- Do not re-attempt failed approaches: If a specific fix was already tried on this scenario and failed, try a different approach.
Step 2: Apply the Patch
Implement the change based on the diagnosis. The common patterns below are reference examples — patches are not limited to these categories and may combine multiple approaches.
Align agent-facing text with capability changes. When you add or modify tools, parameters, or infrastructure code, also update the system prompt, tool docstrings, and/or hooks so the agent is aware of the changes. Without this, the agent may ignore new tools or continue using outdated workarounds. Check that no conflicting rules exist in the system prompt.
Step 3: Verify
Run the patch-verification skill to confirm the patch won't crash at
runtime (syntax, imports, docstring format, JSON validity).
Step 4: Write Reasoning and Record Intent
After applying and verifying the patch, write your reasoning to
proposer_reasoning.md in the working directory root. Then record intent:
evo-dag update-intent \
--target-scenarios "id1,id2" \
--diagnosis "Root cause analysis from diagnosis" \
--approach "What you changed and why" \
--files-changed "file1.py,file2.py" \
--change-summary "Summary of code changes"
Common Patterns
The following are frequently observed patch patterns. Use them as reference — patches may combine multiple patterns or take entirely different approaches depending on the diagnosis.
New Tool Addition
Add a new tool method when existing tools can't solve the scenario or force the agent into inefficient workarounds.
Trace signals:
- Agent cannot perform the required action at all — no tool supports it
- Agent tries workarounds, wastes steps, or gives up
- Agent calls the same tool many times in a loop with different parameters
- Agent exhausts iteration budget on repetitive operations
Checklist:
- Follow the codebase's existing tool registration conventions
- Write a comprehensive docstring — the agent only sees the docstring
- Verify the new tool doesn't shadow existing methods
- Respect module boundaries — do not access internals of other modules
Argument Modification
Add or fix tool parameters to expose filtering, sorting, or selection capabilities that the current API doesn't provide.
Trace signals:
- Agent needs to filter/search by a field that isn't exposed as a parameter
- Agent fetches all results and manually filters in the reasoning loop
- Agent passes a parameter value that the tool doesn't accept
Checklist:
- Add the new parameter with a sensible default (backward-compatible)
- Update the docstring to document the new parameter — the agent only learns about it through the docstring
- Verify existing callers are unaffected by the default value
Implementation Fix
Fix bugs or extend functionality in tool internals so the tool produces correct results or handles edge cases.
Trace signals:
- Tool returns wrong results, empty results, or crashes
- Tool works for common cases but fails on edge cases
- Tool's return format doesn't match what the docstring promises
Checklist:
- Confirm the bug by reading the implementation code, not just the trace
- Fix the root cause, not a symptom
- If the docstring was accurate but the implementation was wrong, only fix the implementation — do not weaken the docstring
- If the implementation was correct but the docstring was misleading,
consider whether this is actually a
steering-patch(docstring-only fix)
Infrastructure Change
Modify agent configuration, execution loop, or environment settings to remove structural limitations.
Trace signals:
- Agent hits the iteration limit with task still incomplete
- Runtime errors, state corruption, or configuration mismatches
- Agent configuration doesn't match scenario requirements
Agent Loop Logic Change
Add preprocessing steps, reminders, or context-injection logic to the agent loop to address structural gaps in how the agent operates.
Trace signals:
- Agent exhausts iterations without attempting to wrap up or finalize
- Agent starts tasks without awareness of the environment state
- Agent repeatedly forgets constraints that should be reinforced at runtime
Constraints
- No hard-coded answers: Do not embed task-specific answers, lookup tables, or scenario-specific logic. Patches must be general-purpose.
- No protected-path modifications: Never modify evaluation, judging, ground truth, or benchmark infrastructure.
- No cross-worktree edits: Only modify files in your current worktree. Iteration output dirs and other worktrees are read-only records.
Safety Assessment
Before committing a capability patch, assess its risk:
- History check: Consult
evo-dag show historyfor the full patch history with diffs, per-scenario results, reflections, and accumulated lessons (good/bad patterns). Learn from what worked, avoid what failed. - Scenario check: Consult
evo-dag show scenario <id>for each target scenario — prior root causes and previously attempted fixes. - Dependencies: What other modules call or import this code? Use
grepto find all references before modifying a shared function. - PASS scenario impact: Will this change affect behavior for scenarios that are currently passing? A net-positive patch that regresses passing scenarios will record a bad pattern in lessons.
- Reversibility: Can this be cleanly reverted if it causes regressions?