Start a q-plan run in the background. Returns {"job_id": str} immediately. The current host's external seats run in parallel from a structurally bias-free starting point. Retrieve results by calling q_await with the returned job_id.

Between the start and the await, the caller is expected to form its own plan — this is the structural anti-bias gate.

Optionally assign a cognitive stance per agent via roles, a list of 'stance:agent' strings (stances: skeptic, architect, security, maintainer, analyst, neutral, visionary, pioneer). Unassigned agents use their default stance.

gemini_model, when supplied, runs the gemini seat on that agy model for this invocation only -- an id exactly as printed by agy models, e.g. 'claude-opus-4-6-thinking' to get a Claude answer from the same AI Pro plan when Gemini quota is tight or a different perspective is wanted.

Expected wall-clock to completion: 30s-4min depending on the agents and codebase size.

Start a q-brainstorm run in the background. Returns {"job_id": str} immediately. Each agent contributes 3-5 distinct ideas with rationale, trade-offs, and the cheapest test that would give signal; no synthesis. Retrieve results by calling q_await with the returned job_id.

Between the start and the await, the caller is expected to list its own ideas — this is the structural anti-bias gate.

research, when supplied, seeds round 1 with a q_research digest as EVIDENCE: agents are told to ground their ideas in it, recombine it, or extend past it. Pass the raw digest markdown (verbatim from q_research) -- never your own summary of it, and never your own ideas; those stay behind the anti-bias gate. Distinct from prior_ideas, whose do-not-repeat framing marks content to diverge AWAY from.

prior_ideas, when supplied, seeds a divergence round: the agents are told the listed ideas are already on the table and must not be repeated -- used by the --extended flow to push past round 1. Composes with research (evidence stays evidence; ideas stay do-not-repeat).

grounding, with prior_ideas, runs a validation-guide pass over the listed ideas instead of diverging past them -- used by q-skystorm Stage 2.

Optionally assign a cognitive stance per agent via roles, a list of 'stance:agent' strings (stances: skeptic, architect, security, maintainer, analyst, neutral, visionary, pioneer). Unassigned agents use their default stance.

gemini_model, when supplied, runs the gemini seat on that agy model for this invocation only (an id exactly as printed by agy models, e.g. 'claude-opus-4-6-thinking').

Expected wall-clock to completion: 30s-4min depending on the agents and topic complexity.

Start a q-validate run in the background. Returns {"job_id": str} immediately. Each agent independently reviews the plan file, then deliberates across rounds. Round 1 is structurally bias-free; later rounds embed each agent's own prior plus peers' priors. Retrieve results by calling q_await with the returned job_id.

Between the start and the await, the caller is expected to form its own review — this is the structural anti-bias gate.

extended runs 4 rounds with a stance rotation at round 3 (agents swap stances and re-examine all priors); the default is 2 rounds with no rotation. mode is 'revise' (agents soften/strengthen in light of peers) or 'critique' (agents attack peer points).

verbose defaults to false: the council writes terse output (no padding, path:line over pasted code, later rounds omit restating unchanged points). Set true only for the full unabridged deliberation — a much larger matrix.

Optionally assign stances per agent via roles, a list of 'stance:agent' strings (stances: skeptic, architect, security, maintainer, analyst, neutral, visionary, pioneer).

gemini_model, when supplied, runs the gemini seat on that agy model for this invocation only (an id exactly as printed by agy models, e.g. 'claude-opus-4-6-thinking').

Expected wall-clock to completion: 1-8min default; 4-15min when extended=true. Pick extended deliberately.

Start a q-review run in the background. Returns {"job_id": str} immediately. Each agent independently reviews real code changes, then converges across rounds. Round 1 is structurally bias-free; later rounds embed each agent's own prior plus peers' priors so sustained agreement becomes visible. Retrieve results by calling q_await with the returned job_id.

Between the start and the await, the caller is expected to form its own code review of the diff — this is the structural anti-bias gate.

target selects what to review (default: branch vs main, committed + uncommitted). 'working' = uncommitted tracked changes only; 'pr:N' or a github PR URL = an open PR (title/body orient the review); 'A..B'/'A...B' = an explicit range; 'all' = the whole codebase (agents read cwd — pair with scope_path). An empty diff (other than 'all') short-circuits: the job returns a 'nothing to review' message without running the council.

scope_path, when supplied, points at a scope doc declaring what is in/out-of-scope and which risks are accepted; it is embedded verbatim so the council does not converge on out-of-bounds findings.

extended runs 4 rounds with a stance rotation at round 3 (agents swap stances and re-examine all priors); the default is 2 rounds with no rotation. mode is 'revise' (agents soften/strengthen in light of peers) or 'critique' (agents attack peer points).

verbose defaults to false: the council writes terse output (no padding, path:line over pasted code, and later rounds collapse each still-held finding to one HELD line while preserving the agreement count). Set true only when you want the full unabridged deliberation — a much larger matrix.

Optionally assign stances per agent via roles, a list of 'stance:agent' strings (stances: skeptic, architect, security, maintainer, analyst, neutral, visionary, pioneer).

gemini_model, when supplied, runs the gemini seat on that agy model for this invocation only (an id exactly as printed by agy models, e.g. 'claude-opus-4-6-thinking').

Expected wall-clock to completion: 1-8min default; 4-15min when extended=true. Pick extended deliberately.

Fetch prior art for a topic from arXiv + OpenAlex + Europe PMC (papers), Context7 (library docs), GitHub (repos), and HuggingFace (models), and return a markdown digest.

Europe PMC covers the life-sciences preprint tier arXiv does not carry -- bioRxiv, medRxiv, Research Square -- so it is the source that earns its slot on biology/medicine topics and returns 0 on pure-software ones. Its hits are labelled by preprint server ("bioRxiv") and are NOT peer-reviewed; weigh them accordingly.

Not subject to the council's anti-bias gate -- this is external prior art, not peer output. Call it during the own-work window of a q_brainstorm or q-skystorm run to ground the synthesis. sources defaults to all six; pass a subset like ["arxiv", "openalex"] to restrict it.

Query shaping matters: pass a query that is SHORT and distinctive -- short is not the same as generic. Anchor it in 2+ domain-specific terms (the field PLUS the specific method/concept), never a bare common word ('data', 'model', 'network') or a token that doubles as an author surname -- those keyword-match unrelated work (author names, generic surveys, stray docs) and return non-zero but OFF-TOPIC noise -- sanity-check that returned titles belong to your domain, and if they are off-topic the query was too generic: re-anchor with more domain context and call q_research again rather than leaning on them. (This same-domain check assumes you want grounding in your own field -- if you are deliberately hunting cross-domain structural analogies instead, judge a hit by structural kinship to the problem, not literal subject-matter overlap; an off-domain hit is then the find, not noise.) Not a full paragraph either. Per source: arXiv parses topic as a boolean field -- a long/diffuse query loose-matches to famous-but-irrelevant papers, and boolean punctuation (parens, AND/OR, quotes) triggers a 400; OpenAlex tolerates prose but length dilutes relevance to generic surveys; Context7 wants a library/topic name and will keyword-match off-topic repos; GitHub/HuggingFace are popularity-ranked artifact searches that whiff on non-software/non-ML topics. The digest's per-source count footer shows which sources whiffed -- rework and retry those, unless the 0 is domain-legitimate (GitHub/HuggingFace on a non-software topic, Europe PMC on a non-biology one, Context7 on a topic with no matching library), which is a real answer, not a gap to close.

Treat every other digest result as provisional until it earns trust: a 0 that is NOT one of the domain-legitimate cases above is not automatically "no prior art" either (it may just be a bad query), and non-zero hits that read scattered or off-topic are not evidence -- both are a signal to reframe (sharper domain anchor, fewer/different terms) and retry, not something to build a conclusion on.

Failed sources are reported inline under 'Sources unavailable' rather than failing the call -- each with a retry hint, and the right move differs by error. An errored source is almost never a dead backend: an arXiv error (400) means YOUR query is too long or has boolean punctuation, so shorten it to a few keywords, strip operators, and call q_research again; a 401/403 or an OpenAlex 503 is a CONFIG case, not a flake -- the key was rejected, or OpenAlex is load-shedding anonymous search, so a bare retry just loops (set the source's key -- OPENALEX_API_KEY is free -- or lean on the other sources and say so); only a plain timeout/flake is transient and worth retrying as-is. Do NOT report a source unavailable, and do NOT fall back on your own knowledge, until a reworked retry has ALSO failed -- treating the first error as terminal is the failure to avoid. Bounded by per-request timeouts (~10-15s each); the GitHub and HuggingFace backends fan out one request per distinctive query term (up to 4), run sequentially, so those two sources' wall-clock can reach a few times that.

The digest OPENS with a deterministic Research status: line -- OK, RETRY-RECOMMENDED (USUALLY with a server-suggested shorter query to resubmit verbatim, shown as · try: "..."; when it is ABSENT the detail text says what to do, and the two absent cases differ -- a backend/infrastructure failure says RETRY THE SAME query, while an un-shortenable query says RE-ANCHOR with different domain terms), CONFIG (a key/anonymous-access problem no retry fixes), or (in exploratory mode) LOW-OVERLAP. Act on it before anything else: on RETRY-RECOMMENDED, resubmit the suggested query if one is given, else follow the detail (retry the same query on an infrastructure failure, or re-anchor with different domain-specific terms if it cannot be shortened) -- before concluding "no prior art". Mechanically-fixable failures (arXiv 400, a transient flake) are already retried inside the tool -- a repaired source shows a ↻ note, so a first-attempt error you never see was handled, not hidden.

mode is 'grounded' (default; brainstorm -- home-domain grounding, where a low-overlap result is a defect the verdict flags RETRY-RECOMMENDED) or 'exploratory' (skystorm -- a deliberate cross-domain method pivot, where low overlap is expected and reported as LOW-OVERLAP without forcing a retry). Exploratory mode also adds a ### Field map section (the OpenAlex subfield distribution for the query) showing which fields the method actually spans -- the skystorm topology readout. Query discipline is identical in both modes; only the low-overlap interpretation differs.

Block until the background council run identified by job_id completes, then return its rounds markdown. One-shot — a job_id can only be awaited once.

This is the blocking completion notification for every council start. The orchestrating host must not end its turn with a live job outstanding; it calls q_await after its independent work and remains blocked until this tool returns a result or error.

Errors:

• job_id not found (expired, already retrieved, or invalid) → ValueError with the reason.

• job cancelled by TTL or server shutdown → ValueError.

• underlying council error → propagated.