deep-research: v2.3.0 — raised clarifying question caps (5/10), added tool selection strategy, post-dispatch no-polling rule; ask-testing: v1.0.0 — new peer agent for testing profile

ask-testing/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: ask-testing
+description: Persistent peer Hermes agent for delegated work on the testing profile. `ask testing <instructions>` delegates a task with full context via headless one-shot commands. Session persists across all turns in one Hermes session via --resume.
+version: 1.0.0
+author: Hermes Agent (cloned from ask-dev)
+license: MIT
+platforms: [linux]
+metadata:
+  hermes:
+    tags: [hermes, peer, delegation, parallel, review, validation, testing]
+    related_skills: [ask-dev, ask-hermes, ask-claude, writing-plans, hermes-agent]
+---
+
+# ask-testing — Peer Hermes Agent for Delegated Work (Testing Profile)
+
+## Overview
+
+A persistent peer Hermes agent session for delegated work. The peer runs on the testing profile (`hermes -p testing`) — a separate agent instance with its own workspace, SOUL.md, AGENTS.md, and all tools (terminal, file, web search, MCP). Fresh context, no memory of this session. Used for parallel work, peer review, validation, and delegated tasks.
+
+Each `ask testing` is a one-shot headless command that runs, returns a clean response, and exits. Continuity (the peer remembering prior turns) comes from `--resume <session_id>`, not from a live process. No start/stop needed — the session starts on the first ask and ends when the Hermes session ends.
+
+## When to Use
+
+- Want a second agent to do real work in parallel: read files, run tests, validate, search
+- Want peer review of my recommendation with full tool access
+- Multi-turn task: peer can iterate, push back (via --resume)
+- Want local delegation without leaving the terminal
+
+## When NOT to Use
+
+- Question is factual and I can answer it
+- Task needs my exact context state (use delegate_task on THIS profile)
+- You want to see the peer's chat directly (this is relay-only — full text in `hermes sessions list`)
+
+## Critical Evaluation — You Are the Final Authority
+
+**The peer's output is input, not a decision.** You are the engineer — you own the code, the system, and the final call. The peer is a separate agent with no memory of your conversation, no access to your context, and no ability to verify its own claims against your environment. Treat every finding as a hypothesis to be tested, not a conclusion to be implemented.
+
+**Mandatory before acting on the peer's output:**
+
+1. **Do your own reasoning first.** Before relaying the peer's answer, ask yourself: does this make sense? Is there a simpler way? Would this actually work in our environment? The peer may flag things as BROKEN that are actually correct, or claim PASS on things that are broken.
+
+2. **Push back when the peer is wrong.** If the peer's analysis doesn't hold up, tell it so in a follow-up `--resume` turn. "Your claim about X is wrong because Y. Re-examine." The peer corrects itself when challenged; it doubles down when unchallenged. Do not silently discard a wrong finding — make the peer confront it.
+
+3. **Do your own web searches to validate.** The peer has SearXNG but its interpretation may be wrong. For any claim about API behavior, version compatibility, or tool capabilities, run your own `mcp_searxng_searxng_web_search` and compare. The peer has been wrong about config keys, endpoint behavior, and system state in real sessions.
+
+4. **Involve the user when there's genuine ambiguity.** If the peer and you disagree after a round of pushback, or if the right approach depends on constraints only the user knows, surface the disagreement with both positions stated clearly. Don't silently pick the peer's answer over your own judgment.
+
+5. **Watch for overcomplication.** Peers, like any agent, can overengineer. If the peer proposes a multi-step protocol, a new abstraction layer, or a refactor that touches 10 files for a 1-line bug — ask: "Is there a simpler way?" The best fix is usually the simplest one that actually works.
+
+## Peer Limitations
+
+**The peer has no memory of your conversation.** The peer runs on the testing profile with its own workspace, SOUL.md, and AGENTS.md. It knows nothing about what you've discussed, what files you've created, or what decisions you've made — unless you tell it via the prompt or it reads files by path. Every `ask testing` must be self-contained with all relevant context.
+
+**The peer may fabricate plausible-sounding analysis when it can't verify.** If the peer can't read a file, reach an endpoint, or confirm a claim, it may still produce confident-sounding analysis based on assumptions. When the peer prefaces a claim with "based on the description" or "assuming the config is..." without having actually read the source, treat it as unverified.
+
+**The peer's environment is not your environment.** The peer has its own terminal session, its own working directory, and its own tool state. A command that works in the peer's session may fail in yours. Always test the peer's suggestions locally before deploying.
+
+**Peer self-reports are not verified fact.** If the peer reports a file write, `read_file` the path to confirm. If it reports a test pass, re-run the test if the result matters. If it reports an endpoint returning 200, curl it yourself. The peer may claim "PASS" on things that are actually broken, or flag things as BROKEN that are correct.
+
+## Command
+
+### `ask testing <instructions>`
+
+**First ask (starts the session):**
+```
+hermes -p testing chat -q "<composed prompt>" -Q --max-turns 20 --yolo
+```
+- Output line 1: `session_id: <id>` — capture this
+- Output line 2+: the peer's response
+- Hold the session_id in conversation context for all subsequent asks
+
+**Subsequent asks (resume the session):**
+```
+hermes -p testing chat --resume <session_id> -q "<composed prompt>" -Q --max-turns 20 --yolo
+```
+- Compose prompt with full context (see Prompt Composition)
+- Run command. Parse response (after the session_id line). Relay to operator.
+- Spot-check side-effects (see Spot-check rule).
+
+## Session Persistence
+
+**HARD RULE: Always --resume the prior session for follow-up asks.** The session_id is captured from output line 1 of the first ask. Every subsequent ask in the same line of work MUST use `--resume <session_id>`, not start a fresh session. Starting fresh discards the peer's context, wastes tokens re-establishing state, and breaks multi-turn workflows. If you don't have the session_id, you failed to capture it — that's a separate failure. The session_id lives in conversation context; hold it there.
+
+The session_id lives in conversation context. No state file. If the LXC crashes, we both crash — next session starts fresh.
+
+## Prompt Composition
+
+Peer has NO memory of this session beyond what --resume carries. Every `ask testing` includes:
+- Operator's exact instructions (quoted)
+- All relevant absolute file paths
+- Constraints: investigation-first, real testing, scoped workspaces, privacy-first
+- Background: what's already done, what's decided
+- Expected output format (e.g. "return a 1-paragraph summary + list of files changed")
+- Verification handle: "return absolute path / exit code for any side-effect"
+
+**HARD RULE: Never paste file content into the prompt.** The peer can read any file by absolute path — point at the path instead (e.g. "read /home/n8n/workspace/testing/hindsight_issue.md and validate it"). Pasting wastes tokens and introduces transcription errors: shell expansion of backticks, encoding issues, and prompt bloat. This is the #1 ask-testing failure mode. Only paste inline when the content is under ~5 lines or the peer genuinely can't access the path.
+
+## Pre-Send Audit
+
+Before executing ANY `ask testing` command, run this 3-question checklist:
+
+1. **Is this a follow-up to a prior ask?** If yes, am I using `--resume <session_id>`? Am I sure I have the session_id from the prior output's first line? Starting fresh when I should resume is the #2 failure mode.
+
+2. **Am I pasting file content the peer could read from an absolute path?** If yes, replace with a path reference. Only paste inline when content is under ~5 lines or the peer genuinely can't access the path.
+
+3. **Does this task involve verifying external facts, docs, or behavior?** If yes, include the web search mandate line: "Use `mcp_searxng_searxng_web_search` for every claim and cite the source URL. Do not rely on parametric knowledge or reason about what a command 'would show.' Run the real command, run the real search."
+
+**ALWAYS insist on detailed, multiple web searches.** The peer has the searxng MCP tool (`mcp_searxng_searxng_web_search`). This is non-negotiable — see the **Web Search Mandate** section below for the canonical, must-follow form. Every `ask testing` prompt that involves verifying facts, docs, or external behavior MUST include the mandate line (specified below).
+
+## Web Search Mandate
+
+The peer MUST confirm every external fact with a live web search. Parametric knowledge is not enough. The peer has the `mcp_searxng_searxng_web_search` tool — it MUST use it.
+
+**What the peer must search for (non-exhaustive):**
+- Version numbers, port numbers, env var names, config keys → official docs (hermes-agent.nousresearch.com, docs.openwebui.com, etc.)
+- Package availability, install commands, library APIs → PyPI, GitHub, official README
+- Behavior claims about a service or tool → vendor docs, GitHub issues, changelog
+- Bug claims, "X is broken" verdicts → live probe + cited source
+
+**How the peer must search:**
+- Multiple searches per claim, different angles. A single search is not enough. Official docs + GitHub + PyPI/API reference is the minimum for version-sensitive claims.
+- For every verdict, cite the source URL inline. No URL = unverified = do not relay.
+- Direct the peer to local files by absolute path, not pasted content. Saves tokens and avoids transcription errors.
+
+**Hard rule for the calling agent (you):** Every `ask testing` prompt that involves verifying facts, docs, or external behavior MUST include the line: "Use `mcp_searxng_searxng_web_search` for every claim and cite the source URL. Do not rely on parametric knowledge or reason about what a command 'would show.' Run the real command, run the real search."
+
+This section is the canonical form of the web-search requirement. The abbreviated guidance in Prompt Composition above references it and does not override or weaken it.
+
+## Turn Budget
+
+**Default:** `--max-turns 20` per `ask-testing` invocation. Hard cap. Fine for short delegation, plan reviews, and quick peer checks. If the peer hits 20 before finishing, it returns what it has — operator decides whether to continue.
+
+**Override — 600 turns (operator standing rule):** For accurate, evidence-based plan-building, deep research, or any task where the operator's intent is thoroughness, use `--max-turns 600 --yolo` instead. The 600 is a safety net, not a budget — the operator's exact rule: *"I don't want to be turn restricted. I just want a safety net. I mostly want the job done right. Not concerned with time or tokens when building accurate plan."* See `writing-plans` skill §"Turn Budget" for the canonical rule. Default to 20 only for short factual lookups or quick peer checks.
+
+## Peer Cross-Validation Pattern
+
+When the user wants a deliverable validated, use TWO independent peer passes:
+
+1. **Build the deliverable yourself** (research, write, verify).
+2. **Dispatch peer to build the SAME deliverable independently.** Give the peer the same goal, your file path to read first, and the instruction "find what I missed." Do NOT give the peer your conclusions — let it discover independently.
+3. **Spot-check the peer's claims** against source (file:line, live commands). The peer may find real gaps AND may overstate some findings.
+4. **Report the delta** — what the peer added, what was wrong, what was confirmed.
+
+This is NOT the same as Delegate-Fix-Then-Validate (where the peer does the work and you verify). Here both agents build independently, then you compare.
+
+## Relay Rule
+
+Do not silently paraphrase. Relay the peer's actual response — if long, chunk it. Call out unverified "I did X" claims.
+
+## Disagreement Scan (MANDATORY before applying)
+
+**Do NOT silently accept the peer's recommendations. Do NOT silently drop suggestions you disagree with. Both are failure modes.**
+
+For every peer response, before applying or moving on, do this scan:
+
+**1. Disagreement check.** Walk through the peer's findings. For each:
+   - **Agree + will apply** → no action this step
+   - **Agree + will skip** → state explicitly WHY you're skipping (overkill, environment constraint, contradicts operator's standing rule, etc.). Do not just drop it.
+   - **Disagree** → push back via `--resume`. Either (a) decide it's not worth the round-trip cost and state your reason, or (b) send a follow-up turn challenging the peer's claim. **If you don't push back on at least one item per multi-finding response, you're accepting the peer's framing wholesale — which defeats the purpose of asking.**
+
+**2. Web-reference check for weak conclusions.** For any peer claim that is:
+   - a tool version, API behavior, library status, or compatibility statement
+   - a system state assertion ("profile X is broken", "service Y is down")
+   - a "best practice" assertion
+   - any concrete factual claim that the plan or system will depend on
+
+   …and where the peer did NOT cite a source URL inline OR run a live command to verify, send a follow-up demanding the verification. Pattern: "Show me the command output that supports X. I want a URL or a live test, not reasoning." This combines with the Web Search Mandate above — the peer MUST search, not reason.
+
+**3. Internal consistency check.** Does the peer's response contradict itself, or contradict a prior turn in this peer session? If yes, point it out in the next follow-up. Don't apply a contradictory recommendation.
+
+**Output format for the scan (use this when relaying the peer's response to the operator):**
+```
+[Peer's findings as-is]
+
+## My disagreement scan
+- **Agreed and applied:** [list]
+- **Agreed but skipped:** [item] — [reason]
+- **Disagreed and pushed back:** [item] — [what I said]
+- **Web references / live tests requested:** [items where I demanded a URL or run]
+- **Disagreed silently dropped:** (should be empty — if not, justify)
+```
+
+If `Disagreed silently dropped` is non-empty, that's a bug. Surface it.
+
+## Spot-check Rule
+
+Peer self-reports are not verified fact. If the peer reports a file write, `read_file` the path to confirm. If it reports a test pass, re-run the test if the result matters.
+
+**Peer verdicts can be WRONG.** A peer may flag a profile as BROKEN when it's actually healthy, or claim PASS on something that's broken. Always independently verify the peer's conclusions — don't relay them as fact.
+
+## Delegate-Fix-Then-Validate Pattern
+
+When the user says "ask testing to fix X, then YOU validate," follow this exact sequence:
+
+1. **Compose findings + goal.** Write a clear prompt with: what's broken, what the correct state should be, file paths, constraints (read-only vs. allowed changes), and expected output format.
+2. **Dispatch peer to fix.** Run `hermes -p testing chat -q "..." -Q --max-turns 20 --yolo`. The peer does the work.
+3. **Independently validate.** Do NOT trust the peer's self-report. Verify every claim: stat files, curl endpoints, read configs, check daemon logs. The peer may claim "PASS" on things that are actually broken, or flag things as BROKEN that are correct.
+4. **Report the validated results** — not the peer's raw self-report.
+
+**CRITICAL: Do NOT jump in and do the fix yourself.** If the user said "ask testing to fix it," the peer does the fixing. You only validate afterward. Doing the fix yourself violates the user's explicit instruction and skips the peer review step.
+
+## Common Pitfalls
+
+1. **Profile flag required.** Use `-p testing` — the sticky default may be general, which would spawn a clone of this agent, not a peer. Always pin the profile explicitly.
+2. **--yolo is required.** The peer runs headless (one-shot, no TTY). Without `--yolo`, dangerous-command approval prompts fail closed (60s timeout → deny) and the peer can't complete tasks that trigger them. `--yolo` bypasses all approval prompts for the peer session only. The hardline blocklist (rm -rf /, fork bombs, mkfs on root, dd to block devices) still applies — no flag overrides that. This does NOT change the testing profile's config; it only affects the peer session.
+3. **Do NOT use interactive REPL mode.** Running `hermes -p testing` without `chat -q` (interactive REPL) was tried and failed — the TUI produces unreadable ANSI redraw noise when driven via `terminal(pty=true)`. The output is garbled and responses cannot be extracted. Always use headless `chat -q "..." -Q` instead.
+4. **Peer is headless.** Operator sees my relay, not the peer's chat. Full text in `hermes sessions list` if needed.
+5. **Peer self-reports are not verified fact.** Spot-check file writes, test passes before confirming to operator.
+6. **Peer's workspace is its own.** Files written to the peer's workspace are NOT in this agent's workspace. Give ABSOLUTE paths (e.g. `/home/n8n/workspace/testing/<path>`) if the peer should write to our workspace.
+7. **Blast radius.** Peer has ALL tools (terminal, web, MCP) — can rm, exfil, burn tokens. Bound with prompt-level constraints. State the blast radius to operator for sensitive tasks.
+8. **Turn budget is hard-capped.** `--max-turns 20` enforces it. If the peer hits 20 before finishing, it returns what it has — operator decides whether to continue.
+9. **Don't silently paraphrase.** Relay the peer's actual response. If long, chunk it. Call out unverified claims.
+10. **Peers can overstate findings.** A peer may correctly identify real gaps AND incorrectly flag things that aren't actually broken. Always verify each claim independently; don't assume all of a peer's findings are correct just because some are.
+
+## Verification Checklist
+
+- [ ] First `ask testing <task>` returns peer's response showing real tool use
+- [ ] `session_id:` captured from output line 1
+- [ ] Second ask with `--resume` — peer remembers prior turn
+- [ ] Spot-check: peer reports "wrote file at /path" → I `read_file` /path and confirm content matches

deep-research/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: deep-research
 description: Dispatch exhaustive deep web research to the research profile. Triggered by "deep research", "ask web", or "research this". The research profile runs with the deep-web-research skill loaded — six-move flow, external ledger, mechanical saturation, disconfirmation, condensation from disk.
-version: 2.2.0
+version: 2.2.1
 author: Hermes Agent
 license: MIT
 platforms: [linux]
@@ -23,12 +23,12 @@ See `references/design-rationale.md` for the v2.0 architecture decisions and Cla
 
 ## Clarifying Questions (Before Dispatch)
 
-If the operator's question is ambiguous enough that the research agent would waste the first ~20 turns guessing, ask clarifying questions BEFORE dispatching. Cap is tight on purpose — if you find yourself writing more than 5, the question itself is under-specified and the right move is to push back to the operator, not interrogate them.
+If the operator's question is ambiguous enough that the research agent would waste the first ~20 turns guessing, ask clarifying questions BEFORE dispatching. The user wants maximum clarity — err on the side of asking.
 
 **Limits:**
-- **Default cap: 3 questions.** Most well-formed questions need 0–3.
+- **Default cap: 5 questions.** Most well-formed questions need 0–5.
-- **Hard cap: 5 questions.** Only if the question has multiple high-stakes branches that genuinely change the research strategy.
+- **Hard cap: 10 questions.** For complex, multi-branch research where precision matters.
-- **Abort at 6+:** If you think you need more than 5, the question is under-specified. Stop and tell the operator: "This question has too many branches to dispatch cleanly. Can you narrow it to [specific scope]?" Do NOT fire 6+ questions.
+- **Abort at 11+:** If you think you need more than 10, the question is under-specified. Stop and tell the operator: "This question has too many branches to dispatch cleanly. Can you narrow it to [specific scope]?" Do NOT fire 11+ questions.
 
 **When to ask vs. when to dispatch:**
 - Ask when the answer would change the research strategy (e.g., "Are you researching a person, a company, or a topic?" — different toolkits).
@@ -52,6 +52,19 @@ hermes -p research -s deep-web-research chat -q "<question>" -Q --max-turns 600
 hermes -p research -s deep-web-research chat --resume <session_id> -q "<follow-up>" -Q --max-turns 600 --yolo
 ```
 
+## Post-Dispatch Behavior (MANDATORY)
+
+**After dispatching, continue working with the user. Do NOT poll, wait, or check for results unless the user explicitly asks.**
+
+- The research runs as a background process. It will complete on its own.
+- Do NOT call `session_search` on the research session to check progress.
+- Do NOT call `process wait` or `process poll` on the background process.
+- Do NOT proactively surface results when the background process completes.
+- **Only check for results when the user explicitly asks** (e.g., "what did the research find?", "is it done?", "show me the results").
+- When the user asks, use `session_search` on the research profile with the captured session_id to retrieve and relay the condensed answer.
+
+The session_id is captured from output line 1 and held in conversation context for follow-up questions and result retrieval. No state file needed.
+
 ## What the Research Agent Does
 
 The `deep-web-research` skill on the research profile enforces:
@@ -65,6 +78,28 @@ The `deep-web-research` skill on the research profile enforces:
 
 The research agent writes all findings to `/tmp/research-<sid>.md` (external ledger) and uses a phase gate file to enforce completion before condensing. Mechanical saturation checks (`grep -c`) prevent endless searching. Re-strategize checkpoints after Move 2 and every ~10 findings during Move 3 enable mid-research pivots.
 
+## Tool Selection Strategy
+
+The research agent must determine the best tools for each research type — not use a fixed set. Analyze the question and select from the full arsenal:
+
+| Research Type | Primary Tools | Secondary Tools |
+|---|---|---|
+| **Person/identity** | SearXNG (people search engines, social media), web scraping (full pages) | Browser (dynamic sites), Python (data enrichment) |
+| **Email/phone** | SearXNG (breach databases, public records), web scraping | Browser (captcha-walled sites), Python (pattern analysis) |
+| **Software/tech** | SearXNG (GitHub, docs, PyPI/npm), web scraping (changelogs, issues) | Terminal (live version checks), Browser (interactive docs) |
+| **Politics/news** | SearXNG (news category, multiple engines), web scraping (primary sources) | Browser (paywalled articles), Python (timeline analysis) |
+| **AI/ML** | SearXNG (arxiv, papers, HuggingFace), web scraping (model cards, benchmarks) | Terminal (live API probes), Python (data analysis) |
+| **General topic** | SearXNG (general + news + scholarly), web scraping (authoritative sources) | Browser (interactive content), Python (synthesis) |
+
+**Tool selection rules:**
+- Always use multiple SearXNG engines per search — never rely on a single engine
+- For any claim about a live system, run a terminal probe (curl, ping, API call) — don't just search
+- For version-sensitive claims, check at least 2 independent sources (docs + GitHub + PyPI)
+- For paywalled or JavaScript-heavy content, use the browser tool
+- For data that needs aggregation or analysis, use Python in the terminal
+- Docker-based tools (SearXNG, Playwright) are available and should be used when appropriate
+- The research agent has full terminal, file, web, browser, and Python access — use all of them
+
 ## When to Use
 
 - User says "deep research", "ask web", "research this", "deep dive on"
@@ -103,6 +138,7 @@ The research agent self-reports are not verified fact. If it claims a file write
 5. **Don't re-condense.** The research agent already produced a condensed answer. Relay it, don't summarize it further.
 6. **Don't do the research yourself.** If the user triggers deep research, dispatch it. Don't run a few searches and call it done. This is the #1 failure mode: the agent runs 2-3 `mcp_searxng_searxng_web_search` calls, gets empty results, and gives up. That's not deep research — that's a casual lookup. If you catch yourself typing `mcp_searxng_searxng_web_search` for a deep research request, STOP. You're doing it wrong. Dispatch to the research profile.
 7. **The methodology skill lives on the research profile.** `deep-web-research` is at `~/.hermes/profiles/research/skills/research/deep-web-research/SKILL.md`. It does NOT exist on the general profile. Don't search for it here — it won't be found. The general profile only has this delegation skill.
+8. **Dispatcher/methodology coordination is a two-skill contract.** This skill (the dispatcher) caps clarifying questions at 5 default / 10 max and aborts the dispatch if the question is under-specified. The `deep-web-research` methodology skill (on the research profile) handles the same problem differently because it's headless — it can't ask the operator, so it aborts with a structured under-specification report naming the plausible interpretations. When updating one, update the other to match. Drift between the two causes the dispatcher to think the question is dispatchable while the methodology aborts it, or vice versa — both waste turns.
 
 ## Pre-Dispatch Reasoning Check (MANDATORY)