[Feature] Add --state_file to adk run for loading initial session state from JSON #7083

🔴 Required Information

Is your feature request related to a specific problem?

adk run currently supports initial session state through --state, but the state must be passed as an inline JSON string:

adk run path/to/agent --state '{"customer_id": "123", "region": "us"}'

For realistic state payloads this becomes hard to use:

• Shell quoting differs across bash, zsh, PowerShell, and cmd.
• Larger state payloads are difficult to read, edit, and reuse.
• Sensitive or environment-specific values can end up in shell history.
• Generated state fixtures cannot be reused directly without wrapping them into a command-line string.

This is especially painful when testing agents that depend on session state, dynamic instructions, or state-backed tools.

I searched for existing issues/PRs targeting this specific CLI feature and did not find one for --state_file / --state-file. Related but distinct: #4961 proposes declarative initial state for adk web; this request is specifically for the adk run CLI path.

Describe the Solution You'd Like

Add a --state_file option to adk run that loads initial session state from a JSON file:

adk run path/to/agent --state_file state.json
adk run path/to/agent "hello" --state_file state.json

The file should contain a JSON object used as the initial session state.

Expected behavior:

• --state_file works in both interactive mode and single-query mode.
• --state and --state_file are mutually exclusive.
• Invalid JSON should surface the same style of error as invalid --state JSON.
• Missing/unreadable files should be reported by Click as a normal CLI input error.

Impact on your work

This would make local agent development and repeatable testing much smoother for stateful agents. Instead of copying JSON into a shell command, developers could keep reusable fixtures like:

state.customer-a.json
state.debug.json
state.empty-cart.json

and run the same agent against each state file.

It also reduces quoting friction on Windows/PowerShell, where inline JSON can be particularly awkward.

Willingness to contribute

Yes. I can open a small PR if this direction looks reasonable.

🟡 Recommended Information

Describe Alternatives You've Considered

• Use --state with inline JSON. This works for tiny examples but becomes brittle for realistic payloads and varies by shell.
• Use --replay. This creates a session from an input file with queries, but it is a different workflow and not ideal when I only want to seed state and continue interactively or run a single query.
• Add initialization logic in callbacks. This works, but puts local testing/setup state into agent code.

Proposed API / Implementation

The CLI already forwards --state as state_str into run_cli / run_once_cli, where the JSON parsing path already exists.

A minimal implementation could:

1. Add a Click option on adk run:

@click.option(
    "--state_file",
    type=click.Path(exists=True, dir_okay=False, file_okay=True, resolve_path=True),
    help="Optional. Path to a JSON file containing initial state for the run.",
)

2. Enforce that --state and --state_file cannot be used together.
3. Read the file as UTF-8 in cli_run and pass the contents as state_str to the existing run_cli / run_once_cli calls.
4. Add unit tests under tests/unittests/cli/utils/test_cli_tools_click.py covering interactive mode, single-query mode, mutual exclusion, and bad/missing file behavior.

Additional Context

This is intentionally smaller than a broader declarative state feature. It only makes the existing adk run --state capability easier and safer to use with real JSON files.