Alphacouncil Agent

---
name: alphacouncil-agent
description: Use AlphaCouncil Agent for listed-equity research workflows that need multiple Codex subagents, shared evidence packets, public-equity analysis, banking/event analysis, filings/news search, valuation, long/short pitch work, risk debate, or portfolio-manager style decisions.
---

# 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 one isolated voice worker explains it; 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`

Pass `objective` and `holding_horizon` together or omit both. Never guess one without the other.
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` and `ko`; stable IDs and JSON field names remain English.

## 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.

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.

**Ask the tier; never make the user type `fast` or `slow`.** `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. Show the menu ABOVE the seat catalog
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 --
highlight the row, still show the menu, still take the answer. No answer means `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.
2. Display the `pace_options` menu with both numbers per tier, then **every returned master
   individually in the returned order**. Preserve the stable number and show `identity`,
   `method`, `best_for` and `maturity` for every row. A school summary, preset or seat count
   does not satisfy this step. Also display the returned advisory panel and decision context:
   name directional contributors, non-voting risk coverage and context-only methods, and state
   that the latter two are not directional votes.
3. Take one submission covering all three decisions. Explicitly show `core = 8` and `all = 11`
   for the analyst scope. The universal method fallback is a numbered text reply: one index in
   `1..N`, any comma/space-separated combination, ranges such as `1-4` or `1..4`, or stable
   IDs/names. Full also accepts `all`; quick requires 1-4 distinct methods and rejects `all`.
   - **Claude Code, Codex, OpenCode and Grok Build** may use a native multi-select when it can
     display the complete catalog without truncation.
   - Native UI is an enhancement, never the protocol. If unavailable, print the same numbered
     table and accept the same text grammar on every host.
4. If the original request already named masters, or said `all` for a full run, mark those
   entries as a prefill, but still display the complete catalog and require a submission for
   this run. An over-limit quick prefill must be reduced by the user's submitted selection.
   Never reuse a prior run's selection. The submission itself is confirmation; do not add a
   second confirmation question.
   The obsolete rule **"Skip the question entirely"** is prohibited for council runs: a
   prefill reduces typing but never replaces this run's displayed catalog and receipt.
5. Call `confirm_master_selection` with the exact `selection_id`, `catalog_hash`,
   `display_ack: true`, the answered `council_pace` (omit to accept `normal`), 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.
6. 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 selected physical v3 seat gets an isolated explanation worker, including
  `out_of_scope`. 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 selected method voice (including `out_of_scope`), 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 -->
2. Give each visible agent a narrow prompt and require JSON evidence or debate output. Tell each agent not to call `alphacouncil-agent` recursively.
3. Use the selected or inferred language for visible agent prompts, evidence packets, debate packets, and final synthesis. Keep JSON field names in English.
4. **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.
5. **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.
6. 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.
7. 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.
8. 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.
9. 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.

| Need | Call | Notes |
|---|---|---|
| Price | `get_quote` | Delayed ~15m. Say so wherever a level matters. |
| Filings-based quality screen | `screen_ticker` | Pass `ticker`; the CIK is resolved for you. A rule whose inputs are missing is `skipped`, **never a pass**. |
| Screen a list | `screen_candidates` | Capped at 40; a fetch failure is `unavailable`, not an elimination. |
| Full US filer list | `list_us_universe` | SEC `company_tickers.json`. |
| Non-US financials | `market_financials`, `market_coverage`, `get_company_sources` | TWSE is structured and keyless. When KR/JP structured adapters have no optional key, or HK/CN are document-only, continue through the keyless regulator-document and company-source ladder; do not stop at adapter status. |
| Macro context | `get_macro_snapshot` | 21 series, 5 derived. Observations, not a regime call. |
| Options positioning | `get_options_chain` | IV term structure, 25-delta skew, put/call ratios, open-interest concentration. |
| Company-specific source map and starter evidence | `get_company_sources` | Resolves the issuer, probes official IR/news/filing/product pages, retrieves dated cross-topic feeds, and returns the frozen 52-item escalation ladder. Call this before treating an empty fixed feed as a gap. |
| Dated news and filings | `get_news` | `symbol`, `query` and/or `cik`. Undated items are excluded, not shown as recent. |
| What the market is talking about | `get_market_narrative` | Themes ranked by coverage, each paired with the series that would corroborate it. |
| Retail and technical chatter | `get_social_pulse` | Reddit, Hacker News, Bluesky. |
| Confirm a quoted X post | `verify_x_post` | A decoded timestamp proves nothing; any invented id decodes to a plausible date. |
| Industry map | `industry_brief`, `industry_peers`, `industry_coverage` | Ask coverage first — it says whether the participant list is authoritative. |
| Facts + brief in one call | `compose_research_brief` | Grounding for a whole run. |
| Persist slow/all verification | `record_verifier_batch` | Visible slow + all-method + all-analyst runs; one complete batch per verifier. |

### 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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
   physical v3 method gets its own isolated voice worker after the deterministic stance is
   frozen, but that worker is not a persistent sidebar agent and is not the named person.
8. 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:

```json
{
  "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:

```json
{
  "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.