Build a Grounded Research Agent with Hallucination Detection

I want to build a Python research agent that combines three capabilities into one pipeline:

1. Grounded research with citations — the agent finds information and tags every claim with the source it came from (document name, URL, or passage).
2. Multi-step agent orchestration — using the Anthropic Claude Agent SDK (the `anthropic` Python package with tool use), the agent breaks a user question into sub-tasks: a planning step, a retrieval step, and a synthesis step.
3. Automatic hallucination detection — after the agent produces its grounded answer, a second pass using the OpenAI API (ChatGPT) checks each claim against its cited source and scores it as VERIFIED, UNCERTAIN, or HALLUCINATED.

Please design the full Python module architecture for this project. For each module, tell me:
- The filename
- Its single responsibility
- Its main functions with input/output types
- How it connects to the other modules

Also draw a simple ASCII data-flow diagram showing how a user query travels through the system from input to final verified JSON output.

Do not write any code yet — just the architecture design.

Based on the architecture we just designed, write the complete Python code for `agent.py`.

This file must:
1. Use the `anthropic` Python SDK with tool use (function calling) to implement a multi-step research agent.
2. Define three tools that Claude can call:
   - `plan_research(question: str) -> list[str]`: breaks a question into 2–4 sub-questions
   - `retrieve_passages(sub_question: str, documents: list[dict]) -> list[dict]`: searches a list of document dicts (each with keys `title`, `url`, `content`) and returns the most relevant passages as dicts with keys `passage`, `source_title`, `source_url`
   - `synthesise_answer(sub_answers: list[dict]) -> str`: combines retrieved passages into a coherent answer
3. Run a loop that calls Claude with these tools until it produces a final answer — exactly the agentic loop pattern from the Claude Agent SDK.
4. Return a structured Python dict with keys: `answer` (string), `claims` (list of dicts, each with `text` and `citation` keys where citation has `title` and `url`).
5. Accept a `question: str` and `documents: list[dict]` as inputs to a `run_agent(question, documents)` function.

Use `claude-3-5-sonnet-20241022` as the model. Include clear comments explaining each part of the agentic loop. Do not add hallucination detection yet — that comes in the next module.

Now write the complete Python code for `grounder.py`.

This module is responsible for enforcing citation traceability on every claim produced by the agent. It must:

1. Define a `Claim` dataclass with fields: `text: str`, `citation_title: str`, `citation_url: str`, `citation_passage: str` (the exact passage from the source that supports this claim).

2. Write a function `extract_claims(agent_output: dict, documents: list[dict]) -> list[Claim]` that:
   - Takes the `claims` list from the agent's output dict
   - For each claim, finds the best matching passage in the source documents using simple keyword overlap (no ML needed)
   - Populates the `citation_passage` field with the actual text from the document
   - Raises a `CitationMissingError` (custom exception) if a claim's cited URL doesn't match any document in the input list

3. Write a function `format_grounded_report(claims: list[Claim]) -> dict` that returns a dict with:
   - `total_claims`: integer count
   - `grounded_claims`: the list of claim dicts with all citation fields populated
   - `ungrounded_count`: how many claims had no matching passage

Include docstrings. Keep it self-contained with no external dependencies beyond Python's standard library.

Write the complete Python code for `hallucination_checker.py`.

This module takes grounded claims (each with a `text` and a `citation_passage`) and uses the OpenAI API (GPT-4o-mini model) to automatically detect hallucinations.

The module must:

1. Define a function `check_claim(claim_text: str, citation_passage: str, openai_client) -> dict` that:
   - Sends a structured prompt to GPT-4o-mini asking it to judge whether `claim_text` is supported by `citation_passage`
   - The system prompt should instruct GPT to act as a strict fact-checker and respond ONLY with a JSON object
   - The JSON response must have exactly these keys: `verdict` (one of "VERIFIED", "UNCERTAIN", "HALLUCINATED"), `confidence` (float 0.0–1.0), `reason` (one sentence explaining the verdict)
   - Use `response_format={"type": "json_object"}` in the API call to enforce JSON output
   - Return the parsed JSON dict

2. Define a function `check_all_claims(grounded_report: dict, openai_client) -> dict` that:
   - Iterates over every claim in `grounded_report["grounded_claims"]`
   - Calls `check_claim` for each one
   - Attaches the verdict dict to each claim under a key called `hallucination_check`
   - Returns a final report dict with keys: `verified_count`, `uncertain_count`, `hallucinated_count`, `claims` (the full enriched list)

3. Handle OpenAI API errors gracefully — if a call fails, set verdict to "UNCERTAIN" and reason to the error message.

Add clear comments. Use the `openai` Python package (v1+).

Write the complete Python code for `cli.py` that wires together `agent.py`, `grounder.py`, and `hallucination_checker.py` into a single runnable pipeline.

The CLI must:
1. Accept a `--question` argument (the research question) and an optional `--docs` argument pointing to a JSON file of documents.
2. If no `--docs` file is provided, use a hardcoded list of 3 sample documents about climate change (each with `title`, `url`, and a multi-sentence `content` field you write inline) so the user can test immediately without any setup.
3. Run this pipeline in order:
   a. Call `run_agent(question, documents)` from `agent.py`
   b. Call `extract_claims(agent_output, documents)` and `format_grounded_report(claims)` from `grounder.py`
   c. Initialise both the `anthropic.Anthropic()` and `openai.OpenAI()` clients using `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` environment variables
   d. Call `check_all_claims(grounded_report, openai_client)` from `hallucination_checker.py`
4. Print a formatted terminal report that shows:
   - The final answer
   - Each claim with its citation and its hallucination verdict (colour-coded: green for VERIFIED, yellow for UNCERTAIN, red for HALLUCINATED using ANSI codes)
   - A summary line: "X verified, Y uncertain, Z hallucinated out of N total claims"
5. Also save the full final report as `output.json` in the current directory.

Include a `if __name__ == "__main__":` guard. Add a comment at the top listing the pip install commands needed: `pip install anthropic openai`.