luckyd-code 1.2.2__py3-none-any.whl

luckyd_code/memory/manager.py

@@ -0,0 +1,339 @@
+"""Persistent memory system — file-based, survives across sessions.
+
+Stores memories in the project data directory under projects/<project-name>/memory/.
+Auto-saves conversation summaries, enables search and injection.
+
+Search strategy:
+  - When ``sentence-transformers`` is installed (the ``rag`` extra), memories
+    are searched semantically using cosine similarity of sentence embeddings.
+  - Otherwise, a simple keyword-frequency fallback is used automatically.
+"""
+
+import os
+import re
+import threading
+from pathlib import Path
+from typing import Any, Optional
+
+from .._data_dir import data_path
+
+# ---------------------------------------------------------------------------
+# SentenceTransformer singleton — loading the model takes 1-3 seconds and
+# pulls ~90 MB into memory.  Caching it here means the cost is paid once per
+# process instead of on every search call.
+# ---------------------------------------------------------------------------
+_ST_MODEL = None
+_ST_MODEL_LOCK = threading.Lock()
+
+
+def _get_st_model():
+    """Return the cached SentenceTransformer, loading it on first call."""
+    global _ST_MODEL
+    if _ST_MODEL is None:
+        with _ST_MODEL_LOCK:
+            if _ST_MODEL is None:  # double-checked locking
+                from sentence_transformers import SentenceTransformer
+                _ST_MODEL = SentenceTransformer("all-MiniLM-L6-v2")
+    return _ST_MODEL
+
+
+class MemoryManager:
+    """Project-scoped persistent memory with CRUD, search, and auto-summary."""
+
+    def __init__(self, project_dir: Optional[str] = None):
+        self.project_dir = project_dir or os.getcwd()
+        self.project_name = Path(self.project_dir).name
+        self.mem_dir = data_path("projects", self.project_name, "memory")
+        self.mem_dir.mkdir(parents=True, exist_ok=True)
+
+    # ------------------------------------------------------------------ #
+    #  CRUD
+    # ------------------------------------------------------------------ #
+
+    def save_memory(self, name: str, content: str, memory_type: str = "general") -> str:
+        """Save a memory file and update MEMORY.md index.
+
+        Returns the file path.
+        """
+        safe_name = self._sanitize(name)
+        filename = f"{memory_type}_{safe_name}.md"
+        filepath = self.mem_dir / filename
+        filepath.write_text(content, encoding="utf-8")
+
+        self._update_index(name, filename, content)
+        return str(filepath)
+
+    def load_memory(self, name: str, memory_type: str = "general") -> Optional[str]:
+        """Load a specific memory by name and type."""
+        safe_name = self._sanitize(name)
+        filepath = self.mem_dir / f"{memory_type}_{safe_name}.md"
+        if filepath.exists():
+            return filepath.read_text(encoding="utf-8")
+        return None
+
+    def delete_memory(self, name: str, memory_type: str = "general") -> bool:
+        """Delete a memory file. Returns True if deleted."""
+        safe_name = self._sanitize(name)
+        filepath = self.mem_dir / f"{memory_type}_{safe_name}.md"
+        if filepath.exists():
+            filepath.unlink()
+            self._rebuild_index()
+            return True
+        return False
+
+    def list_memories(self, memory_type: Optional[str] = None) -> list[dict]:
+        """List all memories, optionally filtered by type. Returns list of {name, type, path}."""
+        results = []
+        pattern = f"{memory_type}_*.md" if memory_type else "*.md"
+        for f in sorted(self.mem_dir.glob(pattern)):
+            if f.name == "MEMORY.md":
+                continue
+            # Parse type_name from filename
+            parts = f.stem.split("_", 1)
+            typ = parts[0] if len(parts) > 1 else "general"
+            name = parts[1] if len(parts) > 1 else parts[0]
+            results.append({"name": name, "type": typ, "path": str(f)})
+        return results
+
+    # ------------------------------------------------------------------ #
+    #  Search
+    # ------------------------------------------------------------------ #
+
+    def search_memories(self, query: str, k: int = 5) -> list[dict]:
+        """Search memories by relevance.
+
+        Uses semantic cosine-similarity search when ``sentence-transformers``
+        is available; falls back to keyword-frequency scoring otherwise.
+
+        Returns up to ``k`` results sorted by relevance, each with
+        ``file``, ``name``, ``score``, and ``snippet`` keys.
+        """
+        try:
+            return self._semantic_search(query, k)
+        except Exception:
+            return self._keyword_search(query, k)
+
+    def _semantic_search(self, query: str, k: int) -> list[dict]:
+        """Cosine-similarity search using sentence-transformers."""
+        from sentence_transformers import util
+
+        files = [f for f in self.mem_dir.glob("*.md") if f.name != "MEMORY.md"]
+        if not files:
+            return []
+
+        model = _get_st_model()
+        contents = [f.read_text(encoding="utf-8") for f in files]
+        corpus_emb = model.encode(contents, convert_to_tensor=True)
+        query_emb = model.encode(query, convert_to_tensor=True)
+        scores = util.cos_sim(query_emb, corpus_emb)[0].tolist()
+
+        results: list[dict[str, Any]] = []
+        for f, content, score in zip(files, contents, scores):
+            if score > 0.1:  # ignore near-zero similarity
+                results.append({
+                    "file": f.name,
+                    "name": f.stem.split("_", 1)[-1] if "_" in f.stem else f.stem,
+                    "score": float(score),
+                    "snippet": self._make_snippet(content, query.lower()),
+                })
+        results.sort(key=lambda r: float(r["score"]), reverse=True)
+        return results[:k]
+
+    def _keyword_search(self, query: str, k: int) -> list[dict]:
+        """Simple keyword-frequency search (always available)."""
+        query_lower = query.lower()
+        words = query_lower.split()
+        results: list[dict[str, Any]] = []
+
+        for f in self.mem_dir.glob("*.md"):
+            if f.name == "MEMORY.md":
+                continue
+            content = f.read_text(encoding="utf-8")
+            content_lower = content.lower()
+            score = sum(content_lower.count(w) for w in words) if words else 0
+            if score > 0:
+                results.append({
+                    "file": f.name,
+                    "name": f.stem.split("_", 1)[-1] if "_" in f.stem else f.stem,
+                    "score": score,
+                    "snippet": self._make_snippet(content, query_lower),
+                })
+
+        results.sort(key=lambda r: int(r["score"]), reverse=True)
+        return results[:k]
+
+    # ------------------------------------------------------------------ #
+    #  Conversation summaries
+    # ------------------------------------------------------------------ #
+
+    def save_conversation_summary(self, summary: str, turn_count: int = 0):
+        """Auto-save a conversation summary to a rotating slot.
+
+        Keeps the last N summaries (default 10) by using a numbered
+        filename.
+        """
+        self.save_memory("latest_summary", summary, memory_type="session")
+        # Also append to running log
+        log_path = self.mem_dir / "session_log.md"
+        from datetime import datetime
+        entry = (
+            f"## Session — {datetime.now().isoformat()}\n"
+            f"**Turns:** {turn_count}\n\n{summary}\n\n"
+        )
+        with open(log_path, "a", encoding="utf-8") as f:
+            f.write(entry)
+
+    # ------------------------------------------------------------------ #
+    #  Context injection helpers
+    # ------------------------------------------------------------------ #
+
+    def get_relevant_memories(self, context: str, k: int = 3) -> str:
+        """Search memories relevant to the given context and return formatted text."""
+        results = self.search_memories(context, k=k)
+        if not results:
+            return ""
+        parts = ["<memories>"]
+        for r in results:
+            parts.append(f"### {r['name']}\n{r['snippet']}")
+        parts.append("</memories>")
+        return "\n\n".join(parts)
+
+    def get_all_memories_formatted(self) -> str:
+        """Return all memories as a formatted XML block for prompt injection."""
+        memories = self.list_memories()
+        if not memories:
+            return ""
+
+        parts = ["<memories>"]
+        for m in memories:
+            content = self.load_memory(m["name"], m["type"]) or ""
+            # Truncate very long memories
+            if len(content) > 500:
+                content = content[:500] + f"\n... (truncated, {len(content)} total chars)"
+            parts.append(f"<memory name='{m['name']}' type='{m['type']}'>\n{content}\n</memory>")
+        parts.append("</memories>")
+        return "\n\n".join(parts)
+
+    # ------------------------------------------------------------------ #
+    #  Project memory helpers (MEMORY.md / CLAUDE.md)
+    # ------------------------------------------------------------------ #
+
+    def load_claude_md(self) -> str:
+        """Load the project memory file.
+
+        Checks MEMORY.md first, then CLAUDE.md for backward compatibility.
+        """
+        for name in ("MEMORY.md", "CLAUDE.md"):
+            path = Path(self.project_dir) / name
+            if path.exists():
+                return path.read_text(encoding="utf-8")
+        return ""
+
+    def save_claude_md(self, content: str):
+        """Save the project memory file as MEMORY.md."""
+        path = Path(self.project_dir) / "MEMORY.md"
+        path.write_text(content, encoding="utf-8")
+
+    # ------------------------------------------------------------------ #
+    #  Internal helpers
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def _sanitize(name: str) -> str:
+        """Make a name safe for use as a filename."""
+        return re.sub(r'[^\w\-]', '_', name).strip('_') or "unnamed"
+
+    @staticmethod
+    def _make_snippet(content: str, query_lower: str, context_chars: int = 120) -> str:
+        """Extract a snippet around the first match of query_lower."""
+        idx = content.lower().find(query_lower)
+        if idx == -1:
+            return content[:300]
+        start = max(0, idx - context_chars)
+        end = min(len(content), idx + context_chars)
+        snippet = content[start:end]
+        if start > 0:
+            snippet = "... " + snippet
+        if end < len(content):
+            snippet = snippet + " ..."
+        return snippet
+
+    def _update_index(self, name: str, filename: str, content: str):
+        """Add or update an entry in MEMORY.md."""
+        index_path = self.mem_dir / "MEMORY.md"
+        entry = f"- [{name}]({filename}) — {content[:80].strip()}"
+        if index_path.exists():
+            existing = index_path.read_text(encoding="utf-8")
+            # Replace existing entry if it exists
+            if f"[{name}]" in existing:
+                lines = existing.split("\n")
+                new_lines = [
+                    entry if f"[{name}]" in l else l
+                    for l in lines
+                ]
+                index_path.write_text("\n".join(new_lines) + "\n", encoding="utf-8")
+            else:
+                with open(index_path, "a", encoding="utf-8") as f:
+                    f.write(entry + "\n")
+        else:
+            index_path.write_text(f"# Memory Index\n\n{entry}\n", encoding="utf-8")
+
+    def _rebuild_index(self):
+        """Rebuild MEMORY.md from all memory files."""
+        index_path = self.mem_dir / "MEMORY.md"
+        files = sorted(self.mem_dir.glob("*.md"))
+        entries = []
+        for f in files:
+            if f.name == "MEMORY.md":
+                continue
+            name = f.stem.split("_", 1)[-1] if "_" in f.stem else f.stem
+            content = f.read_text(encoding="utf-8")
+            entries.append(f"- [{name}]({f.name}) — {content[:80].strip()}")
+        if entries:
+            index_path.write_text("# Memory Index\n\n" + "\n".join(entries) + "\n", encoding="utf-8")
+        elif index_path.exists():
+            index_path.unlink()
+
+
+# ------------------------------------------------------------------ #
+#  Module-level convenience API (backwards-compatible)
+# ------------------------------------------------------------------ #
+
+_DEFAULT_MANAGER: Optional[MemoryManager] = None
+_MANAGER_LOCK = threading.Lock()
+
+
+def _get_manager() -> MemoryManager:
+    global _DEFAULT_MANAGER
+    if _DEFAULT_MANAGER is None:
+        with _MANAGER_LOCK:
+            if _DEFAULT_MANAGER is None:  # double-checked locking
+                _DEFAULT_MANAGER = MemoryManager()
+    return _DEFAULT_MANAGER
+
+
+def get_project_memory_dir() -> str:
+    return str(_get_manager().mem_dir)
+
+
+def load_claude_md() -> str:
+    return _get_manager().load_claude_md()
+
+
+def save_claude_md(content: str):
+    _get_manager().save_claude_md(content)
+
+
+def load_memory_index() -> str:
+    return _get_manager().get_all_memories_formatted()
+
+
+def save_memory(name: str, content: str, memory_type: str = "general"):
+    _get_manager().save_memory(name, content, memory_type)
+
+
+def list_memories() -> str:
+    memories = _get_manager().list_memories()
+    if not memories:
+        return "No memories yet."
+    return "\n".join(f"- {m['name']} ({m['type']})" for m in memories)

luckyd_code/metrics/__init__.py

@@ -0,0 +1,5 @@
+"""Metrics package for DeepSeek Code audit daemon.
+
+Stores the time-series JSONL log produced by AuditDaemon._append_metrics()
+at ``luckyd_code/metrics/time_series.jsonl``.
+"""

luckyd_code/model_registry.py

@@ -0,0 +1,131 @@
+"""Model registry — defines available models with capabilities, costs, and tiers.
+
+Each model has:
+- id: DeepSeek model identifier
+- name: Human-readable name
+- tier: Lowest tier this model serves (1-4)
+- strengths: list of task categories it excels at
+- context_window: max context in tokens
+- cost_per_1k_input: approximate cost per 1K input tokens (USD)
+- cost_per_1k_output: approximate cost per 1K output tokens (USD)
+
+Tier system:
+  Tier 1 — Ultra Fast / Cheap: simple chat, quick Q&A, simple edits
+  Tier 2 — Balanced: general purpose coding and chat
+  Tier 3 — Reasoner: debugging, architecture, complex analysis
+  Tier 4 — Code/Heavy: large refactors, code generation, heavy reasoning
+
+Each physical model appears exactly once. The router maps tier → model id;
+multiple tiers can map to the same model id without duplicating ModelDef objects.
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass
+class ModelDef:
+    id: str
+    name: str
+    tier: int  # primary/lowest tier this model is used for
+    strengths: List[str] = field(default_factory=list)
+    context_window: int = 1_000_000
+    cost_per_1k_input: float = 0.0
+    cost_per_1k_output: float = 0.0
+
+
+# ─── Canonical model definitions (each model appears exactly ONCE) ───
+
+FLASH = ModelDef(
+    id="deepseek-v4-flash",
+    name="DeepSeek V4 Flash",
+    tier=1,
+    strengths=["chat", "quick_qa", "fast_coding", "simple_edits", "coding", "analysis", "general"],
+    context_window=1_000_000,
+    cost_per_1k_input=0.000140,
+    cost_per_1k_output=0.000280,
+)
+
+PRO = ModelDef(
+    id="deepseek-v4-pro",
+    name="DeepSeek V4 Pro",
+    tier=3,
+    strengths=[
+        "reasoning", "debugging", "math", "logic", "complex_analysis",
+        "architecture", "code_generation", "refactoring", "complex_code",
+    ],
+    context_window=1_000_000,
+    cost_per_1k_input=0.001740,
+    cost_per_1k_output=0.003480,
+)
+
+# All unique models, ordered by capability (cheapest first)
+ALL_MODELS_FLAT: list[ModelDef] = [FLASH, PRO]
+
+# Tier → model id mapping.  Tiers 1-2 use Flash; tiers 3-4 use Pro.
+# This is the single source of truth for routing decisions.
+TIER_MODEL_MAP: dict[int, str] = {
+    1: FLASH.id,
+    2: FLASH.id,
+    3: PRO.id,
+    4: PRO.id,
+}
+
+# Reverse map: model id → list of tiers it serves
+_MODEL_TIERS: dict[str, list[int]] = {}
+for _tier, _mid in TIER_MODEL_MAP.items():
+    _MODEL_TIERS.setdefault(_mid, []).append(_tier)
+
+
+def get_model_by_id(model_id: str) -> Optional[ModelDef]:
+    """Find a model definition by its ID."""
+    for m in ALL_MODELS_FLAT:
+        if m.id == model_id:
+            return m
+    return None
+
+
+def get_models_by_tier(tier: int) -> list[ModelDef]:
+    """Return the single model that serves a given tier (wrapped in a list for API compat)."""
+    mid = TIER_MODEL_MAP.get(tier)
+    if not mid:
+        return []
+    m = get_model_by_id(mid)
+    return [m] if m else []
+
+
+def get_unique_model_count() -> int:
+    """Count physically distinct models (not tier slots)."""
+    return len(ALL_MODELS_FLAT)
+
+
+def get_models_by_strength(strength: str, min_tier: int = 1, max_tier: int = 4) -> list[ModelDef]:
+    """Get models that have a specific strength and serve at least one tier in range."""
+    results = []
+    seen: set[str] = set()
+    for tier in range(min_tier, max_tier + 1):
+        mid = TIER_MODEL_MAP.get(tier)
+        if not mid or mid in seen:
+            continue
+        m = get_model_by_id(mid)
+        if m and strength in m.strengths:
+            results.append(m)
+            seen.add(mid)
+    return results
+
+
+def format_model_list() -> str:
+    """Return a human-readable list of all registered models and their tier assignments."""
+    lines = [f"🌐 Model Registry: {get_unique_model_count()} models\n"]
+    tier_names = {1: "Fast/Cheap", 2: "Balanced", 3: "Reasoner", 4: "Code-Specialist"}
+    for m in ALL_MODELS_FLAT:
+        tiers = _MODEL_TIERS.get(m.id, [])
+        tier_labels = ", ".join(f"Tier {t} ({tier_names[t]})" for t in sorted(tiers))
+        cost_in = f"${m.cost_per_1k_input * 1000:.4f}"
+        cost_out = f"${m.cost_per_1k_output * 1000:.4f}"
+        lines.append(f"  • {m.name} ({m.id})")
+        lines.append(f"    Serves: {tier_labels}")
+        lines.append(f"    Cost:   {cost_in}/1K input · {cost_out}/1K output")
+        lines.append(f"    Context: {m.context_window:,} tokens")
+        lines.append("")
+    return "\n".join(lines)

luckyd_code/orchestrator.py

@@ -0,0 +1,204 @@
+"""Multi-agent orchestration — coordinate specialized agents for complex tasks."""
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Any, Dict, List, Optional
+
+from rich.console import Console
+
+from .context import ConversationContext
+from .tools import get_default_registry
+from ._agent_loop import run_agent_loop
+
+_console = Console()
+
+__all__ = ["AgentHandoff", "Coordinator"]
+
+_MAX_PARALLEL_WORKERS = 4  # cap on simultaneous API calls in parallel_orchestrate
+
+
+def _truncate_to_tokens(text: str, max_tokens: int = 1500) -> str:
+    """Truncate *text* to at most *max_tokens* tokens.
+
+    Uses tiktoken (cl100k_base) when available for a precise token count;
+    falls back to a 4-chars-per-token heuristic so the function always works
+    even in environments without the optional tiktoken dependency.
+
+    1500 tokens (≈6 000 chars) is the default — enough to convey full research
+    findings without blowing the coder’s context budget.
+    """
+    try:
+        import tiktoken
+        enc = tiktoken.get_encoding("cl100k_base")
+        tokens = enc.encode(text)
+        if len(tokens) <= max_tokens:
+            return text
+        truncated = enc.decode(tokens[:max_tokens])
+        return truncated + "\n[...truncated to fit context window]"
+    except Exception:
+        char_limit = max_tokens * 4
+        if len(text) <= char_limit:
+            return text
+        return text[:char_limit] + "\n[...truncated to fit context window]"
+
+# Role definitions with specialized system prompts
+ROLE_PROMPTS = {
+    "researcher": """You are a Research Agent. Your job is to investigate and gather information.
+Use WebSearch, WebFetch, Grep, Glob, and Read tools to find information.
+Return comprehensive findings with sources and details.
+Be thorough - leave no stone unturned.""",
+
+    "coder": """You are a Coding Agent. Your job is to implement changes.
+Use Read, Write, Edit, Glob, Grep, and Bash tools.
+Write clean, correct, well-tested code.
+Follow existing patterns in the codebase.
+Verify your changes work before reporting done.""",
+
+    "reviewer": """You are a Review Agent. Your job is to review code and provide feedback.
+Use Read, Glob, and Grep tools to examine code.
+Check for: bugs, edge cases, security issues, performance problems,
+code style consistency, error handling, and documentation.
+Provide specific, actionable feedback with line references.""",
+
+    "tester": """You are a Testing Agent. Your job is to write and run tests.
+Use Read, Write, Edit, Bash, and Glob tools.
+Write tests that cover edge cases and main paths.
+Run existing tests first, then add new ones.
+Report test results clearly (pass/fail).""",
+}
+
+
+class AgentHandoff:
+    """Hand off a subtask to a specialized agent and get results back."""
+
+    def __init__(self, config):
+        self.config = config
+
+    def handoff(self, role: str, task: str,
+                tools: Optional[List[Dict[str, Any]]] = None) -> str:
+        """Hand off a task to a specialized agent."""
+        role = role.lower()
+        if role not in ROLE_PROMPTS:
+            return f"Error: unknown role '{role}'. Available: {', '.join(ROLE_PROMPTS.keys())}"
+
+        # Build a context that combines the base system prompt with the
+        # role-specific prompt. Using a single system message avoids
+        # sending two consecutive system turns, which the DeepSeek API
+        # does not support.
+        combined_system = f"{self.config.system_prompt}\n\n{ROLE_PROMPTS[role]}"
+        agent_ctx = ConversationContext(combined_system, max_messages=20)
+        registry = get_default_registry()
+        agent_ctx.add_user_message(task)
+
+        return run_agent_loop(
+            context=agent_ctx,
+            config=self.config,
+            tools=tools or registry.list_tools(),
+            registry=registry,
+            label=role,
+        )
+
+
+class Coordinator:
+    """Break down tasks and distribute across specialized agents."""
+
+    def __init__(self, config):
+        self.config = config
+        self.handoff = AgentHandoff(config)
+
+    def orchestrate(self, task: str, roles: Optional[List[str]] = None) -> str:
+        """Coordinate multiple agents for a complex task.
+
+        Research and testing phases run in parallel when both are present,
+        cutting total wall-clock time significantly on complex tasks.
+        """
+        if roles is None:
+            roles = ["researcher", "coder", "reviewer"]
+
+        results = {}
+        report_parts = ["# Orchestration Report\n", f"**Task:** {task}\n"]
+
+        # Phase 1: Run researcher + tester in parallel (they don't depend on each other)
+        parallel_roles = [r for r in ["researcher", "tester"] if r in roles]
+        if len(parallel_roles) > 1:
+            _console.print(f"  [orchestrator] Running {' + '.join(parallel_roles)} in parallel...")
+            sub_tasks = [
+                ("researcher", f"Research this task and gather information: {task}"),
+                ("tester", f"Review existing tests and identify what new tests will be needed for: {task}"),
+            ]
+            parallel_results = {}
+            with ThreadPoolExecutor(max_workers=2) as executor:
+                futures = {
+                    executor.submit(self.handoff.handoff, role, sub_task): role
+                    for role, sub_task in sub_tasks
+                }
+                for future in as_completed(futures):
+                    role = futures[future]
+                    try:
+                        parallel_results[role] = future.result()
+                    except Exception as e:
+                        parallel_results[role] = f"Error: {e}"
+            results.update(parallel_results)
+            if "researcher" in results:
+                report_parts.append(f"\n## Research Findings\n{results['researcher']}\n")
+            if "tester" in results:
+                report_parts.append(f"\n## Test Plan\n{results['tester']}\n")
+        elif "researcher" in roles:
+            _console.print("  [orchestrator] Research phase...")
+            results["researcher"] = self.handoff.handoff(
+                "researcher", f"Research this task and gather information: {task}"
+            )
+            report_parts.append(f"\n## Research Findings\n{results['researcher']}\n")
+        elif "tester" in roles:
+            _console.print("  [orchestrator] Test planning phase...")
+            results["tester"] = self.handoff.handoff(
+                "tester",
+                f"Review existing tests and identify what new tests will be needed for: {task}",
+            )
+            report_parts.append(f"\n## Test Plan\n{results['tester']}\n")
+
+        # Phase 2: Implementation (depends on research output)
+        if "coder" in roles:
+            context = results.get("researcher", "")
+            coder_task = task
+            if context:
+                coder_task = f"{task}\n\nResearch context:\n{_truncate_to_tokens(context)}"
+
+            _console.print("  [orchestrator] Implementation phase...")
+            results["implementation"] = self.handoff.handoff("coder", coder_task)
+            report_parts.append(f"\n## Implementation\n{results['implementation']}\n")
+
+        # Phase 3: Review (depends on implementation)
+        if "reviewer" in roles and "implementation" in results:
+            _console.print("  [orchestrator] Review phase...")
+            results["review"] = self.handoff.handoff(
+                "reviewer",
+                f"Review this implementation:\n{_truncate_to_tokens(results['implementation'])}"
+            )
+            report_parts.append(f"\n## Review Feedback\n{results['review']}\n")
+
+        return "\n".join(report_parts)
+
+    def parallel_orchestrate(self, task: str, sub_tasks: list[tuple[str, str]]) -> str:
+        """Run multiple agents in parallel on different subtasks."""
+        results = {}
+        report_parts = ["# Parallel Orchestration\n", f"**Task:** {task}\n"]
+
+        with ThreadPoolExecutor(max_workers=min(len(sub_tasks), _MAX_PARALLEL_WORKERS)) as executor:
+            futures = {}
+            for role, subtask in sub_tasks:
+                _console.print(f"  [orchestrator] Launching {role}...")
+                futures[executor.submit(self.handoff.handoff, role, subtask)] = role
+
+            for future in as_completed(futures):
+                role = futures[future]
+                try:
+                    results[role] = future.result()
+                except Exception as e:
+                    results[role] = f"Error: {e}"
+
+        for role, result in results.items():
+            report_parts.append(f"\n## {role.capitalize()} Results\n{result}\n")
+
+        return "\n".join(report_parts)

luckyd_code/permissions/__init__.py

@@ -0,0 +1 @@
+from .manager import check_permission, TOOL_RISKS