pascal-agent 0.3.0__py3-none-any.whl

pascal/actions.py

@@ -0,0 +1,1066 @@
+"""Pascal action handlers -- extracted from loop.py for maintainability.
+
+Each handler processes one action type and returns a result dict.
+Called by the main loop's dispatcher in loop.py.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+from pascal.effect import classify_command, check_allowed, get_max_effect, escalation_message, effect_to_int
+from pascal.mcp import MCPManager
+from pascal.receipts import Ledger
+from pascal.sandbox import SandboxManager
+from pascal.state import PascalStore
+from pascal.tools import (
+    execute_tool, TOOL_REGISTRY, TOOL_EFFECTS,
+    get_channel_bot, get_owner_chat_id,
+)
+from pascal.trust import scan_tool_input
+from pascal.types import Message, Role, PlanNode, TaskPlan
+
+logger = logging.getLogger(__name__)
+
+# Delegate tool configs
+DELEGATE_TOOLS = {
+    "claude-code": ["claude", "--print", "-p"],
+    "codex": ["codex", "-q"],
+}
+_DELEGATE_MAX_TIMEOUT = 600
+_COMPLETE_TASK_FAILURE_WINDOW = 3
+_COMPLETE_TASK_HISTORY_SCAN_LIMIT = 20
+_PLAN_MAX_STEPS = 20
+_OUTPUT_SOFT_LIMIT = 4000   # chars — show more context than old 2000 hard limit
+_OUTPUT_HARD_LIMIT = 8000   # chars — absolute max to prevent context blowup
+
+# Actions that cannot appear inside plan steps (enforced at validation + runtime)
+PLAN_FORBIDDEN_ACTIONS = frozenset({"plan", "complete_task", "fail_task", "wait", "escalate"})
+
+
+def _plan_step_effect_level(
+    action: str, step: dict, max_effect: str | None, mcp_manager: MCPManager | None,
+) -> str | None:
+    """Compute effect level for a plan step. Returns None for actions without side effects."""
+    if action == "execute":
+        tool_name = str(step.get("tool") or "").strip()
+        if tool_name:
+            from pascal.tools import TOOL_EFFECTS
+            tool_effect = TOOL_EFFECTS.get(tool_name)
+            if tool_effect is not None:
+                return tool_effect
+            if mcp_manager is not None and mcp_manager.has_tool(tool_name):
+                specs = [s for s in mcp_manager.all_tool_specs() if s.name == tool_name]
+                return "E3" if (specs and specs[0].side_effects) else "E0"
+            return "E1"
+        command = str(step.get("command") or "").strip()
+        if command:
+            return classify_command(command)
+    elif action == "delegate":
+        return "E2"
+    return None
+
+
+@dataclass
+class ActionContext:
+    """Bundles runtime dependencies for action handlers.
+
+    Replaces the 9-parameter kwargs signature. Handlers access only what they need.
+    Inspired by OpenAI Agents SDK RunContext / Claude Code tool context patterns.
+    """
+    store: PascalStore
+    llm: Any = None
+    max_effect: str | None = None
+    sandbox: SandboxManager | None = None
+    mcp_manager: MCPManager | None = None
+    execute_command: Callable[[str], str] | None = None
+    thought_buffer: list[str] = field(default_factory=list)
+    ledger: Ledger | None = None
+    skip_verification: bool = False
+    notify_fn: Callable[[str], Any] | None = None
+
+    async def notify(self, msg: str) -> None:
+        if self.notify_fn is not None:
+            await self.notify_fn(msg)
+
+
+def _truncate_output(text: str) -> str:
+    """Truncate output dynamically. Keeps more context than the old 2000-char hard limit."""
+    if len(text) <= _OUTPUT_SOFT_LIMIT:
+        return text
+    if len(text) <= _OUTPUT_HARD_LIMIT:
+        return text  # within limit, keep full
+    return text[:_OUTPUT_HARD_LIMIT] + f"\n... [truncated, {len(text)} chars total]"
+
+
+async def _handle_think(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    thought = str(decision.get("thought") or decision.get("reason") or "").strip()
+    if thought:
+        ctx.thought_buffer.append(thought)
+    return {"thought": thought}
+
+
+async def _handle_plan(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    active = ctx.store.get_active_task()
+    if not active:
+        return {"error": "no active task to plan for"}
+
+    # Accept plan_tree (new tree format) or steps (legacy flat array)
+    plan_tree_data = decision.get("plan_tree")
+    steps = decision.get("steps") or []
+    patch_node_id = decision.get("patch_node_id")  # for subtree repair
+
+    if plan_tree_data:
+        # New tree format: validate and store
+        try:
+            root = PlanNode.from_dict(plan_tree_data)
+        except (KeyError, TypeError) as e:
+            return {"error": f"invalid plan_tree: {e}"}
+        plan = TaskPlan(root=root)
+        errors = plan.validate()
+        if errors:
+            return {"error": f"plan validation failed: {'; '.join(errors[:5])}"}
+    elif steps:
+        # Legacy flat steps → wrap into tree
+        if len(steps) > _PLAN_MAX_STEPS:
+            return {"error": f"plan has {len(steps)} steps, max is {_PLAN_MAX_STEPS}"}
+        children = []
+        for i, step in enumerate(steps):
+            if not isinstance(step, dict):
+                return {"error": f"step {i} must be a dict"}
+            step_action = str(step.get("action") or "").strip()
+            if not step_action or step_action not in VALID_ACTIONS or step_action in PLAN_FORBIDDEN_ACTIONS:
+                return {"error": f"step {i}: action '{step_action}' is not allowed inside a plan"}
+            children.append(PlanNode(
+                id=f"s{i}",
+                title=str(step.get("reason") or step.get("command") or step.get("tool") or f"step {i}"),
+                kind="leaf",
+                done_when=str(step.get("done_when") or step.get("expected_evidence") or "action completes successfully"),
+                action=step,
+            ))
+        root = PlanNode(id="root", title=active["goal"][:80], kind="branch", children=children)
+        plan = TaskPlan(root=root)
+    else:
+        return {"error": "plan requires 'plan_tree' or 'steps'"}
+
+    # Handle subtree repair: patch into existing plan
+    if patch_node_id:
+        existing_data = ctx.store.get_task_plan(active["id"])
+        if existing_data:
+            existing_plan = TaskPlan.from_dict(existing_data)
+            if existing_plan.root:
+                target = existing_plan.root.find_node(patch_node_id)
+                if target and plan.root:
+                    # Replace the target's children with new plan's root children
+                    target.kind = "branch"
+                    target.children = plan.root.children if plan.root.kind == "branch" else [plan.root]
+                    target.status = "pending"
+                    target.action = None
+                    target.last_error = None
+                    target.attempts = 0
+                    existing_plan.revision += 1
+                    plan = existing_plan
+                else:
+                    return {"error": f"patch target node '{patch_node_id}' not found in existing plan"}
+        else:
+            return {"error": "patch_node_id specified but no existing plan"}
+
+    # Store the plan
+    if not patch_node_id:
+        plan.revision = (plan.revision or 0)
+    ctx.store.set_task_plan(active["id"], plan.to_dict())
+
+    # Hybrid execution: compile pending leaves to steps and execute eagerly
+    pending = plan.pending_leaves()
+    if not pending:
+        return {"plan_stored": True, "plan_completed": True, "leaves_total": len(plan.root.get_leaves()) if plan.root else 0}
+
+    plan_results: list[dict[str, Any]] = []
+    for leaf in pending:
+        leaf.status = "active"
+        plan.active_node_id = leaf.id
+        ctx.store.set_task_plan(active["id"], plan.to_dict())
+
+        step = leaf.action or {}
+        step_action = str(step.get("action") or "").strip()
+        if not step_action or step_action not in VALID_ACTIONS or step_action in PLAN_FORBIDDEN_ACTIONS:
+            leaf.status = "failed"
+            leaf.last_error = f"action '{step_action}' is not allowed inside a plan"
+            plan_results.append({"node_id": leaf.id, "error": leaf.last_error})
+            break
+
+        # Effect level gate for plan steps (defense-in-depth)
+        step_effect = _plan_step_effect_level(step_action, step, ctx.max_effect, ctx.mcp_manager)
+        if step_effect is not None:
+            allowed_max = get_max_effect(ctx.max_effect)
+            if not check_allowed(step_effect, allowed_max):
+                leaf.status = "failed"
+                leaf.last_error = escalation_message(
+                    str(step.get("command") or step.get("tool") or step_action),
+                    step_effect, allowed_max,
+                )
+                plan_results.append({"node_id": leaf.id, "error": leaf.last_error})
+                ctx.store.set_task_plan(active["id"], plan.to_dict())
+                break
+
+        step_result = await execute_action(
+            ctx.store, step, step_action, ctx=ctx,
+        )
+        plan_results.append({"node_id": leaf.id, "action": step_action, "result": step_result})
+
+        # Record in history
+        step_reason = str(step.get("reason") or step.get("command") or step.get("tool") or "")
+        ctx.store.record(
+            f"{step_action}: {step_reason}" if step_reason else step_action,
+            task_id=active["id"],
+            details={"decision": step, "result": step_result, "plan_node_id": leaf.id},
+            action_status=step_result.get("status", "ok") if isinstance(step_result, dict) else "ok",
+        )
+        if ctx.ledger is not None:
+            ctx.ledger.record_action(step_action, step, step_result)
+
+        # Update node status based on result
+        step_status = step_result.get("status", "ok") if isinstance(step_result, dict) else "ok"
+        if isinstance(step_result, dict) and (step_result.get("error") or step_result.get("escalate")):
+            leaf.status = "failed"
+            leaf.attempts += 1
+            leaf.last_error = str(step_result.get("error") or "escalated")[:200]
+            ctx.store.set_task_plan(active["id"], plan.to_dict())
+            break  # Stop executing — loop.py will handle replanning
+        elif step_status == "unknown":
+            # Side effect uncertain — do NOT mark as done, treat as failed
+            # Propagate "unknown" status so loop.py can set has_unknown_step
+            leaf.status = "failed"
+            leaf.attempts += 1
+            leaf.last_error = "Action returned unknown status (side effect uncertain). Needs verification."
+            ctx.store.set_task_plan(active["id"], plan.to_dict())
+            # Ensure the aggregate result preserves "unknown" (not just "error")
+            # so loop.py's _observe_result sees ActionStatus.UNKNOWN
+            plan_results.append({"node_id": leaf.id, "action": step_action, "result": step_result})
+            break  # Stop and let loop.py handle readback/replanning
+        else:
+            leaf.status = "done"
+
+    # Save final state
+    plan.active_node_id = None
+    ctx.store.set_task_plan(active["id"], plan.to_dict())
+
+    counts = plan.root.count_by_status() if plan.root else {}
+    all_done = counts.get("pending", 0) == 0 and counts.get("failed", 0) == 0
+    result: dict[str, Any] = {
+        "plan_stored": True,
+        "plan_completed": all_done,
+        "executed": len(plan_results),
+        "status_counts": counts,
+    }
+    # Propagate attachment from last successful step
+    for pr in reversed(plan_results):
+        sr: Any = pr.get("result", {})
+        if isinstance(sr, dict) and sr.get("attachment"):
+            result["attachment"] = sr["attachment"]
+            break
+    # Signal failure for loop.py plan-aware retry
+    if counts.get("failed", 0) > 0:
+        failed = plan.failed_leaves()
+        result["failed_node"] = failed[0].to_dict() if failed else None
+        # Preserve "unknown" status if any step had uncertain side effects,
+        # so loop.py can set has_unknown_step via _observe_result
+        has_unknown = any(
+            isinstance(pr.get("result"), dict) and pr["result"].get("status") == "unknown"
+            for pr in plan_results
+        )
+        result["status"] = "unknown" if has_unknown else "error"
+    return result
+
+
+async def _handle_delegate_action(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    return await _handle_delegate(ctx, decision)
+
+
+async def _handle_execute(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    # Code execution: run Python snippet in sandbox (smolagents pattern)
+    code = str(decision.get("code") or "").strip()
+    if code:
+        scan_result = scan_tool_input("code", {"code": code})
+        if scan_result.verdict == "block":
+            return {"error": f"blocked by trust scanner: {scan_result.reason}", "status": "error"}
+        # Python code is E2 (local write potential)
+        allowed_max = get_max_effect(ctx.max_effect)
+        if not check_allowed("E2", allowed_max):
+            return {"error": escalation_message("python code", "E2", allowed_max), "status": "error", "escalate": True}
+        sb = ctx.sandbox or SandboxManager()
+        # Write code to a temp file to avoid shell quoting issues
+        import tempfile as _tf
+        with _tf.NamedTemporaryFile(mode="w", suffix=".py", delete=False, encoding="utf-8") as f:
+            f.write(code)
+            script_path = f.name
+        try:
+            sb_result = sb.run(f"python3 {script_path}", timeout=60)
+        finally:
+            try:
+                os.unlink(script_path)
+            except OSError:
+                pass
+        active = ctx.store.get_active_task()
+        if active:
+            ctx.store.update_task(active["id"], progress=f"Code: {code[:80]}")
+        return {"output": _truncate_output(sb_result.output), "status": sb_result.status}
+
+    tool_name = str(decision.get("tool") or "").strip()
+    if tool_name:
+        tool_params = decision.get("tool_params") or {}
+        if not isinstance(tool_params, dict):
+            return {"error": "tool_params must be a dict", "status": "error"}
+        scan = scan_tool_input(tool_name, tool_params)
+        if scan.verdict == "block":
+            return {"error": f"blocked by trust scanner: {scan.reason}", "status": "error"}
+        tool_effect = TOOL_EFFECTS.get(tool_name, None)
+        if tool_effect is None:
+            if ctx.mcp_manager is not None and ctx.mcp_manager.has_tool(tool_name):
+                specs = [s for s in ctx.mcp_manager.all_tool_specs() if s.name == tool_name]
+                tool_effect = "E3" if (specs and specs[0].side_effects) else "E0"
+            else:
+                tool_effect = "E1"
+        allowed_max = get_max_effect(ctx.max_effect)
+        if not check_allowed(tool_effect, allowed_max):
+            return {
+                "error": escalation_message(tool_name, tool_effect, allowed_max),
+                "status": "error", "effect_level": tool_effect, "escalate": True,
+            }
+        use_mcp = (ctx.mcp_manager is not None and ctx.mcp_manager.has_tool(tool_name)
+                    and (tool_name not in TOOL_REGISTRY or "uid" in tool_params))
+        if use_mcp and ctx.mcp_manager is not None:
+            tool_result = await ctx.mcp_manager.call_tool(tool_name, tool_params)
+        elif tool_name in TOOL_REGISTRY:
+            tool_result = await execute_tool(tool_name, tool_params)
+        elif ctx.mcp_manager is not None and ctx.mcp_manager.has_tool(tool_name):
+            tool_result = await ctx.mcp_manager.call_tool(tool_name, tool_params)
+        else:
+            return {"error": f"Unknown tool: {tool_name}", "status": "error"}
+        active = ctx.store.get_active_task()
+        if active:
+            ctx.store.update_task(active["id"], progress=f"Tool: {tool_name}")
+        result_dict = {
+            "output": _truncate_output(tool_result.get("output") or ""),
+            "status": "ok" if tool_result.get("ok") else "error",
+            "error": tool_result.get("error", ""),
+            "tool": tool_name,
+        }
+        if tool_result.get("attachment") is not None:
+            result_dict["attachment"] = tool_result["attachment"]
+        return result_dict
+
+    command = str(decision.get("command") or "").strip()
+    if not command:
+        return {"error": "no command or tool provided"}
+    llm_effect = str(decision.get("effect_level") or "")
+    cmd_level = classify_command(command, llm_assessment=llm_effect)
+    allowed_max = get_max_effect(ctx.max_effect)
+    if not check_allowed(cmd_level, allowed_max):
+        return {
+            "error": escalation_message(command, cmd_level, allowed_max),
+            "status": "error", "effect_level": cmd_level, "escalate": True,
+        }
+    scan_result = scan_tool_input("shell", {"command": command})
+    if scan_result.verdict == "block":
+        return {"error": f"blocked by trust scanner: {scan_result.reason}", "status": "error"}
+    if scan_result.verdict == "warn":
+        logger.warning("Trust scanner warning: %s", scan_result.reason)
+    if ctx.execute_command:
+        try:
+            output = ctx.execute_command(command)
+            status = "ok" if output is not None else "error"
+        except Exception as exc:
+            output = str(exc)
+            status = "unknown"
+    else:
+        sb = ctx.sandbox or SandboxManager()
+        sb_result = sb.run(command, timeout=60)
+        output = sb_result.output
+        status = sb_result.status
+    active = ctx.store.get_active_task()
+    if active:
+        ctx.store.update_task(active["id"], progress=f"Ran: {command[:100]}")
+    safe_output = "" if output is None else str(output)
+    return {"output": _truncate_output(safe_output), "status": status}
+
+
+async def _handle_create_task(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    goal = str(decision.get("goal") or "").strip()
+    if not goal:
+        return {"error": "goal is required for create_task"}
+    priority = str(decision.get("priority") or "normal").strip()
+    if priority not in ("urgent", "normal", "low"):
+        priority = "normal"
+    task_id = ctx.store.add_task(goal, priority=priority, source="agent")
+    estimated_effect = str(decision.get("estimated_effect") or "E1").strip()
+    if effect_to_int(estimated_effect) >= 2:
+        ctx.store.update_task(
+            task_id,
+            status="blocked",
+            progress=f"Awaiting approval (agent-initiated, {estimated_effect})",
+        )
+        await ctx.notify(f"📋 제안: {goal}\n효과 수준 {estimated_effect} -- 승인이 필요합니다.")
+    return {"created": task_id, "goal": goal, "source": "agent"}
+
+
+async def _handle_pick_task(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    task_id = str(decision.get("task_id") or "").strip()
+    if not task_id:
+        return {"error": "task_id is required -- choose which task to activate"}
+    current = ctx.store.get_active_task()
+    if current and current["id"] == task_id:
+        return {"activated": task_id, "already_active": True}
+    target = ctx.store.connection.execute(
+        "SELECT id, status FROM tasks WHERE id = ?", (task_id,),
+    ).fetchone()
+    if target is None:
+        return {"error": f"task {task_id} not found"}
+    if target["status"] in ("done", "failed"):
+        return {"error": f"task {task_id} is '{target['status']}' (terminal) -- pick a pending or paused task"}
+    if current and current["id"] != task_id:
+        ctx.store.pause_active_task("switching to another task")
+    ctx.store.activate_task(task_id)
+    task_row = ctx.store.connection.execute("SELECT goal FROM tasks WHERE id = ?", (task_id,)).fetchone()
+    goal = task_row["goal"] if task_row else task_id
+    await ctx.notify(f"▶ 시작: {goal}")
+    return {"activated": task_id}
+
+
+async def _handle_create_subtask(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    active = ctx.store.get_active_task()
+    if not active:
+        return {"error": "no active task to create subtask under"}
+    goal = str(decision.get("subtask_goal") or "").strip()
+    if not goal:
+        return {"error": "subtask_goal is required"}
+    priority = str(decision.get("subtask_priority") or "normal").strip()
+    if priority not in ("urgent", "normal", "low"):
+        priority = "normal"
+    subtask_id = ctx.store.add_task(
+        goal, priority=priority, source="agent", parent_id=active["id"],
+    )
+    return {"created": subtask_id, "parent": active["id"], "goal": goal}
+
+
+async def _handle_handle_notification(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    notif_id = str(decision.get("notification_id") or "").strip()
+    if not notif_id:
+        return {"error": "notification_id is required"}
+    response = str(decision.get("response") or "").strip()
+    reply_text = str(decision.get("reply_text") or "").strip()
+    notif = ctx.store.connection.execute(
+        "SELECT source, message, metadata FROM notifications WHERE id = ?", (notif_id,),
+    ).fetchone()
+    # Reply to a notification is E2 (responding to human message, not unsolicited outbound).
+    # channel_reply tool (unsolicited) stays E3.
+    allowed_max = get_max_effect(ctx.max_effect)
+    if reply_text and not check_allowed("E2", allowed_max):
+        reply_text = ""
+        logger.warning("Reply suppressed: E2 exceeds max_effect %s", allowed_max)
+    if reply_text:
+        from pascal.trust import scan as _trust_scan
+        reply_scan = _trust_scan(reply_text)
+        if reply_scan.verdict == "block":
+            reply_text = ""
+            logger.warning("Reply blocked by trust scanner: %s", reply_scan.reason)
+    reply_sent = False
+    if reply_text and reply_text.strip().upper() != "NO_REPLY" and notif:
+        if get_channel_bot() is not None:
+            import json as _json
+            try:
+                meta = _json.loads(notif["metadata"]) if notif["metadata"] else {}
+            except (ValueError, TypeError):
+                meta = {}
+            chat_id = int(meta.get("chat_id", get_owner_chat_id() or 0))
+            if chat_id:
+                try:
+                    await get_channel_bot().send_message(chat_id=chat_id, text=reply_text)
+                    reply_sent = True
+                except Exception as e:
+                    logger.warning("Channel reply failed: %s", e)
+    if not reply_sent and reply_text and notif:
+        source = notif["source"] if notif else ""
+        try:
+            meta = json.loads(notif["metadata"]) if notif["metadata"] else {}
+        except (ValueError, TypeError):
+            meta = {}
+        # Only use webhook URLs from trusted sources (env vars), never from metadata
+        reply_url = ""
+        if "slack" in source:
+            reply_url = os.environ.get("PASCAL_SLACK_WEBHOOK", "")
+        elif "discord" in source:
+            reply_url = os.environ.get("PASCAL_DISCORD_WEBHOOK", "")
+        if reply_url:
+            from pascal.scheduler import _send_webhook
+            reply_sent = _send_webhook(reply_url, reply_text)
+    ctx.store.handle_notification(notif_id)
+    if notif and reply_sent:
+        ctx.store.push_conversation_turn(notif["source"] if notif else "unknown", "assistant", reply_text)
+    return {"handled": notif_id, "response": response, "reply_sent": reply_sent}
+
+
+async def _handle_dismiss_notification(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    notif_id = str(decision.get("notification_id") or "").strip()
+    if not notif_id:
+        return {"error": "notification_id is required"}
+    ctx.store.dismiss_notification(notif_id)
+    return {"dismissed": notif_id}
+
+
+async def _handle_pause_task(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    pause_reason = str(decision.get("pause_reason") or "interrupted")
+    paused = ctx.store.pause_active_task(pause_reason)
+    return {"paused": paused}
+
+
+async def _handle_complete_task(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    active = ctx.store.get_active_task()
+    if active:
+        summary = str(decision.get("summary") or "completed")
+        guard_history = ctx.store.get_recent_history(limit=_COMPLETE_TASK_HISTORY_SCAN_LIMIT)
+        if _recent_execute_failure_streak(guard_history, active["id"]):
+            reason = (
+                f"Cannot complete: the last {_COMPLETE_TASK_FAILURE_WINDOW} recent execute "
+                "actions for this task failed or returned empty output."
+            )
+            ctx.store.update_task(active["id"], progress=f"Completion blocked: {reason}")
+            return {"error": reason, "retry": True}
+
+        history = ctx.store.get_recent_history(limit=5)
+        proof_required = None
+        if active.get("proof_required"):
+            try:
+                proof_required = json.loads(active["proof_required"])
+            except (json.JSONDecodeError, TypeError):
+                pass
+        # Verification: only run when proof_required is explicitly set on the task.
+        # For normal tasks, trust the LLM's completion claim -- the action history
+        # is already recorded for audit. This saves 1 LLM call per task completion.
+        if proof_required and ctx.llm is not None and not ctx.skip_verification:
+            passed, reason = await _verify_completion(
+                ctx.llm, active["goal"], summary, history, proof_required=proof_required,
+            )
+        else:
+            passed, reason = True, "no_proof_required"
+        if not passed:
+            ctx.store.update_task(active["id"], progress=f"Verification failed: {reason}")
+            return {"error": f"verification_failed: {reason}", "retry": True}
+        ctx.store.update_task(active["id"], status="done", result=summary)
+        # Auto-memorize: extract detailed, reusable procedure from task history
+        _auto_memorize_procedure(ctx.store, {**active, "result": summary}, history)
+        await ctx.notify(f"✓ 완료: {active['goal']}\n{summary}")
+        return {"completed": active["id"], "summary": summary, "verified": True}
+    return {"error": "no active task"}
+
+
+async def _handle_block_task(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    active = ctx.store.get_active_task()
+    if active:
+        reason = str(decision.get("reason") or "blocked")
+        ctx.store.update_task(active["id"], status="blocked", progress=f"Blocked: {reason}")
+        return {"blocked": active["id"], "reason": reason}
+    return {"error": "no active task"}
+
+
+async def _handle_fail_task(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    active = ctx.store.get_active_task()
+    if active:
+        reason = str(decision.get("reason") or "failed")
+        ctx.store.update_task(active["id"], status="failed", progress=f"Failed: {reason}")
+        _auto_postmortem(ctx.store, active, reason)
+        await ctx.notify(f"✗ 실패: {active['goal']}\n{reason}")
+        return {"failed": active["id"], "reason": reason}
+    return {"error": "no active task"}
+
+
+async def _handle_add_todo(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    title = str(decision.get("todo_title") or decision.get("title") or "").strip()
+    active = ctx.store.get_active_task()
+    if not active:
+        return {"error": "no active task to add todo to"}
+    if not title:
+        return {"error": "empty todo title"}
+    todo_id = ctx.store.add_todo(task_id=active["id"], title=title)
+    return {"added": todo_id, "title": title}
+
+
+async def _handle_complete_todo(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    todo_id = str(decision.get("todo_id") or "").strip()
+    if not todo_id:
+        return {"error": "no todo_id"}
+    ctx.store.complete_todo(todo_id)
+    return {"completed": todo_id}
+
+
+async def _handle_memorize(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    kind = str(decision.get("memory_kind") or "").strip()
+    content = str(decision.get("memory_content") or "").strip()
+    if not content:
+        return {"error": "empty memory content"}
+    if kind not in ("fact", "lesson", "preference", "procedure"):
+        return {"error": f"invalid memory_kind '{kind}' -- must be fact|lesson|preference|procedure"}
+    active = ctx.store.get_active_task()
+    mem_id = ctx.store.add_memory(
+        kind=kind, content=content,
+        source_task_id=active["id"] if active else None,
+    )
+    return {"memorized": mem_id, "kind": kind}
+
+
+async def _handle_add_rule(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    rule = str(decision.get("rule") or "").strip()
+    if rule:
+        rule_id = ctx.store.add_rule(rule, mutable=True, added_by="agent")
+        return {"added": rule_id, "rule": rule}
+    return {"error": "empty rule"}
+
+
+async def _handle_remove_rule(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    rule_id = str(decision.get("rule_id") or "").strip()
+    if rule_id:
+        removed = ctx.store.remove_rule(rule_id)
+        return {"removed": removed, "rule_id": rule_id}
+    return {"error": "no rule_id"}
+
+
+async def _handle_set_context(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    key = str(decision.get("key") or "").strip()
+    value = decision.get("value")
+    if not key:
+        return {"error": "no key"}
+    # Protect critical context keys from agent modification
+    _PROTECTED_CONTEXT_KEYS = frozenset({"mission", "identity", "routines"})
+    if key in _PROTECTED_CONTEXT_KEYS:
+        return {"error": f"context key '{key}' is protected and cannot be modified by the agent"}
+    ttl = decision.get("ttl_hours")
+    if isinstance(ttl, (int, float)) and ttl > 0:
+        ctx.store.set_context(key, value, ttl_hours=int(ttl))
+    else:
+        ctx.store.set_context(key, value)
+    return {"set": key}
+
+
+async def _handle_escalate(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    question = str(decision.get("question") or "Need human input")
+    return {"escalated": True, "question": question}
+
+
+async def _handle_wait(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    return {"waiting": True, "reason": str(decision.get("wait_reason") or "")}
+
+
+# ── Handler registry ──────────────────────────────────────────────
+
+ACTION_HANDLERS: dict[str, Callable] = {
+    "think": _handle_think,
+    "plan": _handle_plan,
+    "delegate": _handle_delegate_action,
+    "execute": _handle_execute,
+    "create_task": _handle_create_task,
+    "pick_task": _handle_pick_task,
+    "create_subtask": _handle_create_subtask,
+    "handle_notification": _handle_handle_notification,
+    "dismiss_notification": _handle_dismiss_notification,
+    "pause_task": _handle_pause_task,
+    "complete_task": _handle_complete_task,
+    "block_task": _handle_block_task,
+    "fail_task": _handle_fail_task,
+    "add_todo": _handle_add_todo,
+    "complete_todo": _handle_complete_todo,
+    "memorize": _handle_memorize,
+    "add_rule": _handle_add_rule,
+    "remove_rule": _handle_remove_rule,
+    "set_context": _handle_set_context,
+    "escalate": _handle_escalate,
+    "wait": _handle_wait,
+}
+
+# Valid actions -- single source of truth (must match ACTION_HANDLERS keys)
+VALID_ACTIONS = frozenset(ACTION_HANDLERS)
+
+
+# ── Public dispatch function ──────────────────────────────────────
+
+async def execute_action(
+    store: PascalStore,
+    decision: dict[str, Any],
+    action: str,
+    *,
+    ctx: ActionContext | None = None,
+    llm=None,
+    max_effect: str | None = None,
+    sandbox: SandboxManager | None = None,
+    mcp_manager: MCPManager | None = None,
+    execute_command: Callable[[str], str] | None = None,
+    thought_buffer: list[str] | None = None,
+    ledger: Ledger | None = None,
+    skip_verification: bool = False,
+    notify_fn: Callable[[str], Any] | None = None,
+) -> dict[str, Any]:
+    """Execute a single action and return the result.
+
+    Accepts either an ActionContext (preferred) or individual kwargs (backward compat).
+    """
+    handler = ACTION_HANDLERS.get(action)
+    if handler is None:
+        return {"error": f"unhandled action: {action}"}
+    if ctx is not None:
+        return await handler(ctx, decision)
+    shim_ctx = ActionContext(
+        store=store,
+        llm=llm,
+        max_effect=max_effect,
+        sandbox=sandbox,
+        mcp_manager=mcp_manager,
+        execute_command=execute_command,
+        thought_buffer=thought_buffer or [],
+        ledger=ledger,
+        skip_verification=skip_verification,
+        notify_fn=notify_fn,
+    )
+    return await handler(shim_ctx, decision)
+
+
+# ── Delegate handler ──────────────────────────────────────────────
+
+async def _handle_delegate(ctx: ActionContext, decision: dict[str, Any]) -> dict[str, Any]:
+    """Delegate a task to Claude Code or Codex CLI via async subprocess."""
+    tool_name = str(decision.get("tool") or "").strip()
+    if tool_name not in DELEGATE_TOOLS:
+        return {"error": f"Unknown delegate tool '{tool_name}'. Available: {', '.join(DELEGATE_TOOLS)}", "status": "error"}
+
+    task_desc = str(decision.get("task") or "").strip()
+    if not task_desc:
+        return {"error": "delegate requires a 'task' field", "status": "error"}
+
+    context = str(decision.get("context") or "").strip()
+    success_criteria = str(decision.get("success_criteria") or "").strip()
+
+    combined_text = f"{task_desc}\n{context}\n{success_criteria}"
+    scan_result = scan_tool_input("delegate", {"task": combined_text})
+    if scan_result.verdict == "block":
+        return {"error": f"blocked by trust scanner: {scan_result.reason}", "status": "error"}
+
+    allowed_max = get_max_effect(ctx.max_effect)
+    if not check_allowed("E2", allowed_max):
+        return {
+            "error": escalation_message(f"delegate:{tool_name}", "E2", allowed_max),
+            "status": "error", "effect_level": "E2", "escalate": True,
+        }
+
+    prompt_parts = [task_desc]
+    if context:
+        prompt_parts.append(f"\nContext: {context}")
+    if success_criteria:
+        prompt_parts.append(f"\nSuccess criteria: {success_criteria}")
+    prompt = "\n".join(prompt_parts)
+
+    cmd_base = DELEGATE_TOOLS[tool_name]
+    cmd = cmd_base + [prompt]
+
+    timeout = min(int(decision.get("timeout") or 300), _DELEGATE_MAX_TIMEOUT)
+
+    import shutil as _shutil
+    from pascal.sandbox import make_safe_env
+    from pathlib import Path as _P
+
+    safe_env, tmp_home = make_safe_env()
+
+    def _cleanup_tmp():
+        try:
+            if os.path.isdir(tmp_home):
+                _shutil.rmtree(tmp_home, ignore_errors=True)
+            from pascal.sandbox import _sandbox_temp_dirs
+            if tmp_home in _sandbox_temp_dirs:
+                _sandbox_temp_dirs.remove(tmp_home)
+        except Exception:
+            pass
+
+    real_home = _P.home()
+    _AUTH_FILES = {
+        ".codex": ["auth.json"],
+        ".claude": ["auth.json", "config.toml"],
+    }
+    for auth_dir, allowed_files in _AUTH_FILES.items():
+        src = real_home / auth_dir
+        dst = _P(tmp_home) / auth_dir
+        if src.is_dir():
+            try:
+                dst.mkdir(exist_ok=True)
+                for f in allowed_files:
+                    sf = src / f
+                    if sf.exists():
+                        _shutil.copy2(str(sf), str(dst / f))
+            except Exception:
+                pass
+
+    ctx.store.refresh_lock()
+
+    workspace = ctx.sandbox._restricted._workspace if ctx.sandbox else ""
+    cwd = workspace if workspace and os.path.isdir(workspace) else os.getcwd()
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=cwd,
+            env=safe_env,
+        )
+
+        # Refresh lock periodically during long delegate calls to prevent
+        # another runner from acquiring the lock (TTL=600s, delegate up to 600s)
+        async def _refresh_until_done():
+            while proc.returncode is None:
+                await asyncio.sleep(60)
+                ctx.store.refresh_lock()
+
+        refresh_task = asyncio.create_task(_refresh_until_done())
+        try:
+            stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                proc.communicate(), timeout=timeout,
+            )
+        finally:
+            refresh_task.cancel()
+            try:
+                await refresh_task
+            except asyncio.CancelledError:
+                pass
+        stdout = (stdout_bytes or b"").decode("utf-8", errors="replace")
+        stderr = (stderr_bytes or b"").decode("utf-8", errors="replace")
+        ok = proc.returncode == 0
+    except asyncio.TimeoutError:
+        try:
+            proc.kill()
+        except ProcessLookupError:
+            pass
+        _cleanup_tmp()
+        return {"error": f"delegate:{tool_name} timed out ({timeout}s)", "status": "unknown"}
+    except FileNotFoundError:
+        _cleanup_tmp()
+        return {"error": f"'{cmd_base[0]}' not found. Is {tool_name} installed?", "status": "error"}
+    except Exception as exc:
+        _cleanup_tmp()
+        return {"error": f"delegate failed: {exc}", "status": "error"}
+
+    _cleanup_tmp()
+
+    active = ctx.store.get_active_task()
+    if active:
+        ctx.store.update_task(active["id"], progress=f"Delegated to {tool_name}")
+
+    return {
+        "output": stdout[:8000],
+        "stderr": stderr[:2000] if stderr else "",
+        "status": "ok" if ok else "error",
+        "tool": tool_name,
+        "delegate": True,
+    }
+
+
+# ── Verifier ──────────────────────────────────────────────────────
+
+async def _verify_completion(
+    llm,
+    task_goal: str,
+    task_summary: str,
+    recent_history: list[dict[str, Any]],
+    proof_required: list[str] | None = None,
+) -> tuple[bool, str]:
+    """Ask the LLM to verify whether the task was actually completed."""
+    from pascal.types import extract_json as _extract_json
+    history_text = "\n".join(f"- {h['summary']}" for h in recent_history[-5:])
+    proof_text = ""
+    if proof_required:
+        proof_text = f"\nRequired proof: {', '.join(proof_required)}"
+    messages = [
+        Message(
+            role=Role.SYSTEM,
+            content=(
+                "You verify task completion. Return JSON only.\n"
+                '{"passed": true/false, "reason": "why"}\n'
+                "Be strict: did the actions actually accomplish the goal?\n"
+                "Check that claimed evidence matches what actually happened."
+            ),
+        ),
+        Message(
+            role=Role.USER,
+            content=f"Goal: {task_goal}\nClaimed result: {task_summary}{proof_text}\nRecent actions:\n{history_text}",
+        ),
+    ]
+    try:
+        response = await llm.chat(messages, tools=[])
+        payload = json.loads(_extract_json(response.text or "{}"))
+        return bool(payload.get("passed")), str(payload.get("reason") or "")
+    except Exception as exc:
+        logger.warning("Verification error: %s", exc)
+        return False, str(exc)
+
+
+# ── Auto post-mortem ──────────────────────────────────────────────
+
+def _auto_postmortem(store: PascalStore, task: dict[str, Any], failure_reason: str) -> None:
+    """Generate a lesson from task failure. No LLM needed -- just pattern extraction."""
+    try:
+        history = store.get_recent_history(limit=10)
+        actions = []
+        errors = []
+        for h in history:
+            if h.get("task_id") == task["id"]:
+                actions.append(h["summary"])
+                details = h.get("details")
+                if isinstance(details, str):
+                    try:
+                        details = json.loads(details)
+                    except Exception:
+                        details = {}
+                if isinstance(details, dict):
+                    result = details.get("result", {})
+                    if isinstance(result, dict) and result.get("error"):
+                        errors.append(result["error"][:100])
+        lesson = f"Task '{task['goal']}' failed: {failure_reason}."
+        if errors:
+            lesson += f" Errors: {'; '.join(errors[:3])}"
+        if actions:
+            lesson += f" Attempted: {'; '.join(actions[-3:])}"
+        store.add_memory(kind="lesson", content=lesson, source_task_id=task["id"])
+        logger.info("Auto post-mortem lesson: %s", lesson[:100])
+    except Exception:
+        logger.warning("Post-mortem failed", exc_info=True)
+
+
+def _auto_memorize_procedure(
+    store: PascalStore, task: dict[str, Any], history: list[dict[str, Any]]
+) -> None:
+    """Extract a detailed, reusable procedure from completed task history.
+
+    Saves actual commands, tools, and parameters -- not just action names.
+    This creates a 'work manual' entry that Pascal can replay for similar tasks.
+    """
+    try:
+        task_actions = [h for h in history if h.get("task_id") == task["id"]]
+        if len(task_actions) < 1:
+            return
+
+        steps = []
+        for h in task_actions:
+            details = h.get("details")
+            if isinstance(details, str):
+                try:
+                    details = json.loads(details)
+                except (json.JSONDecodeError, TypeError):
+                    continue
+            if not isinstance(details, dict):
+                continue
+
+            dec = details.get("decision", {})
+            res = details.get("result", {})
+            action_type = dec.get("action", "")
+
+            # Skip think, pick_task, wait -- not part of the procedure
+            if action_type in ("think", "pick_task", "wait", "complete_task", ""):
+                continue
+            # Skip failed actions
+            if isinstance(res, dict) and res.get("status") == "error":
+                continue
+
+            step: dict[str, Any] = {"action": action_type}
+            if action_type == "execute":
+                if dec.get("tool"):
+                    step["tool"] = dec["tool"]
+                    # Generalize params: keep structure but mark variable values
+                    params = dec.get("tool_params", {})
+                    if isinstance(params, dict):
+                        step["tool_params"] = {
+                            k: v if k in ("region",) else f"<{k}>"
+                            for k, v in params.items()
+                        }
+                elif dec.get("command"):
+                    step["command"] = dec["command"]
+            elif action_type == "delegate":
+                step["tool"] = dec.get("tool", "")
+                step["task_pattern"] = dec.get("task", "")[:60]
+            elif action_type == "plan":
+                plan_steps = dec.get("steps", [])
+                step["step_count"] = len(plan_steps)
+
+            steps.append(step)
+
+        if not steps:
+            return
+
+        import platform as _platform
+        task_summary = str(task.get("result") or "")
+        proc = json.dumps({
+            "name": task["goal"][:80],
+            "platform": _platform.system(),
+            "steps": steps[-8:],  # Keep last 8 successful steps max
+            "summary": task_summary[:100],
+        }, ensure_ascii=False)
+
+        store.add_memory(kind="procedure", content=proc, source_task_id=task["id"])
+        logger.info("Auto-memorized procedure: %s (%d steps)", task["goal"][:40], len(steps))
+    except Exception:
+        logger.warning("Auto-memorize failed", exc_info=True)
+
+
+def _recent_execute_failure_streak(
+    history: list[dict[str, Any]],
+    task_id: str,
+    *,
+    window: int = _COMPLETE_TASK_FAILURE_WINDOW,
+) -> bool:
+    """Return True when the last N execute actions for a task all failed or were empty."""
+    recent_executes: list[dict[str, Any]] = []
+    for h in reversed(history):
+        if h.get("task_id") != task_id:
+            continue
+        details = h.get("details")
+        if isinstance(details, str):
+            try:
+                details = json.loads(details)
+            except (json.JSONDecodeError, TypeError):
+                details = {}
+        if not isinstance(details, dict):
+            continue
+        decision = details.get("decision", {})
+        if not isinstance(decision, dict) or decision.get("action") != "execute":
+            continue
+        result = details.get("result", {})
+        recent_executes.append(result if isinstance(result, dict) else {})
+        if len(recent_executes) >= window:
+            break
+    if len(recent_executes) < window:
+        return False
+    return all(_execute_result_failed_or_empty(result) for result in recent_executes)
+
+
+def _execute_result_failed_or_empty(result: dict[str, Any]) -> bool:
+    """Treat explicit failures as insufficient completion evidence.
+
+    Successful commands often emit no stdout (mkdir, touch, git add), so a blank
+    output stream alone is not enough to call the step a failure once status=ok
+    is recorded.
+    """
+    if not isinstance(result, dict):
+        return False
+    status = str(result.get("status") or "").strip().lower()
+    if status == "ok":
+        return False
+    if status in {"error", "unknown"}:
+        return True
+    error = result.get("error")
+    if isinstance(error, str) and error.strip():
+        return True
+    if result.get("attachment") is not None:
+        return False
+    output = result.get("output")
+    if isinstance(output, str):
+        return not output.strip()
+    return not bool(output)