fix: make JSON capture preflight side-effect free

CHANGELOG.md

@@ -13,6 +13,9 @@ and versions are tracked in the repo-root `VERSION` file.
 
 ### Fixed
 
+- Detect JSON capture without running Click callbacks, callable defaults, type
+  converters, or close hooks a second time; respect option-value arity so a
+  payload equal to `--json` remains human output.
 - Preserve explicit application identities losslessly while using
   collision-resistant, path-safe runtime namespace components.
 - Give `BatteriesIncludedConfigLoader.cli_name` a documented identity role by

docs/json-contracts.md

@@ -26,6 +26,11 @@ in memory and rolls the remainder to a temporary file, so both temporary-disk
 use and finalization memory remain bounded. The temporary file is removed when
 the invocation ends.
 
+The mode check respects Click option arity: a value such as
+`--payload --json` does not activate JSON when `--json` is the payload. It does
+not run consumer callbacks, defaults, type converters, or close hooks as a
+second parse before the real invocation.
+
 If a command exceeds the limit, base-cli emits one `base-cli.error` envelope
 with `code: "capture_limit"` and exit code `1`; it never silently truncates
 the captured text. Use the NDJSON contract for larger record sets.

lib/python/base_cli/_app_core.py

@@ -126,6 +126,7 @@ class _InvocationState:
     options_parsed: bool = False
     attached_completion: bool = False
     json_output: bool = False
+    output_router: Any = None
 
 
 @dataclass(frozen=True)
@@ -303,6 +304,10 @@ def _capture_standard_options(standard: dict[str, Any], owner_app: App) -> None:
     state.quiet = bool(standard.get("quiet"))
     state.json_output = bool(standard.get("json"))
     state.options_parsed = True
+    router = state.output_router
+    resolve_json_output = getattr(router, "resolve_json_output", None)
+    if callable(resolve_json_output):
+        resolve_json_output(state.json_output)
 
 
 def _capture_effective_output_options(