ultra-builder-pro-cli 0.5.0

package/hooks/adapters/codex.py

@@ -0,0 +1,302 @@
+#!/usr/bin/env python3
+"""Codex wire adapter for Ultra Builder Pro hooks.
+
+Codex and Claude Code share the JSON-on-stdin command-hook shape, but differ
+at three important boundaries:
+
+- Codex emits ``apply_patch`` with the patch text in ``tool_input.command``;
+  legacy Ultra edit hooks expect one ``Edit`` event per ``file_path``.
+- Codex rejects ``permissionDecision: ask`` in PreToolUse output. Ultra warning
+  decisions therefore become advisory ``systemMessage`` values.
+- Each event has a strict output schema. This adapter removes foreign fields
+  while preserving real deny/block decisions and additional context.
+
+The adapter executes only allowlisted sibling hook modules. It is both a CLI
+entrypoint used by ``hooks/hooks.json`` and an importable normalization layer
+for tests.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+
+HOOK_ROOT = Path(__file__).resolve().parent.parent
+ALLOWED_FEATURES = {
+    "active_task_context.py",
+    "health_check.py",
+    "pre_stop_check.py",
+    "subagent_tracker.py",
+    "workflow_checkpoint.py",
+    "workflow_context.py",
+    "workflow_resume.py",
+}
+UNIVERSAL_OUTPUT_FIELDS = {"continue", "stopReason", "suppressOutput", "systemMessage"}
+PATCH_FILE_RE = re.compile(r"^\*\*\* (?:Add|Update|Delete) File: (.+?)\s*$", re.MULTILINE)
+PATCH_MOVE_RE = re.compile(r"^\*\*\* Move to: (.+?)\s*$", re.MULTILINE)
+
+
+def _patch_paths(tool_input: Any) -> list[str]:
+    if not isinstance(tool_input, dict):
+        return []
+    patch = tool_input.get("command") or tool_input.get("patch") or ""
+    if not isinstance(patch, str):
+        return []
+    paths: list[str] = []
+    for match in [*PATCH_FILE_RE.findall(patch), *PATCH_MOVE_RE.findall(patch)]:
+        candidate = match.strip()
+        if candidate and candidate not in paths:
+            paths.append(candidate)
+    return paths
+
+
+def normalize_inputs(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    """Return legacy-compatible input(s) for one Codex hook payload."""
+    normalized = copy.deepcopy(payload)
+    if normalized.get("tool_response") is not None and normalized.get("tool_output") is None:
+        normalized["tool_output"] = normalized["tool_response"]
+
+    if normalized.get("tool_name") != "apply_patch":
+        return [normalized]
+
+    paths = _patch_paths(normalized.get("tool_input"))
+    if not paths:
+        normalized["tool_name"] = "Edit"
+        tool_input = normalized.get("tool_input")
+        normalized["tool_input"] = dict(tool_input) if isinstance(tool_input, dict) else {}
+        normalized["tool_input"].setdefault("file_path", "")
+        return [normalized]
+
+    outputs: list[dict[str, Any]] = []
+    for file_path in paths:
+        item = copy.deepcopy(normalized)
+        item["tool_name"] = "Edit"
+        tool_input = item.get("tool_input")
+        item["tool_input"] = dict(tool_input) if isinstance(tool_input, dict) else {}
+        item["tool_input"]["file_path"] = file_path
+        outputs.append(item)
+    return outputs
+
+
+def _universal(output: dict[str, Any]) -> dict[str, Any]:
+    return {key: output[key] for key in UNIVERSAL_OUTPUT_FIELDS if key in output}
+
+
+def adapt_output(output: dict[str, Any], event: str) -> dict[str, Any]:
+    """Convert a legacy hook result to the strict Codex event output schema."""
+    if not isinstance(output, dict):
+        return {}
+    result = _universal(output)
+    hook_specific = output.get("hookSpecificOutput")
+    hook_specific = dict(hook_specific) if isinstance(hook_specific, dict) else None
+
+    if event == "PreToolUse":
+        if hook_specific:
+            decision = hook_specific.get("permissionDecision")
+            reason = hook_specific.get("permissionDecisionReason")
+            if decision == "ask":
+                if reason:
+                    result["systemMessage"] = str(reason)
+                additional = hook_specific.get("additionalContext")
+                if additional:
+                    result["systemMessage"] = "\n".join(
+                        part for part in [result.get("systemMessage"), str(additional)] if part
+                    )
+                return result
+            allowed = {
+                "hookEventName": "PreToolUse",
+                **{key: value for key, value in hook_specific.items() if key in {
+                    "permissionDecision", "permissionDecisionReason", "updatedInput", "additionalContext"
+                }},
+            }
+            result["hookSpecificOutput"] = allowed
+        if output.get("decision") in {"block"}:
+            result["decision"] = "block"
+            if output.get("reason"):
+                result["reason"] = output["reason"]
+        return result
+
+    if event == "PermissionRequest":
+        if hook_specific and hook_specific.get("permissionDecision") in {"allow", "deny"}:
+            result["hookSpecificOutput"] = {
+                "hookEventName": "PermissionRequest",
+                "decision": {
+                    "behavior": hook_specific["permissionDecision"],
+                    "message": hook_specific.get("permissionDecisionReason"),
+                },
+            }
+        return result
+
+    if event == "PostToolUse":
+        if output.get("decision") == "block":
+            result["decision"] = "block"
+            result["reason"] = str(output.get("reason") or "Ultra post-edit gate blocked continuation")
+        if hook_specific and hook_specific.get("additionalContext"):
+            result["hookSpecificOutput"] = {
+                "hookEventName": "PostToolUse",
+                "additionalContext": hook_specific["additionalContext"],
+            }
+        return result
+
+    if event == "SessionStart":
+        if hook_specific and hook_specific.get("additionalContext"):
+            result["hookSpecificOutput"] = {
+                "hookEventName": "SessionStart",
+                "additionalContext": hook_specific["additionalContext"],
+            }
+        return result
+
+    if event == "SubagentStart":
+        if hook_specific and hook_specific.get("additionalContext"):
+            result["hookSpecificOutput"] = {
+                "hookEventName": "SubagentStart",
+                "additionalContext": hook_specific["additionalContext"],
+            }
+        return result
+
+    if event == "UserPromptSubmit":
+        if output.get("decision") == "block":
+            result["decision"] = "block"
+            result["reason"] = str(output.get("reason") or "Ultra prompt gate blocked submission")
+        if hook_specific and hook_specific.get("additionalContext"):
+            result["hookSpecificOutput"] = {
+                "hookEventName": "UserPromptSubmit",
+                "additionalContext": hook_specific["additionalContext"],
+            }
+        return result
+
+    if event == "Stop":
+        if output.get("decision") == "block":
+            result["decision"] = "block"
+            result["reason"] = str(output.get("reason") or "Ultra completion gate blocked stop")
+        return result
+
+    if event in {"PreCompact", "PostCompact", "SubagentStop"}:
+        extra = output.get("additionalContext")
+        if not extra and hook_specific:
+            extra = hook_specific.get("additionalContext")
+        if extra:
+            result["systemMessage"] = str(extra)
+        return result
+
+    return result
+
+
+def _parse_output(stdout: str) -> dict[str, Any]:
+    text = stdout.strip()
+    if not text:
+        return {}
+    try:
+        value = json.loads(text)
+    except json.JSONDecodeError:
+        return {"systemMessage": f"Ultra hook returned non-JSON output: {text[:500]}"}
+    return value if isinstance(value, dict) else {}
+
+
+def _merge_outputs(outputs: list[dict[str, Any]], event: str) -> dict[str, Any]:
+    if not outputs:
+        return {}
+    if len(outputs) == 1:
+        return outputs[0]
+
+    messages = [str(item.get("systemMessage")) for item in outputs if item.get("systemMessage")]
+    contexts: list[str] = []
+    blocking: dict[str, Any] | None = None
+    for item in outputs:
+        if item.get("decision") == "block":
+            blocking = item
+            break
+        specific = item.get("hookSpecificOutput")
+        if isinstance(specific, dict) and specific.get("permissionDecision") == "deny":
+            blocking = item
+            break
+        if isinstance(specific, dict) and specific.get("additionalContext"):
+            contexts.append(str(specific["additionalContext"]))
+
+    result = dict(blocking or {})
+    if messages:
+        result["systemMessage"] = "\n\n".join(messages)
+    if contexts and not blocking and event in {"PostToolUse", "SessionStart", "SubagentStart", "UserPromptSubmit"}:
+        result["hookSpecificOutput"] = {
+            "hookEventName": event,
+            "additionalContext": "\n\n".join(contexts),
+        }
+    return result
+
+
+def run_feature(feature: str, payload: dict[str, Any], feature_args: list[str]) -> dict[str, Any]:
+    if feature not in ALLOWED_FEATURES or Path(feature).name != feature:
+        return {"systemMessage": f"Ultra hook adapter refused unknown feature: {feature}"}
+    script = HOOK_ROOT / feature
+    if not script.is_file():
+        return {"systemMessage": f"Ultra hook feature is missing: {feature}"}
+
+    event = str(payload.get("hook_event_name") or "")
+    if feature == "workflow_resume.py" and event == "PostCompact":
+        payload = dict(payload)
+        payload["hook_event_name"] = "SessionStart"
+        payload["source"] = "compact"
+
+    env = os.environ.copy()
+    env["UBP_HOOK_RUNTIME"] = "codex"
+    plugin_data = env.get("PLUGIN_DATA") or env.get("CLAUDE_PLUGIN_DATA")
+    if plugin_data:
+        env["UBP_HOOK_DATA"] = plugin_data
+
+    cwd = payload.get("cwd")
+    run_cwd = str(cwd) if isinstance(cwd, str) and Path(cwd).is_dir() else os.getcwd()
+    outputs: list[dict[str, Any]] = []
+    for normalized in normalize_inputs(payload):
+        proc = subprocess.run(
+            [sys.executable, str(script), *feature_args],
+            input=json.dumps(normalized),
+            text=True,
+            capture_output=True,
+            cwd=run_cwd,
+            env=env,
+            timeout=30,
+            check=False,
+        )
+        if proc.stderr:
+            print(proc.stderr.rstrip(), file=sys.stderr)
+        if proc.returncode != 0:
+            outputs.append({
+                "systemMessage": f"Ultra hook {feature} failed with exit {proc.returncode}: {proc.stderr.strip()[:500]}"
+            })
+            continue
+        outputs.append(adapt_output(_parse_output(proc.stdout), event))
+    return _merge_outputs(outputs, event)
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print(json.dumps({"systemMessage": "Ultra Codex hook adapter requires a feature name"}))
+        return 0
+    feature = sys.argv[1]
+    feature_args = sys.argv[2:]
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+        if not isinstance(payload, dict):
+            payload = {}
+    except json.JSONDecodeError as exc:
+        print(json.dumps({"systemMessage": f"Ultra hook input parse error: {exc}"}))
+        return 0
+    try:
+        output = run_feature(feature, payload, feature_args)
+    except subprocess.TimeoutExpired:
+        output = {"systemMessage": f"Ultra hook {feature} timed out"}
+    except Exception as exc:  # adapter boundary must fail open with evidence
+        output = {"systemMessage": f"Ultra hook adapter error in {feature}: {exc}"}
+    print(json.dumps(output, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/health_check.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Advisory health check for an active Ultra workflow.
+
+No memory, prompt, transcript, or generic host policy is inspected here.
+"""
+
+import json
+import sqlite3
+import sys
+from pathlib import Path
+
+TERMINAL = {"committed", "completed", "done", "cancelled"}
+REQUIRED_TABLES = {"tasks", "events", "sessions", "schema_version"}
+
+
+def main():
+    try:
+        raw = sys.stdin.read()
+        data = json.loads(raw) if raw.strip() else {}
+    except (json.JSONDecodeError, OSError) as exc:
+        print(f"[health_check] invalid hook input: {exc}", file=sys.stderr)
+        data = {}
+    start = Path(data.get("cwd") or Path.cwd()).resolve()
+    root = None
+    state = None
+    for candidate in (start, *start.parents):
+        state_file = candidate / ".ultra" / "workflow-state.json"
+        if state_file.is_file():
+            try:
+                value = json.loads(state_file.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError) as exc:
+                print(f"[health_check] cannot read {state_file}: {exc}", file=sys.stderr)
+                value = None
+            if isinstance(value, dict) and value.get("status") not in TERMINAL:
+                root, state = candidate, value
+            break
+    if root is None or state is None:
+        print(json.dumps({}))
+        return
+    issues = []
+    db_path = root / ".ultra" / "state.db"
+    if not db_path.is_file():
+        issues.append(".ultra/state.db is missing")
+    else:
+        try:
+            with sqlite3.connect(str(db_path), timeout=1) as conn:
+                tables = {row[0] for row in conn.execute(
+                    "SELECT name FROM sqlite_master WHERE type='table'"
+                )}
+            missing = sorted(REQUIRED_TABLES - tables)
+            if missing:
+                issues.append(f"state.db missing tables: {', '.join(missing)}")
+        except sqlite3.Error as exc:
+            issues.append(f"state.db unreadable: {exc}")
+    if issues:
+        print("[Ultra health] " + "; ".join(issues), file=sys.stderr)
+    print(json.dumps({}))
+
+
+if __name__ == "__main__":
+    main()

package/hooks/pre_stop_check.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Block stop only when the active Ultra workflow itself is incomplete."""
+
+import sys
+import json
+from pathlib import Path
+
+TERMINAL = {"committed", "completed", "done", "cancelled"}
+
+
+def allow_stop() -> None:
+    print(json.dumps({}))
+
+
+def block_stop(reason: str) -> None:
+    print(json.dumps({"decision": "block", "reason": reason}))
+
+
+def main():
+    try:
+        hook_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, OSError) as exc:
+        print(f"[pre_stop_check] invalid hook input: {exc}", file=sys.stderr)
+        allow_stop()
+        return
+
+    if hook_data.get("stop_hook_active", False):
+        allow_stop()
+        return
+    start = Path(hook_data.get("cwd") or Path.cwd()).resolve()
+    for root in (start, *start.parents):
+        state_file = root / ".ultra" / "workflow-state.json"
+        if not state_file.is_file():
+            continue
+        try:
+            state = json.loads(state_file.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            print(f"[pre_stop_check] cannot read {state_file}: {exc}", file=sys.stderr)
+            allow_stop()
+            return
+        if not isinstance(state, dict) or state.get("status") in TERMINAL:
+            allow_stop()
+            return
+        block_stop(
+            "Active Ultra workflow is incomplete: "
+            f"command={state.get('command', 'unknown')}, "
+            f"task={state.get('task_id', state.get('task', 'unknown'))}, "
+            f"step={state.get('step', 'unknown')}, status={state.get('status', 'active')}. "
+            "Complete or explicitly cancel the Ultra workflow before stopping."
+        )
+        return
+    allow_stop()
+
+
+if __name__ == '__main__':
+    main()

package/hooks/subagent_tracker.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Subagent lifecycle tracker.
+
+Logs SubagentStart/Stop events to .ultra/debug/subagent-log.jsonl (project-level)
+for debugging and cost analysis.
+
+Protocol fields:
+  SubagentStart: agent_id, agent_type, session_id
+  SubagentStop: agent_id, agent_type, session_id, agent_transcript_path,
+                last_assistant_message, stop_hook_active
+
+Usage:
+  python3 subagent_tracker.py start  # called by SubagentStart hook
+  python3 subagent_tracker.py stop   # called by SubagentStop hook
+"""
+
+import json
+import os
+import random
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+TERMINAL = {"committed", "completed", "done", "cancelled"}
+MAX_LOG_LINES = 5000
+
+
+def get_log_dir(hook_input: dict):
+    start = Path(hook_input.get("cwd") or Path.cwd()).resolve()
+    for root in (start, *start.parents):
+        state_file = root / ".ultra" / "workflow-state.json"
+        if not state_file.is_file():
+            continue
+        try:
+            state = json.loads(state_file.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            print(f"[subagent_tracker] cannot read {state_file}: {exc}", file=sys.stderr)
+            return None
+        if isinstance(state, dict) and state.get("status") not in TERMINAL:
+            return root / ".ultra" / "runtime"
+        return None
+    return None
+
+
+def rotate_log(log_file: Path) -> None:
+    """Keep last MAX_LOG_LINES entries to prevent unbounded growth."""
+    try:
+        if not log_file.exists():
+            return
+        with open(log_file, "r", encoding="utf-8") as f:
+            lines = f.readlines()
+        if len(lines) <= MAX_LOG_LINES:
+            return
+        with open(log_file, "w", encoding="utf-8") as f:
+            f.writelines(lines[-MAX_LOG_LINES:])
+    except OSError as exc:
+        print(f"[subagent_tracker] log rotation failed: {exc}", file=sys.stderr)
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(json.dumps({}))
+        return
+
+    action = sys.argv[1]
+    if action not in ("start", "stop"):
+        print(json.dumps({}))
+        return
+
+    # Read hook input from stdin
+    try:
+        raw = sys.stdin.read()
+        hook_input = json.loads(raw) if raw.strip() else {}
+        if not isinstance(hook_input, dict):
+            hook_input = {}
+    except (json.JSONDecodeError, EOFError) as exc:
+        print(f"[subagent_tracker] invalid hook input: {exc}", file=sys.stderr)
+        hook_input = {}
+
+    # Lazy init: avoid module-level subprocess
+    log_dir = get_log_dir(hook_input)
+    if log_dir is None:
+        print(json.dumps({}))
+        return
+    log_file = log_dir / "subagent-log.jsonl"
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    entry = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "event": f"subagent_{action}",
+        "agent_id": hook_input.get("agent_id", "unknown"),
+        "agent_type": hook_input.get("agent_type", "unknown"),
+        "session_id": hook_input.get("session_id", ""),
+    }
+
+    # SubagentStop provides additional fields
+    if action == "stop":
+        transcript = hook_input.get("agent_transcript_path", "")
+        if transcript:
+            entry["agent_transcript_path"] = transcript
+
+    try:
+        with open(log_file, "a", encoding="utf-8") as f:
+            f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+    except OSError as exc:
+        print(f"[subagent_tracker] event write failed: {exc}", file=sys.stderr)
+
+    # Periodic log rotation (~1% of writes)
+    if random.random() < 0.01:
+        rotate_log(log_file)
+
+    print(json.dumps({}))
+
+
+if __name__ == "__main__":
+    main()

package/hooks/workflow_checkpoint.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Write a minimal, mechanical compaction checkpoint for an active workflow."""
+
+import json
+import os
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+TERMINAL = {"committed", "completed", "done", "cancelled"}
+
+
+def main() -> None:
+    try:
+        data = json.loads(sys.stdin.read() or "{}")
+        data = data if isinstance(data, dict) else {}
+    except json.JSONDecodeError as exc:
+        print(f"[workflow_checkpoint] invalid hook input: {exc}", file=sys.stderr)
+        data = {}
+    start = Path(data.get("cwd") or Path.cwd()).resolve()
+    for root in (start, *start.parents):
+        state_file = root / ".ultra" / "workflow-state.json"
+        if not state_file.is_file():
+            continue
+        try:
+            state = json.loads(state_file.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            print(f"[workflow_checkpoint] cannot read {state_file}: {exc}", file=sys.stderr)
+            break
+        if not isinstance(state, dict) or state.get("status") in TERMINAL:
+            break
+        runtime_dir = root / ".ultra" / "runtime"
+        runtime_dir.mkdir(parents=True, exist_ok=True)
+        checkpoint = {
+            "schema": 1,
+            "captured_at": datetime.now(timezone.utc).isoformat(),
+            "session_id": data.get("session_id", ""),
+            "workflow": state,
+        }
+        fd, temp_name = tempfile.mkstemp(prefix="checkpoint.", suffix=".json", dir=runtime_dir)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                json.dump(checkpoint, handle, ensure_ascii=False, indent=2)
+                handle.write("\n")
+            os.replace(temp_name, runtime_dir / "checkpoint.json")
+        finally:
+            if os.path.exists(temp_name):
+                os.unlink(temp_name)
+        print(json.dumps({"systemMessage": "Ultra workflow checkpoint saved."}))
+        return
+    print(json.dumps({}))
+
+
+if __name__ == "__main__":
+    main()

package/hooks/workflow_context.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""Inject the live Ultra workflow state at session start.
+
+This hook is deliberately project-local and contains no cross-session memory.
+It is a no-op unless an active .ultra/workflow-state.json exists.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+TERMINAL = {"committed", "completed", "done", "cancelled"}
+
+
+def payload() -> dict:
+    try:
+        value = json.loads(sys.stdin.read() or "{}")
+        return value if isinstance(value, dict) else {}
+    except json.JSONDecodeError as exc:
+        print(f"[workflow_context] invalid hook input: {exc}", file=sys.stderr)
+        return {}
+
+
+def active_state(data: dict):
+    start = Path(data.get("cwd") or Path.cwd()).resolve()
+    for root in (start, *start.parents):
+        state_file = root / ".ultra" / "workflow-state.json"
+        if not state_file.is_file():
+            continue
+        try:
+            state = json.loads(state_file.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            print(f"[workflow_context] cannot read {state_file}: {exc}", file=sys.stderr)
+            return None
+        if isinstance(state, dict) and state.get("status") not in TERMINAL:
+            return root, state
+        return None
+    return None
+
+
+def main() -> None:
+    found = active_state(payload())
+    if not found:
+        print(json.dumps({}))
+        return
+    root, state = found
+    context = "\n".join([
+        "[Ultra active workflow]",
+        f"Project: {root}",
+        f"Command: {state.get('command', 'unknown')}",
+        f"Task: {state.get('task_id', state.get('task', 'unknown'))}",
+        f"Step: {state.get('step', 'unknown')}",
+        f"Status: {state.get('status', 'active')}",
+        "Authority: .ultra/state.db; workflow recovery: .ultra/workflow-state.json.",
+    ])
+    print(json.dumps({"hookSpecificOutput": {
+        "hookEventName": "SessionStart",
+        "additionalContext": context,
+    }}))
+
+
+if __name__ == "__main__":
+    main()