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

release: v0.13.0 (#184)

Jordan Gibbs6a297faa066d
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index ebf6f68..268f852 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "hyperresearch",
- "version": "0.12.0",
+ "version": "0.13.0",
"description": "Deep research skill for Claude Code. Bootstraps the hyperresearch CLI and hands off to its 16-step research pipeline with a persistent, searchable source vault.",
"author": {
"name": "Jordan Gibbs",
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 33c4ad9..95e62ca 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "hyperresearch",
- "version": "0.12.0",
+ "version": "0.13.0",
"description": "Deep research skill for Codex and Claude Code. Bootstraps the hyperresearch CLI and hands off to its 16-step research pipeline with a persistent, searchable source vault.",
"author": {
"name": "Jordan Gibbs",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 68b3897..bf5a25b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,10 +2,13 @@
## [Unreleased]
+## [0.13.0] - 2026-10-27
+
- **Step prompts agree with each other (#102).** Settles the contract conflicts listed in the issue: the no-re-synthesis invariant names the ship gate's compression pass as its one exception; width-sweep fetchers take no new topic searches but still chase the primary sources their batch cites; step 7 has a documented path for fewer than the target tensions when step 4 justified zero loci; a failed critic is re-spawned once and otherwise leaves an empty `critic_failed` findings file, since the ship gate checks all four exist; the step 11 outline leaves out Opinionated Synthesis for `short` reports; the step 1 example no longer shows a wrapper requirement in the decomposition; the readability recommender writes a JSON object, matching its schema; the polish auditor receives `wrapper_contract_path` so it knows whether to keep YAML frontmatter; step 16 hands off to the ship gate instead of declaring the run done; the one-chapter case in step 1.5 is described as an escape hatch; and the cite-check Goal states that non-numeric citations are sampled.
-- **The pipeline runs on the OpenAI Codex CLI.** `hyperresearch install . --target codex` installs the entry skill at `.agents/skills/hyperresearch/`, invoked as `$hyperresearch <query>`, along with the 18 step procedures as plain files under `.hyperresearch/codex/steps/`, the subagent roster as custom agents in `.codex/agents/*.toml`, a Stop hook in `.codex/hooks.json`, and an `AGENTS.md` block. The step procedures are plain files because Codex caps the skill listing and has no skill-to-skill invocation. `--target all` installs both platforms. `--global --target codex` writes the skill to `~/.agents/skills/` and the agents to `~/.codex/agents/`. `--target claude` is the default and its output is byte-identical to 0.12.0. Differences on Codex: there is no browser lane, so blocked fetches stay queued and are listed for the user; the Read+Edit tool locks are instructions rather than enforcement; and the Stop hook (`hyperresearch run stop-gate`) blocks the session from ending mid-pipeline. The Stop hook exists because an earlier Codex attempt answered inline and never touched the vault. Codex's sandbox defaults to read-only with no network, so a session needs `--sandbox workspace-write -c sandbox_workspace_write.network_access=true`. hyperresearch documents these flags and never writes to Codex's config.
+- **The pipeline runs on the OpenAI Codex CLI.** `hyperresearch install . --target codex` installs the entry skill at `.agents/skills/hyperresearch/`, invoked as `$hyperresearch <query>`, along with the 18 step procedures as plain files under `.hyperresearch/codex/steps/`, the subagent roster as custom agents in `.codex/agents/*.toml`, a Stop hook in `.codex/hooks.json`, and an `AGENTS.md` block. The step procedures are plain files because Codex caps the skill listing and has no skill-to-skill invocation. `--target all` installs both platforms. `--global --target codex` writes the skill to `~/.agents/skills/` and the agents to `~/.codex/agents/`. `--target claude` is the default and installs the same layout as before. Differences on Codex: there is no browser lane, so blocked fetches stay queued and are listed for the user; the Read+Edit tool locks are instructions rather than enforcement; and the Stop hook (`hyperresearch run stop-gate`) blocks the session from ending mid-pipeline. The Stop hook exists because an earlier Codex attempt answered inline and never touched the vault. Codex's sandbox defaults to read-only with no network, so a session needs `--sandbox workspace-write -c sandbox_workspace_write.network_access=true`. hyperresearch documents these flags and never writes to Codex's config.
- **The repo is a Codex plugin marketplace too.** `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json` publish the same `deep-research` bootstrap skill as the Claude Code plugin: `codex plugin marketplace add jordan-gibbs/hyperresearch`, then `codex plugin add hyperresearch@hyperresearch`. The skill no longer assumes Claude Code. On Codex it runs `install --target codex` and then reads the entry skill directly, because Codex discovers skills when a session starts. It gains `license` and `compatibility` frontmatter and an `agents/openai.yaml`. Codex namespaces plugin skills, so from the plugin it is `$hyperresearch:deep-research`; installed standalone with `npx skills add jordan-gibbs/hyperresearch -a codex` (to `.agents/skills/deep-research/`) it is `$deep-research`. The `openai.yaml` starter prompt names the skill in words rather than by a `$` mention that would only match one of those. The README now leads with Claude Code and Codex install paths side by side.
- **`run resume` follows the tier step 1 declared.** A run is initialized with the installed gear's step list, and step 1 can reclassify it (usually to `light`) in `prompt-decomposition.json`. The ship gate already honoured that tier; `resume_position` did not, so a light-tier run that finished step 2 was told to resume at step 3, a step its tier skips. `run resume`, `run status` and the Codex Stop gate now use the declared tier's steps. Found during the first live Codex run.
+- **The SSRF gate resolves the name httpx connects to (#161).** `check_url` looked up the hostname as urlparse returns it, and `getaddrinfo` encodes a non-ASCII name with the stdlib IDNA 2003 codec, while httpx connects with IDNA 2008. For `http://straße.attacker.example/` the gate resolved `strasse.attacker.example` and httpx connected to `xn--strae-oqa.attacker.example`, two separate DNS names. The gate now resolves `httpx.URL(url).raw_host`. `allow_private_hosts` entries and the URL host go through one normalization (lowercase, IDNA 2008 via `idna.encode`, trailing dot stripped), so an entry matches its unicode/punycode and root-dot spellings; an entry that can never match raises an error naming it. A URL httpx cannot parse, and a name `getaddrinfo` cannot encode, raise `SafeHTTPError` instead of escaping and failing a whole batch. `idna` is now a declared dependency.
- **The SSRF gate refuses URLs a browser reads differently.** `check_url` learns the host from urlparse and httpx (RFC 3986), but the crawl4ai lane hands the URL to Chromium (WHATWG). For `http://127.0.0.1\@evil.com/` the gate checked `evil.com` while Chromium, which reads `\` as `/`, connected to 127.0.0.1; the final-URL recheck only ran after the request was sent. The gate now refuses a backslash in the authority, a percent-encoded hostname (`127.0.0.%31`, which Chromium decodes), and a host whose last label is numeric unless it is a canonical dotted quad (`127.1`, `0x7f.1`, `2130706433`: Chromium parses these as IPv4 in its own grammar, getaddrinfo varies by platform). Tabs, newlines and other control characters inside the URL were already refused by the httpx parse. A backslash in the path, query or fragment is still allowed: it cannot move the host. The check is in `check_url`, so every lane gets it.
- **Codex bench harness rebuilt (`codex_bench/`).** Each query runs in its own git-initialized project set up by `install --target codex`, with the prompt in `research/prompt.txt` and the inline-citation wrapper contract. The session is one `codex exec` under the workspace-write-plus-network sandbox, with JSONL events captured. `result.json` records whether the pipeline ran: vault note count, manifest steps done and not done, tier, subagent spawns, sandbox rejections, and `run verify`. An inline answer that skipped the vault is reported as `PIPELINE_SKIPPED`. `--dry-run` sets up the run dir and prints the exact `codex exec` command without running it. There are no dollar fields.
- **Run spend counters and count ceilings (#92).** `hpr run step --status done` and `hpr run reconcile` count tagged notes and distinct fetched URLs linked to those notes in the vault DB, including HTML and PDFs. Optional `hpr run init --max-sources` / `--max-notes` ceilings block at step boundaries. `run resume` or `run step --status done --force` can clear a count block up to three times; the same count stays clear until it increases, and a fourth clear rejects the step. Agent-reported `estimated_usd` stays unchanged; `--budget` stays inert unless something calls `hpr run spend`. Real runs get count ceilings only when the entry skill passes them to `run init`.
@@ -16,6 +19,8 @@
- **`research` no longer crashes when every search result is skipped.** If all results were login walls or already in the vault, the closing summary indexed `created_notes[-1]` and raised `IndexError`. It now prints "No notes created". `--json` already returned an empty `notes_created` list and still does.
- **`research` reads the vault's `[junk]` config.** Its login-wall check used the built-in defaults, so `extra_login_signals` and the other `[junk]` thresholds were ignored. `fetch` and `fetch-batch` already applied them.
- **`research` builds its provider with the vault's `[fetch]` settings and `[junk]` gates.** It called `get_provider` without `settings` / `gates`, so research fetches ignored settings such as `browser_verify_tls` and `allow_private_hosts`. It now passes them the way `fetch` and `fetch-batch` do.
+- **Search text keeps numeric comparisons (#153).** `strip_markdown` removed everything from a `<` to the next `>`, so `<22.5 V DC ... >23.5 V` lost its first number from full-text search and snippets. Only a `<` that starts like markup (a letter, `/` plus a letter, `!` or `?`) now opens a tag.
+- **New notes skip ids already in the index (#160).** After `note mv topic topic-moved` the file `topic.md` is free but the id `topic` is taken, so the next note titled "Topic" was written to `topic.md`, refused by sync, and its fetched URL recorded under the moved note. `write_note` now skips indexed ids (`topic-2`) in every path that creates a note under a derived id, and the fetch paths check after sync that the new file owns its id; if it does not, nothing is recorded and the fetch reports `NOTE_NOT_INDEXED`.
## [0.12.0] - 2026-09-24
diff --git a/pyproject.toml b/pyproject.toml
index 3517a6d..9927884 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "hyperresearch"
-version = "0.12.0"
+version = "0.13.0"
description = "Claude Code harness for disciplined, adversarially-audited deep research with full provenance."
readme = "README.md"
license = "MIT"
diff --git a/src/hyperresearch/__init__.py b/src/hyperresearch/__init__.py
index 83c97f4..94b1a12 100644
--- a/src/hyperresearch/__init__.py
+++ b/src/hyperresearch/__init__.py
@@ -1,3 +1,3 @@
"""Hyperresearch — agent-driven research knowledge base."""
-__version__ = "0.12.0"
+__version__ = "0.13.0"