AlphaCouncil Agent

Use this plugin when the user invokes @alphacouncil-agent or asks for a multi-agent public-equity research workflow.

Agent-Skills Governance

Also apply ../agent-skills-governance/SKILL.md before planning, running, synthesizing, or reporting. That bundled skill provides the agent-skills-style anti-laziness gates for every installer of this plugin; it is not a separate local dependency.

Method-lens references

When the user asks to compare methodologies, inspect how one or all methods reason, or test a public investor Skill, also apply ../alphacouncil-method-lenses/SKILL.md. It routes to 26 on-demand, hash-bound method_reference_provisional files and excludes persona voice from the method contract. During a council run it is an explanation layer only: the physical PersonaPack deterministic executor remains the decision authority, and the Skill may not alter a frozen stance, native state, decisive rule, or input hash.

Mandatory Council Contract (MUST READ FIRST)

Every council run has an explicit council_mode. full is the default. Never infer quick from impatience, a short prompt, a deadline, or a model/tool failure, and never switch modes after Stage 0.

• Full council (`full_v2`): first bind an independent analyst scope. core runs the 8

mandatory evidence roles (market_data, earnings_deep_dive, forward_expectations, quant_factor, valuation_long_short, news_industry_management, insider_sec, ib_event_analysis); all runs those eight plus macro_regime, market_narrative, and social_pulse, for exactly 11 analyst seats. Then every selected master, then the three-round bull/bear cross-exam, then portfolio_manager. In the plugin-managed headless path every receipt-bound analyst role starts in one parallel wave; each selected v3 method freezes its deterministic stance before an isolated voice worker explains scored decisions; frozen headless abstentions retain a deterministic explanation without another call; and Bull/Bear run in parallel within each round with a barrier between rounds. Every selected analyst seat is equally mandatory. A mandatory evidence failure is a fail-fast barrier: persist the failure and final diagnostic artifacts, skip masters/debate/PM model calls, and terminate incomplete; do not synthesize around it. Headless full runs at one of three depth tiers set by council_pace: fast 900000 ms, normal (default) 1800000 ms, slow 3600000 ms, queue-to-terminal-persistence. It fails closed at expiry and does not promise all-seat success when external services deteriorate.

• Quick council (`quick_v1`): only the plugin-managed headless analyze_symbol path may

execute it. It runs the four fixed evidence roles in parallel, 1-4 selected methods in parallel, one parallel bull/bear statement, and one short PM inside the hard 600000 ms end-to-end ceiling. It is not a shortened claim of full-council completion.

• You MUST NOT answer single-pass from model knowledge, skip a planned seat silently, or call

plan_visible_run and jump directly to a PM decision. plan_visible_run rejects quick.

• Completeness is mode-aware. Full is complete only when all planned evidence, selected

methods (including deterministic out_of_scope decisions), all required debate rounds and the PM are recorded. Plugin-managed headless full may terminate degraded when every structural stage is present but a mute voice worker left an explicitly labelled deterministic_fallback; contract, provenance, language or action failures remain incomplete. Quick may terminate degraded only under its explicit coverage rule and system-owned degraded ledger. Never relabel degraded, incomplete, needs_revision or failed as complete.

Preflight Interaction

Infer these fields rather than asking separate startup questions:

• language: user's apparent language
• objective: use directional_rating for an unambiguous buy/hold/sell or “worth buying”

request; otherwise choose the matching supported objective only when the request is explicit

• holding horizon: map an explicit period to the supported enum; “hold for one year” is 1_year.

For an unambiguous directional-rating request without a period, propose 1_year and show “12 months (default)” in the setup for confirmation. Never override a stated period.

Pass objective and holding_horizon together or omit both. The disclosed 12-month default only applies with directional_rating; do not infer it for other objectives. The runtime may narrowly infer the exact directional_rating + 1_year pair from an unambiguous original prompt, but the returned decision_context.source and hash remain authoritative.

Every council judgment still has one mandatory preflight: the per-run master selection in Stage 0. This applies to both full and quick council modes. It is not an optional preference question and it cannot be inferred, silently reused or skipped because the request already named a master. Data-only screen, options, news and market calls do not enter the council and skip Stage 0.

Use the inferred language for the Stage 0 catalog, visible progress, agent prompts, evidence packets, debate packets and final synthesis unless the user explicitly requests another language. Always pass the original user request in prompt and the inferred language in language. System-owned catalog/report/handoff labels and failure text are localized for zh-CN, en, ja, ko, es, fr, de, pt-BR, it, ru, vi and id; stable IDs, JSON field names and machine enums remain unchanged. Preserve original source quotations and explain them in the selected language.

Stage 0 — Display, confirm and receipt-gate the master selection

No research, run envelope, network request or subagent may start before this gate passes.

list_council_options remains a read-only discovery view for users who ask what the system can do. It does not create a selection session, prove that the individual catalog was displayed, or issue a receipt, so it never substitutes for the steps below.

Claude Code, Codex, OpenCode and Grok Build use the same text fallback and confirmation.

The gate takes three decisions in ONE interaction: which methods sit on the bench, whether the analyst scope is core (8) or all (11), and which depth tier the run uses. Method selection and analyst scope are independent: selecting all methods never silently selects or omits analyst seats, and selecting all analysts never changes the method bench.

Show the depth in the configuration; accept a numbered change without requiring enum names. begin_council_selection returns pace_options, one row per tier with hard_ceiling_minutes, configured_stage_budget_minutes, observed_completion_status and what the extra time buys. The configured budget is not an observed completion time. Keep this menu available when the user adjusts depth, and leave completion explicitly unvalidated until a preregistered live terminal run exists:

本次分析要跑多深？（默认 2）
  1. 快速   持久化上限 15 分钟；配置分段约 14 分钟；完整完成实测：尚未验证  每证据席 4 分钟，每方法席 2 分钟，每轮辩论每侧 85 秒
  2. 标准   持久化上限 30 分钟；配置分段约 25 分钟；完整完成实测：尚未验证  每证据席 6 分钟，每轮辩论每侧 180 秒   ← 默认
  3. 深入   持久化上限 60 分钟；配置分段约 58 分钟；完整完成实测：尚未验证  每证据席 12 分钟，每轮辩论每侧 360 秒
三档都保留已选择的分析席、方法席、三轮辩论和 PM；slow + 全部方法席 + 全部分析席另强制加入三重核验。

Pass the answer as council_pace to confirm_master_selection; it binds into the receipt, so an execution call may repeat it but never change it. If the request already said a speed, pass it as council_pace to begin_council_selection: that is a PREFILL exactly like a named master -- show it in the configuration and obtain the one configuration submission. If no depth was requested or saved, the displayed default is normal.

Quick returns an empty pace_options and rejects the field: it is a smaller contract, not a slower one. Say that plainly if a user asks for a fast quick run.

Then take this run's method selection and the separate analyst-scope choice:

1. Call begin_council_selection with symbol, the original prompt, inferred language,

the calling host, and the intended council_mode (full by default). If the request explicitly names masters, resolve their stable IDs and pass them as preselected_master_ids; if it named a speed, pass council_pace. Both are prefills that highlight only and never confirm. When objective and horizon are unambiguous, pass the supported objective and holding_horizon together.

1. Show returned display_markdown first: named methods, horizon, scope, pace and budget

ceiling. A starter_pending_data panel is a proposed starting configuration whose instrument type and coverage remain unchecked; do not describe it as data-backed. Identify a previous selection as a prefill awaiting fresh confirmation. Keep the complete returned catalog available on request or in an expandable section, preserving identity, method, best_for and maturity for each row. Show directional contributors, non-voting risk coverage and context-only methods from the returned decision context.

1. Take one submission for the configuration. Accept “confirm” only when the displayed

configuration names the exact suggested_master_ids, analyst scope and pace. Otherwise accept numbered choices, ranges, IDs/names or all (full only). Quick requires 1-4 distinct methods. Explicitly offer core = 8 and all = 11 evidence seats for full. Native selection UI is optional; the numbered text catalog is the universal fallback.

1. Explicit request choices and remembered choices are prefills, never consent. Obtain this

run's submission, then map “confirm” to the exact displayed IDs, pace and scope. Never reuse a prior receipt. The submission is confirmation; do not add a second confirmation question.

1. Call confirm_master_selection with the exact selection_id, catalog_hash,

display_ack: true, the displayed/answered council_pace, the explicit analyst_scope: "core" | "all", and exactly one of:

• selected_master_ids: [...] for a native multi-select;
• select_all: true for all in full mode only;
• selection: "1,4-6" (or another supported text selection) for the fallback.

If Stage 0 returned recommendation_hash or decision_context_hash, echo each one unchanged.

1. Retain the returned one-use, mode-bound selection_receipt. Only after that may the host call

plan_visible_run, collect_evidence or analyze_symbol, and each call must include the receipt plus the same symbol, prompt, language and council_mode. Never also pass masters or masters_roster; the confirmed receipt is authoritative. Missing, expired, stale, consumed or mode-mismatched receipts restart at step 1.

Never collapse “all methods” and “all analysts” into one all. Both choices must be displayed and confirmed independently. If the user selects full analyst breadth, the frozen receipt and the run must contain exactly the 11 canonical analyst IDs.

Full v2 plugin-managed contract

Use this contract when full runs through headless analyze_symbol:

• Call analyze_symbol once with the full-mode receipt, council_mode: "full",

wait_for_completion: false, and no task override unless the user explicitly requested optional breadth. Poll the one durable run_id; never create a replacement.

• All analyst roles frozen in the receipt (8 core or exactly 11 all-scope roles) start together.

Each has one bounded parse-only repair; repair converts malformed output and does not repeat web research.

• After the evidence barrier, every selected physical v3 method executes its deterministic

policy and freezes its stance. Each seat that reached a stance then gets exactly one isolated voice worker for that stable ID. It may explain the recorded policy result in the user's language, but cannot change the stance, invent a typed fact or speak as the real named person. If both the original voice and normal no-search transport repair remain in the wrong reader language, one final no-search language-only translation pass may preserve the same stance, figures, source IDs, dossier hash, and packet acknowledgements; any further mismatch fails closed. A mute process-level voice failure after a sourced deterministic stance was frozen retains that frozen view as deterministic_fallback; it never becomes “no deliverable opinion” and a full run can finish only as disclosed degraded, not complete. Contract, provenance, reader-language, parse and unsafe-action failures remain hard failures. Visible-host full remains strict and requires every returned real method voice.

• On an operating-company run, every method voice must return the exact shared dossier hash and

one evidence_packet_acks row per frozen packet. The eight core rows are mandatory in every full run; all-scope runs also acknowledge the three supplemental packets. Each row is exactly used, reviewed_not_relevant, or unavailable, with the packet hash and the status-specific source/reason fields required by the runtime.

• slow + all methods + all analysts forcibly inserts the three parallel verifier batches

source_fidelity, rederivation, and refuter before any method worker. Each batch must cover every frozen material claim. The headless runner may schedule bounded claim-transport chunks concurrently within each verifier; Codex structured output keys every expected claim and the server records only the exact canonical union. Source fidelity uses smaller ten-claim chunks. A transport/schema defect gets one no-search repair; a verifier-coverage defect gets one web-enabled audit retry over the same frozen chunk with its exact failed checks recorded first. Neither retry may mutate or redispatch the analyst packets. Zero, missing, duplicate, unexpected, or malformed coverage makes the terminal state needs_verification; the runtime must not run methods/debate/PM or write complete. A complete batch may legitimately find partial, cannot_confirm, contradiction, refutation, or an independently retrieved same-source rederivation: those become visible completed_with_findings results. They require explicit PM correction/acknowledgement and may support the one sourced downside notch under pm_rating_rubric_v2; they never create an automatic vote, weight change or rating.

• Every scored physical v3 seat gets an isolated explanation worker. In plugin-managed

headless runs only, a hashed frozen out_of_scope record uses its deterministic explanation and records not_required_frozen_abstention; it remains a non-vote in the full ledger. Visible hosts still require every returned worker, including abstentions. Require voice_mode=first_person_public_method_simulation_v1, the exact disclosure ack, a stance-compatible position_intent, and all five strong first-person fields. The worker must use the selected method's characteristic public questions, vocabulary, reasoning order and failure mode; neutral third-person summary is invalid.

• Every condition id a seat cites is resolved back to the id its pack declares. The ids are

hashed before the policy runs so the decision layer cannot recognise the seat, but past the freeze the seat is named in the report and in its own worker prompt, so a surviving anon_<hash> only stopped a seat from telling a reader which condition decided it.

• Round 1 Bull/Bear run together; after both pass, Round 2 runs together; after both pass,

Round 3 runs together with exact saved-question bindings. The PM starts after both Round-3 sides pass.

• The ceiling is the selected tier's total from durable queueing through terminal artifact

persistence, including queueing, retries, all workers and deterministic finalization: fast 900000 ms, normal 1800000 ms, slow 3600000 ms. A caller or environment may lower the selected tier's budget, never raise it. At expiry persist incomplete and name every timed-out/failed/skipped role. The deadline guarantees a terminal saved run, not successful completion under provider/search/data degradation.

• The tier moves every per-stage cap with the total, because those caps are what bound each

worker: evidence 4/6/12 minutes per seat, method 2/3/4.25 minutes per seat, debate 85/180/360 seconds per round, PM 1.5/3/8 minutes. The rounded configured stage totals returned by the selector are 14/25/58 minutes. Raising total_timeout_ms alone buys idle time rather than depth; the tier is what buys depth. All three tiers are full_v2 and preserve the separately selected analyst scope, method bench, three rounds and PM. The exact slow + all methods + all analysts combination also activates the mandatory triple-verifier stage. Quick rejects council_pace.

• The tier also shapes each worker's output, and this is the part that makes fast fast rather

than merely short of time. A cap alone is a timeout, and the same prompt with a shorter fuse produces a packet the worker could not finish. Since an LLM call's wall clock is dominated by the tokens it generates, fast asks for the same information in less prose: at most six arguments, one to two sentences each, citing a source ID instead of re-quoting the evidence, no opponent recap and no methodology preamble — while every figure, every scoped source ID and every required report section stays mandatory, and price levels and invalidation conditions may not be compressed. Dropping an argument is acceptable at fast; dropping a source ID or filling a number from memory never is. slow instead asks for the derivation written out step by step with explicit falsification conditions. normal adds nothing.

• The concise handoff lists every selected stable master ID, frozen stance and voice-worker

explanation/status; all 8 or 11 receipt-bound analyst task IDs, statuses and summaries; and a system-owned price snapshot with currency/time/source or an explicit unavailable-data gap.

#### Operating-company dossier barrier

For a non-dry operating-company full_v2 decision run, the eight evidence packets jointly populate operating_company_dossier_v1. This is a finite, auditable decision-relevant coverage contract, not a claim to have read the whole internet.

• Every one of the fixed 52 coverage IDs in docs/report-contract.md must appear exactly once.

covered needs a same-task packet-local evidence source with an HTTP(S) URL. Static sources need a parseable publication time no later than as_of; a directly fetched dynamic page with no publication date must keep published_at: unknown, declare source_kind: dynamic_snapshot, and add its actual observed_at, also no later than as_of. An ordinary undated article cannot use this label, and news/event coverage (except the event calendar) still needs dated evidence. PersonaPack/proxy and cross-task source IDs cannot satisfy it. unavailable needs a named attempt, at least one actually attempted HTTP(S) locator in attempted_urls, and the identical gap in open_questions; not_applicable needs a concrete reason. Missing, duplicate, renamed, unexpected or unresolved rows stop the evidence barrier.

• Coverage completeness and evidence sufficiency are different. A structurally complete

dossier with a non-critical unavailable field is limited and keeps the gap visible. An unavailable or not-applicable decision-critical field makes sufficiency insufficient, prevents methods, debate and PM from starting, and cannot be repaired into a rating by prose.

• At the evidence barrier, freeze company_dossier.json and its canonical SHA-256 hash. Before

every dispatched method voice, Bull/Bear or PM worker, the runtime re-reads and re-hashes the frozen disk artifact and derives operating_company_dossier_decision_projection_v1: all packet claims, every referenced source, the exact 52 coverage rows, frozen acquisition outcomes/data, complete packet metrics, explicit gaps and packet/dossier hashes, without raw acquisition payloads or large time series. Successful acquisition routes retain deduplicated attempt_source_ids; unavailable routes retain their full bounded attempt records. The projection has a deterministic hash and a 512 KiB fail-closed cap; it is never silently truncated or rebuilt from a separately mutable run summary.

• Every method, Bull/Bear round and PM receives that packet-complete projection and returns the exact original company_dossier_hash_ack.

Missing/mismatched acknowledgement, artifact mutation, projection oversize or a conflicting evidence replay fails closed. Method voices additionally keep the packet-by-packet receipts. The dossier hash is bound into every physical v3 evidence snapshot, while its deterministic stance still consumes only compatible point-in-time typed facts; do not claim arbitrary dossier prose changed the frozen policy result.

• collect_evidence remains the task-selective evidence-only diagnostic and reports

evidence_only_v1. Public analyze_symbol is always decision-producing and rejects synthesis=false; an evidence-only result must never be described as a completed full council.

plan_visible_run is not governed by this clock: the external host schedules and owns those subagents, so the plugin cannot force-stop them. Do not promise the 30-minute headless bound for visible-host execution.

Quick v1 fixed contract

Quick remains a council judgment and passes the same display/confirmation gate, but its execution graph is deliberately smaller and immutable:

• Call analyze_symbol with council_mode: "quick", the mode-bound receipt,

wait_for_completion: false, and no task override. Do not call plan_visible_run; it rejects quick so the host cannot silently turn a bounded run into visible orchestration.

• Launch exactly these four evidence roles in one parallel wave: market_data,

earnings_deep_dive, valuation_long_short, news_industry_management.

• The news role covers dated company and industry developments in the 120 days ending at

as_of. Future, undated, and older items are not presented as recent.

• Run the 1-4 selected methods in one parallel wave. Then run one bull and one bear statement

in parallel, followed by one short PM. There are no rebuttal/Q&A rounds and no adversarial source_fidelity / rederivation / refuter fan-out.

• Enforce the 600000 ms queue-to-persistence ceiling: deterministic grounding 20 seconds;

each parallel evidence worker 210 seconds; each parallel selected method 90 seconds; bull and bear 90 seconds per side; PM 90 seconds; final assembly/persistence reserve 20 seconds. Retry time is inside those caps and the global deadline. Callers and environment variables may lower the ceiling, never raise it.

• Missing data is not invented. If minimum evidence coverage survives, timed-out or failed

seats are explicitly degraded and the terminal run keeps one idempotent, system-owned alphacouncil:degraded-ledger:v1 block. If minimum coverage does not survive, terminate incomplete. report_quality=passed checks only quick_v1 structure and never erases a degraded status or implies full_council_equivalent=true.

• A valid quick_v1 report has 13 visible sections: conclusion/rating; analyst work log;

one-round Bull/Bear record; system-owned Master Bench; earnings-call management signals; recent company/industry news; valuation range; price conditions; major risks; position recommendation; data gaps; confidence; and source table.

Visible-First Workflow

This section applies to full council only. If the user explicitly chooses quick, use the plugin-managed Headless MCP path; never emulate quick with visible subagents.

Use visible Codex subagents whenever the user asks to see subagents, asks for a chat-style analyst team, says child agents must be visible, or invokes @alphacouncil-agent for an investment decision without explicitly requesting headless/background mode. If the user requires a hard 30-minute terminal bound, explain that visible host tasks cannot be force-stopped by the plugin and use plugin-managed headless full after Stage 0.

Default to the full workflow. Do not downgrade to a lite/smoke/visible-only summary unless the user explicitly asks for lite, smoke test, or debug output. Do not describe the final user-facing report as "visible version", "lite", "smoke", or "debug"; those are execution details, not investment-report content.

1. If multi_agent_v1.spawn_agent is available, spawn separate visible agents for the full default analyst team:

<!-- generated:roster start -->

• macro_regime
• market_data
• earnings_deep_dive
• forward_expectations
• quant_factor
• valuation_long_short
• news_industry_management
• market_narrative
• social_pulse
• insider_sec
• ib_event_analysis
• bull_researcher
• bear_researcher
• portfolio_manager

<!-- generated:roster end -->

1. Give each visible agent a narrow prompt and require JSON evidence or debate output. Tell each agent not to call alphacouncil-agent recursively.
2. Use the selected or inferred language for visible agent prompts, evidence packets, debate packets, and final synthesis. Keep JSON field names in English.
3. Master bench — runs on every host, not only Claude Code. After Stage 0, pass its

selection_receipt to plan_visible_run; the run envelope resolves the exact selected master IDs. After the evidence agents finish and before the debate, run each selected lens. Each master reads the SAME established facts the analysts read plus the analyst packets, and returns one JSON opinion recorded with record_master_opinion(run_id, master, packet).

• There is no silent default roster. At least one method or all is confirmed per run.
• A master whose method cannot judge this name returns stance: "out_of_scope". That is a conclusion, not an abstention, and it carries zero weight rather than being coerced into a view.
• The run is `incomplete` until every selected master has reported. A bench nobody consulted is worse than no bench: the reader believes the verdict survived every lens when it survived none.
• Feed only primary, non-out_of_scope method judgments into Bull and Bear once. Supporting,

risk and context-only methods reach the PM once through the non-voting risk projection; out_of_scope stays visible in the method bench but is excluded from PM rating inputs. Never count raw stances, ratings or seats.

1. Mandatory triple verifier for `slow + all methods + all analysts`. After all 11 packets

are frozen, run source_fidelity, rederivation, and refuter independently over the exact same complete material-claim ledger. Record one claim-complete result from each via record_verifier_batch(run_id, verifier, packet, thread_id=...); never use a sampled subset or individual record_verifier_verdict calls to satisfy this path.

• Zero verifier verdicts or a missing/duplicate/unexpected/malformed claim binding leaves the

run needs_verification and blocks every method, debate, and PM write. It can never be published as complete. Allowed adverse or unresolved verdicts are findings, not missing execution: exact coverage becomes completed_with_findings, is shown in the report, and requires an explicit correction or sourced PM risk adjustment without any automatic vote.

• rederivation must not receive the original URLs; it searches independently. refuter

records a concrete negative query for every claim. source_fidelity opens a cited URL and records an excerpt for every supported claim.

1. Wait for the evidence agents, merge their outputs into a shared evidence set in the main thread, then run bull, bear, and portfolio-manager agents.

• Round 1: bull writes the long case; bear writes the short case; launch both in parallel and wait for both.
• Round 2: pass bull's packet to bear and bear's packet to bull for rebuttal; each side

ends with exactly three questions for the opponent.

• Round 3: cross-feed those six saved questions; each side preserves its own three in

questions and answers the opponent's three as exact {question, answer} bindings in questions_answered.

• Final: portfolio_manager reads evidence plus all debate rounds and decides whether bull, bear, or balanced won.

1. Return a concise but evidence-rich user handoff in the selected or inferred language: rating, debate winner, key earnings/financial results, forward expectations or event thresholds, important news/industry signals, valuation range, position guidance, top invalidation conditions, and saved file locations. It must name every selected master and every mandatory evidence analyst, with each status/summary, plus the system price snapshot or an explicit quote-data gap. Do not paste an overlong report into chat unless the user asks for the full body inline. The saved final_report.md must still be complete enough to read without opening artifacts: include each evidence analyst's summary, key data/news/filing/quant findings, the bull case, bear case, rebuttals/questions where available, portfolio-manager verdict, data gaps, and source table. Include links/paths to saved artifacts in the handoff.

• If the Data Analytics datascienceWidgets tools are available, also create a real dashboard/report artifact from the completed evidence and decision: call validate_artifact first, then render_artifact. Do not treat output_mode=data_analytics as only a prose style.
• If Documents, PDF, Spreadsheets, or Presentations are requested as output formats, use their plugin/skill workflow as a delivery layer after the investment decision is complete; do not move investment judgment into those format plugins.

1. If the user specifically wants left-sidebar Codex chat threads, use codex_app.list_projects and codex_app.create_thread instead of MCP headless execution. Create one thread per major role and report the created thread IDs.
2. Do not treat plan_visible_run as execution. It only creates the run envelope and prompts; visible agents/threads must actually be created and read before final synthesis.

Data Tools — call these instead of searching

Every tool below is keyless. A number these can supply must never come from a search result, from a summary, or from memory. Search is for what the tools cannot reach: explanation, guidance, competitor commentary, and anything not yet filed.

Limits you must carry into the report, not discover later

• IV percentile needs local history. Each successful current CBOE observation is appended

to the plugin's local ledger. Until at least 60 daily observations exist, percentile stays an explicit building_history gap; never manufacture it from one snapshot.

• X / Twitter has no free discovery channel. Professional FinTwit is not covered and

Reddit is not a substitute. Say so rather than implying you looked at social media.

• Non-US names have no options chain here and often no structured financials. Continue with

the market-specific regulator/exchange document route from get_company_sources; never substitute a US peer's numbers. Only an exhaustively attempted field may remain unavailable.

• A skipped screen rule is a gap. Reporting 6/7 passed without naming the seventh

misrepresents the screen.

Headless MCP Workflow

Use MCP only when the user explicitly accepts background/headless execution, wants saved files, or asks to inspect/re-run a previous saved run.

1. Call collect_evidence for a full-mode source-gathering request that needs file artifacts.

Quick is an end-to-end contract and must enter through analyze_symbol, not a hand-built sequence of lower-level tools.

1. Call analyze_symbol with the intended council_mode, mode-bound receipt, and

wait_for_completion=false when the user wants a long/short or portfolio decision saved under ~/.alphacouncil-agent/runs/. This returns a small durable accepted response with run_id, status_json, and events_jsonl; acceptance does not mean the report is done. For quick, do not pass task overrides and do not request synthesis=false. For full, pass council_pace when the user asked for a speed (fast 15 min / normal 30 / slow 60); the selected tier's global maximum and the parallel/barrier topology in the full contract above apply. total_timeout_ms above the tier's total is rejected and names the tier that allows it.

1. Poll read_run(run_id) at a bounded interval until status.status is terminal:

complete, degraded, incomplete, needs_verification, needs_revision, or failed. Surface meaningful phase changes, not every unchanged poll. Poll the same run_id; never create a replacement because progress is slow. Only read/return decision and final artifacts after a terminal status. Use wait_for_completion=true only when the caller explicitly requires a synchronous run and its MCP connection is known to outlive the entire council.

1. Headless analyze_symbol forcibly runs source_fidelity, rederivation, and refuter

when the receipt is exactly slow + all methods + all analysts. Read status.verification_scope, verifier_required, verifier_expected_count, verifier_verdict_count, and verifier_zero. Every other combination remains source_id_presence_only; never relabel source-ID presence as adversarial verification.

1. Call council_diagnostics over saved run IDs to measure descriptive agreement, unique

cited-source contribution, and repeated-input behavioural differentiation. Do not turn its seat count or agreement into N_eff; that remains null without the separately preregistered, signed, resolved-outcome ledger.

1. Headless MCP defaults to real codex exec workers. Pass dry_run=true only for explicit planning/self-test requests, not for a user-requested stock analysis.
2. Do not describe MCP codex exec workers as visible chat subagents. They are isolated

background processes with status.json, events.jsonl, and all_agents.md. Each selected scored physical v3 method gets its own isolated voice worker after the deterministic stance is frozen (headless frozen abstentions retain deterministic explanations), but that worker is not a persistent sidebar agent and is not the named person.

1. For full mode, any mandatory evidence failure closes the evidence barrier and terminates

before masters, debate, and PM model calls. For quick, inspect the degraded ledger and the independent execution-status, evidence-coverage, and report-quality fields before handing off the result.

Claude Code Parallel Path

This path is full-council-only. An explicit quick request always uses plugin-managed headless analyze_symbol, even when the Task tool is available.

Use this path when running under Claude Code with the Task tool available. It reuses the exact same MCP run envelope and recording tools as the Visible-First and Headless workflows above; only the executor and the gating change. If the Task tool is NOT available, fall back to the Visible-First Workflow (or Headless MCP), and say so plainly per the fail-closed visibility rule.

Detect capability first: if you can emit Task subagent calls in one turn, prefer this path over the sequential fallback. Otherwise do not claim a parallel council ran.

Model policy (cost-aware)

Opus on every subagent is expensive. Default to a tiered policy, and let the user override at launch:

• Evidence analysts (Stage 1) and verifiers (Stage 2b) → a fast, cheaper model (Sonnet 4.6, or Haiku for pure fetch/extract). These are bounded source-gathering jobs.
• Bull/bear debate (Stage 3) and `portfolio_manager` verdict (Stage 4) → the strongest model (Opus 4.8), because these carry the reasoning.

Default is "evidence on Sonnet, debate/verdict on Opus 4.8". Ask once at launch only to offer overrides ("all Opus" for max depth, "all Sonnet" for max thrift); otherwise use the default tiering. Set the model per Task subagent (model: option). If the host cannot set per-subagent models, say so and proceed on the host default.

Language

Detect the user's language from their request and propagate it to EVERY subagent: each Task prompt, the evidence/debate/verdict content the subagents produce, and all workflow progress text shown in the main thread must be in that language (Chinese in -> Chinese throughout; Japanese in -> Japanese throughout). Keep JSON field names and role keys in English; translate values and prose. This matches the Preflight language rule.

Stage 0 — Plan (envelope only)

Call plan_visible_run with symbol, prompt (original user request), as_of, inferred language, council_mode: "full", and the Stage 0 selection_receipt. It returns run_id, the planned evidence agent specs, the selected master specs, the 3 debate agent specs, and artifact paths. This is planning only (SKILL step 9); do not treat it as execution. The tool rejects council_mode: "quick".

Every planned prompt is written to <run>/prompts/ and each agent spec carries prompt_file. Check prompts_inline: when it is false the prompt bodies were deliberately left out of the result, because returning them together would exceed what a host accepts, and you must Read each prompt_file instead of the inline field. What drives that size is the grounding each prompt embeds rather than the seat count, so a run with a full macro series crosses the budget where a sparse one does not. A truncated or rejected plan result is never a reason to write prompts from memory.

Stage 1 — Evidence fan-out (one turn, isolated context)

In a SINGLE assistant turn, emit one Task (subagent_type: general-purpose) call for every evidence role returned by the plan. analyst_scope=core returns the eight core roles: market_data, earnings_deep_dive, forward_expectations, quant_factor, valuation_long_short, news_industry_management, insider_sec, and ib_event_analysis. analyst_scope=all returns those eight plus macro_regime, market_narrative, and social_pulse, for exactly eleven analyst seats. Run the returned list exactly; do not add, omit, or replace seats. Each subagent:

• May use ONLY WebSearch + WebFetch. It must NOT call @alphacouncil-agent, collect_evidence, analyze_symbol, or read_run (leaf-worker rule, Boundaries).
• Runs a query ladder: a primary-locator search (use allowed_domains such as sec.gov and the company IR/exchange domain), a dated recency search, and one mandatory disconfirming search (e.g. <ticker> guidance cut, downgrade, accounting concern).
• WebFetches the actual primary doc where one exists (insider_sec -> EDGAR full-text + Form 4; earnings_deep_dive -> 8-K Ex-99.1 plus the IR transcript; ib_event_analysis -> 8-K / 424B / deal release; market_data -> exchange/quote page) and quotes exact figures with real dates.
• Returns exactly one JSON evidence packet matching the Agent Output Contract, with a real url and published_at on every source and every paywalled/missing/stale item routed into open_questions.

Stage 2 — Collect + barrier

As each Task returns, call record_visible_packet(run_id, task, packet, thread_id=<subagent id>). The server upserts by task, rescopes sources to <task>:S1, rewrites source_manifest.json + all_agents.md, and flips the run phase toward visible_debate. HARD GATE: do not start the master stage or debate until every task returned by the full plan is recorded and completed. If a bounded repair still leaves a task failed or degraded, call finalize_visible_run(run_id, reason="evidence_worker_failed", failed_tasks=[...]); it persists the run as incomplete, names skipped downstream roles, and returns the mandatory user_response_markdown. Deliver that body unchanged instead of authoring a fallback recap. Proceeding with fewer than the planned count violates the barrier.

Stage 2b — Mandatory triple verification for slow + all methods + all analysts

This is a fail-closed audit stage, not an optional repair loop. It is required only when the frozen receipt is exactly council_pace=slow, selection_mode=all, and analyst_scope=all; every other full combination records source_id_presence_only and must not claim adversarial verification.

Build the frozen material-claim ledger from every non-low source-backed claim (or every source-backed claim if all claims are low). In one turn, run exactly three verifier Task subagents, each over the complete ledger:

• source_fidelity: open the original cited URL for every claim and return one allowed verdict plus the checked URL and supporting excerpt.
• rederivation: receive no original URLs, independently search and recompute every claim, and return one allowed verdict plus query, different URL, and derivation when confirmed or contradicted.
• refuter: run at least one concrete disconfirming/newer-evidence query for every claim and return one allowed verdict with its search record.

Record each complete result with record_verifier_batch(run_id, verifier, packet). Each batch must contain every frozen claim_id exactly once; missing, duplicate, unexpected, or malformed coverage fails the audit. Allowed unresolved or adverse verdicts are preserved as completed_with_findings; they require explicit correction and may support a sourced one-notch downside adjustment, but never create an automatic vote, weight change or rating. Do not mutate or re-dispatch the frozen analyst packets from this stage. Continue to method seats only after all three batches achieve exact coverage. If no verifier verdict is recorded, or if the exact expected count/coverage does not pass, call finalize_visible_run; the terminal status must be needs_verification, never complete. Verifiers also obey the leaf-worker rule.

Stage 2c - Selected master methods

Run every master_agent returned by plan_visible_run after the evidence and verification barrier, and before the bull/bear debate. Immediately before each launch, re-read that agent's prompt_file: the server refreshes it after the barrier with the verified bounded projection. Never paste or append Evidence JSON, evidence.json, company_dossier.json, or another evidence/dossier artifact. Physical v3 agents are explanation workers over an already frozen stance, including out_of_scope; require acknowledged_stance to match frozen_stance, and record each result with record_master_opinion. masters_declined documents the deterministic result but does not waive a returned visible explanation worker. HARD GATE: status.json.pending_masters must be empty before Stage 3. If any selected method remains failed after its bounded repair, call finalize_visible_run(run_id, reason="method_worker_failed", failed_masters=[...]) and deliver the returned user_response_markdown. The final ledger will show completed statements in full and failed seats as non-directional failure records; never invent the missing seat's stance or omit it.

Stage 3 — Debate pipeline (3 rounds, parallel per round)

Run the documented rounds, each as a parallel fan-out of bull_researcher + bear_researcher. Re-read each role's refreshed prompt_file as the complete verified evidence base; append only the prior Bull/Bear packets and the exact round-specific Q&A bindings required below, never Evidence JSON or an evidence/dossier artifact:

• Round 1: bull writes the long case; bear writes the short case (parallel).
• Round 2: cross-feed each side the other's round-1 packet for rebuttal; require exactly

three opponent questions in each returned questions array (parallel).

• Round 3: cross-feed the saved Round-2 questions; each side copies its own questions and

answers the opponent's three as exact {question, answer} bindings in questions_answered (parallel). A missing, reordered, substituted or non-three question/answer array fails the Q&A gate and the run remains incomplete. Persist each round via record_visible_decision(run_id, role, packet) so all_agents.md accumulates the full trace. DISPUTED/UNVERIFIABLE claims may appear in a thesis only with an explicit caveat. If a debate worker or exact-Q&A repair fails, call finalize_visible_run(run_id, reason="debate_worker_failed", failed_roles=[...]) and deliver its returned handoff; do not write a manual investment verdict.

Stage 4 — Verdict + synthesize

Run one portfolio_manager Task from its refreshed prompt_file plus all three debate rounds. Do not paste Evidence JSON or an evidence/dossier artifact; the refreshed file is the PM's complete verified evidence base. Its packet MUST carry report_markdown as the complete report body with every authored contract section; the tool rejects a packet that does not, before taking the idempotency lock, and the rejection lists each missing section with the heading to use. Do not send a PM packet without it and expect the report to be assembled from the summary. The master bench and any instrument-structure section are system-appended and are never asked of you. Record it via record_visible_decision(run_id, 'portfolio_manager', packet), which writes decision.json + final_report.md and marks the run complete. A successful PM response has handoff_contract=inline_user_response_v1 and returns user_response_markdown; use that Markdown as the final user-facing response body instead of replacing it with a shorter recap. This rule applies to every terminal path: finalize_visible_run returns the same handoff contract for incomplete visible runs. Its system-owned last section has the exact selected-seat count, the complete untruncated recorded statement for each speaking seat, and an explicit non-directional terminal diagnostic for every failed/unavailable seat. Never shorten, reorder, sample, or append another summary after this ledger. Then link the complete report and audit artifacts in an appendix. The saved full report still contains the Analyst Work Log, Bull/Bear Debate record, verification ledger, all mandated sections, data gaps, horizons and <task>:<source_id> source table.

Honest limits: Task fan-out is best-effort, not a guaranteed workflow engine; enforce the barrier by polling artifacts, not by assuming. WebSearch/WebFetch is the only evidence channel (no financial API), so some numeric claims stay "narratively corroborated, not vendor-verified". This is the same auditable contract as the other paths — a stronger runner, not a different audit story.

Agent Output Contract

Evidence agents return:

{
  "task": "market_data",
  "symbol": "NOK",
  "as_of": "YYYY-MM-DD",
  "summary": "string",
  "claims": [{"claim": "string", "evidence": "string", "confidence": "high|medium|low", "source_ids": ["S1"]}],
  "metrics": {},
  "sources": [{"id": "S1", "title": "string", "url": "string", "published_at": "YYYY-MM-DD or unknown", "retrieved_at": "YYYY-MM-DD"}],
  "open_questions": ["string"],
  "coverage_items": [{"id": "role-owned.coverage_id", "status": "covered|unavailable|not_applicable", "source_ids": ["S1"], "note": "string", "attempted": "string", "attempted_urls": ["https://actual-route.example"], "gap": "string"}],
  "confidence": "high|medium|low"
}

coverage_items is mandatory only when the prompt includes the operating_company_dossier_v1 coverage block. Return exactly the IDs listed there; do not copy the example ID. For covered, attempted* and gap may be omitted. For unavailable, source_ids may be empty but attempted, attempted_urls, gap and the identical open_questions entry are mandatory.

Debate agents return:

{
  "role": "bull_researcher",
  "symbol": "NOK",
  "as_of": "YYYY-MM-DD",
  "verdict": "string",
  "rating": "Buy|Overweight|Hold|Underweight|Sell",
  "winner": "bull|bear|balanced|unknown",
  "summary": "string",
  "long_thesis": ["string"],
  "short_thesis": ["string"],
  "valuation_range": "string",
  "catalysts": ["string"],
  "risks": ["string"],
  "position": "string",
  "invalidation": ["string"],
  "source_ids": ["S1"],
  "confidence": "high|medium|low",
  "report_markdown": "string"
}

When the frozen context is exactly objective=directional_rating and holding_horizon=1_year, the portfolio-manager packet must additionally return the complete rating_basis required by its refreshed prompt: rubric_id=pm_rating_rubric_v2, horizon_months=12, return_formula_id=price_target_plus_income_v1, the exact frozen price_currency and reference_price, numeric base_case_price_target, income_return_pct, base_case_total_return_pct, raw_rating, risk_adjustment, final_rating, adjustment_reason, non-empty frozen source_ids, adjustment_source_ids, and adjustment_context_ids. The server recomputes total return and the raw band and permits only a one-notch downgrade linked to a server-owned eligible cause context and its frozen sources; out_of_scope creates no eligible cause. Other objective/horizon pairs must not invent this 12-month rubric. A real calibrated run must have a positive frozen quote and currency before any seat launches; all price_levels rows use that same currency, and every hard verifier finding must be acknowledged exactly once on both headless and visible-host PM paths.

Boundaries

• Public-equity-investing and investment-banking methodology is bundled as local skills

(skills/public-equity-investing, skills/investment-banking); use them as the research method on BOTH editions. On Codex you may additionally use the curated remote @public-equity-investing / @investment-banking workflows; on Claude Code (or when the remote workflows are unavailable) the bundled local skills ARE the method, driven by WebSearch + WebFetch. Treat them as agent playbooks run by subagents, not Python libraries.

• Keep non-public information out of scope unless the user provides the document directly.
• For exact index / index-futures (incl. night session) / FX / rates / vol / commodity / stock levels, call the `get_quote` MCP tool (keyless, ~15m delayed; accepts names like KOSPI/纳指期货/VIX/美元指数 or raw tickers) and cite it. Web search is the interpretation layer and the fallback when get_quote errors — then record the gap in open_questions. get_quote is delayed market data, never a real-time feed.
• Classify the instrument before choosing company-data routes. ETFs/funds use dated

holdings look-through; cash indices use aggregate-index methodology. Do not call or ask for operating-company revenue, EPS, guidance, Form 4 or Company Facts as if they belonged to a fund/index. Cover methodology, holdings/constituent date and weights, concentration, fee or index rules, liquidity/tracking/flows, rebalances and same-date aggregate valuation with disclosed coverage; every missing field is an explicit gap.

• Every material claim should map back to an evidence packet with sources and confidence.
• Evidence sources are globally scoped as <task>:<local_source_id> and mirrored in source_manifest.json; never cite bare S1/S2 after packets are merged.
• Full full_v2 manager reports must include separate visible sections for market expectations / implied beat-miss thresholds, analyst rating or target-price revisions, earnings-call management signals, quant factor / technical risk view, news and management/industry voice signals, short interest / borrow / options where available, strategic transaction or banking-event terms where relevant, data gaps / unavailable data, and separate short-term 1-4 weeks / medium-term 3-6 months / long-term 12 months views. Do not hide these only in the source table. If a data source is unavailable, state that explicitly instead of omitting the section. If no key source is missing, include a data-gaps section saying no critical gaps were found.
• Full full_v2 reports must also include an "Analyst Work Log" / "分析师工作记录" section summarizing every evidence agent packet, plus a "Bull/Bear Debate" / "多空辩论记录" section summarizing the long case, short case, rebuttals, exact Round-3 Q&A, unanswered questions, and who won. Do not replace these with a one-paragraph execution summary.
• Quick quick_v1 reports use the fixed 13-section contract stated above. Do not fail a quick report merely because it lacks full-only quant, event-banking, three-horizon, three-round-Q&A, or adversarial-verifier sections; likewise, never present a passing quick report as full-equivalent.
• Terminal runs must preserve the standard artifacts appropriate to the executed contract, including final_report.md, user_response.md, artifact_index.md, report_quality.json, evidence-role Markdown, selected-method output, and bull/bear/PM output or explicit failure records. If report_quality.json is not passed, report needs_revision, not complete. A passing report-quality gate checks structure only: it does not convert a quick degraded execution into complete or prove evidence coverage.
• A full user_response.md lists every selected analyst status/summary (eight for core,

exactly eleven for all), every selected stable master ID with frozen stance and readable explanation/status, and one system-owned price snapshot with currency/time/source or an explicit unavailable gap. Its machine-gated final section contains the exact selected-seat count and either the complete, untruncated recorded statement or an explicit statement_status=not_produced failure record for every selected ID. Visible PM completion and finalize_visible_run return user_response_markdown; deliver it instead of an ACK or manually written recap.

• The management_industry_voices agent only uses publicly verifiable commentary from executives, board members, official company channels, customers, suppliers, competitors, regulators, industry experts, and channel voices. It must separate direct quotes, paraphrases, and media interpretation, and must not imply non-public inside information.
• Fail closed on visibility: if visible agent/thread tools are unavailable, say that visible subagents are unavailable in this runtime and use MCP only with that limitation stated.
• Never let a subagent call @alphacouncil-agent, collect_evidence, analyze_symbol, or read_run; visible agents are leaf workers.