feat(agent): add explore sub-agent and expand task agent capabilities by dcu · Pull Request #2989 · charmbracelet/crush

dcu · 2026-05-24T01:12:15Z

Summary

feat(agent): add explore sub-agent for fast read-only codebase search
- Add explore task type to the agent tool alongside the existing task type
- Introduce resolveExploreTools to give the explore agent a focused read-only toolset: glob, grep, ls, sourcegraph, view
- Explore agent uses the small model and no context paths for speed
feat(agent): enable full toolset for task sub-agent
- Replace the task agent's read-only-only toolset with resolveTaskTools, granting it:
  - File editing: edit, multiedit, write
  - Shell execution: bash
  - Network/data: fetch, agentic_fetch, download
  - LSP support: lsp_diagnostics, lsp_references, lsp_restart
  - Task tracking: todos
  - Code search: glob, grep, ls, sourcegraph, view
  - MCP resources: list_mcp_resources, read_mcp_resource
  - Meta tools: crush_info, crush_logs, job_output, job_kill
- The task agent is now capable of autonomous delegated work (editing, running commands, etc.) rather than being functionally identical to the explore agent
docs(agent): update sub-agent tool and task templates
- agent_tool.md: update task description to explicitly mention editing files, running commands, fetching data, and multi-step investigations
- task.md.tpl: add explicit capabilities statement so the task sub-agent knows it can modify state
- coder.md.tpl: add context-length guidance for sub-agent delegation and parallel tool usage rules
refactor(config): split resolveReadOnlyTools into resolveExploreTools and resolveTaskTools
- Clear separation between read-only exploration and general delegated work
- Updated all load_test.go assertions to match the new tool lists

Test plan

go test ./internal/config/ — 225 passed
go test ./internal/agent/ — 81 passed
go test ./... — 1743 passed across 65 packages
Verify task agent can perform edits, shell commands, and fetches when delegated
Verify explore agent remains strictly read-only

💘 Generated with Crush

…e guidelines Improve agent_tool.md with comprehensive usage instructions, when to use and when not to use guidance, and parallel usage tips. Rewrite task.md.tpl with structured search methodology, efficiency guidelines, output format requirements, and anti-patterns for read-only agents. 💘 Generated with Crush Assisted-by: Crush:accounts/fireworks/models/kimi-k2p6

vadiminshakov · 2026-05-24T07:01:25Z

+Launch a specialized read-only agent to thoroughly search and explore the code and documentation.
+
+This agent has access to `glob`, `grep`, `ls`, `view`, and `sourcegraph`. It is optimized for finding files, searching code and documentation, and analyzing architecture — but it **cannot edit files or run commands**.
+


agent_tool is intended for running subagents, not necessarily for exploring the codebase as it does now.

In the future, we may add custom agents, and then this prompt would confuse the model.

Essentially, this is a description for the task subagent.

vadiminshakov · 2026-05-24T07:09:00Z

+You do NOT have access to file editing tools (`edit`, `multiedit`, `write`).
+You do NOT have access to command execution (`bash`).
+You do NOT have access to web fetching (`fetch`, `agentic_fetch`).


The model already sees which tools are available to it in every prompt.

I don’t think we should hardcode everything so strictly here, because changes in the buildTools logic would then become tightly coupled to this prompt.

vadiminshakov · 2026-05-24T07:14:45Z

+
+<efficiency>
+- Spawn **multiple parallel tool calls** whenever searches are independent (e.g., glob for `*.go` AND grep for `func main` at the same time). This is required, not optional.
+- Don't read entire files — use `offset` and `limit` to read only the sections you need.


- Prefer not to read entire files when it's unnecessary. Use `offset` and `limit` to inspect only the relevant sections when the file is large or when you already know where to look.

We should leave the model room to choose.

- Add strengths, guidelines, and completion-report expectations to coder - Add when-not-to-use guardrails to task agent - Add writing-the-prompt guidance with "never delegate understanding" rule - Add trust and intent-clarity notes to task efficiency section 💘 Generated with Crush Assisted-by: Crush:accounts/fireworks/models/kimi-k2p6

dcu · 2026-05-25T22:17:16Z

@vadiminshakov review again please

vadiminshakov · 2026-05-26T13:22:49Z

+<strengths>
+- Searching for code, configurations, and patterns across large codebases
+- Analyzing multiple files to understand system architecture
+- Investigating complex questions that require exploring many files
+- Performing multi-step research tasks
+</strengths>


I think this is the responsibility of the task agent.

hey @vadiminshakov do you think it makes sense to create a specific exploration task?

vadiminshakov · 2026-05-26T13:24:40Z

+<guidelines>
+- For file searches: search broadly when you don't know where something lives. Use `view` when you know the specific file path.
+- For analysis: Start broad and narrow down. Use multiple search strategies if the first doesn't yield results.
+- Be thorough: Check multiple locations, consider different naming conventions, look for related files.
+- NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one.
+- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested.
+</guidelines>


I think frontier models know better how to perform search. We shouldn’t constrain them with our own instructions just to better guide weaker models.

vadiminshakov · 2026-05-26T17:04:03Z

+Your job is to use the tools available to you to complete the assigned task fully and report back concisely. You can use whatever tools are appropriate for the task at hand, subject to what is available in your toolset.



If that’s the case, then we should adjust the task agent’s AllowedTools.

what tools would you suggest for it?

All tools except agent

ok done and prompt adjusted

@vadiminshakov so I've been using this with plan mode and it sometimes uses the task agent to write even in plan mode. how do you suggest tackling that? maybe allowing to scope the agent tool like agent:explore and agent:task

agent:explore and agent:task

Yes, that’s one possible approach. Scopes are a better design choice. Another option would be to disallow task usage in plan mode by returning an error from the agentTool call.

That said, I’m not sure it makes much sense for us to decide this without input from the maintainers.

Add a new "explore" task type to the agent tool alongside the existing task agent. The explore agent is designed for fast read-only codebase search with a dedicated prompt template and configuration. - Add AgentTaskExplore constant and explore prompt template - Update agent tool to dispatch between task and explore agents - Add AgentExplore config key support - Update golden testdata for GLM-5.1 💘 Generated with Crush Assisted-by: Crush:accounts/fireworks/models/kimi-k2p6

dcu · 2026-05-26T22:09:11Z

@kujtimiihoxha @taciturnaxolotl hello, can you guys take a look at this? according to the log you were the last people working on this

also if you can take a look at plan mode which is related to this ticket. #2822
it's very important for our company workflow

let me know how can I help

thanks in advance

Simplify agentTool signature to only accept ctx and fixedTask, using embedded description and deriving the tool name from the task. Add IsAgentTool helper for identifying agent tool variants. Include tests for scoped tool names and buildTools inclusion. 💘 Generated with Crush Assisted-by: Crush:accounts/fireworks/models/kimi-k2p6

charmcli added area: docs area: tools labels May 24, 2026

dcu mentioned this pull request May 24, 2026

feat: add plan mode #2822

Open

dcu force-pushed the improve-sub-agents branch from 21d829d to 25952f4 Compare May 24, 2026 01:38

dcu force-pushed the improve-sub-agents branch from 25952f4 to b65a54b Compare May 24, 2026 04:04

vadiminshakov reviewed May 24, 2026

View reviewed changes

dcu force-pushed the improve-sub-agents branch from 3bdd4d2 to 36c4ae0 Compare May 25, 2026 22:16

vadiminshakov reviewed May 26, 2026

View reviewed changes

dcu force-pushed the improve-sub-agents branch from 89c7c22 to 0800fff Compare May 26, 2026 18:50

dcu force-pushed the improve-sub-agents branch from 0800fff to 36b8763 Compare May 26, 2026 18:56

dcu requested a review from vadiminshakov May 26, 2026 18:58

dcu changed the title ~~docs(agent): enhance sub-agent tool and task templates~~ feat(agent): add explore sub-agent and expand task agent capabilities May 26, 2026

vadiminshakov approved these changes May 26, 2026

View reviewed changes

		Launch a specialized read-only agent to thoroughly search and explore the code and documentation.

		This agent has access to `glob`, `grep`, `ls`, `view`, and `sourcegraph`. It is optimized for finding files, searching code and documentation, and analyzing architecture — but it cannot edit files or run commands.

		Your job is to use the tools available to you to complete the assigned task fully and report back concisely. You can use whatever tools are appropriate for the task at hand, subject to what is available in your toolset.

Conversation

dcu commented May 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dcu commented May 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dcu May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dcu commented May 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dcu commented May 24, 2026 •

edited

Loading

dcu May 27, 2026 •

edited

Loading