✨ feat(core): unified tool-use loop with agent hypervisor (#78)

## Summary
- Replace the multi-class orchestration pipeline (planner → executor →
reflector → synthesizer) with a single async `ToolUseLoop` driven
entirely by native `bind_tools` / `tool_use`
- Introduce `AgentRegistry` hypervisor control plane — admission control
via semaphore, lifecycle tracking, structured cancellation, and
guaranteed cleanup
- Add `AgentContext` (immutable, frozen) for depth-aware context
propagation across the agent tree; root agent gets user-steering
primitives (`message_queue`, `interrupt_step`), sub-agents do not
- Add `SpawnAgentTool` — LLM-callable tool for creating child
`ToolUseLoop` instances with scoped tool access (allowlist/denylist
filtered before `bind_tools`, so denied tools never appear in the
schema)
- Add `AgentConfig` to `AppConfig` — `max_depth`, `max_concurrent`,
`allowed_models`, `default_sub_model`, `default_denied_tools`,
`sub_agent_max_steps`
- Add real-time CLI agent tree display via `AgentDisplayManager` + Rich
Live, driven by `on_agent_start`/`on_agent_stop` lifecycle hooks
- Autoload `CLAUDE.md`/`AGENTS.md` from CWD as project instructions
injected into system prompts for all agents (opt-out via `<!--
meeseeks:noload -->`)
- Remove `ActionRunner`, `Reflection`, multi-step planner prompts
(`plan-updater.txt`, `step-executor.txt`, `tool-selector.txt`,
`response-synthesizer.txt`)
- Migrate all `AGENTS.md` to `CLAUDE.md` across packages

## Breaking changes
- `Orchestrator` API simplified — no longer exposes plan/execute/reflect
cycle; runs `ToolUseLoop` directly
- `ActionRunner` and `Reflection` modules deleted
- `planning.py` reduced to `Planner.generate()` +
`PromptBuilder.build()`; old multi-prompt pipeline removed
- Test suites replaced: `test_orchestration.py`,
`test_action_runner.py`, `test_reflection.py`, `test_planning_intent.py`
removed; `test_tool_use_loop.py`, `test_agent_context.py`,
`test_spawn_agent.py`, `test_cli_agent_display.py`,
`test_project_instructions.py` added

## Tests
- `pytest tests/ -v` — 287 passed
- `ruff check` — all passed
- `mypy` — all passed

## Notes
- Net delta: **-706 lines** (3,571 added / 4,277 removed)
- Sub-agents bypass `Orchestrator` and plan/mode logic entirely — they
always execute
- Depth ceiling (default 5) enforced at `AgentContext.child()`;
`spawn_agent` removed from schema at max depth
- Concurrency ceiling (default 20) enforced via `AgentRegistry`
semaphore

Author: bearlike

.devin/wiki.json

@@ -20,8 +20,13 @@
       "parent": "Core Runtime & Orchestration (meeseeks_core)"
     },
     {
-      "title": "Orchestration Engine",
-      "purpose": "orchestrate_session, Orchestrator, ActionPlanRunner, and plan-act-observe-replan flow.",
+      "title": "Unified Tool-Use Loop",
+      "purpose": "ToolUseLoop as the single async execution engine: message construction, LLM invocation, tool dispatch, depth-aware prompts, and project instructions (CLAUDE.md/AGENTS.md) autoloading.",
+      "parent": "Core Runtime & Orchestration (meeseeks_core)"
+    },
+    {
+      "title": "Agent Hypervisor & Sub-Agents",
+      "purpose": "AgentHypervisor (hypervisor.py) control plane, AgentContext propagation, SpawnAgentTool, tool scoping (filter-before-binding), admission control, lifecycle tracking, and structured cleanup.",
       "parent": "Core Runtime & Orchestration (meeseeks_core)"
     },
     {
@@ -35,8 +40,8 @@
       "parent": "Core Runtime & Orchestration (meeseeks_core)"
     },
     {
-      "title": "Permissions, Hooks, Reflection",
-      "purpose": "Approval callbacks, hook pipeline, and step reflection behavior.",
+      "title": "Permissions & Hooks",
+      "purpose": "PermissionPolicy, approval callbacks, HookManager pipeline, and agent lifecycle hooks (on_agent_start, on_agent_stop).",
       "parent": "Core Runtime & Orchestration (meeseeks_core)"
     },
     {
@@ -76,7 +81,7 @@
     },
     {
       "title": "CLI Project (meeseeks_cli)",
-      "purpose": "CLI flow, dialogs, in-process runtime usage, and command handling.",
+      "purpose": "CLI flow, dialogs, agent tree display (AgentDisplayManager + Rich Live), in-process runtime usage, and command handling.",
       "parent": "Overview & Repo Map"
     },
     {
@@ -91,7 +96,7 @@
     },
     {
       "title": "Configuration & Runtime Settings",
-      "purpose": "configs/app.json, configs/mcp.json, env layering, and runtime defaults.",
+      "purpose": "configs/app.json, configs/mcp.json, AgentConfig, env layering, and runtime defaults.",
       "parent": "Overview & Repo Map"
     },
     {
@@ -101,7 +106,7 @@
     },
     {
       "title": "Testing & Quality",
-      "purpose": "Integration-first test patterns, boundaries, and coverage targets from tests/AGENTS.md.",
+      "purpose": "Integration-first test patterns, boundaries, and coverage targets from tests/CLAUDE.md.",
       "parent": "Overview & Repo Map"
     },
     {
@@ -122,15 +127,19 @@
     },
     {
       "title": "Core Runtime & Orchestration (meeseeks_core)",
-      "notes": "Mermaid: runtime facade flow (SessionRuntime -> Orchestrator -> ActionPlanRunner) and how clients call it."
+      "notes": "Mermaid: runtime facade flow (SessionRuntime -> Orchestrator -> ToolUseLoop) and how clients call it."
     },
     {
       "title": "Session Runtime & Store",
       "notes": "Mermaid: sequence for async run + JSONL event log + API polling (explicitly API-only); include RunRegistry and SessionStore."
     },
     {
-      "title": "Orchestration Engine",
-      "notes": "Mermaid: state machine for plan -> act -> observe -> replan -> respond; label orchestrate_session/Orchestrator/ActionPlanRunner."
+      "title": "Unified Tool-Use Loop",
+      "notes": "Mermaid: ToolUseLoop step cycle (build messages -> LLM invoke -> tool dispatch -> gather results -> repeat or done). Show spawn_agent as a recursive call back into ToolUseLoop."
+    },
+    {
+      "title": "Agent Hypervisor & Sub-Agents",
+      "notes": "Mermaid: agent tree diagram showing AgentContext.root() -> child() propagation, AgentHypervisor (admission, registration, cleanup), and SpawnAgentTool filter-before-binding flow."
     },
     {
       "title": "LLM Abstraction",
@@ -141,8 +150,8 @@
       "notes": "Mermaid: data flow from EventRecord -> summary -> ContextBuilder snapshot."
     },
     {
-      "title": "Permissions, Hooks, Reflection",
-      "notes": "Mermaid: sequence diagram of tool call -> hooks -> permission -> tool result -> reflection."
+      "title": "Permissions & Hooks",
+      "notes": "Mermaid: sequence diagram of tool call -> hooks -> permission -> tool result; include on_agent_start/on_agent_stop lifecycle hooks."
     },
     {
       "title": "Core Data Models & Events",
@@ -174,7 +183,7 @@
     },
     {
       "title": "CLI Project (meeseeks_cli)",
-      "notes": "Mermaid: sync flow CLI -> SessionRuntime -> Orchestrator -> response (no polling)."
+      "notes": "Mermaid: sync flow CLI -> SessionRuntime -> Orchestrator -> ToolUseLoop -> response; include AgentDisplayManager + Rich Live rendering of agent tree via lifecycle hooks."
     },
     {
       "title": "Chat UI Project (meeseeks_chat)",
@@ -186,7 +195,7 @@
     },
     {
       "title": "Configuration & Runtime Settings",
-      "notes": "Mermaid: config resolution flow (configs/app.json, configs/mcp.json, env overrides)."
+      "notes": "Mermaid: config resolution flow (configs/app.json, configs/mcp.json, env overrides); include AgentConfig section (max_depth, max_concurrent, allowed_models, default_denied_tools)."
     },
     {
       "title": "CI/CD & Docs Pipeline",

.gitignore

@@ -4,6 +4,10 @@ repo-to-prompt.codemod.js
 # MCP config (contains auth tokens)
 .mcp.json
 
+# macOS resource forks / metadata
+._*
+.DS_Store
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

AGENTS.md

@@ -0,0 +1,3 @@
+This is a shim file for Claude agents.
+
+Read and follow [@CLAUDE.md](./CLAUDE.md) in this directory as the source of truth for project instructions.

CLAUDE.md

@@ -1,18 +1,24 @@
 # Agents Guide - Personal Assistant (Meeseeks)
 
 ## What this codebase is
-Meeseeks is a multi-agent LLM personal assistant that decomposes user requests into atomic actions, runs them through tools, and returns a synthesized response. It ships multiple interfaces (CLI, chat UI, REST API, Home Assistant) that share the same core engine.
+Meeseeks is a multi-agent LLM personal assistant with an async sub-agent hypervisor. The core engine uses a single async `ToolUseLoop` that the LLM drives via native `bind_tools` / `tool_use`. Sub-agents are spawned via a `spawn_agent` tool, tracked by an `AgentHypervisor`, and cleaned up via structured concurrency. It ships multiple interfaces (CLI, chat UI, REST API, Home Assistant) that share the same core engine.
 
 ## Core entry points
-- `packages/meeseeks_core/src/meeseeks_core/task_master.py`: action planning + task execution loop
+- `packages/meeseeks_core/src/meeseeks_core/tool_use_loop.py`: async tool-use conversation loop (`ToolUseLoop`) — the core execution engine
+- `packages/meeseeks_core/src/meeseeks_core/agent_context.py`: `AgentContext` (immutable per-agent state)
+- `packages/meeseeks_core/src/meeseeks_core/hypervisor.py`: `AgentHypervisor` (control plane), `AgentHandle` (per-agent runtime state)
+- `packages/meeseeks_core/src/meeseeks_core/spawn_agent.py`: `SpawnAgentTool` + `SPAWN_AGENT_SCHEMA` — sub-agent creation with tool scoping
+- `packages/meeseeks_core/src/meeseeks_core/orchestrator.py`: session lifecycle, sync→async bridge via `asyncio.run()`
+- `packages/meeseeks_core/src/meeseeks_core/task_master.py`: `generate_action_plan` + `orchestrate_session` entry points
 - `packages/meeseeks_core/src/meeseeks_core/classes.py`: `ActionStep` (tool_id/operation/tool_input), `TaskQueue`, `AbstractTool` contracts
-- `packages/meeseeks_core/src/meeseeks_core/planning.py`: `Planner`, `ToolSelector`, `StepExecutor`, `PlanUpdater`
-- `packages/meeseeks_core/src/meeseeks_core/session_runtime.py`: session lifecycle, listing, archiving, and async runs
+- `packages/meeseeks_core/src/meeseeks_core/planning.py`: `Planner`, `PromptBuilder`
+- `packages/meeseeks_core/src/meeseeks_core/session_runtime.py`: session lifecycle, listing, user steering (`enqueue_message`, `interrupt_step`)
 - `packages/meeseeks_core/src/meeseeks_core/session_store.py`: transcript storage, tags, and archive state
+- `packages/meeseeks_core/src/meeseeks_core/config.py`: `AppConfig` including `AgentConfig` (max_depth, max_concurrent, allowed_models, etc.)
 - `packages/meeseeks_tools/src/meeseeks_tools/`: tool implementations and integration glue
 - `apps/meeseeks_chat/src/meeseeks_chat/chat_master.py`: Streamlit UI
 - `apps/meeseeks_api/src/meeseeks_api/backend.py`: Flask API
-- `apps/meeseeks_cli/src/meeseeks_cli/cli_master.py`: terminal CLI
+- `apps/meeseeks_cli/src/meeseeks_cli/cli_master.py`: terminal CLI with Rich Live agent display
 - `meeseeks_ha_conversation/`: Home Assistant integration
 
 ## How to get context fast
@@ -50,7 +56,7 @@ Observability platform for LLM traces. Meeseeks instruments all LLM calls with L
 #### Investigation workflow (most common path)
 1. **Start broad**: `get_error_count(age=1440)` to check if there are recent errors (last 24h).
 2. **List recent sessions**: `fetch_sessions(age=1440)` to find Meeseeks session IDs.
-3. **List traces for a session**: `fetch_traces(age=1440, session_id="...", name="meeseeks-task-master")` to find planning traces, or `name="meeseeks-response"` for synthesis traces.
+3. **List traces for a session**: `fetch_traces(age=1440, session_id="...", name="meeseeks-tool-use")` to find tool-use loop traces, or `name="meeseeks-task-master"` for planning traces.
 4. **Inspect a trace**: `fetch_trace(trace_id="...", include_observations=True)` to see all LLM calls within a trace, including prompts, completions, token counts, and latency.
 5. **Drill into a specific LLM call**: `fetch_observation(observation_id="...")` to inspect a single generation's input/output.
 6. **Check exceptions**: `get_exception_details(trace_id="...")` when a trace has errors.
@@ -59,7 +65,7 @@ Observability platform for LLM traces. Meeseeks instruments all LLM calls with L
 - **`get_error_count(age)`**: Quick health check — returns count of traces with exceptions in the last N minutes (max 10080 = 7 days).
 - **`fetch_sessions(age)`**: List Langfuse sessions. Meeseeks sessions map to Langfuse sessions via the session ID in `orchestrator.py`.
 - **`get_session_details(session_id, include_observations=True)`**: Deep-dive into a session with all its traces and observations.
-- **`fetch_traces(age, ...)`**: Find traces by name, user_id, session_id, tags, or metadata. Key trace names in Meeseeks: `meeseeks-task-master` (planning), `meeseeks-response` (synthesis), `meeseeks-reflection` (step reflection), `meeseeks-context` (context selection).
+- **`fetch_traces(age, ...)`**: Find traces by name, user_id, session_id, tags, or metadata. Key trace names in Meeseeks: `meeseeks-tool-use` (main tool-use loop), `meeseeks-task-master` (planning), `meeseeks-context` (context selection).
 - **`fetch_trace(trace_id, include_observations=True)`**: Full trace with all child observations. Use `output_mode="full_json_file"` for large traces.
 - **`fetch_observations(age, type="GENERATION")`**: Find all LLM generations in a time window. Filter by `name`, `user_id`, `trace_id`, or `parent_observation_id`.
 - **`fetch_observation(observation_id)`**: Single observation detail — includes full input/output, model name, token usage, latency.
@@ -93,7 +99,7 @@ Official library/framework documentation and code examples.
 - **Parallel queries**: When investigating, fire multiple MCP calls in parallel (e.g., DeepWiki for architecture + Langfuse for traces + SearXNG for docs).
 - **Cross-reference**: Use DeepWiki/Devin wiki for "how should it work" and Langfuse for "how did it actually work" during debugging.
 - **Session IDs bridge Meeseeks and Langfuse**: The `session_id` from `SessionStore` is the same ID used in Langfuse traces. Use it to jump between local transcript analysis and Langfuse observability.
-- **Trace names in Meeseeks**: Planning traces use `user_id="meeseeks-task-master"`, response synthesis uses `user_id="meeseeks-response"`, reflection uses `user_id="meeseeks-reflection"`, context selection uses `user_id="meeseeks-context"`.
+- **Trace names in Meeseeks**: Tool-use loop traces use `user_id="meeseeks-tool-use"`, planning uses `user_id="meeseeks-task-master"`, context selection uses `user_id="meeseeks-context"`. Sub-agent traces share the same session_id but have distinct agent_id tags in event payloads.
 - **Age parameter**: Langfuse tools use `age` in minutes (not timestamps). Common values: 60 (1h), 1440 (24h), 10080 (7 days max).
 
 ## Engineering principles (project-specific)
@@ -108,9 +114,13 @@ Official library/framework documentation and code examples.
 - Treat language models as black-box APIs with non-deterministic output; avoid anthropomorphic language and describe changes objectively (e.g., “updated prompts/instructions”).
 - Keep type hints precise; avoid loosening to `Any` unless no accurate alternative exists.
 
-## Orchestration insights (transferable)
-- Separate tool execution from user-facing response: synthesize after tool results, don't dump raw tool output.
-- Keep the loop explicit: plan -> act -> observe -> decide; re-plan only when needed.
+## Orchestration architecture
+- **Single async loop**: `ToolUseLoop.run()` is the only execution engine. The LLM decides which tools to call via native `bind_tools`. No separate planner→executor→synthesizer pipeline.
+- **Sub-agent spawning**: The LLM can call `spawn_agent(task, model, allowed_tools, denied_tools)` to create child `ToolUseLoop` instances. Tool scoping follows Claude Code's "filter before binding" pattern.
+- **Agent hypervisor**: `AgentHypervisor` tracks all agents, enforces admission control (max_concurrent via Semaphore), and guarantees cleanup via structured concurrency (`asyncio.gather` + `finally` blocks).
+- **Depth control**: Max depth 5 (configurable). At max depth, `spawn_agent` is removed from the tool schema entirely. Depth-aware prompts guide spawn behavior.
+- **User steering**: Root agent has a `message_queue` (drained between steps as HumanMessage) and `interrupt_step` event. Sub-agents do not receive user messages.
+- **Planning is root-only**: Sub-agents always execute (act mode). They bypass `Orchestrator` and its plan/mode logic entirely.
 - Make tool inputs schema-aware; prefer structured `tool_input` for MCP tools.
 - Surface tool activity clearly (permissions, tool IDs, arguments) to reduce user confusion.
 

README.md

@@ -19,7 +19,7 @@ https://github.com/user-attachments/assets/78754e8f-828a-4c54-9e97-29cbeacbc3bc
 
 # Intro
 
-Meeseeks is an AI task agent assistant built on a plan → tool selection → step execution loop. It breaks a request into steps, chooses tools per step, runs them, and synthesizes a final reply. It keeps a session transcript, compacts long histories, and stores summaries for continuity across longer conversations.
+Meeseeks is an AI task agent assistant built on a single async tool-use loop driven by native `bind_tools`. The LLM decides which tools to call, can spawn sub-agents for parallel work, and synthesizes a final reply. It keeps a session transcript, compacts long histories, and stores summaries for continuity across longer conversations.
 
 <details>
 <summary><i>Legends (Expand to View) </i></summary>
@@ -61,10 +61,10 @@ We are upgrading the API backend to better support a task-orchestration frontend
 </table>
 
 ## Core workflow
-- (✅) **Plan → select tools → execute:** Builds a short plan, chooses the right tools per step, and executes them.
-- (✅) **Step-level reflection:** Validates tool outcomes and adjusts tool inputs when required.
-- (✅) **Plan updates:** Emits updated action plans after each step so UIs can refresh the to‑do list.
-- (✅) **Synthesized replies:** Produces a final answer after tool results are collected and summarized.
+- (✅) **Unified tool-use loop:** A single async `ToolUseLoop` where the LLM drives tool selection and execution via native `bind_tools`.
+- (✅) **Sub-agent spawning:** The LLM can delegate subtasks to parallel sub-agents via `spawn_agent`, managed by the `AgentHypervisor` control plane.
+- (✅) **Tool scoping & permissions:** Sub-agents receive scoped tool access (allowlist/denylist filtered before binding). Permission policies gate all tool execution.
+- (✅) **Synthesized replies:** Produces a final answer after tool results are collected.
 
 ## Memory and context management
 - (✅) **Session transcripts:** Writes tool activity and responses to disk for continuity.
@@ -136,13 +136,11 @@ flowchart LR
   subgraph Core["Core Orchestration\n(packages/meeseeks_core)"]
     TaskMaster["orchestrate_session\n(task_master.py)"]
     Orchestrator["Orchestrator\n(orchestrator.py)"]
+    ToolUseLoop["ToolUseLoop\n(tool_use_loop.py)"]
+    Hypervisor["AgentHypervisor\n(hypervisor.py)"]
+    SpawnAgent["SpawnAgentTool\n(spawn_agent.py)"]
     Planner["Planner\n(planning.py)"]
-    ToolSelector["ToolSelector\n(planning.py)"]
-    StepExecutor["StepExecutor\n(planning.py)"]
-    PlanUpdater["PlanUpdater\n(planning.py)"]
-    ActionPlanRunner["ActionPlanRunner\n(action_runner.py)"]
     ContextBuilder["ContextBuilder\n(context.py)"]
-    ActionStep["ActionStep\n(classes.py)"]
     TaskQueue["TaskQueue\n(classes.py)"]
   end
 
@@ -182,24 +180,24 @@ flowchart LR
   SessionRuntime --> RunRegistry
 
   TaskMaster --> Orchestrator
+  Orchestrator --> ToolUseLoop
   Orchestrator --> Planner
-  Orchestrator --> ToolSelector
-  Orchestrator --> StepExecutor
-  Orchestrator --> PlanUpdater
-  Orchestrator --> ActionPlanRunner
+  Orchestrator --> Hypervisor
   Orchestrator --> ContextBuilder
-  Orchestrator --> ToolRegistry
   Orchestrator --> SessionStore
 
-  ActionPlanRunner --> TaskQueue
-  ActionPlanRunner --> ActionStep
+  ToolUseLoop --> SpawnAgent
+  ToolUseLoop --> ToolRegistry
+  ToolUseLoop --> TaskQueue
+  SpawnAgent -->|"child loop"| ToolUseLoop
+  SpawnAgent --> Hypervisor
 
   ToolRegistry --> AbstractTool
   AbstractTool --> LocalTools
   AbstractTool --> MCPTools
   AbstractTool --> HATools
 
-  Orchestrator --> BuildChatModel
+  ToolUseLoop --> BuildChatModel
   BuildChatModel --> ChatModel
 
   SessionStore --> EventLog