Skip to content

Convert Claude Code or Codex into the most intelligent Deep Research Agent. Collect, search, and synthesize web research into a persistent, searchable wiki that builds on itself. Hosted API + MCP: hyperresearch.ai

22.4 KB
Raw Blame
"""Tests for hook installer and skill file provisioning (hyperresearch roster)."""

from __future__ import annotations

import json
import os
import shlex
import shutil
import subprocess

import pytest

from hyperresearch.core.hooks import (
    _RETIRED_AGENT_FILES,
    _RETIRED_SKILL_DIRS,
    _install_claude_hook,
    _install_depth_critic_agent,
    _install_depth_investigator_agent,
    _install_dialectic_critic_agent,
    _install_hyperresearch_skill,
    _install_instruction_critic_agent,
    _install_loci_analyst_agent,
    _install_patcher_agent,
    _install_polish_auditor_agent,
    _install_researcher_agent,
    _install_source_analyst_agent,
    _install_width_critic_agent,
    _prune_retired_agents,
    _write_hook_script,
    install_hooks,
)

# ---------------------------------------------------------------------------
# Entry skill — installs at /hyperresearch only (v0.8.1+)
# ---------------------------------------------------------------------------


def test_install_hyperresearch_skill_creates_skill_dir(tmp_vault):
    """The entry skill installs at .claude/skills/hyperresearch/SKILL.md so
    Claude Code registers `/hyperresearch` as the slash-command trigger.
    The /research alias was retired in v0.8.1 — only /hyperresearch now.
    """
    result = _install_hyperresearch_skill(tmp_vault.root)
    assert result is not None

    hyper_path = tmp_vault.root / ".claude" / "skills" / "hyperresearch" / "SKILL.md"
    assert hyper_path.exists()

    # /research dir must NOT be created
    research_path = tmp_vault.root / ".claude" / "skills" / "research" / "SKILL.md"
    assert not research_path.exists()

    hyper_body = hyper_path.read_text(encoding="utf-8")
    assert "name: hyperresearch" in hyper_body
    # Entry skill is the chain router — must reference step skills
    assert "hyperresearch-1-decompose" in hyper_body
    assert "hyperresearch-10-triple-draft" in hyper_body
    assert "hyperresearch-11-synthesize" in hyper_body
    assert "hyperresearch-16-readability-audit" in hyper_body
    # Chain mechanics: must explain Skill tool invocation
    assert "Skill" in hyper_body
    # Patching invariant must appear in the skill prose
    assert "PATCH" in hyper_body
    # The most common V7 failure mode (single-draft instead of ensemble) must be
    # called out by name in the entry skill
    assert "PIPELINE VIOLATION" in hyper_body


def test_install_hyperresearch_skill_idempotent(tmp_vault):
    first = _install_hyperresearch_skill(tmp_vault.root)
    assert first is not None
    second = _install_hyperresearch_skill(tmp_vault.root)
    assert second is None


def test_install_hyperresearch_step_skills_creates_all(tmp_vault):
    """Each step skill lives at .claude/skills/hyperresearch-N-name/SKILL.md so the
    orchestrator can invoke it via the Skill tool. All 18 (16 numbered +
    1.5 chapter-partition + 14.5 cite-check) must install on a fresh vault."""
    from hyperresearch.core.hooks import (
        _HYPERRESEARCH_STEP_SKILLS,
        _install_hyperresearch_step_skills,
    )

    result = _install_hyperresearch_step_skills(tmp_vault.root)
    assert result is not None
    assert len(_HYPERRESEARCH_STEP_SKILLS) == 18

    skills_root = tmp_vault.root / ".claude" / "skills"
    for skill_name in _HYPERRESEARCH_STEP_SKILLS:
        skill_path = skills_root / skill_name / "SKILL.md"
        assert skill_path.exists(), f"missing step skill: {skill_name}"

        body = skill_path.read_text(encoding="utf-8")
        # Every step skill must have its name in frontmatter so the Skill tool
        # can invoke it
        assert f"name: {skill_name}" in body
        # Every step skill (except 16, the terminal step) must point to the
        # next step via the Skill tool
        if skill_name != "hyperresearch-16-readability-audit":
            assert "Skill" in body


def test_install_hyperresearch_step_skills_idempotent(tmp_vault):
    from hyperresearch.core.hooks import _install_hyperresearch_step_skills

    first = _install_hyperresearch_step_skills(tmp_vault.root)
    assert first is not None
    second = _install_hyperresearch_step_skills(tmp_vault.root)
    assert second is None


def test_installed_skills_carry_the_resolved_cli_path(tmp_vault):
    """Skills must name the CLI by the path install resolved, the way CLAUDE.md
    and the agent prompts do. `$HPR` shipped for months with nothing defining
    it, so `$HPR run finish` ran as `run finish` (#133)."""
    from hyperresearch.core.hooks import (
        _HYPERRESEARCH_STEP_SKILLS,
        _install_hyperresearch_step_skills,
    )

    hpr = r"C:\venv\Scripts\hyperresearch.exe"
    _install_hyperresearch_skill(tmp_vault.root, hpr)
    _install_hyperresearch_step_skills(tmp_vault.root, hpr)

    skills_root = tmp_vault.root / ".claude" / "skills"
    bodies = {
        name: (skills_root / name / "SKILL.md").read_text(encoding="utf-8")
        for name in ["hyperresearch", *_HYPERRESEARCH_STEP_SKILLS]
    }
    for name, body in bodies.items():
        assert "$HPR" not in body, name
        assert "{hpr_path}" not in body, name
    assert "C:/venv/Scripts/hyperresearch.exe run finish" in bodies["hyperresearch"]


# ---------------------------------------------------------------------------
# Subagent installers — per-agent sanity checks
# ---------------------------------------------------------------------------


def test_install_fetcher_agent(tmp_vault):
    result = _install_researcher_agent(tmp_vault.root, "hyperresearch")
    agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-fetcher.md"
    assert agent_path.exists()
    body = agent_path.read_text(encoding="utf-8")
    assert "model: sonnet" in body
    # Summary policy is length-proportional — no hard one-sentence cap.
    # Long sources should get multi-paragraph summaries, short ones stay
    # short. The prompt must discuss both ends of that range AND flag
    # long-source delegation to hyperresearch-source-analyst.
    assert "proportional" in body.lower()
    assert "hyperresearch-source-analyst" in body
    assert "5000 words" in body
    assert result is not None


def test_install_loci_analyst_agent(tmp_vault):
    result = _install_loci_analyst_agent(tmp_vault.root, "hyperresearch")
    agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-loci-analyst.md"
    assert agent_path.exists()
    body = agent_path.read_text(encoding="utf-8")
    assert "model: sonnet" in body
    assert "corpus_evidence" in body
    assert "analyst_id" in body
    assert result is not None


def test_install_depth_investigator_agent(tmp_vault):
    result = _install_depth_investigator_agent(tmp_vault.root, "hyperresearch")
    agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-depth-investigator.md"
    assert agent_path.exists()
    body = agent_path.read_text(encoding="utf-8")
    assert "model: sonnet" in body
    # Depth investigator must have Task tool so it can spawn fetcher subagents
    assert "Task" in body
    assert "interim" in body.lower()
    assert "10 new" in body  # the fetch budget rule
    assert result is not None


def test_install_source_analyst_agent(tmp_vault):
    """The source-analyst reads ONE long source end-to-end on Sonnet's 1M
    context window and produces a structured source-analysis note
    backlinked to the original. Leaf subagent — no Task tool (no
    recursive spawns)."""
    result = _install_source_analyst_agent(tmp_vault.root, "hyperresearch")
    agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-source-analyst.md"
    assert agent_path.exists()
    body = agent_path.read_text(encoding="utf-8")
    assert "model: sonnet" in body
    # Leaf subagent: no Task, cannot spawn other subagents
    assert "tools: Bash, Read, Write" in body
    tools_line = body.split("tools:")[1].split("\n")[0]
    assert "Task" not in tools_line
    # Must produce a source-analysis note (canonical NoteType value)
    assert "source-analysis" in body
    # Structural template sections the prompt mandates
    assert "Thesis / Central claim" in body
    assert "Methodology / Basis of claims" in body
    assert "Key findings" in body
    assert "Load-bearing citations" in body
    assert "Relevance to research_query" in body
    # Backlink mechanism via body breadcrumb (no custom CLI flag needed)
    assert "Suggested by" in body
    # Word-count threshold that decides whether the analyst is appropriate
    assert "5000" in body
    assert result is not None


def test_install_dialectic_critic_agent(tmp_vault):
    result = _install_dialectic_critic_agent(tmp_vault.root, "hyperresearch")
    agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-dialectic-critic.md"
    assert agent_path.exists()
    body = agent_path.read_text(encoding="utf-8")
    assert "model: opus" in body
    # Critics have Bash + Read + Write (Write for JSON output; no Edit
    # since they don't mutate the draft — that's the revisor's job)
    assert "tools: Bash, Read, Write" in body
    assert "recommendation" in body
    assert "location" in body
    assert "surgical" in body.lower()
    assert result is not None


def test_install_depth_critic_agent(tmp_vault):
    result = _install_depth_critic_agent(tmp_vault.root, "hyperresearch")
    agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-depth-critic.md"
    assert agent_path.exists()
    body = agent_path.read_text(encoding="utf-8")
    assert "model: opus" in body
    assert "tools: Bash, Read" in body
    assert "interim" in body.lower()
    assert result is not None


def test_install_width_critic_agent(tmp_vault):
    result = _install_width_critic_agent(tmp_vault.root, "hyperresearch")
    agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-width-critic.md"
    assert agent_path.exists()
    body = agent_path.read_text(encoding="utf-8")
    assert "model: opus" in body
    assert "tools: Bash, Read" in body
    assert "coverage" in body.lower()
    assert result is not None


def test_install_instruction_critic_agent(tmp_vault):
    """Instruction-critic specifically targets the instruction-following
    dimension by checking the draft against prompt-decomposition atomic
    items. Read-only tool lock — it produces findings, never patches."""
    result = _install_instruction_critic_agent(tmp_vault.root, "hyperresearch")
    agent_path = (
        tmp_vault.root / ".claude" / "agents" / "hyperresearch-instruction-critic.md"
    )
    assert agent_path.exists()
    body = agent_path.read_text(encoding="utf-8")
    assert "model: opus" in body
    assert "tools: Bash, Read" in body
    # The critic explicitly consumes the decomposition artifact
    assert "prompt-decomposition.json" in body
    assert "atomic_item" in body
    # Failure modes it tracks
    assert "missing|under-covered|wrong-order|wrong-format" in body
    # Structural-mirror check: runs FIRST, emits findings against
    # required_section_headings. This is the highest-leverage InstF lever.
    assert "STRUCTURAL MIRROR CHECK" in body
    assert "required_section_headings" in body
    # Escalation field for restructures the patcher cannot handle
    assert "requires_orchestrator_restructure" in body
    assert result is not None


def test_install_patcher_agent_is_edit_only(tmp_vault):
    """The revisor (patcher) MUST be tool-locked to Read + Edit only — no
    Write, no Bash. This is the load-bearing invariant that enforces
    REVISE-NOT-REGEN."""
    result = _install_patcher_agent(tmp_vault.root, "hyperresearch")
    agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-patcher.md"
    assert agent_path.exists()
    body = agent_path.read_text(encoding="utf-8")
    # Opus: substance-integration judgment about which findings serve
    # the research_query is a reasoning task Sonnet underperforms on.
    assert "model: opus" in body
    # Tool lock: must be exactly "Read, Edit" — not Write, not Bash. The
    # tool lock is what enforces the no-regeneration invariant.
    assert "tools: Read, Edit" in body
    assert "tools: Bash" not in body
    assert "Write" not in body.split("tools:")[1].split("\n")[0]
    assert "regenerat" in body.lower()  # the invariant spelled out
    assert "surgical" in body.lower()
    # Integrate-don't-caveat rule lifts insight score by preventing
    # hedge-appending edits that dilute committed claims.
    assert "Integrate, don't caveat" in body
    assert "scoping the claim" in body
    # Dynamic revision: revisor reads findings with location/issue/
    # recommendation fields and applies edits using its own judgment.
    assert "location" in body
    assert "recommendation" in body
    assert "requires_orchestrator_restructure" in body
    assert result is not None


def test_install_polish_auditor_agent_is_edit_only(tmp_vault):
    """The polish auditor is the second tool-locked [Read, Edit] agent.
    Same invariant: no regeneration path."""
    result = _install_polish_auditor_agent(tmp_vault.root, "hyperresearch")
    agent_path = tmp_vault.root / ".claude" / "agents" / "hyperresearch-polish-auditor.md"
    assert agent_path.exists()
    body = agent_path.read_text(encoding="utf-8")
    # Opus: semantic rewrites of scaffold vocabulary + hedge-language
    # judgment need strong prose comprehension.
    assert "model: opus" in body
    assert "tools: Read, Edit" in body
    assert "tools: Bash" not in body
    # scaffold-only section list must be injected
    assert "User Prompt (VERBATIM" in body
    # Hedge-language cutting category — strikes softeners on claims the
    # paragraph already supports with evidence. Highest-leverage polish cut.
    assert "Hedge language that softens committed claims" in body
    assert "suggests that" in body
    assert result is not None


# ---------------------------------------------------------------------------
# Idempotency — at least one agent confirms the pattern holds
# ---------------------------------------------------------------------------


def test_loci_analyst_install_idempotent(tmp_vault):
    first = _install_loci_analyst_agent(tmp_vault.root, "hyperresearch")
    assert first is not None
    second = _install_loci_analyst_agent(tmp_vault.root, "hyperresearch")
    assert second is None


def test_patcher_install_idempotent(tmp_vault):
    first = _install_patcher_agent(tmp_vault.root, "hyperresearch")
    assert first is not None
    second = _install_patcher_agent(tmp_vault.root, "hyperresearch")
    assert second is None


# ---------------------------------------------------------------------------
# Retired-roster pruning
# ---------------------------------------------------------------------------


def test_prune_retired_agents_removes_old_files(tmp_vault):
    """Pre-hyperresearch vaults have analyst/auditor/rewriter/subrun/merger agent
    files and a research-ensemble skill dir. Installing onto such a vault
    must prune those so the installed state matches the current architecture."""
    agents_dir = tmp_vault.root / ".claude" / "agents"
    agents_dir.mkdir(parents=True, exist_ok=True)
    for name in _RETIRED_AGENT_FILES:
        (agents_dir / name).write_text("pre-hyperresearch content\n", encoding="utf-8")

    skills_dir = tmp_vault.root / ".claude" / "skills"
    for name in _RETIRED_SKILL_DIRS:
        retired_skill = skills_dir / name
        retired_skill.mkdir(parents=True, exist_ok=True)
        # What we actually shipped into these dirs: the entry skill, renamed.
        # Every version of it named the project in its body.
        (retired_skill / "SKILL.md").write_text(
            f"---\nname: {name}\n---\n\n# Deep research\n\nRun the hyperresearch pipeline.\n",
            encoding="utf-8",
        )

    result = _prune_retired_agents(tmp_vault.root)
    assert result is not None
    assert "Pruned retired" in result

    for name in _RETIRED_AGENT_FILES:
        assert not (agents_dir / name).exists(), f"{name} still present"
    for name in _RETIRED_SKILL_DIRS:
        assert not (skills_dir / name).exists(), f"skill dir {name} still present"


def test_prune_retired_agents_noop_on_clean_vault(tmp_vault):
    """On a fresh vault, prune is a no-op."""
    result = _prune_retired_agents(tmp_vault.root)
    assert result is None


def test_prune_retired_agents_spares_a_users_own_research_skill(tmp_vault):
    """`research` is an obvious name for a hand-written personal skill, and on a
    --global install the prune runs against ~/.claude/skills/. Deleting on name
    alone destroyed user content that was never ours (#73)."""
    skills_dir = tmp_vault.root / ".claude" / "skills"
    mine = skills_dir / "research"
    mine.mkdir(parents=True, exist_ok=True)
    (mine / "SKILL.md").write_text(
        "---\nname: research\ndescription: My own literature workflow\n---\n\nStep 1...\n",
        encoding="utf-8",
    )
    (mine / "reference.md").write_text("notes I wrote\n", encoding="utf-8")

    result = _prune_retired_agents(tmp_vault.root)

    assert (mine / "SKILL.md").read_text(encoding="utf-8").startswith("---\nname: research")
    assert (mine / "reference.md").exists()
    # And the user is told it was left behind, rather than it happening silently.
    assert result is not None
    assert "Left alone (not ours)" in result
    assert ".claude/skills/research" in result


def test_prune_retired_agents_spares_a_dir_with_no_skill_file(tmp_vault):
    """No SKILL.md means we have no evidence it was ever ours, so leave it."""
    skills_dir = tmp_vault.root / ".claude" / "skills"
    mine = skills_dir / "research"
    mine.mkdir(parents=True, exist_ok=True)
    (mine / "scratch.txt").write_text("something\n", encoding="utf-8")

    _prune_retired_agents(tmp_vault.root)

    assert (mine / "scratch.txt").exists()


# ---------------------------------------------------------------------------
# PreToolUse hook — the reminder must reach the model (#94)
# ---------------------------------------------------------------------------


def test_installed_hook_delivers_reminder_through_the_injection_channel(tmp_vault):
    """Exit 0 + hookSpecificOutput JSON on stdout is the only channel that
    reaches the model. stderr at exit 0 is written to the debug log, so a hook
    that writes the reminder there has no effect at all."""
    script = _write_hook_script(tmp_vault.root, "hyperresearch").read_text(encoding="utf-8")

    assert "hookSpecificOutput" in script
    assert "hookEventName: 'PreToolUse'" in script
    assert "additionalContext" in script
    assert "process.stderr.write" not in script


@pytest.mark.skipif(shutil.which("node") is None, reason="node is not installed")
def test_installed_hook_emits_parseable_injection_json(tmp_vault):
    """Run the installed script the way Claude Code does, and read the channel
    the model reads."""
    hook_path = _write_hook_script(tmp_vault.root, "hyperresearch")

    proc = subprocess.run(
        ["node", str(hook_path)],
        capture_output=True,
        text=True,
        env={**os.environ, "CLAUDE_PROJECT_DIR": str(tmp_vault.root)},
        timeout=60,
    )

    assert proc.returncode == 0, proc.stderr
    assert proc.stderr == ""
    output = json.loads(proc.stdout)["hookSpecificOutput"]
    assert output["hookEventName"] == "PreToolUse"
    assert "HYPERRESEARCH" in output["additionalContext"]
    assert "hyperresearch fetch" in output["additionalContext"]


# ---------------------------------------------------------------------------
# install_hooks — end-to-end integration
# ---------------------------------------------------------------------------


def test_install_hooks_registers_full_hyperresearch_roster(tmp_vault):
    """install_hooks wires the hook, both entry-skill aliases, and the agent roster."""
    actions = install_hooks(tmp_vault.root, "hyperresearch")
    assert actions  # something happened

    # All agent files must be present
    agents_dir = tmp_vault.root / ".claude" / "agents"
    expected_agents = {
        "hyperresearch-fetcher.md",
        "hyperresearch-loci-analyst.md",
        "hyperresearch-depth-investigator.md",
        "hyperresearch-source-analyst.md",
        "hyperresearch-corpus-critic.md",
        "hyperresearch-dialectic-critic.md",
        "hyperresearch-depth-critic.md",
        "hyperresearch-width-critic.md",
        "hyperresearch-instruction-critic.md",
        "hyperresearch-patcher.md",
        "hyperresearch-polish-auditor.md",
        "hyperresearch-readability-recommender.md",
        "hyperresearch-draft-orchestrator.md",
        "hyperresearch-synthesizer.md",
        "hyperresearch-browser-fetcher.md",
        "hyperresearch-cite-checker.md",
    }
    actual_agents = {p.name for p in agents_dir.iterdir() if p.is_file()}
    assert expected_agents == actual_agents, (
        f"missing: {expected_agents - actual_agents}, extra: {actual_agents - expected_agents}"
    )

    # Entry skill registered as /hyperresearch (the /research alias was
    # retired in v0.8.1)
    assert (tmp_vault.root / ".claude" / "skills" / "hyperresearch" / "SKILL.md").exists()
    assert not (tmp_vault.root / ".claude" / "skills" / "research" / "SKILL.md").exists()

    # Hook settings written
    assert (tmp_vault.root / ".claude" / "settings.json").exists()
    assert (tmp_vault.root / ".hyperresearch" / "hook.js").exists()


def test_install_hooks_second_run_is_noop(tmp_vault):
    first = install_hooks(tmp_vault.root, "hyperresearch")
    assert first
    second = install_hooks(tmp_vault.root, "hyperresearch")
    # Hook installer may still report the hook is already installed → no
    # actions or a trivial subset. Must not crash, must not reinstall files.
    assert not second or all("pruned" not in a.lower() for a in second)


# ---------------------------------------------------------------------------
# The registered command must survive the shell that runs it
# ---------------------------------------------------------------------------


def test_installed_hook_command_keeps_the_script_path_in_one_argument(tmp_path):
    """Claude Code runs a hook command through a shell, so an unquoted path is
    split at its first space and node receives a truncated script path. Project
    directories with spaces are ordinary — a Windows user directory, or anything
    under "My Documents" — and the hook then fails on every matching tool call
    without the reminder ever appearing."""
    project = tmp_path / "my project"
    project.mkdir()

    _install_claude_hook(project, "hyperresearch")

    settings = json.loads((project / ".claude" / "settings.json").read_text(encoding="utf-8"))
    command = settings["hooks"]["PreToolUse"][0]["hooks"][0]["command"]

    assert shlex.split(command) == ["node", (project / ".hyperresearch" / "hook.js").as_posix()]