@research-copilot/plugin 1.1.15 → 1.1.17

package/dist/hooks/scripts/copilot_subagent_stop.py

@@ -0,0 +1,203 @@
+"""SubagentStop hook: HANDOFF freshness (HARD), STATE_OUTPUT 6-field (SOFT),
+state-machine no-jump (SOFT).
+
+Decision contract:
+  - block: {"decision": "block", "reason": "..."}
+  - allow: {"hookSpecificOutput": {"permissionDecision": "allow"}}
+
+3-strike fuse: if CHECK 1 fails 3 times for the same (agent, file), the hook
+releases the 3rd attempt with [HARD/RELEASE] to avoid lockout.
+
+Falls open via safe_main().
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import _copilot_hook_lib as lib
+
+
+HANDOFF_FILES: dict[str, list[str]] = {
+    # research-copilot retired as a sub-agent (now the main-session conductor);
+    # state.md/decisions.md freshness is a CONDUCTOR-PROTOCOL standing order,
+    # not SubagentStop-enforced (the main session never fires SubagentStop).
+    "copilot-literature":  ["literature.md"],
+    "copilot-ideation":    ["ideas.md"],
+    "copilot-experiment":  ["experiments.md"],
+    # writer/polisher/reviewer/rebuttal write handoff.md (append-only multi-writer)
+    # — not subject to HARD freshness; SOFT checks only.
+    "copilot-writer":    [],
+    "copilot-polisher":  [],
+    "copilot-reviewer":  [],
+    "copilot-rebuttal":  [],
+}
+
+
+def _file_handoff_last_updated(workspace: Path, filename: str) -> str | None:
+    f = workspace / ".copilot" / filename
+    if not f.is_file():
+        return None
+    try:
+        text = f.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    h = lib.extract_handoff(text)
+    return h.get("last_updated") if h else None
+
+
+def _iso_strictly_later(current: str | None, snapshot: str | None) -> bool:
+    """ISO 8601 strings sort lexicographically. None snapshot ('first boot')
+    is treated as 'any current value counts as later'."""
+    if not current:
+        return False
+    if snapshot is None:
+        return True
+    return current > snapshot
+
+
+def _check_handoff_freshness(workspace: Path, agent: str
+                              ) -> tuple[str, str, str | None]:
+    """Returns (status, message, file_that_failed).
+    status in {PASS, HARD_FAIL, SOFT_FAIL}.
+
+    HARD_FAIL = stale/missing handoff AND a snapshot file exists to compare against.
+    SOFT_FAIL = no snapshot file exists at all (first boot / hook reenabled).
+    PASS     = all owned files have fresh handoff blocks.
+    """
+    files = HANDOFF_FILES.get(agent, [])
+    if not files:
+        return "PASS", "", None
+    snapshot_path = workspace / ".copilot" / lib.SNAPSHOT_NAME
+    snapshot_exists = snapshot_path.is_file()
+    snapshot = lib.read_snapshot(workspace)
+    for fname in files:
+        cur = _file_handoff_last_updated(workspace, fname)
+        snap = snapshot.get(fname)
+        if _iso_strictly_later(cur, snap):
+            continue
+        msg = (f"{agent} did not update .copilot/{fname} __HANDOFF__ "
+               f"block this session. Append/refresh the block and "
+               f"re-emit STATE_OUTPUT before exiting.")
+        return ("SOFT_FAIL" if not snapshot_exists else "HARD_FAIL"), msg, fname
+    return "PASS", "", None
+
+
+def _read_last_assistant_text(transcript_path: str) -> str:
+    """Return the concatenated text content of the most recent assistant
+    message in the transcript JSONL. Empty string if none found.
+    """
+    if not transcript_path:
+        return ""
+    p = Path(transcript_path)
+    if not p.is_file():
+        return ""
+    try:
+        lines = p.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return ""
+    for line in reversed(lines[-100:]):
+        if not line.strip():
+            continue
+        try:
+            entry = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if entry.get("role") != "assistant":
+            continue
+        chunks: list[str] = []
+        content = entry.get("content")
+        if isinstance(content, list):
+            for item in content:
+                if isinstance(item, dict) and item.get("type") == "text":
+                    chunks.append(item.get("text", ""))
+        elif isinstance(content, str):
+            chunks.append(content)
+        if chunks:
+            return "\n".join(chunks)
+    return ""
+
+
+def _run_soft_checks(workspace: Path, agent: str, transcript: str) -> None:
+    """CHECK 3 (STATE_OUTPUT 6 fields) + CHECK 4 (state transition legality).
+    Both are SOFT — append to violations.log but never block."""
+    text = _read_last_assistant_text(transcript)
+    so = lib.extract_state_output(text)
+    missing = lib.state_output_missing_fields(so)
+    if missing:
+        if so is None:
+            lib.log_violation(workspace, "SOFT", "WARN", agent,
+                              "STATE_OUTPUT block absent from final reply")
+        else:
+            lib.log_violation(workspace, "SOFT", "WARN", agent,
+                              f"STATE_OUTPUT missing fields: {missing}")
+    if so:
+        prev, curr = so.get("Previous"), so.get("Current")
+        if prev and curr and not lib.is_transition_legal(agent, prev, curr):
+            lib.log_violation(workspace, "SOFT", "WARN", agent,
+                              f"transition {prev} -> {curr} not in allowed "
+                              f"set {lib.STATE_MACHINE.get(agent, {}).get(prev, [])}")
+
+
+def real_main() -> int:
+    raw = sys.stdin.read()
+    if not raw.strip():
+        print(json.dumps(lib.allow_decision()))
+        return 0
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        print(json.dumps(lib.allow_decision()))
+        return 0
+
+    agent = lib.detect_active_agent(payload.get("transcript_path", ""))
+    if not lib.is_copilot_agent(agent):
+        print(json.dumps(lib.allow_decision()))
+        return 0
+
+    workspace = Path.cwd()
+
+    if lib.env_guard_disabled():
+        lib.log_violation(workspace, "INFO", "DISABLED", agent,
+                          "SubagentStop guard bypassed by env var")
+        print(json.dumps(lib.allow_decision()))
+        return 0
+
+    if lib.override_match(workspace, agent, "skip-handoff-check"):
+        lib.log_violation(workspace, "INFO", "OVERRIDE", agent,
+                          "skip-handoff-check active")
+        print(json.dumps(lib.allow_decision()))
+        return 0
+
+    # CHECK 1 — HARD freshness with 3-strike fuse, or SOFT degrade at first boot
+    status, fail_msg, fail_file = _check_handoff_freshness(workspace, agent)
+    if status == "HARD_FAIL":
+        n = lib.counter_inc(workspace, agent, fail_file)
+        if n < 3:
+            lib.log_violation(workspace, "HARD", "BLOCK", agent,
+                              f"{fail_msg} (strike {n}/3)", file=fail_file)
+            print(json.dumps(lib.block_decision(fail_msg)))
+            return 0
+        lib.log_violation(workspace, "HARD", "RELEASE", agent,
+                          "3-strike fuse triggered, releasing", file=fail_file)
+        lib.counter_reset(workspace, agent, fail_file)
+        print(json.dumps(lib.allow_decision()))
+        return 0
+
+    if status == "SOFT_FAIL":
+        lib.log_violation(workspace, "INFO", "NO-SNAPSHOT", agent,
+                          f"{fail_msg} (degraded: no .session_snapshot.json)",
+                          file=fail_file)
+
+    if status == "PASS":
+        lib.counter_reset_all(workspace, agent)
+
+    # CHECK 3+4 SOFT — never block
+    _run_soft_checks(workspace, agent, payload.get("transcript_path", ""))
+    print(json.dumps(lib.allow_decision()))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(lib.safe_main(real_main))

package/dist/hooks/scripts/copilot_write_guard.py

@@ -0,0 +1,96 @@
+"""PreToolUse hook: enforce owned-file partition (PIPELINE-OS §8).
+
+When the active sub-agent is copilot-*, denies Write/Edit to non-owned
+artifacts. Paths outside the research-artifact universe (.copilot/,
+sections/*.tex, references.bib) are unconditionally allowed.
+
+handoff.md special case (Task 10) is added in the next commit.
+
+Falls open on any exception via safe_main().
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import _copilot_hook_lib as lib
+
+
+def real_main() -> int:
+    raw = sys.stdin.read()
+    if not raw.strip():
+        print(json.dumps(lib.allow_decision()))
+        return 0
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        print(json.dumps(lib.allow_decision()))
+        return 0
+
+    agent = lib.detect_active_agent(payload.get("transcript_path", ""))
+    if not lib.is_copilot_agent(agent):
+        print(json.dumps(lib.allow_decision()))
+        return 0
+
+    workspace = Path.cwd()
+
+    if lib.env_guard_disabled():
+        lib.log_violation(workspace, "INFO", "DISABLED", agent,
+                          "guard bypassed by env var")
+        print(json.dumps(lib.allow_decision()))
+        return 0
+
+    if lib.override_match(workspace, agent, "skip-owned-check"):
+        lib.log_violation(workspace, "INFO", "OVERRIDE", agent,
+                          "skip-owned-check active")
+        print(json.dumps(lib.allow_decision()))
+        return 0
+
+    file_path = str((payload.get("tool_input") or {}).get("file_path", ""))
+    if not file_path:
+        print(json.dumps(lib.allow_decision()))
+        return 0
+
+    norm = lib.normalize_path(file_path, workspace=workspace)
+
+    # handoff.md special case: append-only for the 4 multi-writers.
+    if norm.endswith(".copilot/handoff.md"):
+        tool_name = payload.get("tool_name", "")
+        if agent in lib.HANDOFF_APPEND_ONLY_AGENTS:
+            if tool_name == "Write":
+                lib.log_violation(workspace, "HARD", "DENY", agent,
+                                  "Write (overwrite) to handoff.md; "
+                                  "use Edit to append", file=norm)
+                msg = ("Blocked by copilot-write-guard: handoff.md is "
+                       "append-only. Use Edit to add a new block, not Write.")
+                print(json.dumps(lib.deny_decision(msg)))
+                return 0
+            # Edit allowed for these 4 agents — fall through to owned check
+        else:
+            lib.log_violation(workspace, "HARD", "DENY", agent,
+                              "agent has no write right to handoff.md",
+                              file=norm)
+            msg = (f"Blocked by copilot-write-guard: {agent} is not an "
+                   f"owner of handoff.md.")
+            print(json.dumps(lib.deny_decision(msg)))
+            return 0
+
+    if lib.is_owned(agent, norm):
+        print(json.dumps(lib.allow_decision()))
+        return 0
+
+    if lib.is_known_research_artifact(norm):
+        lib.log_violation(workspace, "HARD", "DENY", agent,
+                          "writing to non-owned artifact", file=norm)
+        msg = (f"Blocked by copilot-write-guard: {agent} may not write "
+               f"{norm}. See PIPELINE-OS §8.")
+        print(json.dumps(lib.deny_decision(msg)))
+        return 0
+
+    print(json.dumps(lib.allow_decision()))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(lib.safe_main(real_main))

package/dist/hooks/scripts/post_tool_loop_armer.py

@@ -0,0 +1,61 @@
+"""PostToolUse hook: detect long background experiments and recommend
+arming a CronCreate-based self-poll so the main session continues after
+notifications. Sets `.copilot/.loop-armed` to avoid duplicate suggestions."""
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+LONGRUN_PATTERNS = (
+    re.compile(r"\btrain(\.py|_)"),
+    re.compile(r"\bmain\.py\b"),
+    re.compile(r"\bai_scientist\b"),
+    re.compile(r"\btorchrun\b"),
+    re.compile(r"\bdeepspeed\b"),
+    re.compile(r"\bexperiments?/"),
+    re.compile(r"\baccelerate launch\b"),
+)
+
+
+def should_arm(event: dict) -> bool:
+    if event.get("tool_name") != "Bash":
+        return False
+    inp = event.get("tool_input") or {}
+    if not inp.get("run_in_background"):
+        return False
+    cmd = inp.get("command", "") or ""
+    return any(p.search(cmd) for p in LONGRUN_PATTERNS)
+
+
+def main() -> int:
+    try:
+        raw = sys.stdin.read()
+        event = json.loads(raw) if raw.strip() else {}
+    except json.JSONDecodeError:
+        return 0
+
+    if not should_arm(event):
+        return 0
+
+    flag = Path.cwd() / ".copilot" / ".loop-armed"
+    if flag.exists():
+        return 0
+
+    sys.stdout.write(
+        "[loop-armer] Detected long-running background experiment.\n"
+        "[loop-armer] Recommend arming a self-poll so the loop continues across notifications:\n"
+        "  CronCreate(cron=\"*/3 * * * *\", prompt=\"<<autonomous-loop>>\", recurring=true, durable=false)\n"
+        "[loop-armer] Or the user can paste:\n"
+        "  /loop 1m If a background experiment task is still running, check its log tail and decide next step. Otherwise, delete this scheduled task.\n"
+        "[loop-armer] On EXECUTING -> END the agent MUST CronDelete the returned id and remove .copilot/.loop-armed.\n"
+    )
+    sys.stdout.flush()
+    flag.parent.mkdir(parents=True, exist_ok=True)
+    flag.write_text("", encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/hooks/scripts/research_copilot_guard.py

@@ -0,0 +1,208 @@
+"""Research Copilot Workflow Guard hook (PreToolUse).
+
+Polices the MAIN SESSION acting as conductor. The main session must delegate
+domain work to copilot-* sub-agents and must publish a TaskCreate plan list
+before dispatching. copilot-* sub-agents run freely (exempt).
+
+Origin attribution uses the authoritative `agent_id` payload field: it is
+present ONLY inside a sub-agent call, so its absence => main session. Any
+ambiguity resolves to main (conservative — never silently exempt the conductor).
+"""
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+READ_ONLY_PREFIXES = ("grep", "cat", "ls", "head", "tail", "find",
+                      "Get-Content", "Select-String", "Get-ChildItem")
+EXPERIMENT_KEYWORDS = ("train.py", "run_experiment", "wandb", "mlflow",
+                       "tensorboard", "torchrun", "deepspeed", "accelerate")
+EXPERIMENT_REGEX = re.compile(r"python[\w\s.-]*\b(train|experiment|run_exp)\b",
+                              re.IGNORECASE)
+RESEARCH_MCP_PREFIXES = (
+    "mcp__arxiv-search__",
+    "mcp__arxivsub-search__",
+    "mcp__google-scholar__",
+    "mcp__dblp-bib__",
+)
+# Conductor-owned artifacts: the main session MAY write these.
+CONDUCTOR_OWNED_ARTIFACTS = (".copilot/state.md", ".copilot/decisions.md")
+# Delegated artifact files the main session must NOT write. Matched segment-anchored
+# (see _path_matches) so 'references.bib' does NOT match 'old_references.bib'. The
+# sections/*.tex case is handled separately by a path-segment check.
+DELEGATED_ARTIFACT_FILES = (".copilot/ideas.md", ".copilot/experiments.md",
+                            ".copilot/literature.md", "references.bib")
+READ_ONLY_TOOLS = ("Read", "Grep", "Glob", "TaskCreate", "TaskUpdate",
+                   "TaskList", "TaskGet", "Skill", "AskUserQuestion")
+COPILOT_SUBAGENT_PREFIX = "copilot-"
+
+
+def allow() -> dict[str, Any]:
+    return {"hookSpecificOutput": {"permissionDecision": "allow"}}
+
+
+def deny(message: str) -> dict[str, Any]:
+    return {"hookSpecificOutput": {"permissionDecision": "deny",
+                                   "permissionDecisionReason": message},
+            "systemMessage": message}
+
+
+def is_main_session(payload: dict[str, Any]) -> bool:
+    """Main session iff `agent_id` absent/empty (per Claude Code hooks docs)."""
+    return not payload.get("agent_id")
+
+
+def is_exempt_subagent(payload: dict[str, Any]) -> bool:
+    if is_main_session(payload):
+        return False
+    return str(payload.get("agent_type") or "").startswith(COPILOT_SUBAGENT_PREFIX)
+
+
+def is_read_only(command: str) -> bool:
+    stripped = command.strip()
+    return any(stripped.startswith(prefix) for prefix in READ_ONLY_PREFIXES)
+
+
+def _norm(path: str) -> str:
+    return str(path).replace("\\", "/")
+
+
+def _path_matches(path: str, target: str) -> bool:
+    """True iff `path` equals `target` or ends with `/target` (segment-anchored).
+    Prevents substring false-positives like 'references.bib' matching
+    'old_references.bib', or '.copilot/ideas.md' matching an unrelated path."""
+    p = _norm(path)
+    return p == target or p.endswith("/" + target)
+
+
+def _iter_transcript_tool_uses(transcript_path: str | None):
+    if not transcript_path:
+        return
+    p = Path(transcript_path)
+    if not p.is_file():
+        return
+    try:
+        text = p.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            rec = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(rec, dict) and rec.get("type") == "tool_use":
+            yield {"name": rec.get("name", ""), "input": rec.get("input", {}) or {}}
+            continue
+        content = None
+        if isinstance(rec, dict):
+            content = rec.get("content")
+            if content is None:
+                msg = rec.get("message")
+                if isinstance(msg, dict):
+                    content = msg.get("content")
+        if isinstance(content, list):
+            for item in content:
+                if isinstance(item, dict) and item.get("type") == "tool_use":
+                    yield {"name": item.get("name", ""),
+                           "input": item.get("input", {}) or {}}
+
+
+def check_m1_delegation(tool_name: str, tool_input: dict[str, Any]) -> str | None:
+    """M1 delegation gate: deny main-session execution-class work."""
+    # Experiment scripts via shell.
+    if tool_name in ("Bash", "PowerShell"):
+        command = str((tool_input or {}).get("command", ""))
+        if not command or is_read_only(command):
+            return None
+        if any(kw in command for kw in EXPERIMENT_KEYWORDS) or EXPERIMENT_REGEX.search(command):
+            return ("Blocked by research-copilot-guard (M1 delegation gate): the "
+                    "conductor must not run experiments inline. Delegate via "
+                    "Agent(subagent_type='copilot-experiment').")
+        return None
+    # Paper-retrieval MCP tools.
+    if any(tool_name.startswith(p) for p in RESEARCH_MCP_PREFIXES):
+        return ("Blocked by research-copilot-guard (M1 delegation gate): the "
+                "conductor must not search papers inline. Delegate via "
+                "Agent(subagent_type='copilot-literature').")
+    # Writes to delegated research artifacts (segment-anchored, not substring).
+    if tool_name in ("Write", "Edit"):
+        path = _norm((tool_input or {}).get("file_path", ""))
+        if any(_path_matches(path, owned) for owned in CONDUCTOR_OWNED_ARTIFACTS):
+            return None  # conductor owns state.md / decisions.md
+        segments = path.split("/")
+        is_sections_tex = "sections" in segments and path.endswith(".tex")
+        if is_sections_tex or any(_path_matches(path, f) for f in DELEGATED_ARTIFACT_FILES):
+            return ("Blocked by research-copilot-guard (M1 delegation gate): the "
+                    "conductor must not write research artifacts (sections/*.tex, "
+                    "references.bib, .copilot/{ideas,experiments,literature}.md) "
+                    "inline. Delegate to the matching copilot-* sub-agent.")
+    return None
+
+
+def check_m2_task_list(tool_name: str, tool_input: dict[str, Any],
+                       transcript_path: str | None) -> str | None:
+    """M2 task-list gate: deny copilot-* dispatch with no TaskCreate this turn."""
+    if tool_name != "Agent":
+        return None
+    sub_type = str((tool_input or {}).get("subagent_type", ""))
+    if not sub_type.startswith(COPILOT_SUBAGENT_PREFIX):
+        return None
+    if not transcript_path:
+        return None  # fail-open: cannot inspect
+    for entry in _iter_transcript_tool_uses(transcript_path):
+        if entry["name"] == "TaskCreate":
+            return None
+    return ("Blocked by research-copilot-guard (M2 task-list gate): dispatching "
+            "a copilot-* sub-agent requires a TaskCreate plan list (one task per "
+            "planned dispatch) in this turn. Call TaskCreate first, then Agent().")
+
+
+def main() -> int:
+    raw = sys.stdin.read()
+    if not raw:
+        print(json.dumps(allow()))
+        return 0
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        print(json.dumps(allow()))
+        return 0
+    try:
+        decision = _decide(payload)
+    except Exception:
+        # Fail-open: any unexpected error yields allow, never traps the user
+        # (mirrors _copilot_hook_lib.safe_main's contract).
+        import traceback
+        sys.stderr.write(traceback.format_exc())
+        decision = allow()
+    print(json.dumps(decision))
+    return 0
+
+
+def _decide(payload: dict[str, Any]) -> dict[str, Any]:
+    """Pure decision logic for a parsed payload. Raising is safe — main()
+    catches and fails open."""
+    # Exempt copilot-* sub-agents outright (they run experiments/searches/writes).
+    if is_exempt_subagent(payload):
+        return allow()
+    # Everything else (incl. ambiguous) is treated as MAIN SESSION -> police.
+    tool_name = payload.get("tool_name", "")
+    tool_input = payload.get("tool_input", {}) or {}
+    if tool_name in READ_ONLY_TOOLS:
+        return allow()
+    transcript_path = payload.get("transcript_path")
+    for check in (check_m1_delegation(tool_name, tool_input),
+                  check_m2_task_list(tool_name, tool_input, transcript_path)):
+        if check:
+            return deny(check)
+    return allow()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/hooks/scripts/scientist_guardrails.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+
+
+def main() -> int:
+    workspace = Path.cwd()
+    packaged_runtime = workspace / ".github" / "runtimes" / "scientist-support" / "runtime"
+    source_runtime = workspace / "self" / "runtimes" / "scientist-support" / "runtime"
+    lines = [
+        "[scientist-guardrails] AI Scientist workflow loaded.",
+        "[scientist-guardrails] Upstream defaults assume Linux + CUDA and may not fully run on Windows hosts.",
+        "[scientist-guardrails] AI Scientist executes LLM-written code; prefer a container or sandbox before running full experiments.",
+    ]
+    if packaged_runtime.exists():
+        lines.append(f"[scientist-guardrails] Detected skill runtime: {packaged_runtime}")
+    elif source_runtime.exists():
+        lines.append(f"[scientist-guardrails] Detected skill runtime: {source_runtime}")
+    else:
+        lines.append("[scientist-guardrails] Scientist-support runtime was not found in the workspace.")
+    lines.append("[scientist-guardrails] Recommended first action: run scientist runtime validation before ideation or experiment launch.")
+    sys.stdout.write("\n".join(lines) + "\n")
+    sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())