subcortex 0.3.0__py3-none-any.whl

subcortex/evalset.py

@@ -0,0 +1,241 @@
+"""Labeled examples for calibrating subcortex's questions and thresholds.
+
+A decision model's probability is not an accuracy: thresholds only mean
+something against labeled data, per backend and per question wording. These
+examples back ``subcortex eval`` and the calibration notes in docs/.
+
+PROMPTS: (prompt, simple) — simple = a lookup or a small, local edit.
+OUTPUTS: (task, tool call, output, needed) — needed = the output's middle holds
+details the task relies on. Failing commands are left out: subcortex never
+trims output that looks like a failure, whatever the model says.
+
+The questions and thresholds were chosen on PROMPTS/OUTPUTS. HELDOUT_* were
+written afterwards and never used for choosing anything — including requests
+that sound small but aren't ("fix the bug") and needed output that looks like
+noise — so they show whether a rule generalizes.
+"""
+
+from __future__ import annotations
+
+from typing import List, Tuple
+
+SIMPLE = [
+    "what is 2+2?",
+    "what does git rebase do?",
+    "fix the typo 'recieve' in README.md",
+    "rename the variable tmp to buffer in utils.py",
+    "what port does the dev server use?",
+    "show me the last commit message",
+    "is python's dict ordered?",
+    "add a newline at the end of main.go",
+    "what's the difference between let and const in JS?",
+    "bump the version in package.json to 1.4.2",
+    "run the tests",
+    "which node version does this repo need?",
+    "delete the unused import of os in cli.py",
+    "what does the -p flag do in mkdir?",
+    "change the default port from 8080 to 3000 in config.yaml",
+    "print the current git branch",
+    "add .DS_Store to .gitignore",
+    "how do I list docker containers?",
+    'make the error message in login.ts say "Invalid password" instead of "Error"',
+    "what license is this project under?",
+]
+
+COMPLEX = [
+    "implement OAuth login with Google and GitHub, including token refresh",
+    "refactor the parser into a visitor pattern across all modules",
+    "debug the intermittent race condition in the job scheduler",
+    "migrate the database schema to support multi-tenancy",
+    "why is the docker build so slow? speed it up",
+    "add end-to-end tests for the checkout flow and fix whatever fails",
+    "port the CLI from argparse to click and keep all flags compatible",
+    "find where we parse the CSV upload and add a size limit",
+    "set up CI with GitHub Actions for lint, test and release",
+    "our memory usage grows over time in production, find the leak",
+    "add pagination to every list endpoint in the API",
+    "upgrade the project from React 17 to 18 and fix the breakages",
+    "design a caching layer for the product catalog with invalidation",
+    "the build fails on Linux but not macOS, figure out why",
+    "write a migration script that backfills user timezones from IP logs",
+    "split the monolith's billing module into its own service",
+    "make the app work offline with a service worker and sync queue",
+    "add role-based access control to the admin panel",
+    "investigate why p99 latency doubled after yesterday's deploy",
+    "convert the codebase from JavaScript to TypeScript with strict mode",
+]
+
+PROMPTS: List[Tuple[str, bool]] = [(p, True) for p in SIMPLE] + [(p, False) for p in COMPLEX]
+
+
+def _lines(template: str, n: int) -> str:
+    return "\n".join(template.format(i=i, j=i * 7 % 97, k=i * 13 % 1000) for i in range(n))
+
+
+_NPM = _lines("npm http fetch GET 200 https://registry.npmjs.org/pkg-{i} {j}ms (cache miss)", 60) \
+    + "\nadded 1402 packages, and audited 1403 packages in 38s\nfound 0 vulnerabilities"
+_CARGO = _lines("   Compiling crate_{i} v0.{j}.{i}", 70) + "\n    Finished dev [unoptimized + debuginfo] target(s) in 41.20s"
+_PIP = _lines("Collecting package-{i}==1.{j}.0\n  Downloading package_{i}-1.{j}.0-py3-none-any.whl ({k} kB)", 40) \
+    + "\nSuccessfully installed " + " ".join(f"package-{i}-1.{i * 7 % 97}.0" for i in range(40))
+_DOCKER_PULL = _lines("{i:012x}: Pull complete", 50) + "\nDigest: sha256:" + "ab" * 32 + "\nStatus: Downloaded newer image for node:20"
+_PYTEST_OK = _lines("tests/test_module_{i}.py::test_case_{j} PASSED                      [{k:3d}%]", 70) \
+    + "\n============================== 70 passed in 12.31s =============================="
+_WEBPACK = _lines("[webpack] <s> [webpack.Progress] {i}% building {j}/{k} entries {i}/{j} dependencies", 60) \
+    + "\nwebpack 5.90.0 compiled successfully in 8412 ms"
+_APT = _lines("Get:{i} http://archive.ubuntu.com/ubuntu jammy/main amd64 lib{j}-dev amd64 1.{i}-1 [{k} kB]", 50) \
+    + "\nFetched 48.2 MB in 6s (8,120 kB/s)"
+_LS_NODE = _lines("node_modules/pkg-{i}/package.json\nnode_modules/pkg-{i}/index.js\nnode_modules/pkg-{i}/README.md", 50)
+_TERRAFORM = _lines("aws_security_group_rule.rule_{i}: Refreshing state... [id=sgrule-{k}]", 60)
+_GIT_LOG = _lines("{k:07x} chore(deps): bump dependency-{i} from 1.{j}.0 to 1.{j}.1", 60)
+
+_GREP_CSV = _lines("src/ui/table_{i}.tsx:{j}:  rows.map(row => <Row key={{row.id}} {{...row}} />)", 30) + "\n" + "\n".join([
+    "src/api/upload.py:88:def parse_csv(file: UploadFile) -> list[dict]:",
+    "src/api/upload.py:91:    reader = csv.DictReader(io.TextIOWrapper(file.file, encoding='utf-8'))",
+    "src/api/upload.py:94:    return [row for row in reader]",
+    "src/api/routes.py:41:    rows = parse_csv(upload)",
+]) + "\n" + _lines("src/ui/list_{i}.tsx:{j}:  items.map(item => <Item key={{item.id}} />)", 30)
+_DOCKER_BUILD = "\n".join([
+    "#1 [internal] load build definition from Dockerfile", "#1 DONE 0.0s",
+    "#4 [builder 1/7] FROM python:3.12-slim", "#4 DONE 0.4s",
+    "#5 [builder 2/7] COPY . /app", "#5 DONE 41.3s",
+    "#6 [builder 3/7] RUN pip install -r requirements.txt", "#6 212.7s (no cache: COPY . /app changed)",
+    "#7 [builder 4/7] RUN npm ci", "#7 DONE 98.0s",
+    "#8 [builder 5/7] RUN npm run build", "#8 DONE 64.2s",
+]) + "\n" + _lines("#9 sending tarball layer {i} {k}kB", 40)
+_SESSION_PY = "\n".join([
+    "import time", "from .tokens import decode, TokenExpired", "",
+    "class Session:",
+    "    def __init__(self, user_id, expires_at):",
+    "        self.user_id = user_id", "        self.expires_at = expires_at", "",
+    "    def expired(self, now=None):",
+    "        return (now or time.time()) > self.expires_at", "",
+    "def login(token):",
+    "    claims = decode(token)",
+    "    session = Session(claims['sub'], claims['exp'])",
+    "    if session.expired():",
+    "        raise TokenExpired(claims['sub'])",
+    "    return session",
+] * 4)
+_PYTEST_LOGIN = _lines("tests/test_module_{i}.py::test_case_{j} PASSED", 30) + "\n" + "\n".join([
+    "tests/auth/test_session.py::test_login_rejects_expired_token PASSED",
+    "tests/auth/test_session.py::test_login_accepts_clock_skew XFAIL (skew not handled)",
+    "tests/auth/test_session.py::test_login_sets_cookie PASSED",
+]) + "\n" + _lines("tests/test_module_{i}.py::test_other_{j} PASSED", 30)
+_DU = "\n".join(f"{size}\t{name}" for size, name in [
+    ("48G", "./data/raw_exports"), ("12G", "./.git"), ("3.1G", "./node_modules"), ("820M", "./build"),
+    ("410M", "./logs"), ("96M", "./coverage")] + [(f"{i}K", f"./src/module_{i}") for i in range(80)])
+_GIT_DIFF = "\n".join([
+    "diff --git a/src/api/upload.py b/src/api/upload.py",
+    "@@ -85,10 +85,14 @@ def parse_csv(file: UploadFile) -> list[dict]:",
+    "+MAX_UPLOAD_BYTES = 10 * 1024 * 1024",
+    "+    if file.size and file.size > MAX_UPLOAD_BYTES:",
+    "+        raise HTTPException(413, 'CSV upload too large')",
+    "     reader = csv.DictReader(io.TextIOWrapper(file.file, encoding='utf-8'))",
+] * 8)
+_EXPLAIN = "\n".join([
+    "Gather  (cost=1000.00..184732.41 rows=1 width=64) (actual time=1893.112..1905.442 rows=12 loops=1)",
+    "  Workers Planned: 2",
+    "  ->  Parallel Seq Scan on orders  (cost=0.00..183732.31 rows=1 width=64) (actual time=1874.2..1880.9 rows=4 loops=3)",
+    "        Filter: ((customer_email)::text = 'a@b.com'::text)",
+    "        Rows Removed by Filter: 4166663",
+    "Planning Time: 0.211 ms", "Execution Time: 1905.520 ms",
+] * 6)
+_KUBECTL = "NAME                         READY   STATUS             RESTARTS   AGE\n" + "\n".join(
+    [f"api-7d9f8c6b5-{i:05d}         1/1     Running            0          2d" for i in range(20)]
+    + ["worker-5c4b8d7f9-x2k9p        0/1     ImagePullBackOff   0          14m",
+       "worker-5c4b8d7f9-q8w3e        0/1     ImagePullBackOff   0          14m"]
+    + [f"cron-{i:05d}                  0/1     Completed          0          3h" for i in range(20)])
+_NPM_LS = "app@2.3.0 /srv/app\n" + _lines("├─┬ @scope/widget-{i}@3.{j}.0\n│ └── react@17.0.2 deduped", 25) \
+    + "\n├── react@17.0.2\n├── react-dom@17.0.2\n└─┬ react-router-dom@5.3.4\n  └── react@17.0.2 deduped"
+_CURL = "\n".join([
+    "*   Trying 10.0.4.12:443...", "* Connected to api.example.com (10.0.4.12) port 443",
+    "> OPTIONS /v2/orders HTTP/2", "> Origin: https://app.example.com",
+    "> Access-Control-Request-Method: POST",
+    "< HTTP/2 204", "< access-control-allow-origin: https://admin.example.com",
+    "< access-control-allow-methods: GET, OPTIONS", "< vary: Origin",
+] * 5)
+_PROFILE = "   ncalls  tottime  percall  cumtime  percall filename:lineno(function)\n" + "\n".join([
+    "   120000   14.212    0.000   31.877    0.000 cache.py:48(_store)",
+    "   120000    9.101    0.000    9.101    0.000 {method 'append' of 'list' objects}",
+    "        1    0.002    0.002   42.120   42.120 worker.py:12(run)",
+]) + "\n" + _lines("      {k}    0.00{i:02d}    0.000    0.00{i:02d}    0.000 util_{i}.py:{j}(helper_{i})", 60)
+_ENV = "\n".join([f"VAR_{i}=value_{i}" for i in range(40)]
+                 + ["DATABASE_URL=postgres://app@db.internal:5433/app", "DATABASE_POOL=5", "PGSSLMODE=require"]
+                 + [f"OTHER_{i}=x" for i in range(40)])
+
+OUTPUTS: List[Tuple[str, str, str, bool]] = [
+    ("fix the failing login test in auth/session.py", "Bash: npm install", _NPM, False),
+    ("find where we parse the CSV upload and add a size limit", "Bash: cargo build", _CARGO, False),
+    ("rename the variable tmp to buffer in utils.py", "Bash: pip install -r requirements.txt", _PIP, False),
+    ("fix the typo in README.md", "Bash: docker pull node:20", _DOCKER_PULL, False),
+    ("add pagination to the orders endpoint", "Bash: pytest", _PYTEST_OK, False),
+    ('make the error message in login.ts say "Invalid password"', "Bash: npm run build", _WEBPACK, False),
+    ("set up CI with GitHub Actions", "Bash: apt-get install -y build-essential", _APT, False),
+    ("fix the failing login test in auth/session.py", "Bash: find node_modules -name '*.js*'", _LS_NODE, False),
+    ("rename the output variable in main.tf", "Bash: terraform plan", _TERRAFORM, False),
+    ("add a size limit to the CSV upload", "Bash: git log --oneline -60", _GIT_LOG, False),
+    ("upgrade the project from React 17 to 18", "Bash: cargo build", _CARGO, False),
+    ("why is the docker build so slow? speed it up", "Bash: npm install", _NPM, False),
+    ("find where we parse the CSV upload and add a size limit", "Bash: rg -n 'csv|rows' src", _GREP_CSV, True),
+    ("why is the docker build so slow? speed it up", "Bash: docker build --progress=plain .", _DOCKER_BUILD, True),
+    ("fix the failing login test in auth/session.py", "Bash: cat auth/session.py", _SESSION_PY, True),
+    ("fix the failing login test in auth/session.py", "Bash: pytest -v", _PYTEST_LOGIN, True),
+    ("find what is using all the disk space", "Bash: du -sh ./*", _DU, True),
+    ("review my changes before I commit", "Bash: git diff", _GIT_DIFF, True),
+    ("speed up the slow orders-by-email query", "Bash: psql -c 'EXPLAIN ANALYZE ...'", _EXPLAIN, True),
+    ("why is the worker deployment not ready?", "Bash: kubectl get pods", _KUBECTL, True),
+    ("upgrade the project from React 17 to 18", "Bash: npm ls react", _NPM_LS, True),
+    ("why can't the app connect to the database?", "Bash: env", _ENV, True),
+    ("debug the CORS error when posting orders", "Bash: curl -v -X OPTIONS https://api.example.com/v2/orders", _CURL, True),
+    ("our worker gets slower over time, find the hotspot", "Bash: python -m cProfile worker.py", _PROFILE, True),
+]
+
+
+# -- held out ------------------------------------------------------------------------------
+
+HELDOUT_SIMPLE = [
+    "what's the capital of France?", "undo my last git commit but keep the changes",
+    "how do I exit vim?", "rename README.txt to README.md", "what does `ls -la` show?",
+    "remove the trailing whitespace on line 12 of app.py", "which python version is active?",
+    "is 1024 a power of two?", "add 'node_modules' to .dockerignore", "what port is postgres on by default?",
+    "change the page title in index.html to 'Dashboard'", "show the diff of my staged changes",
+]
+HELDOUT_COMPLEX = [
+    "just make the tests pass",                       # sounds small, is open-ended
+    "fix the bug",                                     # vague, needs investigation
+    "make it faster",                                  # vague optimisation
+    "add dark mode to the whole app",
+    "why does login fail only in production?",
+    "rename the User model to Account everywhere, including the database",
+    "migrate from REST to GraphQL for the mobile client",
+    "the CI is flaky, figure out which test and fix it",
+    "implement rate limiting per API key with Redis",
+    "clean up this codebase",
+    "add i18n support with French and German translations",
+    "our docker image is 2GB, get it under 300MB",
+]
+HELDOUT_PROMPTS: List[Tuple[str, bool]] = ([(p, True) for p in HELDOUT_SIMPLE]
+                                           + [(p, False) for p in HELDOUT_COMPLEX])
+
+HELDOUT_OUTPUTS: List[Tuple[str, str, str, bool]] = [
+    # disposable for the task
+    ("rename the prop `title` to `heading` in Card.tsx", "Bash: yarn install", _lines("[{i}/4] Fetching package-{i}@1.{j}.0 ...", 80) + "\nDone in 21.3s.", False),
+    ("update the README badge", "Bash: gradle build", _lines("> Task :module{i}:compileJava UP-TO-DATE", 90) + "\nBUILD SUCCESSFUL in 12s", False),
+    ("fix the typo in the footer", "Bash: docker compose up -d", _lines("Container app-svc{i}-1  Started", 70), False),
+    ("bump lodash to 4.17.21", "Bash: go mod download -x", _lines("# get https://proxy.golang.org/mod{i}/@v/v1.{j}.0.zip: 200 OK ({k}ms)", 60), False),
+    ("add a unit test for parse_date", "Bash: pip install -e .", _lines("Requirement already satisfied: lib{i}>=1.{j} in ./venv/lib/python3.12/site-packages", 70), False),
+    ("change the button color to blue", "Bash: npx tsc --noEmit", _lines("Checking src/components/C{i}.tsx", 90) + "\nDone.", False),
+    # needed for the task
+    ("why is the API slow on /orders?", "Bash: grep -c 'GET /orders' access.log && tail -n 80 access.log",
+     _lines("10.0.0.{i} - - [22/Sep/2026:10:{j:02d}:00] \"GET /orders?page={i} HTTP/1.1\" 200 512 rt={k}ms", 80), True),
+    ("which of our dependencies have known vulnerabilities?", "Bash: npm audit",
+     _lines("# npm audit report\n\npackage-{i}  <1.{j}.0\nSeverity: high\nPrototype Pollution - https://github.com/advisories/GHSA-{k}\nfix available via `npm audit fix`", 12), True),
+    ("find all TODOs about authentication", "Bash: rg -n TODO src",
+     _lines("src/mod{i}.py:{j}: # TODO: tidy imports", 40) + "\nsrc/auth/session.py:88: # TODO: rotate refresh tokens\nsrc/auth/oauth.py:41: # TODO: validate state param\n" + _lines("src/ui{i}.ts:{j}: // TODO: styles", 40), True),
+    ("what changed in the last release?", "Bash: git log --stat v1.4.0..v1.5.0",
+     _lines("commit {k:07x}\n    feat(billing): proration for plan changes #{i}\n src/billing/proration.py | {j} +++---", 20), True),
+    ("is the disk full on the build server?", "Bash: df -h",
+     "Filesystem Size Used Avail Use% Mounted on\n" + _lines("/dev/disk{i} 100G {j}G {k}G {j}% /mnt/vol{i}", 60), True),
+    ("which process is holding port 8080?", "Bash: lsof -i -P",
+     _lines("proc{i} {k} user {i}u IPv4 0x{j:x} 0t0 TCP *:{k} (LISTEN)", 60) + "\njava 4242 user 7u IPv4 0xabc 0t0 TCP *:8080 (LISTEN)\n" + _lines("proc{i} {k} user {i}u IPv4 0x{j:x} 0t0 TCP *:{j} (LISTEN)", 30), True),
+]

subcortex/hook.py

@@ -0,0 +1,254 @@
+"""Hardened entry point for every command-hook TUI.
+
+    subcortex-hook <tui> [<event>]          (console script)
+    subcortex hook <tui> [<event>]          (same thing, routed before argparse)
+    python -m subcortex.hook <tui> [<event>]
+
+The hook JSON arrives on stdin; the response (if any) goes to stdout. The
+process contract is what keeps TUIs safe, so it is enforced here, not in the
+adapters:
+
+- exit status is ALWAYS 0 — even for bad arguments, unknown TUIs/events,
+  invalid JSON, exceptions, ``SystemExit`` or ``KeyboardInterrupt``. (Exit 2
+  means "block" in Claude Code and several of its imitators.)
+- a watchdog ends the process silently (exit 0, no output) once the
+  ``hooks.budget_s`` wall-clock budget is spent, so a hung daemon can never
+  stall a turn.
+- stdout/stderr are captured while work runs; only the final response is
+  written, as one line. Nothing is ever written to stderr (some TUIs surface
+  it to the model or the user) unless ``SUBCORTEX_DEBUG`` is set.
+- the adapter's ``guard`` drops any response carrying a blocking field.
+
+Failures are appended to ``<data_dir>/hooks.log``; with ``SUBCORTEX_DEBUG=1``
+every invocation is logged there too.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import sys
+import threading
+import time
+import traceback
+from typing import Any, Dict, List, Optional
+
+LOG_MAX_BYTES = 1_000_000
+
+
+def _log(line: str) -> None:
+    try:
+        from .config import data_dir
+
+        path = data_dir() / "hooks.log"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if path.is_file() and path.stat().st_size > LOG_MAX_BYTES:
+            path.replace(path.with_suffix(".log.1"))
+        with open(path, "a", encoding="utf-8") as fh:
+            fh.write(time.strftime("%Y-%m-%d %H:%M:%S ") + line.rstrip() + "\n")
+    except Exception:
+        pass
+
+
+def run(tui: str, event_name: Optional[str], raw: str,
+        cfg: Optional[Dict[str, Any]] = None, client: Any = None,
+        commits: Optional[List[Any]] = None) -> Optional[str]:
+    """Process one hook invocation; returns the stdout text or None.
+
+    Pure with respect to the process (no exit, no stream handling) so tests and
+    the installer self-test can call it directly. May raise; ``main`` doesn't.
+    """
+    from . import policy
+    from .adapters import get_adapter
+    from .adapters.base import POST_COMPACT, PRE_COMPACT, PROMPT, SESSION_START, TOOL_OUTPUT
+    from .config import load_config
+
+    adapter = get_adapter(tui)
+    if adapter is None:
+        return None
+    try:
+        payload = json.loads(raw) if raw and raw.strip() else {}
+    except ValueError:
+        return None
+    if not isinstance(payload, dict):
+        return None
+    resolved = adapter.resolve(event_name or payload.get(adapter.event_field))
+    if resolved is None:
+        return None
+    name, kind = resolved
+    event = adapter.parse(name, kind, payload)
+    if event is None:
+        return None
+    # Consumed state (restored snapshots) is committed only after delivery.
+    event.commits = commits
+
+    def on_delivery(kind_: str, **fields: Any) -> None:
+        """Count it in the ledger (``subcortex stats``) once the response is out."""
+        from . import ledger
+
+        action = lambda: ledger.record(kind_, adapter.name, **fields)  # noqa: E731
+        if commits is None:
+            action()
+        else:
+            commits.append(action)
+
+    cfg = cfg or load_config()
+    if client is None:
+        from .client import DaemonClient
+
+        client = DaemonClient(cfg)
+
+    # The adapter can tell a compaction happened (e.g. a manual /compress).
+    compacted = bool(event.extra.get("compacted"))
+    if compacted and kind != PRE_COMPACT:
+        policy.mark_compacted(event.session_id, tui=adapter.name)
+
+    response = None
+    if kind == PROMPT:
+        policy.remember_prompt(event.session_id, event.prompt, tui=adapter.name)
+        # The slow part (a daemon round trip) first, the restore last: context is
+        # claimed only when there is budget left to deliver it.
+        hint = policy.prompt_hint(event.prompt, cfg, client.classify) if adapter.delivers_hints else None
+        restored = adapter.prompt_context(event, cfg)
+        text = "\n\n".join(p for p in (restored, hint) if p)
+        response = adapter.render_prompt(event, text) if text else None
+        if response is not None:
+            if hint:
+                on_delivery("hint")
+            if restored:
+                on_delivery("restore")
+    elif kind == TOOL_OUTPUT:
+        replacement = policy.trim_output(
+            event.output, cfg, client.judge, event.tool, event.tool_input, event.failed,
+            task=event.extra.get("task") or policy.last_prompt(event.session_id, tui=adapter.name))
+        # Some TUIs can only deliver restored context alongside a tool result.
+        context = adapter.output_context(event, cfg)
+        if context:
+            event.extra["context"] = context
+        if replacement or event.extra.get("context"):
+            response = adapter.render_tool_output(event, replacement)
+            if response is not None and replacement:
+                on_delivery("trim", before=len(event.output or ""), after=len(replacement))
+            if response is not None and context:
+                on_delivery("restore")
+    elif kind == PRE_COMPACT:
+        if event.messages is not None:
+            policy.save_snapshot(event.session_id, event.messages, cfg, event.trigger, tui=adapter.name)
+        else:
+            policy.snapshot_transcript(event.session_id, event.transcript_path, cfg, event.trigger,
+                                       tui=adapter.name)
+        if compacted:  # only once the snapshot exists
+            policy.mark_compacted(event.session_id, tui=adapter.name)
+        response = adapter.render_pre_compact(event)
+    elif kind == POST_COMPACT:
+        policy.mark_compacted(event.session_id, tui=adapter.name)
+        response = adapter.render_post_compact(event)
+    elif kind == SESSION_START and adapter.is_after_compaction(event):
+        context = policy.restore_snapshot(event.session_id, cfg, tui=adapter.name, commits=commits)
+        response = adapter.render_session_start(event, context) if context else None
+        if response is not None:
+            on_delivery("restore")
+
+    response = adapter.guard(kind, response)
+    if response is None:
+        return None
+    return response if isinstance(response, str) else json.dumps(response, ensure_ascii=False)
+
+
+# Held while the response line is written: the watchdog must not cut it in half.
+_WRITING = threading.Lock()
+MAX_STDIN_BYTES = 64 * 1024 * 1024
+
+
+def _bail() -> None:
+    # Budget exhausted: leave without output. os._exit skips cleanup on purpose.
+    if _WRITING.acquire(blocking=False):
+        os._exit(0)
+
+
+def _budget(cfg: Dict[str, Any]) -> float:
+    try:
+        budget = float((cfg.get("hooks") or {}).get("budget_s", 4.0))
+    except (TypeError, ValueError):
+        return 4.0
+    return min(max(budget, 0.5), 30.0) if budget == budget else 4.0  # NaN -> default
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """Hook process entry. Returns 0 on every path."""
+    real_stdout = sys.stdout
+    real_stderr = sys.stderr
+    debug = bool(os.environ.get("SUBCORTEX_DEBUG"))
+    # Streams are captured before anything else can print.
+    sys.stdout = io.StringIO()
+    if not debug:
+        sys.stderr = io.StringIO()
+    timer = None
+    started = time.perf_counter()
+    args: List[str] = []
+    backstop = None
+    try:
+        args = [str(a) for a in (sys.argv[1:] if argv is None else argv)]
+        tui = args[0] if args else ""
+        event_name = args[1] if len(args) > 1 else None
+
+        from .config import load_config
+
+        cfg = load_config()
+        budget = _budget(cfg)
+        timer = threading.Timer(budget, _bail)
+        timer.daemon = True
+        timer.start()
+        # The timer needs the GIL; C code (a regex, a JSON parse of a huge
+        # payload) can hold it for longer than the budget. faulthandler's
+        # watchdog is a C thread: it ends the process regardless (status 1,
+        # which the installed "|| true" guard turns into 0).
+        import faulthandler
+
+        backstop = open(os.devnull, "w")
+        faulthandler.dump_traceback_later(budget + 1.0, exit=True, file=backstop)
+
+        stdin = getattr(sys.stdin, "buffer", None)
+        data = stdin.read(MAX_STDIN_BYTES + 1) if stdin is not None else b""
+        if len(data) > MAX_STDIN_BYTES:
+            raise ValueError("hook payload too large")
+        commits: List[Any] = []
+        out = run(tui, event_name, data.decode("utf-8", "replace"), cfg, commits=commits)
+
+        with _WRITING:
+            timer.cancel()
+            sys.stdout, sys.stderr = real_stdout, real_stderr
+            if out:
+                real_stdout.write(out + "\n")
+                real_stdout.flush()
+                for commit in commits:  # delivered: consumed state can go
+                    try:
+                        commit()
+                    except Exception:
+                        pass
+        if debug:
+            ms = (time.perf_counter() - started) * 1000
+            _log(f"{' '.join(args)} ok {ms:.0f}ms -> {out[:200] if out else '(no output)'}")
+    except BaseException:  # noqa: BLE001 — SystemExit/KeyboardInterrupt included, by design
+        if timer is not None:
+            timer.cancel()
+        sys.stdout, sys.stderr = real_stdout, real_stderr
+        _log(f"{' '.join(args)} failed:\n{traceback.format_exc()}")
+    finally:
+        if backstop is not None:
+            import faulthandler
+
+            faulthandler.cancel_dump_traceback_later()
+            backstop.close()
+    return 0
+
+
+def entry() -> None:
+    """Console-script entry (``subcortex-hook``): exit status is always 0."""
+    main()
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    entry()

subcortex/installers/__init__.py

@@ -0,0 +1,62 @@
+"""Registry of TUI installers (hook-, plugin- and MCP-based)."""
+
+from __future__ import annotations
+
+import importlib
+from typing import Dict, List, Optional
+
+from ..tuis import canonical
+from .base import Installer
+
+# canonical name -> "module:Class" (relative to this package)
+_INSTALLERS: Dict[str, str] = {
+    # command hooks
+    "claude-code": "claude_family:ClaudeCodeInstaller",
+    "qoder": "claude_family:QoderInstaller",
+    "codebuddy": "claude_family:CodeBuddyInstaller",
+    "droid": "claude_family:DroidInstaller",
+    "junie": "claude_family:JunieInstaller",
+    "devin": "claude_family:DevinInstaller",
+    "codex": "codex:CodexInstaller",
+    "open-interpreter": "codex:OpenInterpreterInstaller",
+    "gemini-cli": "gemini_family:GeminiCliInstaller",
+    "qwen-code": "gemini_family:QwenCodeInstaller",
+    "cursor": "cursor:CursorInstaller",
+    "copilot": "copilot:CopilotInstaller",
+    "kimi-code": "kimi_code:KimiCodeInstaller",
+    "openhands": "openhands:OpenHandsInstaller",
+    "grok-build": "more_hooks:GrokBuildInstaller",
+    "docker-agent": "more_hooks:DockerAgentInstaller",
+    "letta": "more_hooks:LettaInstaller",
+    "vibe": "more_hooks:VibeInstaller",
+    # plugins
+    "opencode": "opencode:OpenCodeInstaller",
+    "kilo": "opencode:KiloInstaller",
+    "amp": "amp:AmpInstaller",
+    "pi": "pi_cline:PiInstaller",
+    "cline": "pi_cline:ClineInstaller",
+    # MCP only
+    "crush": "crush:CrushInstaller",
+    "goose": "goose:GooseInstaller",
+    "warp": "mcp_only:WarpInstaller",
+    "zed": "mcp_only:ZedInstaller",
+    "auggie": "mcp_only:AuggieInstaller",
+    "kiro": "mcp_only:KiroInstaller",
+}
+
+
+def canonical_name(name: str) -> Optional[str]:
+    return canonical(name, _INSTALLERS)
+
+
+def get_installer(name: str, mcp: bool = False) -> Optional[Installer]:
+    key = canonical_name(name)
+    if key is None:
+        return None
+    module_name, cls_name = _INSTALLERS[key].split(":")
+    module = importlib.import_module(f".{module_name}", __name__)
+    return getattr(module, cls_name)(mcp=mcp)
+
+
+def names() -> List[str]:
+    return sorted(_INSTALLERS)

subcortex/installers/amp.py

@@ -0,0 +1,39 @@
+"""Amp: a Bun plugin in the system plugin dir (+ optional ``amp.mcpServers``).
+
+Amp's Neo plugin API has no command hooks, but its plugins can append hidden
+context to a prompt (``agent.start``) and replace a tool result
+(``tool.result``), so the plugin covers behaviors 1 and 2 natively and 3/4 via
+a rolling snapshot plus compaction detection. See ``plugins/amp/subcortex.ts``.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import List
+
+from .base import Installer, Target, rendered_plugin, mcp_json_target, plugin_file_target
+
+
+def amp_config_dir() -> Path:
+    xdg = os.environ.get("XDG_CONFIG_HOME", "").strip()
+    return (Path(xdg) if xdg else Path.home() / ".config") / "amp"
+
+
+class AmpInstaller(Installer):
+    name = "amp"
+    display_name = "Amp"
+    seam = "plugin"
+    binaries = ("amp",)
+    docs = "https://ampcode.com/docs/customize/plugins"
+    supports_mcp = True
+    post_install = ("reload plugins in Amp (Ctrl+O → plugins: reload) or restart it; "
+                    "for `amp -x` runs pass --plugin-ready-timeout")
+
+    def targets(self) -> List[Target]:
+        content = rendered_plugin("amp")
+        targets = [plugin_file_target(amp_config_dir() / "plugins" / "subcortex.ts", content)]
+        if self.mcp:
+            targets.append(mcp_json_target(amp_config_dir() / "settings.json", self.mcp_command(),
+                                           key="amp.mcpServers"))
+        return targets