loopx 0.4.8__py3-none-any.whl

loopx/claude_goal_mode/scripts/goalmode_cmd.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+"""Smart entry for the `/loopx` slash command — the loopx setup helper.
+
+LoopX does NOT own the run loop on Claude Code. Claude Code's native `/loop` is
+the scheduler/executor; loopx provides the control-plane protocol (the MCP tools
++ a per-iteration `.claude/loop.md`). `/loopx` just sets a goal up and hands off
+to `/loop`.
+
+Routing by first token:
+  <free text task>  -> ONE-SHOT: ensure a goal exists for this project (bootstrap
+                       if needed), register a default agent, add the task as a
+                       todo, write `.claude/loop.md` (the protocol), and do one
+                       bounded first segment. Then drive it with native `/loop`.
+  (no args) / on    -> (re)write `.claude/loop.md` for this project's existing
+                       goal and show how to drive it with `/loop`.
+  status            -> the project's goal detail (objective, state, next, todos).
+  off               -> remove `.claude/loop.md` (native `/loop` then has nothing
+                       to run). Registry/goal are left intact.
+
+The LoopX registry (`.loopx/registry.json`) is the single source of truth for
+goal_id/agent/scope. The default agent `cc` is registered so the loopx identity
+contract is active and `quota should-run --agent-id cc` is satisfied.
+"""
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+DEFAULT_AGENT = "cc"
+
+# registry-driven context, shared with the hooks/MCP
+sys.path.insert(0, str(HERE.parent / "hooks"))
+from goal_state import goal_context, find_registry, loop_md_path  # noqa: E402
+
+
+def gh_prefix():
+    """Cross-platform loopx invocation: the CLI shim if on PATH, else the module."""
+    exe = shutil.which("loopx")
+    return [exe] if exe else [sys.executable, "-m", "loopx.cli"]
+
+
+def gh(args, cwd=None):
+    return subprocess.run(gh_prefix() + args, cwd=cwd, capture_output=True, text=True, timeout=120)
+
+
+def slug(name: str) -> str:
+    s = re.sub(r"[^a-zA-Z0-9]+", "-", name).strip("-").lower() or "project"
+    return f"cc-{s}"[:48]
+
+
+def loop_md_content(goal_id, agent_id) -> str:
+    """The per-iteration protocol that native `/loop` runs (written to
+    .claude/loop.md). loopx's should_run is the deterministic per-tick gate; the
+    agent uses the wired loopx MCP tools, never raw CLI guessing.
+
+    The leading `loopx:armed` marker persists WHICH goal /loopx armed for this
+    project, so goal_state.goal_context() resolves the right goal in multi-goal
+    registries instead of guessing from registry order."""
+    armed = json.dumps({"goal_id": goal_id, "agent_id": agent_id})
+    return (
+        f"<!-- loopx:armed {armed} -->\n"
+        f"loopx tick — advance goal `{goal_id}` (agent `{agent_id}`). Use the wired loopx MCP\n"
+        f"tools; do NOT run `loopx --help` or guess ids.\n\n"
+        f"1. Call `should_run()`. If should_run=false, say why in ONE line and STOP this\n"
+        f"   iteration (do nothing else) — loopx has paused, gated, or converged.\n"
+        f"2. If should_run=true: `claim_task` the next open todo, do ONE bounded segment,\n"
+        f"   then VERIFY it with a real check (build/test) — never claim success from\n"
+        f"   reasoning — and `complete_task(..., agent_id=\"{agent_id}\", evidence=\"<ran + result>\")`.\n"
+        f"3. Stay within the goal's scope; do not start initiatives outside the todos.\n"
+        f"   Irreversible actions (push/delete) only to finish work already authorized.\n"
+        f"4. Re-check `should_run()`; stop when should_run=false or no open todos remain.\n"
+    )
+
+
+def write_loop_md(proj: Path, goal_id, agent_id) -> Path:
+    """Write the protocol to <project>/.claude/loop.md (bare `/loop` runs it)."""
+    path = loop_md_path(proj)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(loop_md_content(goal_id, agent_id), encoding="utf-8")
+    return path
+
+
+def goal_detail(ctx):
+    """Objective (from the registry goal entry's active-state file) + live state
+    (from quota should-run) for the `/loopx status` detail view."""
+    gid, reg, agent = ctx.get("goal_id"), ctx.get("registry"), ctx.get("agent_id")
+    objective = ""
+    if reg:
+        try:
+            regp = Path(reg)
+            data = json.loads(regp.read_text(encoding="utf-8"))
+            entry = next((g for g in data.get("goals", []) if g.get("id") == gid), None)
+            sf = (entry or {}).get("state_file")
+            if sf:
+                text = (regp.parent.parent / sf).read_text(encoding="utf-8")
+                m = re.search(r"^objective:\s*(.+)$", text, re.MULTILINE)
+                if m:
+                    objective = m.group(1).strip().strip('"').strip("'")
+        except Exception:
+            pass
+    payload = {}
+    try:
+        cmd = gh_prefix() + (["--registry", reg] if reg else []) + \
+            ["--format", "json", "quota", "should-run", "--goal-id", gid]
+        if agent:
+            cmd += ["--agent-id", agent]
+        out = subprocess.run(cmd, capture_output=True, text=True, timeout=15)
+        payload = json.loads(out.stdout or "{}")
+    except Exception:
+        pass
+    return objective, payload
+
+
+def print_status(ctx):
+    gid = ctx.get("goal_id")
+    objective, d = goal_detail(ctx)
+    a = d.get("agent_todo_summary") or {}
+    done, open_ = a.get("done_count"), a.get("open_count")
+    gate = d.get("gate_prompt")
+    if gate:
+        state = f"⚠ needs you: {gate}"
+    elif d.get("should_run") is True:
+        state = "▶ running"
+    else:
+        state = f"⏸ {d.get('state') or 'paused'}" + (f" — {d['reason']}" if d.get("reason") else "")
+    print(f"goal      : {gid}")
+    print(f"agent     : {ctx.get('agent_id') or DEFAULT_AGENT}")
+    if objective:
+        print(f"objective : {objective}")
+    print(f"state     : {state}")
+    if d.get("recommended_action"):
+        print(f"next      : {d['recommended_action']}")
+    if done is not None or open_ is not None:
+        print(f"todos     : {done} done / {open_} open")
+    for it in (a.get("first_open_items") or [])[:8]:
+        t = (it.get("text") or "").strip()
+        if t:
+            print(f"   ▸ {t}")
+    armed = "armed (.claude/loop.md present)" if loop_md_path(Path.cwd()).exists() else "not armed (run /loopx to arm)"
+    print(f"loop      : {armed} — drive with native /loop")
+
+
+def main():
+    args = sys.argv[1:]
+    first = args[0] if args else None
+    proj = Path.cwd()
+
+    # off: remove the loop protocol; native /loop then has nothing to run.
+    if first == "off":
+        lp = loop_md_path(proj)
+        if not lp.exists():
+            print("goal-mode OFF (no .claude/loop.md here).")
+            return
+        try:
+            lp.unlink()
+            print("goal-mode OFF — removed .claude/loop.md. (Press Esc to stop a running /loop.)")
+        except OSError as e:
+            print(f"goal-mode OFF — could not remove {lp} ({e}); remove it manually.")
+        return
+
+    # status: full goal detail.
+    if first == "status":
+        ctx = goal_context(proj)
+        if not ctx:
+            print("loopx goal-mode: no goal in this project yet — run `/loopx <task>` to create one.")
+            return
+        print_status(ctx)
+        return
+
+    # bare (=on) / on: (re)arm THIS project's existing goal and show how to drive it.
+    if not args or first == "on":
+        ctx = goal_context(proj)
+        if not ctx or not ctx.get("goal_id"):
+            print("loopx goal-mode: ready — no goal set in this project yet.")
+            print("Tell me what to work on and I'll set it up:")
+            print("    /loopx <your goal>   e.g.  /loopx 写一个 RTL 模块并跑通仿真")
+            return
+        write_loop_md(proj, ctx["goal_id"], ctx.get("agent_id") or DEFAULT_AGENT)
+        print(f"goal-mode armed  goal={ctx['goal_id']}  agent={ctx.get('agent_id') or DEFAULT_AGENT}")
+        print("Drive it with native /loop:  `/loop` (Claude self-paces)  |  `/loop 10m` (fixed).")
+        print("Stop with Esc; `/loopx off` removes the loop protocol.")
+        return
+
+    # free-text task -> one-shot setup + write loop.md + first bounded segment.
+    task = " ".join(args).strip().strip('"').strip("'")
+    reg = find_registry(proj)
+    if reg is not None:
+        ctx = goal_context(proj) or {}
+        goal_id = ctx.get("goal_id")
+        registry = str(reg)
+    else:
+        goal_id = slug(proj.name)
+        registry = str(proj / ".loopx" / "registry.json")
+        # Claude projects keep goal state under .claude/ (not the Codex-default .codex/)
+        state_file = f".claude/goals/{goal_id}/ACTIVE_GOAL_STATE.md"
+        r = gh(["bootstrap", "--project", str(proj), "--goal-id", goal_id,
+                "--objective", task, "--state-file", state_file, "--no-onboarding-scan"])
+        if "ok: `True`" not in r.stdout and "ok=True" not in r.stdout and r.returncode != 0:
+            print("[loopx] bootstrap failed:\n" + (r.stdout + r.stderr)[:600])
+            sys.exit(1)
+
+    if not goal_id:
+        print("[loopx] could not determine goal id")
+        sys.exit(1)
+
+    # register the default agent (identity contract) and add the task as a todo
+    gh(["--registry", registry, "configure-goal", "--goal-id", goal_id,
+        "--agent-model", "peer_v1", "--registered-agent", DEFAULT_AGENT, "--execute"])
+    add = gh(["--registry", registry, "--format", "json", "todo", "add",
+              "--goal-id", goal_id, "--role", "agent", "--text", task])
+    todo_id = ""
+    try:
+        todo_id = json.loads(add.stdout).get("todo_id", "")
+    except Exception:
+        pass
+
+    # write the per-iteration protocol; the RUN happens when the user types /loop
+    # (this command only SETS UP the goal — it must not do the work itself).
+    write_loop_md(proj, goal_id, DEFAULT_AGENT)
+
+    tid = todo_id or "(see should_run output)"
+    print("goal set up. loopx is the control plane; Claude Code's native /loop is the runtime.")
+    print(f"  goal_id : {goal_id}")
+    print(f"  agent   : {DEFAULT_AGENT}")
+    print(f"  todo_id : {tid}")
+    print(f"  scope   : {proj}")
+    print(f"  task    : {task}")
+    print(f"  wrote   : .claude/loop.md  (the per-tick protocol)")
+    print()
+    print("START WORKING — run native `/loop`  (Claude self-paces)  or  `/loop 10m`  (fixed cadence).")
+    print("Each /loop tick runs: should_run -> claim_task -> ONE bounded verified segment -> complete_task.")
+    print("Stop with Esc or `/loopx off`.")
+
+
+if __name__ == "__main__":
+    main()

loopx/claude_goal_mode/scripts/install.py

@@ -0,0 +1,328 @@
+#!/usr/bin/env python3
+"""Install the loopx Claude Code adapter — EXPLICIT, scoped, opt-in.
+
+This is NOT run by the default loopx installer. It is invoked deliberately
+(`LOOPX_INSTALL_CLAUDE=1 scripts/install-local.sh`, or directly). It installs the
+minimum: the loopx **MCP server** (the control-plane tools) + the **`/loopx`**
+slash command. The run loop is Claude Code's native `/loop`; loopx only provides
+the `should_run` protocol, so NO global hooks are wired by default.
+
+  python install.py --scope project [--project DIR]   # this project only (preferred)
+  python install.py --scope user                      # all your Claude Code projects
+  python install.py --scope ... --harden              # ALSO add the optional
+                                                       # PreToolUse should_run gate
+                                                       # + statusline at that scope
+
+`--scope` is required (a deliberate choice). User scope is announced loudly. We
+NEVER delete existing permission rules; legacy loopx entries get a printed
+cleanup suggestion instead.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+PLUGIN_ROOT = Path(__file__).resolve().parents[1]
+MCP_VENV = Path.home() / ".local" / "share" / "loopx" / "mcp-venv"
+
+
+def _p(*parts) -> str:
+    return str(PLUGIN_ROOT.joinpath(*parts)).replace("\\", "/")
+
+
+def _python_cmd() -> str:
+    """Interpreter to bake into hook / statusline / command strings — robust where
+    only `python` (not `python3`) is registered."""
+    return shutil.which("python3") or shutil.which("python") or sys.executable
+
+
+def deep_merge(base: dict, add: dict) -> dict:
+    for k, v in add.items():
+        if isinstance(v, dict) and isinstance(base.get(k), dict):
+            deep_merge(base[k], v)
+        elif isinstance(v, list) and isinstance(base.get(k), list):
+            base[k] += [x for x in v if x not in base[k]]
+        else:
+            base[k] = v
+    return base
+
+
+# ---- optional hardening (only with --harden) --------------------------------
+
+def hardening_block() -> dict:
+    """The OPTIONAL per-tool gate + statusline. Not installed unless --harden."""
+    py = _python_cmd()
+    return {
+        "hooks": {
+            "PreToolUse": [{"matcher": "*", "hooks": [
+                {"type": "command", "command": f'{py} "{_p("hooks", "goal_policy.py")}"', "timeout": 10}]}],
+        },
+        "statusLine": {"type": "command", "command": f'{py} "{_p("statusline", "goal_status.py")}"'},
+    }
+
+
+# ---- MCP dependency provisioning --------------------------------------------
+
+def _venv_python(venv: Path) -> Path:
+    sub = "Scripts" if sys.platform == "win32" else "bin"
+    exe = "python.exe" if sys.platform == "win32" else "python"
+    return venv / sub / exe
+
+
+# The server imports `mcp.server.fastmcp`, which MCP SDK 2.x no longer ships.
+# Checking a bare `import mcp` accepts an interpreter that cannot actually run
+# the server, so registration would write a config that fails to start —
+# `cursor-agent mcp list` reports "Connection failed" and Claude silently drops
+# the tools. Probe the module the server really needs.
+MCP_PROBE = "import mcp.server.fastmcp"
+# Upper bound for the same reason; drop it once loopx_mcp.py speaks the 2.x API.
+MCP_REQUIREMENT = "mcp<2"
+
+
+def _has_mcp(py) -> bool:
+    try:
+        return subprocess.run([str(py), "-c", MCP_PROBE], capture_output=True).returncode == 0
+    except (FileNotFoundError, OSError):
+        return False
+
+
+def provision_mcp_python(dry: bool, allow_system_pip: bool = False) -> str:
+    """Return an interpreter that can `import mcp`, installing it into a dedicated
+    venv if needed (works under PEP 668 externally-managed pythons).
+
+    We install `mcp` ONLY into a dedicated venv we own. We never silently mutate
+    the user's active/system interpreter (`pip install --break-system-packages`);
+    that is gated behind an explicit ``allow_system_pip`` opt-in."""
+    if _has_mcp(sys.executable):
+        print(f"[deps] mcp already importable by {sys.executable}")
+        return sys.executable
+    vpy = _venv_python(MCP_VENV)
+    if _has_mcp(vpy):
+        print(f"[deps] reusing mcp venv {MCP_VENV}")
+        return str(vpy)
+    if dry:
+        print(f"[deps] (dry-run) would create venv {MCP_VENV} and pip install mcp")
+        return str(vpy)
+    print(f"[deps] creating mcp venv {MCP_VENV} …")
+    MCP_VENV.parent.mkdir(parents=True, exist_ok=True)
+    r = subprocess.run([sys.executable, "-m", "venv", str(MCP_VENV)], capture_output=True, text=True)
+    if r.returncode == 0:
+        subprocess.run([str(vpy), "-m", "pip", "install", "-q", "--upgrade", "pip"], capture_output=True, text=True)
+        pip = subprocess.run([str(vpy), "-m", "pip", "install", "-q", MCP_REQUIREMENT], capture_output=True, text=True)
+        if pip.returncode == 0 and _has_mcp(vpy):
+            print(f"[deps] mcp installed into {MCP_VENV}")
+            return str(vpy)
+        print("[deps] venv pip install failed:\n" + (pip.stdout + pip.stderr)[:300])
+    else:
+        print("[deps] venv creation failed:\n" + (r.stdout + r.stderr)[:300])
+    # The dedicated venv is the only place we install `mcp`. Do NOT touch the
+    # user's active/system interpreter unless they explicitly opted in.
+    if allow_system_pip:
+        print("[deps] --allow-system-pip: pip install --break-system-packages mcp")
+        subprocess.run([sys.executable, "-m", "pip", "install", "-q", "--break-system-packages", MCP_REQUIREMENT],
+                       capture_output=True, text=True)
+        if _has_mcp(sys.executable):
+            return sys.executable
+    print("[deps] WARNING: could not provision `mcp` into a dedicated venv, and we will\n"
+          "       NOT modify your system Python. The loopx MCP tools will not load until\n"
+          "       you install `mcp` yourself, e.g.:\n"
+          f"       {sys.executable} -m venv {MCP_VENV} && {vpy} -m pip install '{MCP_REQUIREMENT}'\n"
+          "       (or re-run install.py with --allow-system-pip to use the active interpreter).")
+    return _python_cmd()
+
+
+def install_mcp(
+    dry: bool,
+    py: str,
+    scope: str,
+    migrate_goal_harness: bool = False,
+    project_dir: Path | None = None,
+):
+    """Register the loopx MCP server at the chosen scope via `claude mcp add`.
+
+    We replace only OUR `loopx` entry. A legacy/user-owned `goal-harness` MCP is
+    left untouched by default — we don't delete a server we don't own. If one
+    exists we print a manual cleanup hint; `--migrate-goal-harness` removes it."""
+    if scope == "project" and project_dir is None:
+        raise ValueError("project_dir is required for project-scoped MCP registration")
+    cwd_run = str(project_dir) if scope == "project" else None
+    claude = shutil.which("claude")
+    mcp_path = _p("mcp", "loopx_mcp.py")
+    add = ["mcp", "add", "--scope", scope, "loopx", "--", py, mcp_path]
+    if not claude:
+        print("[mcp] claude CLI not on PATH — add the MCP server manually:\n   claude " + " ".join(add))
+        return
+    print(f"[mcp] claude mcp add --scope {scope} loopx -- {py} <loopx_mcp.py>")
+    if dry:
+        return
+    subprocess.run(
+        [claude, "mcp", "remove", "--scope", scope, "loopx"],
+        capture_output=True,
+        text=True,
+        cwd=cwd_run,
+    )
+    has_gh = subprocess.run(
+        [claude, "mcp", "get", "goal-harness"],
+        capture_output=True,
+        text=True,
+        cwd=cwd_run,
+    ).returncode == 0
+    if has_gh:
+        if migrate_goal_harness:
+            print(f"[mcp] --migrate-goal-harness: removing legacy goal-harness MCP at {scope} scope")
+            subprocess.run(
+                [claude, "mcp", "remove", "--scope", scope, "goal-harness"],
+                capture_output=True,
+                text=True,
+                cwd=cwd_run,
+            )
+        else:
+            print("[mcp] note: a legacy `goal-harness` MCP entry exists — left untouched. Remove it "
+                  f"yourself with `claude mcp remove --scope {scope} goal-harness`, or re-run with "
+                  "--migrate-goal-harness.")
+    r = subprocess.run(
+        [claude, *add],
+        capture_output=True,
+        text=True,
+        cwd=cwd_run,
+    )
+    if r.returncode != 0:
+        print("  (mcp add failed; add manually:\n   claude " + " ".join(add) + "\n  " + (r.stdout + r.stderr)[:200] + ")")
+
+
+# ---- /loopx command ----------------------------------------------------------
+
+def command_md() -> str:
+    entry = _p("scripts", "goalmode_cmd.py")
+    py = _python_cmd()
+    return (
+        "---\n"
+        "description: loopx goal-mode setup (NOT Claude Code's built-in /goal). "
+        "`/loopx <task>` sets up a goal + writes .claude/loop.md; drive the loop with native /loop. "
+        "bare /loopx = arm; off | status.\n"
+        "argument-hint: <task to do>  |  (no args = arm)  |  off  |  status\n"
+        f"allowed-tools: Bash({py}:*)\n"
+        "---\n\n"
+        "Run the loopx setup helper and read its output:\n\n"
+        f"!`{py} \"{entry}\" $ARGUMENTS`\n\n"
+        "The output is loopx control-plane SETUP / status info — it is the COMPLETE, user-facing "
+        "result. Show it to the user VERBATIM and STOP. Do NOT do any work, claim todos, write "
+        "files, or loop here: the WORK runs when the user types Claude Code's native `/loop` (which "
+        "executes `.claude/loop.md`). Do not summarize a multi-line `status` detail block into one line.\n\n"
+        "NOTE: this is `/loopx` (loopx control-plane SETUP), NOT a runtime and NOT Claude Code's "
+        "built-in `/goal`. The run loop is native `/loop`; loopx provides the deterministic "
+        "`should_run` protocol.\n"
+    )
+
+
+def install_command(dry: bool, cmd_dir: Path):
+    path = cmd_dir / "loopx.md"
+    print(f"[command] /loopx -> {path}")
+    if dry:
+        return
+    cmd_dir.mkdir(parents=True, exist_ok=True)
+    old = cmd_dir / "goalmode.md"  # migrate the legacy /goalmode entry name
+    if old.exists():
+        old.unlink()
+    path.write_text(command_md(), encoding="utf-8")
+
+
+def add_hardening(dry: bool, settings_path: Path):
+    """Deep-merge the optional hook + statusline into settings_path, preserving
+    existing config. NEVER deletes permission rules."""
+    cur = {}
+    if settings_path.exists():
+        try:
+            cur = json.loads(settings_path.read_text(encoding="utf-8"))
+        except Exception:
+            cur = {}
+    # prune prior loopx PreToolUse entries (avoid stacking on reinstall)
+    for grp in (cur.get("hooks", {}) or {}).get("PreToolUse", []) or []:
+        grp["hooks"] = [h for h in grp.get("hooks", []) if "goal_policy.py" not in str(h.get("command", ""))]
+    if isinstance(cur.get("hooks", {}).get("PreToolUse"), list):
+        cur["hooks"]["PreToolUse"] = [g for g in cur["hooks"]["PreToolUse"] if g.get("hooks")]
+    merged = deep_merge(cur, hardening_block())
+    print(f"[harden] PreToolUse should_run gate + statusline -> {settings_path}")
+    if not dry:
+        settings_path.parent.mkdir(parents=True, exist_ok=True)
+        settings_path.write_text(json.dumps(merged, indent=2), encoding="utf-8")
+
+
+def warn_legacy_perms(settings_path: Path):
+    """Detect a legacy loopx credential-deny and SUGGEST manual cleanup. Never mutate."""
+    try:
+        cur = json.loads(settings_path.read_text(encoding="utf-8"))
+    except Exception:
+        return
+    deny = ((cur.get("permissions") or {}).get("deny")) or []
+    legacy = [r for r in deny if r in ("Read(~/.ssh/**)", "Read(~/.aws/**)")]
+    if legacy:
+        print(f"[note] {settings_path} has loopx-era permission deny rules {legacy}. "
+              "We no longer add these and will NOT remove them automatically. "
+              "To drop them, edit that file's `permissions.deny` by hand.")
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--scope", choices=["user", "project"], required=True,
+                    help="user = ~/.claude (all projects); project = THIS project's .claude (preferred)")
+    ap.add_argument("--project", default=None, help="project dir for --scope project (default: cwd)")
+    ap.add_argument("--harden", action="store_true",
+                    help="ALSO install the optional PreToolUse should_run gate + statusline")
+    ap.add_argument("--skip-mcp", action="store_true",
+                    help="skip MCP venv provisioning + `claude mcp add` (for tests/CI)")
+    ap.add_argument("--allow-system-pip", action="store_true",
+                    help="if the dedicated mcp venv can't be built, fall back to "
+                         "`pip install --break-system-packages mcp` into the active interpreter "
+                         "(off by default — we don't mutate your system Python)")
+    ap.add_argument("--migrate-goal-harness", action="store_true",
+                    help="also remove a legacy `goal-harness` MCP entry at this scope "
+                         "(off by default — we don't delete MCP servers we don't own)")
+    ap.add_argument("--dry-run", action="store_true")
+    a = ap.parse_args()
+    dry = a.dry_run
+
+    project_dir = None
+    if a.scope == "project":
+        project_dir = Path(a.project).resolve() if a.project else Path.cwd()
+        claude_dir = project_dir / ".claude"
+        print(f"[scope] PROJECT — installs into {claude_dir} (this project only)")
+    else:
+        claude_dir = Path.home() / ".claude"
+        print("[scope] USER — installs into ~/.claude. The /loopx command and MCP become")
+        print("        available in ALL your Claude Code projects." +
+              ("  --harden adds USER-LEVEL, matcher-wide hooks too." if a.harden else ""))
+
+    if a.skip_mcp:
+        print("[mcp] skipped (--skip-mcp)")
+    else:
+        mcp_python = provision_mcp_python(dry, a.allow_system_pip)
+        install_mcp(
+            dry,
+            mcp_python,
+            a.scope,
+            a.migrate_goal_harness,
+            project_dir=project_dir,
+        )
+    install_command(dry, claude_dir / "commands")
+
+    settings_path = claude_dir / "settings.json"
+    if a.harden:
+        add_hardening(dry, settings_path)
+    else:
+        print("[harden] skipped (default): no hooks/statusline installed. Add later with --harden.")
+    warn_legacy_perms(settings_path)
+
+    print("\nloopx Claude adapter installed.")
+    print("Next: in a project with a goal, type `/loopx <task>`, then drive it with native `/loop`.")
+    print("Restart any open Claude Code session so the command/MCP load.")
+    if dry:
+        print("(dry-run: nothing written)")
+
+
+if __name__ == "__main__":
+    main()

loopx/claude_goal_mode/statusline/goal_status.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""Statusline segment: a glanceable loopx goal state for the Claude Code CLI.
+
+Claude Code feeds session JSON on stdin; we resolve THIS project's goal (only
+while goal-mode is armed) and run one quick `loopx quota should-run` probe, then
+render a single compact line. We surface the signals a watching user actually
+needs, in priority order:
+
+  1. ⚠ needs you   — an operator gate / open user todo is blocking (highest signal)
+  2. ▶ working      — should_run=true, plus the next concrete action loopx picked
+  3. ⏸ <state>      — paused/holding, plus the short reason (quota, gate, health…)
+
+…always tailed with todo progress (done✓/open▸). Prints nothing when there is no
+goal here or goal-mode is off.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+# Share the registry-driven resolver with the hooks so the statusline shows THIS
+# session's project goal, and only while goal-mode is armed (heartbeat installed).
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "hooks"))
+from goal_state import active_context
+
+
+import shutil as _shutil
+def _gh_prefix():
+    _exe = _shutil.which("loopx")
+    return [_exe] if _exe else [__import__("sys").executable, "-m", "loopx.cli"]
+
+
+def _clip(s, n: int) -> str:
+    s = " ".join(str(s or "").split())  # collapse whitespace/newlines
+    return s if len(s) <= n else s[: n - 1] + "…"
+
+
+def _render(gid: str, d: dict) -> str:
+    """Turn a `quota should-run` payload into one compact statusline string."""
+    agent = d.get("agent_todo_summary") or {}
+    done, open_ = agent.get("done_count"), agent.get("open_count")
+    prog = f"{done}✓/{open_}▸" if (done is not None or open_ is not None) else ""
+
+    ic = d.get("interaction_contract") or {}
+    user_ch = ic.get("user_channel") or {}
+    users = d.get("user_todo_summary") or {}
+    gate = d.get("gate_prompt")
+    needs_user = bool(gate) or bool(user_ch.get("action_required")) or bool(users.get("open_count"))
+
+    if needs_user:
+        msg = gate or f"{users.get('open_count') or 'a'} user todo(s) to answer"
+        return f"[loopx {gid} · ⚠ needs you: {_clip(msg, 46)}]"
+
+    if d.get("should_run") is True:
+        nxt = d.get("recommended_action")
+        head = f"▶ {prog}".rstrip() if prog else "▶ working"
+        return f"[loopx {gid} · {head}" + (f" · next: {_clip(nxt, 40)}]" if nxt else "]")
+
+    # paused / holding: lead with WHY (state + short reason), then progress
+    state = (d.get("state") or "paused").strip()
+    reason = d.get("reason")
+    tail = f" · {prog}" if prog else ""
+    return f"[loopx {gid} · ⏸ {state}" + (f": {_clip(reason, 38)}" if reason else "") + f"{tail}]"
+
+
+def main():
+    raw = sys.stdin.read()  # Claude's session json carries this session's cwd
+    cwd = None
+    try:
+        sess = json.loads(raw or "{}")
+        cwd = sess.get("cwd") or (sess.get("workspace") or {}).get("current_dir")
+    except Exception:
+        pass
+    st = active_context(cwd or Path.cwd())
+    if not st:
+        print("")  # no goal here, or goal-mode off -> no segment
+        return
+    gid = st.get("goal_id", "?")
+    try:
+        cmd = list(_gh_prefix())
+        if st.get("registry"):
+            cmd += ["--registry", st["registry"]]
+        cmd += ["--format", "json", "quota", "should-run", "--goal-id", gid]
+        if st.get("agent_id"):
+            cmd += ["--agent-id", st["agent_id"]]
+        out = subprocess.run(cmd, capture_output=True, text=True, timeout=8)
+        d = json.loads(out.stdout or "{}")
+        print(_render(gid, d))
+    except Exception:
+        # probe failed: still show that goal-mode is armed, without counts/state
+        print(f"[loopx {gid}]")
+
+
+if __name__ == "__main__":
+    main()