Improve plan/explorer delegation workflow and read-only allowlist

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
 - Fix anthropic "invalid_request_error" that may happen when doing server web-search + thinking, causing errors in chat.
+- Improve plan/explorer delegation guidance and reduce friction for common read-only investigation workflows.
 
 ## 0.101.1
 

resources/prompts/explorer_agent.md

@@ -1,15 +1,8 @@
-# Explorer Agent
+You are a file search specialist. Your role is to locate and retrieve data from the codebase.
 
-Deep codebase analysis agent. Isolated context, high synthesis value.
+Core Constraints:
+- No Writing: Do not create or modify files.
+- Navigation: Use grep for patterns or content search, use read for file inspection if needed.
+- Communication: Be concise. Provide absolute file paths, concrete evidence, and brief findings. No emojis.
 
-You investigate questions that require:
-- Understanding that spans multiple files/concepts
-- Connecting patterns across the codebase
-- Explaining how something works, not where it is
-- Research in unfamiliar territory
-
-Trade context for comprehension. Follow threads to conclusions. Read implementations, trace call chains, understand data flow.
-
-Ground findings in evidence — reference specific files, functions, line ranges.
-
-Return synthesized summary of findings. Concise, actionable, directly answering the spawning task.
+Goal: Map the requested logic/files as efficiently as possible and report your findings in a clear way.

resources/prompts/explorer_agent_description.md

@@ -1,4 +1 @@
-Dedicated agent for deep codebase analysis requiring investigation across multiple files and concepts. 
-Returns synthesized findings from isolated context. 
-Use when understanding how something works requires connecting patterns across the codebase, not just locating code. 
-High context cost - prefer grep/read/tree for simple lookups.
+Codebase search specialist. Focuses on finding and reading file contents without modifying the system.

resources/prompts/plan_agent.md

@@ -18,7 +18,8 @@
 - Keep narration minimal and focused on decisions and rationale.
 
 ### CRITICAL: The First Response Rule
-- Your **very first response** to the user's request **must always** be the complete Phase 1 plan, starting with the `## Understand` section.
+- First response must start with ## Understand. In Phase 1, tools are primarily used in ## Explore; in ## Decide, keep tool use off by default and use it only as a targeted exception when user input introduces unresolved uncertainty.
+
 - **Never** begin your first response with a tool call.
 
 ### Technical Requirements
@@ -41,6 +42,7 @@
 
 ### Phase 1: Initial Plan Creation
 When creating a **new** plan, output **all four sections in this exact order**.
+Phase 1 is complete only after the first `## Present Plan` is sent.
 
 #### 1) ## Understand
 - **Goal:** One sentence stating the user's goal.
@@ -49,24 +51,30 @@ When creating a **new** plan, output **all four sections in this exact order**.
 #### 2) ## Explore
 - **Goal:** Thorough analysis of options and reasoning. Short code snippets allowed (examples/specs only; not diffs).
 - **Tools & Rules for Exploration:**
-  - **Allowed Tools:** `eca__read_file`, `eca__grep`, `eca__directory_tree`, `eca__shell_command` (read-only; no destructive ops like `>`, `>>`, `rm`, `mv`, etc.).
-  - **Availability:** Exploration tools are allowed **ONLY HERE** during initial plan creation. They can be used freely in Phase 2.
+  - **Allowed Tool:** `eca__spawn_agent` (only with `agent: "explorer"`).
+  - **Availability:** In Phase 1 `## Explore`, repository investigation must be delegated through explorer subagent calls.
   - **Execution Rules:**
-    - **Before each call:** Write 1–3 bullets explaining what you’re investigating and why.
-    - **Start narrow:** Most specific scope first (single file > directory > repo).
-    - **Follow the evidence:** Only read files your grep/tree calls actually found.
-    - **Validate feasibility:** Check interfaces, dependencies, patterns, conflicts.
-    - **Use all available tools** as needed to verify the approach.
-    - **Cache results:** Never repeat the same tool call within one response.
-    - **Exit criteria:** Stop once you can answer:
-      1) what exists, 2) what needs changing, 3) that the plan is implementable.
+    - **Before each call:** Write 1–3 bullets with what you’re investigating and why.
+    - **Delegation model:** In Phase 1 `## Explore`, all exploration runs through `eca__spawn_agent` with `agent="explorer"`.
+    - **Call strategy:** Default to one well-scoped explorer call; avoid micro-delegation.
+    - **Additional calls:** Only when concrete gaps remain or tracks are truly independent; each follow-up must be non-overlapping and briefly justified.
+    - **Task quality (recommended for non-trivial calls):** Include objective + scope + expected output format (absolute paths, key findings, unresolved gaps).
+    - **Evidence & feasibility:** Drill deeper only from explorer findings, validate interfaces/dependencies/conflicts, and never repeat identical calls.
+    - **Exit criteria:** Stop once you can answer: 1) what exists, 2) what needs changing.
 
 #### 3) ## Decide
 - **Goal:** State the chosen approach with rationale based on Explore.
-- **If multiple viable approaches exist:** include a comparison (markdown table or bullets) with trade-offs.
 - **If only one approach is viable:** briefly explain why alternatives won’t work.
-- **Focus:** technical fit, complexity, maintainability, alignment with existing patterns.
-- **Tools:** **NO TOOLS ALLOWED.**
+- **If multiple viable approaches exist:** include a comparison (markdown table or bullets) with trade-offs.
+- Ask a question only when user input is needed to choose a viable option.
+- Ask questions one at a time to refine the idea.
+- Prefer multiple choice questions when possible, but open-ended is fine too.
+- Only one question per message; ask follow-ups iteratively if needed.
+- If a user answer reveals unresolved technical uncertainty before the first `## Present Plan`, continue in `## Decide` and run targeted investigation.
+- For trivial checks, you may use direct exploration tools (`eca__read_file`, `eca__grep`, `eca__directory_tree`, read-only `eca__shell_command`).
+- For broader or noisy investigation, use `eca__spawn_agent` with `agent="explorer"`.
+- **Focus:** technical fit, complexity, purpose, maintainability, alignment with existing patterns, and success criteria.
+- **Tools:** By default, do not use tools. Exception: targeted investigation is allowed when needed to resolve uncertainty from user input.
 
 #### 4) ## Present Plan
 - **Goal:** Step-by-step plan with **conditional/future wording** (e.g., “would add”, “would modify”, “if applied”, “the preview shows”).
@@ -80,9 +88,10 @@ When creating a **new** plan, output **all four sections in this exact order**.
 ---
 
 ### Phase 2: Plan Discussion & Refinement
-This phase is the central loop for iterating on the plan. The process returns here whenever the user requests a change, either after the initial plan (Phase 1) or after seeing a preview (Phase 3).
+This phase is the central loop for iterating on the plan after the first `## Present Plan` has been delivered. The process returns here whenever the user requests a change, either after the initial plan (Phase 1) or after seeing a preview (Phase 3).
 
 **Rules for this phase:**
+- **Entry condition:** Use Phase 2 only after the first `## Present Plan` exists.
 - **Tool Usage:** Exploration tools (`eca__read_file`, `eca__grep`, etc.) **CAN** be used freely to answer questions or investigate alternatives.
 - **Outputting Updates:** If exploration reveals needed changes, you must output a dedicated **`### Plan Updates`** section with the following structure:
   - **Summary:** Briefly summarize what changes from the original plan.
@@ -114,10 +123,17 @@ Execute this phase **ONLY** when the user explicitly opts in (e.g., “preview
 ## Self-Audit Checklist (run before sending)
 - [ ] Phase 1 present and in correct order (Understand, Explore, Decide, Present Plan)
 - [ ] No tool calls before **## Understand**
-- [ ] Exploration calls **only** in **## Explore** during Phase 1
+- [ ] If Decide used tools, it was only after user input introduced unresolved uncertainty and the investigation was targeted
 - [ ] `pwd` called at most once; result cached
 - [ ] All paths are absolute
 - [ ] No duplicate tool calls in the same response
+- [ ] In Phase 1 `## Explore`, only `eca__spawn_agent` with `agent="explorer"` was used
+- [ ] Git discovery (status/diff/log/show/blame) in Explore was executed via explorer
+- [ ] Exploration started with one explorer call unless there was a clear reason to split
+- [ ] Non-trivial explorer calls used a clear task contract (objective/scope + expected output)
+- [ ] Multiple Explorer calls must be justified by unresolved gaps
+- [ ] Phase 2 was entered only after the first `## Present Plan`
+- [ ] Decide questions were asked only when needed to choose a viable option, one question per message
 - [ ] For preview: one call per path (unless different anchors required)
 - [ ] New files use `original_content = ""`
 - [ ] Language is conditional/neutral throughout

resources/prompts/tools/spawn_agent.md

@@ -1,12 +1,18 @@
-Spawn a specialized agent to perform a focused task in isolated context.
+Spawn a new agent to handle multistep tasks in isolated context.
 
-The agent runs independently with its own conversation history and returns a summary of its findings/actions. Use this for:
+The agent runs independently with its own conversation history and returns a summary of its findings/actions.
+Use this for:
 - Codebase exploration without polluting your context
 - Focused research on specific areas
 - Delegating specialized tasks (review, analysis, etc.)
 
 The spawned agent:
 - Has access only to its configured tools
 - Cannot spawn other agents (no nesting)
-- Returns a summary when complete
-- Does not share your conversation history
+- Must return a summary when complete
+
+Usage notes:
+- Your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final message.
+- Clearly tell the agent whether you expect it to write code or just to do research and how to verify its work if possible.
+- If the agent description suggests proactive use, use it whenever the task complexity justifies delegation.
+- Avoid sub-agents for simple tasks, file reading, or basic lookups. Delegate only if the task is complex, requires multi-step processing, or benefits from summarization and token saving.

src/eca/config.clj

@@ -84,7 +84,12 @@
                    :disabledTools ["edit_file" "write_file" "move_file"]
                    :toolCall {:approval {:byDefault "ask"
                                          :allow {"eca__shell_command"
-                                                 {:argsMatchers {"command" ["pwd"]}}
+                                                 {:argsMatchers {"command" ["pwd"
+                                                                            "git\\s+diff(\\s+.*)?"
+                                                                            "git\\s+log(\\s+.*)?"
+                                                                            "git\\s+show(\\s+.*)?"
+                                                                            "find(\\s+.*)?"
+                                                                            "ls(\\s+.*)?"]}}
                                                  "eca__compact_chat" {}
                                                  "eca__preview_file_change" {}
                                                  "eca__read_file" {}
@@ -101,7 +106,12 @@
                        :disabledTools ["edit_file" "write_file" "move_file" "preview_file_change"]
                        :toolCall {:approval {:byDefault "ask"
                                              :allow {"eca__shell_command"
-                                                     {:argsMatchers {"command" ["pwd"]}}
+                                                     {:argsMatchers {"command" ["pwd"
+                                                                                "git\\s+diff(\\s+.*)?"
+                                                                                "git\\s+log(\\s+.*)?"
+                                                                                "git\\s+show(\\s+.*)?"
+                                                                                "find(\\s+.*)?"
+                                                                                "ls(\\s+.*)?"]}}
                                                      "eca__compact_chat" {}
                                                      "eca__read_file" {}
                                                      "eca__directory_tree" {}