JSON Report Plugin

What It Does

@agentxchain/plugin-json-report writes structured lifecycle artifacts to disk for each built-in hook phase:

• after_acceptance
• before_gate
• on_escalation

This is the simplest externalization surface for CI jobs, dashboards, or repo-local automation that wants machine-readable AgentXchain state without calling external APIs.

Install

Install by short name (recommended):

agentxchain plugin install json-report

Install with a custom output path:

agentxchain plugin install json-report \
  --config '{"report_dir":".agentxchain/custom-reports"}'

Proven Built-In Path

The built-in short-name path is not just documented; it is exercised in repo proof surfaces:

• continuous subprocess proof: cli/test/e2e-builtin-json-report.test.js
• live product-example proof: node examples/governed-todo-app/run-json-report-proof.mjs --json

The live proof installs json-report by short name into a temp governed-todo-app harness, runs agentxchain run --auto-approve, and verifies that plugin-written JSON artifacts appear in .agentxchain/reports/.

Recorded live case study (2026-04-13):

Metric	Value
Plugin install path	agentxchain plugin install json-report
Run type	governed-todo-app transformed auto-run proof
Plugin source	builtin:json-report
Reports verified	latest.json, latest-after_acceptance.json, latest-before_gate.json
Timestamped plugin JSON files	6
Roles	pm -> dev -> qa
Accepted turns	3
Total cost	$0.0220
Run ID	run_583e233dd47ca238
Result	PASS

Config

{
  "report_dir": ".agentxchain/custom-reports"
}

• report_dir Optional output directory relative to the governed project root.

If report_dir is omitted, the plugin writes to .agentxchain/reports.

Files Written

Each invocation writes:

• one timestamped JSON file named <timestamp>-<hook_phase>.json
• latest.json
• latest-<hook_phase>.json

The report payload includes:

• plugin_name
• hook_phase
• run_id
• hook_name
• turn_id when present
• timestamp
• payload

Failure Semantics

• Advisory only.
• Invalid AGENTXCHAIN_PLUGIN_CONFIG JSON returns warn.
• Missing AGENTXCHAIN_PROJECT_ROOT returns warn.
• A configured report_dir that escapes the governed project root returns warn.

Boundaries

• This plugin is filesystem-local only. It does not upload to external storage.
• report_dir must stay inside the governed project root.
• It writes hook evidence; it does not mutate governance state or approve transitions.
• latest.json reflects the most recent plugin invocation, which is often a before_gate event in auto-approved runs.