feat: structured JSON output mode for programmatic consumption

[Jamie-BitFlight]

Summary

Add a JSON/JSONL output mode so trigger matches can be consumed programmatically by CI pipelines, dashboards, or other tools.

Current Behavior

The stop hook outputs human-readable text to stdout. This works for Claude Code's stop hook mechanism but is difficult to parse for automation.

Proposed Behavior

Support multiple output formats via config or environment variable:

text (default, current)

HALLUCINATION_DETECTED: speculation_language — "I think" at offset 12

json

{
  "status": "fail",
  "triggerCount": 3,
  "triggers": [
    { "kind": "speculation_language", "evidence": "I think", "offset": 12, "confidence": 75 },
    { "kind": "causality_language", "evidence": "because", "offset": 45, "confidence": 82 }
  ],
  "scannedLength": 1024,
  "timestamp": "2026-02-28T03:50:00Z"
}

jsonl

One JSON object per line — suitable for streaming and log aggregation.

Use Cases

• CI pipeline integration (fail build on hallucination triggers)
• Dashboard/metrics collection
• Integration with other tools that consume structured output
• Aggregating trigger statistics across sessions

Acceptance Criteria

• `outputFormat` setting in config (feat: config file handling — cascading settings from multiple sources #10) controls format
• `HALLUCINATION_DETECTOR_FORMAT` env var as override
• JSON schema documented
• Text format remains the default
• Tests cover all three output modes

[Jamie-BitFlight]

Grouping: Group E — Output Pipeline

Implement together with: #13

Rationale: Both modify the output format. The JSON schema defined here should include the suggestedFix field from #13, the confidence field from #12/#21, and any future fields — designing the schema once rather than extending it incrementally.

Dependencies: Benefits from #10 (config) for the outputFormat setting and HALLUCINATION_DETECTOR_FORMAT env var.

[Jamie-BitFlight]

Deep Analysis: Implementation Impact

Classification

• Impact type: CONTRACT
• Risk: CRITICAL — can silently disable the entire hook
• Phase: 5 — Output pipeline (after scoring shape is stable)

The danger

The Stop hook's stdout contract with Claude Code is exactly { "decision": "block", "reason": "..." }. This issue proposes emitting { "status": "fail", "triggerCount": 3, "triggers": [...] } — a completely different JSON schema. If this replaces stdout, Claude Code will never see decision: "block" and will never block any response.

Implementation constraint

The structured JSON output MUST use one of:

1. A separate channel (stderr, a sidecar file, or an env-var-specified output path)
2. Embedded within the existing reason field
3. Only active in CI/standalone mode — not when running as a Claude Code hook
4. Always emit both — the Claude Code contract on stdout, plus structured data in a secondary field

Dependencies

• Depends on feat: config file handling — cascading settings from multiple sources #10 for outputFormat config key and HALLUCINATION_DETECTOR_FORMAT env var
• Should be implemented AFTER feat: sentence-level granularity and weighted multi-signal scoring #21 (scoring) so the JSON schema includes per-sentence scores
• Should be implemented AFTER feat: corrected text suggestions alongside flags #13 (suggestions) so the schema includes suggestedFix
• Designing the schema once avoids breaking it incrementally

Sequencing

• Blocked by: feat: config file handling — cascading settings from multiple sources #10, ideally feat: sentence-level granularity and weighted multi-signal scoring #21 and feat: corrected text suggestions alongside flags #13
• Blocks: nothing directly, but feat: Expose hallucination audit logic as MCP tool #1 (MCP server) benefits from a stable JSON schema

Failure mode

If the default output format changes → every existing user's hook silently stops working. No error. No crash. Responses just pass through unaudited.

The issue body has a factual discrepancy

The issue describes current behavior as "human-readable text to stdout." The actual current behavior is JSON: { "decision": "block", "reason": "..." }. The implementation must account for this.