ask

# ask ## Stop First If the user names `$ask`, `/ask`, an ask mode, oracle, deep review, parallel review, roundtable, argue, CAE gap review, or ask DAG, read this whole file before acting. Then use the real runtime entrypoint unless the user explicitly asks for a fallback or the runtime is unavailable and that fallback is reported. Do not substitute `spawn_agent`, a plain model call, a plain web search, a manual summary, or an invented review for `$ask`. ## Runtime Entrypoint Run commands from this directory. Pi skill-command syntax such as `/skill:ask webgpt What is 2 + 2?` is a first-class shortcut: the leading browser handler (`webgpt`, `webclaude`, `webkimi`, `webgemini`, or `webgrok`) routes to a Tau `single-call` browser-handler DAG with `--execute --json`. Inline Pi skill references such as `$ask webgpt What is 2 + 2?` and the spaced natural language spelling `$ask web gpt What is 2 + 2?` must be treated the same way (`web gpt` normalizes to `webgpt`). This is only a compatibility shortcut for Pi users; it must not use the removed direct WebGPT oracle path. `./run.sh tau-dag "<request>"` maps to the Typer `tau-dag run` subcommand internally. `./run.sh team-plan "<request>" --team <preset>` renders a role-based multi-agent plan and frozen Tau DAG preview; execution requires explicit `--execute --live` (see README "Team Orchestration"). ```bash cd skills/ask ./run.sh --help ./run.sh webgpt What is 2 + 2? ./run.sh webgpt --compile-only What is 2 + 2? ./run.sh ask --help ./run.sh tau-dag run --help ``` Every nontrivial run must preserve the runtime artifacts. The standard artifact set is: - `<ask_id>.request.json` - `<ask_id>.status.json` - `<ask_id>.events.jsonl` - mode-specific outputs such as `review.md`, `review.json`, DAG manifests, or browser evidence Runtime artifacts default under `.ask_artifacts/runs/<ask_id>` or the provided `--run-output-root`. For long, live, or generated runs prefer a storage-backed root such as `/mnt/storage12tb/skills/ask/outputs/...`. Do not commit generated ask artifacts. Every executed handler call (success or failure) is recorded to the `ask_call_log` collection in `$memory` at the execution choke point, with handler, status, failure_code, and `controlled_tab_id`/conversation URL when present, plus the proven method of the last successful call (reasoning selection, tab binding, lifecycle mode, dispatch command with secrets redacted). Model ids are validated against the live SciLLM catalog at compile (`invalid_scillm_model_id` BLOCKED with nearest valid alternatives); a browser seat with 3+ consecutive recorded failures is flagged as known-bad before dispatch with its failure codes. Check a seat before relying on it: `python3 skills/ask/scripts/ask_call_history.py --handler webgemini` prints the last successful call and recent failures; add `--recommend` for the exact proven method to reuse. A handler with no recorded success is a blind guess — compile-only or probe cheaply first. Historical runs are backfillable: `python3 skills/ask/scripts/backfill_call_log.py [outputs-root]` ingests every on-disk node receipt idempotently (deterministic _key per run+node). Every EXECUTED run's result JSON (and `execution-status.json`) also carries `handler_last_success`: per seat, the last successful method from memory (conversation URL, tab, lifecycle/layout), current consecutive failures, and failure codes to avoid — returned in context so the project agent never needs a separate history lookup after consuming a run. ## Deep-Dive References (read on demand) | Before doing this | Read | | --- | --- | | `team-plan` with a plan file; `status --run --projection` | `references/plans-and-status.md` | | Explicit Pi-native subagent target | `references/pi-subagents.md` | | Turning ask output (one-shot/roundtable/compete/clean-room) into subagent lanes | `references/lane-handoff.md` | | `herdr list/who/send` to another agent's pane | `references/herdr.md` | | Choosing one-shot vs roundtable vs compete; model/effort selectors | `references/modes.md` | | Panel audits, seat roster, rate-limited seats, webclaude policy | `references/seats-and-audits.md` | | Executing/supervising any live run (monitoring, windows, payload matrix, unblock, drift) | `references/operations.md` | | Any run failure | `references/diagnosis.md` | | Compiling/executing any multi-seat DAG (roundtable/compete/creator-reviewer) | `references/workflows.md` | | Any browser-handler execution | `references/browser.md` | ## Four Kinds Of Target `/ask` addresses four peer target types. They differ in transport, not in standing: | Target | Example | Transport owner | | --- | --- | --- | | **Herdr session** — a live agent in a pane | `memory`, `w11:p13` | `$monitor-herdr` via `herdr pane run` | | **Model call** — API/model handler | `gpt-5.5-high`, `Codex-opus-5-high`, `deepseek-ai/DeepSeek-V3.2-TEE` | `$tau` (SciLLM is internal to Tau) | | **Web model** — browser-backed reviewer (chat tab, NOT the agentic model; see the `webclaude` warning below) | `webgpt`, `webclaude`, `webkimi` | `$surf` + `$browser-oracle` | | **Pi-native subagent** — local Pi child advisor/worker | `pi reviewer`, `subagent general-purpose`, `local coder` | `pi-subagents` native `subagent` tool | A project agent should not care which side is browser, model, Herdr session, or Pi-native subagent beyond naming the target. ## Project-Agent Quickstart Start here when the user asks for a single model call, roundtable, competition, or creator-reviewer loop. Use one of these shapes; do not invent a custom orchestration path. | User intent | Command shape | | --- | --- | | One handler answers | `./run.sh tau-dag "<task>" --repo <repo> --target <target> --immutable-goal "<goal>" --handler <handler-or-model> --execute --json` | | Roundtable | `./run.sh tau-dag "<shared task>" --repo <repo> --target <target> --immutable-goal "<goal>" --dag-template roundtable --handler <a> --handler <b> --topology concurrent --execute --json` | | Competition | `./run.sh compete "<isolated task>" --repo <repo> --target <target> --immutable-goal "<goal>" --handler <a> --handler <b> --criterion <criterion> --execute --json` | | One-shot (per-seat answers, no consensus) | `./run.sh one-shot "<question>" --handler <a> --handler <b> --handler <c>` — N independent single-call lanes run concurrently; each returns its own nonce-bound answer or a named blocker. Partial answers are DEGRADED-but-usable (exit 0 at or above `--min-answered`); a roundtable's quorum refusal never applies here. | | Pi-native subagent from inside Pi | `subagent({ action: "list" })`, then `subagent({ agent: "<agent>", task: "<task>" })` or one `workflowScript` fanout. This is for explicit `pi`/`subagent`/`local reviewer` targets only; it is not a replacement for Tau/browser handlers. | | Creator then reviewer | `./run.sh tau-dag "<creator task then reviewer verdict>" --repo <repo> --target <target> --immutable-goal "<goal>" --dag-template creator-reviewer --handler <creator> --handler <reviewer> --topology sequential --execute --json` | | Diagnose/fix/close GitHub issues | `./run.sh fix-issues --repo <owner/name> --issue <N> [--issue <M>] [--handler gpt-5.5] [--execute]` — gathers each issue via `gh`, diagnoses through a live one-shot handler into structured cause/fix JSON with the **debugger ladder gate** (`needs_debugger` recommends `$debugger` only when the failing transition is in-process runtime state no artifact explains), and is fail-closed: dry-run by default; `--execute` closes an issue ONLY after its named verify command (typically an `$agentic-evals` fixture) actually passes. No verify → `blocked`; failing verify → `verify-failed`, issue stays open. Per-issue receipts under `outputs/fix-issues/`. Gate: `fixtures/fix_issues.json`. | Handlers are peers even when their transports differ. Browser handlers (`webgpt`, `webclaude`, `webkimi`, `webgemini`, `webgrok`) run through `$surf` and `$browser-oracle`. API/model handlers such as `gpt-5.5-high`, `gpt-5.5-xhigh`, `Codex-opus-5-high`, or `chutes deepseek-ai/DeepSeek-V3.2-TEE` are routed by Tau. Project agents should not care which side is browser or API beyond naming the handler. Handlers are peers whether browser-backed (`webgpt`, `webclaude`, `webkimi`, `webgemini`, `webgrok` via `$surf`/`$browser-oracle`) or API-backed (`gpt-5.5-high`, `claude-opus-5-high`, `chutes <provider/model>` via Tau). Before executing any multi-seat DAG: compile first (omit `--execute`), show the human the printed ASCII chart, and run only on confirmation. Full mode examples and selector rules: `references/modes.md`. Full protocols and fail-closed tables: `references/workflows.md`. ## Non-Negotiables For Every Run - An explicit immutable goal (`--immutable-goal` or a labeled `Immutable goal:` line) is required for roundtable, creator-reviewer, and compete; missing goal fails preflight with `NEEDS_INTERVIEW` before any handler is contacted. - Roundtables are ALWAYS `--topology concurrent` with an identical packet for every seat. Compete candidates are isolated and never see each other. - Executed DAGs must be monitored to a terminal verdict via the run's JSON stream artifacts (`events.jsonl`, `dag-progress.json`, node receipts, `execution-status.json`); do not launch and walk away. - `PASS` is reviewer/model evidence only; local closure requires deterministic local proof. `DEGRADED`/`NEEDS_ATTENTION`/rate limits are lane-local: keep usable seats, follow the failed lane's recovery packet. - Non-streaming API completions must pass typed admission with `finish_reason=stop` before their text can count as evidence. Truncated, filtered, missing-finish-reason, or malformed completions emit `scillm_response_incomplete`; retain raw bytes and `response.meta.json` validation errors. Do not repair partial verdict text or retry automatically. Retained cases: `completion-admission-rejects-truncation` (captured replay) and `completion-admission-live-positive` (real provider readback). - Failures are non-silent: every failed lane exposes `failure_code`, a recovery packet, and `next_command`/ticket instruction. On any failure, read `references/diagnosis.md` and dispatch on the owning receipt before theorising. - Direct WebGPT oracle routing (`$ask chatgpt`, `--oracle-backend webgpt`, `--webgpt-*`) fails closed; Tau browser handlers remain supported. - **Follow-up continuity:** every browser lane's node receipt / `response.meta.json` must carry `controlled_tab_id` and the conversation URL; a null tab id is a failed handoff. When the human may ask clarifying or follow-up questions, run with `--browser-tab-lifecycle fresh-keep` (or `reuse-bound`) — the default `auto`/fresh-temporary CLOSES the window after the run, killing the conversation. After the run, report the tab id + conversation URL and bind them (`skills/browser-oracle/run.sh bind <project> --backend <b> --tab-id <id> --url <url> --manual`) so the follow-up targets the same session. - **Tab visibility gate (observed 2026-09-15, webgemini):** some providers (Gemini confirmed) defer the composer send while the tab is a hidden document — in a shared window only one tab can be frontmost, so N-1 of N concurrent lanes are always hidden and stall as `prompt_too_large_or_stalled` ("prompt remained in the composer after send"). Concurrent browser lanes therefore default to isolated windows (one window per seat, placed on the reviewer desktop) so every lane tab is a visible document; `--window-layout shared` is opt-in. A stalled already-typed composer is salvageable: `skills/surf/run.sh tab.switch <id>` makes the tab visible and the queued send dispatches. Check `document.visibilityState` before shrinking prompts for this failure class. The verified per-seat working method is stored in `$memory` (`ask_call_log` key `ask:method:webgemini`; see `ask_call_history.py --handler webgemini --recommend`). - `webclaude` is a claude.ai chat tab, testing-only — NOT agentic Claude. Prefer `claude-fable-low`, then `claude-opus-4-8-high` (see `references/seats-and-audits.md`). ## Mode Router Use the narrowest mode that matches the user request. | Request | Runtime pattern | Required details | | --- | --- | --- | | Memory-backed question | `./run.sh ask "<question>" --json` | Include scope when relevant. | | Oracle answer | `./run.sh ask "<question>" --oracle ... --json` | Choose backend/model/persona explicitly when requested. | | Pi browser-handler shortcut | `./run.sh webgpt What is 2 + 2?` from `/skill:ask webgpt What is 2 + 2?` | Rewrites to Tau `single-call` with `--handler webgpt --execute --json`; use `--compile-only` to emit the DAG without live browser transport. | | Single named handler | `./run.sh tau-dag "<request>" --handler <handler-or-model> --json` | Browser handlers use `$surf`; non-browser handlers are `$scillm` model names routed by Tau. Add `--execute` for live transport. | | Pi-native subagent target | Native Pi `subagent` tool, after `subagent({ action: "list" })` | Only when running inside Pi and the user explicitly names `pi`, `subagent`, `pi-subagent`, `local reviewer`, or `local coder`. Browser/model/Tau Ask requests do not use this route. | | Multi-handler roundtable | `./run.sh tau-dag "<request>" --handler webclaude --handler gpt-5.5 ... --topology concurrent --execute --json` | Roundtable is prompt-to-Tau-DAG. Browser handlers get an Ask-owned fresh window by default. Preserve `browser-tab-lifecycle.json`, `dag.json`, command specs, handler receipts, and join receipts. | | Compete / bakeoff | `./run.sh compete "<task>" --handler webgpt --handler webclaude --handler gpt-5.5-high --criterion deterministic-proof --execute --json` | Isolated candidates plus compete scorecard and winner continuation request. Browser/API handlers are peers. Project agent must locally verify features before promotion. | | Creator-reviewer loop | `./run.sh tau-dag "<request>" --handler <creator> --handler <reviewer> --topology sequential --json` | The reviewer receives prior handler receipts. Pass/fail requests require a verdict in the reviewer response. | | Supported direct browser oracle | documented browser mode such as `webgemini`, `webkimi`, `webperplexity`, or `cursor-browser` | Use only when the user asks for that direct mode; attach local target content when browser cannot read paths. | | Deep review | `./run.sh ask "<question>" --deep-review --deep-review-target <path> ... --json` | Pass complete target bundle; return `review.md` and `review.json`. | | Parallel review | `./run.sh ask "<question>" --parallel-review ... --json` | State reviewer count/focus and preserve per-reviewer outputs. |