| name | proactive-research |
| description | Hook-driven proactive research pipeline. Runs automatically via UserPromptSubmit
— there is no slash command to trigger it. This page documents how it works,
how to disable it, and the env-var knobs.
|
Proactive Research
Every substantive user prompt is fed through a 3-stage background pipeline
that detects external-knowledge gaps in the project wiki and fills them by
dispatching /wiki-ingest against canonical URLs.
Pipeline shape
user prompt
↓ proactive-research-extract.sh (UserPromptSubmit hook, ≤50ms)
│ filters: WIKI_DRIVER guard, opt-in gate, AGENT_ID guard,
│ slash-command, MIN_TOKENS, rate-limit
│ spawns: detached driver subprocess
↓
proactive-research-driver.sh (background, fire-and-forget)
├─ Step 1: claude -p '/wiki-query <prompt>' (Sonnet)
│ → markdown with Answer / Evidence / Gaps
├─ Step 2: curl Haiku messages API
│ system: templates/classifier.md
│ user: wiki-context + sanitized prompt
│ → {worthy, reason, sources:[{topic,url}, ...]}
└─ Step 3: for each source.url:
claude -p '/wiki-ingest <url>' (Sonnet, detached)
Cost per worthy prompt: 1 Sonnet /wiki-query + 1 Haiku curl + N Sonnet
/wiki-ingest. Cost per not-worthy prompt that cleared the token gate:
1 Sonnet /wiki-query + 1 Haiku curl, then stop.
The hook contract is fire-and-return: filter, fork, exit. All real work
happens in the detached driver. The hook never touches an LLM and never
writes a queue entry.
Recursion guard (architectural — do not remove)
The driver invokes claude -p to run /wiki-query and /wiki-ingest. Each
of those would re-trigger UserPromptSubmit and fork-bomb us if not
guarded. The driver runs with WIKI_DRIVER=1 exported into its env; the
producer hook short-circuits at the top when this is set. Removing this
guard breaks the architecture.
Sanitization (privacy)
Before any external call, the prompt is run through
wiki_sanitize_for_external in wiki-common.sh:
- Strip absolute paths (
/Users/..., /home/..., /opt/..., etc.).
- Redact tokens matching the existing
simple-secrets-scan.sh regex set.
- Strip repo-local identifiers from
git ls-files (best-effort).
With PROACTIVE_RESEARCH_PRIVACY_STRICT=1, the driver fails closed if
any <repo-local> placeholder is still present after sanitization.
Env-var knobs
| Variable | Default | Effect |
|---|
PROACTIVE_RESEARCH_ENABLED | 0 | Opt-in gate — set to 1 per project to enable the producer hook. |
PROACTIVE_RESEARCH_MIN_TOKENS | 7 | Producer skips prompts under this token count (tiktoken if importable, else char/4). |
PROACTIVE_RESEARCH_RATE_LIMIT_PER_HR | 20 | Producer drops prompts beyond this count per UTC hour. |
PROACTIVE_RESEARCH_MAX_SOURCES | 4 | Driver caps the number of /wiki-ingest dispatches. |
PROACTIVE_RESEARCH_PRIVACY_STRICT | 0 | Driver skips if a repo-local identifier remains after sanitization. |
The driver also requires ANTHROPIC_API_KEY for the Haiku curl call. If
unset, the driver logs and exits without dispatching.
Logs
Driver stdout/stderr append to ~/.claude/proactive-research/log with one
line per stage:
[2026-05-03T19:41:02Z] driver session:abc12345 step1 /wiki-query: ...
[2026-05-03T19:41:08Z] driver session:abc12345 step2 classify (Haiku)
[2026-05-03T19:41:09Z] driver session:abc12345 WORTHY=true reason="..." sources=2
[2026-05-03T19:41:09Z] driver session:abc12345 dispatch /wiki-ingest https://...
The producer hook also emits a single PROACTIVE driver spawned (tokens=N)
line per dispatch into the wiki's log.md.
Enabling
Proactive research is opt-in (off by default). To enable for a project,
add PROACTIVE_RESEARCH_ENABLED=1 to the project's .claude/settings.json
env block (or to the shell env). The hook short-circuits silently when
unset, so leaving it off has zero cost.
To temporarily disable on an opted-in project: unset PROACTIVE_RESEARCH_ENABLED
or override via PROACTIVE_RESEARCH_ENABLED=0.
Files
${CLAUDE_PLUGIN_ROOT}/handlers/proactive-research-extract.sh — producer hook.${CLAUDE_PLUGIN_ROOT}/handlers/proactive-research-driver.sh — driver subprocess.${CLAUDE_PLUGIN_ROOT}/templates/classifier.md — Haiku classifier system prompt.
Related
/wiki-ingest — explicit, foreground source ingestion (the curated path
the driver dispatches into)./wiki-query — synthesis with citations (the driver's Step 1)./wiki-lint — wiki health check.
