🔧 fix(core): fix orchestration loops, over-correction, and redundant LLM calls

Root cause analysis comparing against Claude Code revealed Meeseeks made
12-14 LLM calls per 3-step task (vs ~3 for CC). Each extra call introduced
drift, plan inflation, and loop risk.

Prompts:
- action-planner: enforce 1-2 steps for simple tasks, max 5 total
- plan-updater: NEVER add new steps, return empty when goal met
- step-executor: prefer "respond" over "tool" when uncertain
- reflection: default to "ok" unless clear failure (error/empty/contradiction)

Hard guards:
- Cap PlanUpdater output (never more steps out than in)
- Skip PlanUpdater when only 1 step remains (saves 1 LLM call)
- Pass budget context (steps_run/max_steps) to PlanUpdater
- Reduce max_steps multiplier from 5 to 3 (default 9 instead of 15)

Redundant LLM call elimination:
- Remove ToolSelector from act-mode flow (Planner already filters by intent)
- Make reflection opt-in per tool via metadata.reflect (shell/edit only)

Cleanup:
- Remove dead _should_replan() and _build_revised_query() methods
- Add .mcp.json to .gitignore (contains auth tokens)

Author: bearlike

.gitignore

@@ -1,6 +1,9 @@
 # Ignore Repo to Prompt
 repo-to-prompt.codemod.js
 
+# MCP config (contains auth tokens)
+.mcp.json
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

packages/meeseeks_core/src/meeseeks_core/action_runner.py

@@ -199,7 +199,10 @@ def _execute_step(self, action_step: ActionStep) -> StepOutcome:
             content = "" if action_result is None else str(action_result)
         reflection = None
         if self._reflector is not None:
-            reflection = self._reflector.reflect(action_step, content)
+            spec = self._tool_registry.get_spec(action_step.tool_id)
+            should_reflect = spec is not None and spec.metadata.get("reflect", False)
+            if should_reflect:
+                reflection = self._reflector.reflect(action_step, content)
         return StepOutcome(content=str(content), reflection=reflection)
 
     def _handle_tool_error(

packages/meeseeks_core/src/meeseeks_core/orchestrator.py

@@ -23,7 +23,6 @@
     PlanUpdater,
     ResponseSynthesizer,
     StepExecutor,
-    ToolSelector,
 )
 from meeseeks_core.reflection import StepReflector
 from meeseeks_core.session_store import SessionStore
@@ -59,7 +58,6 @@ def __init__(
         self._hook_manager = hook_manager or default_hook_manager()
         self._context_builder = ContextBuilder(self._session_store)
         self._planner = Planner(self._tool_registry)
-        self._tool_selector = ToolSelector(self._tool_registry)
         self._step_executor = StepExecutor(self._tool_registry)
         self._plan_updater = PlanUpdater(self._tool_registry)
         self._synthesizer = ResponseSynthesizer(self._tool_registry)
@@ -146,16 +144,8 @@ def _run_with_session_context(
                 else self._tool_registry.list_specs_for_mode("act")
             )
             if plan is None:
-                if resolved_mode != "plan":
-                    selection = self._tool_selector.select(
-                        user_query,
-                        self._model_name,
-                        tool_specs=tool_specs,
-                        context=context,
-                    )
-                    if selection.tool_required and selection.tool_ids:
-                        selected_ids = self._expand_tool_ids(set(selection.tool_ids), tool_specs)
-                        tool_specs = [spec for spec in tool_specs if spec.tool_id in selected_ids]
+                # Tool filtering is handled by Planner._filter_specs_by_intent()
+                # No separate ToolSelector LLM call needed in act mode
                 plan = self._planner.generate(
                     user_query,
                     self._model_name,
@@ -183,7 +173,7 @@ def _run_with_session_context(
                 state.done = True
                 state.done_reason = "planned"
             else:
-                max_steps = max(0, max_iters) * 5
+                max_steps = max(0, max_iters) * 3
                 steps_run = 0
                 allowed_tool_ids = {spec.tool_id for spec in tool_specs}
                 while remaining_steps and steps_run < max_steps:
@@ -250,15 +240,21 @@ def _run_with_session_context(
                         state.done = True
                         state.done_reason = "canceled"
                         break
-                    if remaining_steps:
+                    if remaining_steps and len(remaining_steps) > 1:
+                        old_count = len(remaining_steps)
                         remaining_steps = self._plan_updater.update(
                             user_query,
                             self._model_name,
                             completed_step=current_step,
                             last_result=tool_outputs[-1] if tool_outputs else None,
                             remaining_steps=remaining_steps,
                             context=context,
+                            steps_run=steps_run,
+                            max_steps=max_steps,
                         )
+                        # Hard guard: never allow plan inflation
+                        if len(remaining_steps) > old_count:
+                            remaining_steps = remaining_steps[:old_count]
                     state.plan = completed_steps + remaining_steps
                     self._append_action_plan(session_id, state.plan)
 
@@ -541,17 +537,6 @@ def _should_synthesize_response(task_queue: TaskQueue) -> bool:
             return True
         return bool(Orchestrator._collect_tool_outputs(task_queue))
 
-    @staticmethod
-    def _build_revised_query(user_query: str, task_queue: TaskQueue) -> str:
-        failure_note = (
-            f"Last tool failure: {task_queue.last_error}\n" if task_queue.last_error else ""
-        )
-        return (
-            f"{user_query}\n\nPrevious tool results:\n{task_queue.task_result or ''}\n"
-            f"{failure_note}"
-            "Please revise the action plan to resolve remaining tasks."
-        )
-
     @staticmethod
     def _resolve_mode(user_query: str, mode: str | None) -> str:
         if mode in {"plan", "act"}:
@@ -569,17 +554,6 @@ def _resolve_mode(user_query: str, mode: str | None) -> str:
             return "plan"
         return "act"
 
-    @staticmethod
-    def _should_replan(task_queue: TaskQueue, iteration: int, max_iters: int, *, mode: str) -> bool:
-        if iteration >= max_iters - 1:
-            return False
-        if mode == "plan":
-            return False
-        if task_queue.last_error:
-            lowered = task_queue.last_error.lower()
-            if "permission denied" in lowered or "tool not allowed" in lowered:
-                return False
-        return True
 
 
 __all__ = ["Orchestrator"]

packages/meeseeks_core/src/meeseeks_core/planning.py

@@ -526,25 +526,36 @@ def update(
         last_result: str | None,
         remaining_steps: list[PlanStep],
         context: ContextSnapshot | None = None,
+        steps_run: int = 0,
+        max_steps: int = 0,
     ) -> list[PlanStep]:
         """Return updated remaining steps."""
         parser = PydanticOutputParser(pydantic_object=PlanUpdate)  # type: ignore[type-var]
         system_prompt = get_system_prompt("plan-updater")
         remaining_lines = [f"- {step.title}: {step.description}" for step in remaining_steps]
         remaining_text = "\n".join(remaining_lines) or "(none)"
+        budget_note = ""
+        if max_steps > 0:
+            budget_note = (
+                f"Steps completed so far: {steps_run} of {max_steps} maximum.\n"
+                "If most steps are used, prioritize completing the goal over thoroughness.\n\n"
+            )
         prompt = ChatPromptTemplate(
             messages=[
                 SystemMessage(content=system_prompt),
                 HumanMessagePromptTemplate.from_template(
                     "User request:\n{user_query}\n\n"
                     "Completed step:\n- {title}\n- {description}\n\n"
                     "Latest result:\n{result}\n\n"
+                    "{budget_note}"
                     "Remaining steps:\n{remaining}\n\n"
                     "{format_instructions}"
                 ),
             ],
             partial_variables={"format_instructions": parser.get_format_instructions()},
-            input_variables=["user_query", "title", "description", "result", "remaining"],
+            input_variables=[
+                "user_query", "title", "description", "result", "budget_note", "remaining",
+            ],
         )
         model = build_chat_model(
             model_name=model_name,
@@ -557,6 +568,7 @@ def update(
                 "title": completed_step.title,
                 "description": completed_step.description,
                 "result": last_result or "",
+                "budget_note": budget_note,
                 "remaining": remaining_text,
             }
         )

packages/meeseeks_core/src/meeseeks_core/prompts/action-planner.txt

@@ -3,9 +3,12 @@ You are Meeseeks, a task-completing agent running on a configured model. Create
 - `description` (one paragraph describing the step)
 
 Guidelines:
+- Prefer the FEWEST steps possible. A simple task MUST have 1-2 steps. Never generate more than 5 steps total.
+- If a task can be done in one tool call, create exactly one step.
+- Do NOT create separate steps for "verify" or "validate" unless explicitly requested.
 - Keep steps crisp and relevant.
-- Include steps even if no tool is needed (e.g., “Answer directly”).
+- Include steps even if no tool is needed (e.g., "Answer directly").
 - Do not output tool calls or tool arguments; tool selection happens separately.
-- If the user mentions local files, current directory, or \"pwd\", include a step to inspect local files.
+- If the user mentions local files, current directory, or "pwd", include a step to inspect local files.
 - If the request needs external data, include a step to retrieve it.
 - Examples in the prompt are illustrative only; the actual user request begins at the final user query message.

packages/meeseeks_core/src/meeseeks_core/prompts/plan-updater.txt

@@ -1,9 +1,11 @@
-You are Meeseeks. Decide whether to update the remaining plan steps based on the latest result.
+You are Meeseeks. Review the remaining plan steps after the latest result.
 
 Return a PlanUpdate JSON object with:
 - steps: the updated remaining steps (title + description)
 
 Rules:
-- Only include remaining steps (do not repeat completed steps).
-- If no changes are needed, return the same steps unchanged.
-- Keep steps concise and in a logical order.
+- NEVER add new steps. You may only KEEP or REMOVE existing remaining steps.
+- If the latest result already achieves the user's goal, return an EMPTY steps list.
+- If a remaining step is redundant given the latest result, remove it.
+- When in doubt, remove rather than keep.
+- Do not repeat completed steps.

packages/meeseeks_core/src/meeseeks_core/prompts/step-executor.txt

@@ -10,4 +10,5 @@ Rules:
 - Use only tool IDs listed under "Allowed tools".
 - If a tool has a schema, args must match it.
 - Prefer calling a tool when the step requires external information, file/system access, or verification.
-- Respond directly only if you can answer from the given context or you need a single clarifying question from the user.
+- If the plan step's purpose is already satisfied by prior context or the user's query can be answered directly, choose "respond".
+- Prefer "respond" over "tool" when uncertain.

packages/meeseeks_core/src/meeseeks_core/reflection.py

@@ -57,8 +57,14 @@ def reflect(self, action_step: ActionStep, result_text: str) -> StepReflection |
                 SystemMessage(
                     content=(
                         "Reflect on whether the tool result satisfies the step objective. "
-                        "Return status 'ok' if complete, 'retry' if the step should be "
-                        "re-executed, or 'revise' if the tool input needs adjustment."
+                        "Return status 'ok' unless there is a CLEAR failure: "
+                        "the tool returned an explicit error message, "
+                        "the tool produced completely empty output when output was expected, "
+                        "or the result directly contradicts the objective. "
+                        "In all other cases, return 'ok'. "
+                        "Partial or imperfect results are acceptable. "
+                        "Do NOT return 'retry' or 'revise' for cosmetic issues "
+                        "or minor imperfections."
                     )
                 ),
                 HumanMessagePromptTemplate.from_template(

packages/meeseeks_core/src/meeseeks_core/tool_registry.py

@@ -181,6 +181,7 @@ def _default_registry() -> ToolRegistry:
                 "AiderEditBlockTool",
             ),
             prompt_path="tools/aider-edit-blocks",
+            metadata={"reflect": True},
         )
     )
     registry.register(
@@ -219,6 +220,7 @@ def _default_registry() -> ToolRegistry:
                 "AiderShellTool",
             ),
             prompt_path="tools/aider-shell",
+            metadata={"reflect": True},
         )
     )
     return registry
@@ -262,6 +264,7 @@ def _built_in_manifest_entries() -> list[dict[str, object]]:
             "kind": "local",
             "enabled": True,
             "prompt": "tools/aider-edit-blocks",
+            "reflect": True,
         },
         {
             "tool_id": "aider_read_file_tool",
@@ -294,6 +297,7 @@ def _built_in_manifest_entries() -> list[dict[str, object]]:
             "kind": "local",
             "enabled": True,
             "prompt": "tools/aider-shell",
+            "reflect": True,
         },
     ]
     if not ha_status.enabled and ha_status.reason:

tests/test_action_runner.py

@@ -387,6 +387,7 @@ class DummyReflection:
             name="Dummy",
             description="Dummy tool",
             factory=lambda: DummyTool(),
+            metadata={"reflect": True},
         )
     )
     runner = ActionPlanRunner(