maida assert

Evaluates one already-completed trace against v2 invariant and measured rules, or standalone CLI flags. Statistical, distributional, and plan metrics require maida run or maida drift; this single-run interface rejects them instead of silently skipping checks.

Usage:

maida assert [TRACE_ID] [options]

maida init does not change ordinary run selection: maida assert --baseline PATH still checks the latest SDK/Python run without any additional option. Adding or removing assertion flags never switches to Claude capture. Use maida check for the first captured task’s report, or pass an explicit Claude trace ID to assert against your own policy or baseline. Explicit Claude IDs and prefixes resolve automatically, including after detach.

Arguments / options:

Argument/Option	Default	Description
TRACE_ID	(latest run)	OTel trace ID or prefix to check
--baseline, -b	-	Baseline JSON file to compare against
--policy	.maida/policy.yaml (auto-detected)	Policy file with an explicit supported version (2 or 2.1)
--max-steps	-	Max total events allowed
--step-tolerance	0.5	Fractional tolerance for step count
--max-tool-calls	-	Max tool calls allowed
--tool-call-tolerance	0.5	Fractional tolerance for tool calls
--no-new-tools	false	Fail if run uses tools not in baseline
--no-loops	false	Fail if any LOOP_WARNING present
--no-guardrails	false	Fail if any guardrail was triggered
--max-cost-tokens	-	Max total tokens allowed
--cost-tolerance	0.5	Fractional tolerance for token cost
--max-duration-ms	-	Max run duration in ms
--duration-tolerance	0.5	Fractional tolerance for duration
--expect-status	-	Expected run status (ok or error)
--ignore-check	-	Skip a named check. Repeatable.
--format, -f	text	Output format: text, json, or markdown

Precedence: CLI flags override the policy file, which overrides defaults. See the Policy YAML reference for the full override rules and threshold semantics.

Examples:

# Assert the latest run against a baseline with default tolerances
maida assert --baseline .maida/baselines/my_agent.json

# Assert a specific run with standalone thresholds (no baseline)
maida assert a1b2c3d4 --max-steps 80 --max-tool-calls 30 --no-loops

# Assert using a policy file
maida assert --baseline baseline.json --policy ci-policy.yaml

# Markdown output for GitHub PR comments / step summaries
maida assert --baseline baseline.json --format markdown

Exit codes: 0 all checks passed; 1 one or more checks failed; 2 invalid policy, run or baseline not found; 10 internal error.

Each assertion result includes a stable reason_code; JSON output also includes a top-level reason_codes array for failed checks. Markdown output starts with a pass/fail verdict, shows Top behavior changes when a baseline diff is available, groups failed checks by reason code, and includes concise next steps plus a local-repro snippet. The text report appends the structural diff on failure.