Add SDK evolution agent

[ebarti]

Summary

• Add a local SDK evolution agent runnable with python -m examples.sdk_evolution_agent.
• Route AI reasoning stages through agent-runtime-kit primitives, including AgentTask, RuntimeRegistry, output schemas, permission profiles, event sinks, and structured AgentResult handling.
• Add deterministic SDK evidence collection, freshness-cutoff bypassing for UV_EXCLUDE_NEWER, API snapshot/diff helpers, direction/architecture/review stages, recursive self-adaptation gates, local reports, and optional draft PR plumbing.
• Document local usage and add OpenSpec artifacts for the change.
• Update runtime auth handling so provider-owned auth is not flattened to API keys: Claude supports env pass-through for Bedrock/Vertex/AWS/Azure provider modes, Codex supports env pass-through plus Bedrock provider diagnostics, and Antigravity supports Google Application Default Credentials through Vertex AI config.
• Inject an isolated CODEX_HOME=~/.codex_agent_runtime_sdk for the SDK evolution agent's Codex runtime, creating the directory with private permissions before launch.
• Restrict Antigravity report-only analysis/review stages to its finish tool so structured output can complete without unrelated workspace tool use.

Real Runtime Validation

Current full SDK evolution-agent runs completed through two real runtimes:

env -u UV_EXCLUDE_NEWER uv run python -m examples.sdk_evolution_agent \
  --runtime codex-agent-sdk \
  --refresh-preview \
  --report-dir /tmp/ark-sdk-evolution-real-codex-current

Report from the pre-isolated Codex home validation:

/private/tmp/ark-sdk-evolution-real-codex-current/20260621T223655Z/report.md

After adding CODEX_HOME=~/.codex_agent_runtime_sdk, a fresh isolated Codex home was created successfully but the real Codex run correctly failed with 401 until that new home is authenticated through supported Codex login/API-key/access-token flows. This PR does not copy or scrape credentials from the user's normal Codex home.

/opt/homebrew/bin/timeout 300 /Users/eloibarti/.codex/worktrees/b0df/agent-runtime-kit/.venv/bin/python \
  -m examples.sdk_evolution_agent \
  --runtime antigravity-agent-sdk \
  --refresh-preview \
  --report-dir /tmp/ark-sdk-evolution-real-antigravity

Report:

/private/tmp/ark-sdk-evolution-real-antigravity/20260621T223529Z/report.md

The Antigravity run was executed from a non-hidden workspace copy because the Google local harness rejects hidden .codex worktree paths. It completed successfully after the stage permissions were narrowed to the finish tool for report-only reasoning stages.

A real Claude adapter smoke test also completed through the local configured provider auth:

availability True available available {'auth_source': 'google-vertex-ai', 'credential_chain': 'google-application-default-credentials', 'project_configured': True}
finish_reason done
output claude auth ok
error None

Provider availability diagnostics during validation:

• claude-agent-sdk: available with auth_source=google-vertex-ai.
• codex-agent-sdk: available with provider-owned local auth; isolated CODEX_HOME requires its own supported auth setup.
• antigravity-agent-sdk: available with auth_source=application-default-credentials.

Bedrock support was verified at the adapter/configuration boundary, not with a live AWS Bedrock invocation in this environment. The PR adds Claude runtime env pass-through for CLAUDE_CODE_USE_BEDROCK=1 and AWS SDK credential-chain configuration, Codex env pass-through plus model_provider=amazon-bedrock diagnostics, tests for both paths, and docs pointing users to the supported vendor auth mechanisms.

Validation

• env -u UV_EXCLUDE_NEWER uv run ruff check .
• env -u UV_EXCLUDE_NEWER uv run mypy
• env -u UV_EXCLUDE_NEWER uv run pytest (93 passed, 3 skipped)
• Core-install reproduction: UV_PROJECT_ENVIRONMENT=/tmp/ark-ci-core-venv uv run mypy and UV_PROJECT_ENVIRONMENT=/tmp/ark-ci-core-venv uv run pytest (84 passed, 12 skipped)
• openspec validate add-sdk-evolution-agent
• env -u UV_EXCLUDE_NEWER uv run python -m examples.sdk_evolution_agent --runtime codex-agent-sdk --refresh-preview --report-dir /tmp/ark-sdk-evolution-real-codex-current
• /opt/homebrew/bin/timeout 300 /Users/eloibarti/.codex/worktrees/b0df/agent-runtime-kit/.venv/bin/python -m examples.sdk_evolution_agent --runtime antigravity-agent-sdk --refresh-preview --report-dir /tmp/ark-sdk-evolution-real-antigravity
• Real Claude adapter smoke through ClaudeAgentRuntime with the configured Vertex auth.

Notes

The agent defaults to report-only mode and blocks implementation when reviewer, capability, evidence, or recursive self-adaptation gates fail. It does not auto-merge, auto-publish, or scrape unsupported credentials.