agent-runtime-kit 0.5.1__tar.gz → 0.5.3__tar.gz

{agent_runtime_kit-0.5.1 → agent_runtime_kit-0.5.3}/CHANGELOG.md

@@ -5,6 +5,58 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.5.3 - 2026-10-02
+
+### Added
+
+- Codex tasks can request provider-native named permission profiles through
+  `PermissionProfile(native_profile="...")`, with conflicting settings rejected
+  and the effective policy preserved across reused sessions.
+- Claude runtime exposes opt-in `verbatim_prompts=True` for literal composed
+  goals, with a typed refusal if the installed SDK cannot honor the option.
+
+### Changed
+
+- Updated tested Claude Agent SDK to `0.2.163`, Google Antigravity SDK to
+  `0.1.20`, and the exactly coupled Codex SDK and CLI to `0.160.0`.
+- Raised the Codex SDK minimum to `0.157.1` for native named-profile support.
+- Quickstart and examples now provide runnable offline, structured-output,
+  event-streaming, diagnostics, and provider-task flows.
+
+### Fixed
+
+- Codex named permission profiles no longer receive a legacy sandbox override
+  that could bypass the requested profile.
+- Antigravity explicit read-only allowlists retain directory/search tools after
+  the SDK removes them from default tool collections, without re-enabling them
+  by default or admitting deprecated write tools.
+
+## 0.5.2 - 2026-09-19
+
+### Changed
+
+- Updated tested Claude Agent SDK to `0.2.157`, Google Antigravity SDK to
+  `0.1.17`, and the Codex SDK and its exactly coupled CLI to `0.154.0`.
+- SDK evolution supports explicit model, reasoning effort and analysis executable
+  options, preserves older locked baselines in implementation history, and
+  constructs real Claude options and Codex wire parameters in candidate probes.
+- Upgrade skill invocations now include necessary runtime adaptations,
+  verification, and a regular pull request. Explicit report-only and local-only
+  requests retain their narrower scope.
+
+### Fixed
+
+- Antigravity permissive deny-lists preserve all unrelated tools when the SDK's
+  default tool set changes, including the `ask_question` change in 0.1.17.
+- Codex release evidence uses the current official documentation endpoints.
+- Antigravity preserves explicit `vertex=True` with an API key for Vertex
+  Express authentication, rejects mixed regional credentials, and refuses older
+  SDKs or configurations that would silently drop the requested endpoint.
+- Release-note collection recognizes versions present only in a GitHub
+  discussion title and rejects unrelated or longer version-prefix matches.
+- PyPI publication validates and uploads Core Metadata 2.5 distributions with
+  matching Twine support.
+
 ## 0.5.1 - 2026-08-29
 
 ### Added

agent_runtime_kit-0.5.3/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: agent-runtime-kit
+Version: 0.5.3
+Summary: One typed runtime API for Claude, Codex, and Antigravity agent SDKs.
+Project-URL: Homepage, https://github.com/ebarti/agent-runtime-kit
+Project-URL: Repository, https://github.com/ebarti/agent-runtime-kit
+Project-URL: Issues, https://github.com/ebarti/agent-runtime-kit/issues
+Author: Eloi Barti
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-runtime,agent-sdk,agents,antigravity,async-python,claude,claude-code,codex,coding-agents,developer-tools,google-antigravity,mcp,openai-codex,runtime-api,sdk,typed-python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: jsonschema<5,>=4.18
+Requires-Dist: tomli<3,>=2; python_version < '3.11'
+Provides-Extra: all
+Requires-Dist: claude-agent-sdk<0.3,>=0.2.87; extra == 'all'
+Requires-Dist: google-antigravity<0.2,>=0.1.2; extra == 'all'
+Requires-Dist: openai-codex<0.161,>=0.157.1; extra == 'all'
+Provides-Extra: antigravity
+Requires-Dist: google-antigravity<0.2,>=0.1.2; extra == 'antigravity'
+Provides-Extra: claude
+Requires-Dist: claude-agent-sdk<0.3,>=0.2.87; extra == 'claude'
+Provides-Extra: codex
+Requires-Dist: openai-codex<0.161,>=0.157.1; extra == 'codex'
+Description-Content-Type: text/markdown
+
+# agent-runtime-kit
+
+`agent-runtime-kit` gives Python 3.10+ applications one typed, async API for
+running coding-agent tasks with Claude Agent SDK, OpenAI Codex SDK, or Google
+Antigravity SDK. It exposes capability checks, events, diagnostics, and results
+while keeping each provider's permissions and supported inputs explicit.
+
+## Install and try it offline
+
+The core install has no vendor SDK or credential requirement:
+
+```bash
+python -m pip install agent-runtime-kit
+```
+
+```python
+import asyncio
+
+from agent_runtime_kit import AgentKit, FakeAgentRuntime
+
+
+async def main() -> None:
+    async with AgentKit() as kit:
+        result = await kit.run(
+            FakeAgentRuntime(output="offline example complete"),
+            goal="Demonstrate a task result",
+        )
+        if not result.is_success:
+            raise RuntimeError(result.error or result.finish_reason)
+        print(result.output)
+
+
+asyncio.run(main())
+```
+
+This prints `offline example complete`. The fake runtime returns a deterministic
+result; it does not inspect the repository or contact a provider. Run the file
+version with `python -m examples.basic_offline` from a source checkout.
+
+## Run a real provider
+
+Install only the provider you use, then configure its supported authentication:
+
+```bash
+python -m pip install "agent-runtime-kit[claude]"      # Claude Agent SDK
+python -m pip install "agent-runtime-kit[codex]"       # OpenAI Codex SDK
+python -m pip install "agent-runtime-kit[antigravity]" # Google Antigravity SDK
+```
+
+`agent-runtime-kit[all]` installs all three. A real task may use a paid provider
+and may invoke tools. After setting up the chosen provider, run one explicitly
+from a source checkout:
+
+```bash
+python -m examples.provider_task claude
+```
+
+Choose `codex` or `antigravity` instead to use that runtime. The example checks
+package availability, probes setup, requests read-only filesystem access, and
+checks `result.is_success`. Readiness only indicates whether a task is worth
+attempting; it cannot guarantee the provider will accept the request.
+
+The adapters share `AgentTask` and `AgentResult`, but inputs are not silently
+discarded. For example, Claude supports per-task MCP servers and a cost budget;
+Codex does not expose either per task; Antigravity supports MCP servers without
+per-server environment values. Unsupported inputs raise typed errors. The
+provider's native model selection is used unless you set a model explicitly.
+
+## Guides
+
+- [Quickstart](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/quickstart.md): install, offline result, and first provider run
+- [Examples](https://github.com/ebarti/agent-runtime-kit/blob/main/examples/README.md): runnable commands and expected results
+- [Recipes](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/recipes.md): results, events, preflight, permissions, sessions, and MCP
+- [Provider diagnostics](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/providers.md) and [capability matrix](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/capability-matrix.md)
+- [Deadlines and cancellation](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/task-control.md) and [API stability](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/api-stability.md)
+- [Live smoke tests](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/live-smoke.md) and [SDK evolution agent](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/sdk-evolution-agent.md)
+
+The package is a runtime layer, not a router, queue, hosted service, or full
+agent framework. Applications choose when and where to run a task.

agent_runtime_kit-0.5.3/README.md

@@ -0,0 +1,79 @@
+# agent-runtime-kit
+
+`agent-runtime-kit` gives Python 3.10+ applications one typed, async API for
+running coding-agent tasks with Claude Agent SDK, OpenAI Codex SDK, or Google
+Antigravity SDK. It exposes capability checks, events, diagnostics, and results
+while keeping each provider's permissions and supported inputs explicit.
+
+## Install and try it offline
+
+The core install has no vendor SDK or credential requirement:
+
+```bash
+python -m pip install agent-runtime-kit
+```
+
+```python
+import asyncio
+
+from agent_runtime_kit import AgentKit, FakeAgentRuntime
+
+
+async def main() -> None:
+    async with AgentKit() as kit:
+        result = await kit.run(
+            FakeAgentRuntime(output="offline example complete"),
+            goal="Demonstrate a task result",
+        )
+        if not result.is_success:
+            raise RuntimeError(result.error or result.finish_reason)
+        print(result.output)
+
+
+asyncio.run(main())
+```
+
+This prints `offline example complete`. The fake runtime returns a deterministic
+result; it does not inspect the repository or contact a provider. Run the file
+version with `python -m examples.basic_offline` from a source checkout.
+
+## Run a real provider
+
+Install only the provider you use, then configure its supported authentication:
+
+```bash
+python -m pip install "agent-runtime-kit[claude]"      # Claude Agent SDK
+python -m pip install "agent-runtime-kit[codex]"       # OpenAI Codex SDK
+python -m pip install "agent-runtime-kit[antigravity]" # Google Antigravity SDK
+```
+
+`agent-runtime-kit[all]` installs all three. A real task may use a paid provider
+and may invoke tools. After setting up the chosen provider, run one explicitly
+from a source checkout:
+
+```bash
+python -m examples.provider_task claude
+```
+
+Choose `codex` or `antigravity` instead to use that runtime. The example checks
+package availability, probes setup, requests read-only filesystem access, and
+checks `result.is_success`. Readiness only indicates whether a task is worth
+attempting; it cannot guarantee the provider will accept the request.
+
+The adapters share `AgentTask` and `AgentResult`, but inputs are not silently
+discarded. For example, Claude supports per-task MCP servers and a cost budget;
+Codex does not expose either per task; Antigravity supports MCP servers without
+per-server environment values. Unsupported inputs raise typed errors. The
+provider's native model selection is used unless you set a model explicitly.
+
+## Guides
+
+- [Quickstart](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/quickstart.md): install, offline result, and first provider run
+- [Examples](https://github.com/ebarti/agent-runtime-kit/blob/main/examples/README.md): runnable commands and expected results
+- [Recipes](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/recipes.md): results, events, preflight, permissions, sessions, and MCP
+- [Provider diagnostics](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/providers.md) and [capability matrix](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/capability-matrix.md)
+- [Deadlines and cancellation](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/task-control.md) and [API stability](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/api-stability.md)
+- [Live smoke tests](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/live-smoke.md) and [SDK evolution agent](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/sdk-evolution-agent.md)
+
+The package is a runtime layer, not a router, queue, hosted service, or full
+agent framework. Applications choose when and where to run a task.

{agent_runtime_kit-0.5.1 → agent_runtime_kit-0.5.3}/docs/providers.md

@@ -153,6 +153,17 @@ per-query session id. `AgentResult.metadata["sdk_process_reuse_scope"]` reports
 `"conversation"` or `"shared"` accordingly. The runtime restarts the SDK process
 when the option fingerprint changes and evicts it after SDK exceptions.
 
+With Claude Agent SDK 0.2.158 or newer, pass
+`ClaudeAgentRuntime(verbatim_prompts=True)` when goals contain composed or
+third-party text. This opts into the SDK's literal prompt delivery: `@path`
+mentions and slash commands are not expanded or dispatched. The default stays
+`False`. An older SDK that cannot accept the requested option raises
+`UnsupportedTaskInputError` before dispatch. The bundled Claude CLI must be
+2.1.248 or newer; older custom CLIs may ignore the option. Verbatim delivery also
+skips the CLI's initial attachment pass, including MCP mentions, nested
+`CLAUDE.md`/rules, and skill/tool listings; some context arrives after the first
+tool call instead. It applies to both one-shot and reused-process execution.
+
 Codex uses the `openai-codex` package and maps working directory, session
 resume, approval mode, sandbox, structured output, model, and reasoning effort.
 Approval mode follows `PermissionMode`: `STRICT`/`CAUTIOUS` → `deny_all` (never
@@ -188,16 +199,32 @@ constructor, `GEMINI_API_KEY`, or `GOOGLE_API_KEY`. Without an API key, the
 adapter uses Vertex AI config with Google ADC when a project can be discovered
 from ADC, `GOOGLE_CLOUD_PROJECT`, or `GCLOUD_PROJECT`; location defaults to
 `global` unless `GOOGLE_CLOUD_LOCATION`, `GOOGLE_CLOUD_REGION`, or
-`CLOUD_ML_REGION` is set. Precedence: an explicit constructor `api_key` is the
-most specific request and wins; otherwise an explicit
+`CLOUD_ML_REGION` is set. An explicit constructor `api_key` takes precedence over
+ambient credentials. With `vertex=True`, that key selects Vertex Express mode
+(supported by released `google-antigravity>=0.1.16` versions): no ADC, project,
+or location is required. Older or unverifiable SDK releases raise
+`UnsupportedTaskInputError` for Express mode; their existing authentication
+modes remain available. Explicit project/location arguments cannot be combined
+with Express mode. For example:
+
+```python
+runtime = AntigravityAgentRuntime(vertex=True, api_key=vertex_express_key)
+```
+
+Without an explicit key, an explicit
 `AntigravityAgentRuntime(vertex=True, ...)` takes precedence over an ambient
 `GEMINI_API_KEY`/`GOOGLE_API_KEY`, so a Vertex-configured runtime is never
-silently redirected to the Gemini API by an exported environment key. Under
-`PERMISSIVE`, `disallowed_tools` maps to `CapabilitiesConfig.disabled_tools`
-(the baseline is every tool, so "enable everything else" is exact); under any
-other posture the deny-list is folded into an allow-list of the mode's baseline
-minus the denied tools, so denying one tool can never re-enable others past the
-baseline. An allow-list and a deny-list are mutually exclusive (the SDK forbids
+silently redirected to the Gemini API by an exported environment key. When no
+model is supplied, the adapter preserves the vendor default (`gemini-3.8-flash`
+in Antigravity 0.1.16); supply `default_model` or `AgentTask.model` when a stable
+model selection is required. Under
+`PERMISSIVE`, `disallowed_tools` becomes an explicit `enabled_tools` list of all
+built-in tools minus the denied tools. Antigravity 0.1.17 changed its implicit
+deny-list baseline to exclude `ask_question`; using an explicit list preserves
+the adapter's existing all-tools contract. Under other postures the deny-list
+is subtracted from the mode's narrower baseline, so denying one tool can never
+re-enable others past that baseline. An allow-list and a deny-list are mutually
+exclusive (the SDK forbids
 combining enabled and disabled tool lists), so supplying both is rejected. Tool
 names are validated against the
 `BuiltinTools` enum (`"view_file"`, not `"Read"`). `budget_usd` and
@@ -217,6 +244,13 @@ dropped only for `STRICT`. When an explicit `allowed_tools` list is combined wit
 a `READ_ONLY` filesystem, any non-read-only tool in it is rejected rather than
 silently granted.
 
+Antigravity 0.1.20 removes `list_directory`, `search_directory`, and `find_file`
+from its default read-only and nondestructive collections. Request them
+explicitly through `allowed_tools` when needed; they remain valid under
+`READ_ONLY` or `STRICT`. Default and deny-list baselines continue to follow the
+SDK's collections. The SDK also adds `schedule` to those collections; callers
+that need a narrower toolset should provide an explicit allow-list.
+
 A deny-list under a `READ_ONLY` filesystem (or `STRICT`) subtracts from the
 read-only toolset, and under `DEFAULT`/`CAUTIOUS` from the nondestructive
 toolset — `disabled_tools` alone would re-enable every unnamed write or

agent_runtime_kit-0.5.3/docs/quickstart.md

@@ -0,0 +1,114 @@
+# Quickstart
+
+`agent-runtime-kit` requires Python 3.10 or newer. Install the core package to
+run the credential-free example:
+
+```bash
+python -m pip install agent-runtime-kit
+```
+
+If you cloned the repository, run examples from its root with
+`python -m examples.basic_offline`. For a standalone script, save the following
+as `offline.py` and run `python offline.py`:
+
+```python
+import asyncio
+
+from agent_runtime_kit import AgentKit, FakeAgentRuntime
+
+
+async def main() -> None:
+    async with AgentKit() as kit:
+        result = await kit.run(
+            FakeAgentRuntime(output="offline example complete"),
+            goal="Demonstrate a task result",
+        )
+        if not result.is_success:
+            raise RuntimeError(result.error or result.finish_reason)
+        print(result.output)
+
+
+asyncio.run(main())
+```
+
+Expected output: `offline example complete`. `FakeAgentRuntime` is a
+deterministic test runtime. Its goal is carried through the API, but it does not
+read files or call a model.
+
+## Choose a provider
+
+Install exactly the extra you need, or use `agent-runtime-kit[all]`:
+
+```bash
+python -m pip install "agent-runtime-kit[claude]"
+python -m pip install "agent-runtime-kit[codex]"
+python -m pip install "agent-runtime-kit[antigravity]"
+```
+
+Set up authentication with the provider's supported mechanism: [Claude Agent
+SDK](https://code.claude.com/docs/en/agent-sdk/overview), [Codex
+authentication](https://learn.chatgpt.com/docs/auth), or [Antigravity SDK
+setup](https://github.com/google-antigravity/antigravity-sdk-python). For
+example, Codex supports `codex login` and `codex login status`; Antigravity's
+API-key path uses `GEMINI_API_KEY`. See [provider notes](providers.md) for this
+package's exact adapter mappings.
+
+From a source checkout, run one chosen provider:
+
+```bash
+python -m examples.provider_task claude
+```
+
+The command takes `claude`, `codex`, or `antigravity`. It may make a paid model
+call. It checks the installed package and bounded readiness probe, then asks
+the provider to summarize the current directory with explicit read-only
+filesystem access. A confirmed `NOT_READY` result stops the example;
+`INDETERMINATE` also stops until you explicitly pass `--attempt-indeterminate`.
+That flag is a caller policy choice, not proof of readiness.
+
+## Use the API directly
+
+```python
+import asyncio
+from pathlib import Path
+
+from agent_runtime_kit import AgentKit, ReadinessStatus
+
+
+async def main() -> None:
+    async with AgentKit() as kit:
+        provider = "claude"
+        availability = kit.availability_for(provider)
+        if not availability.available:
+            raise RuntimeError(availability.message)
+
+        readiness = await kit.readiness_for(provider)
+        if readiness.status is not ReadinessStatus.READY_TO_ATTEMPT:
+            raise RuntimeError(readiness.message)
+
+        result = await kit.run(
+            provider,
+            goal="Summarize the purpose of this repository in one paragraph.",
+            working_directory=Path.cwd(),
+            permissions="strict",
+            filesystem="read-only",
+        )
+        if not result.is_success:
+            raise RuntimeError(result.error or result.finish_reason)
+        print(result.output)
+
+
+asyncio.run(main())
+```
+
+`AgentKit` lazily resolves and caches built-in runtimes; `async with` closes
+those it created. A runtime instance passed directly to `run` remains the
+caller's responsibility to close. `permissions="strict"` alone does not
+request read-only filesystem access: the default filesystem posture is
+`workspace-write`. Each provider maps permission requests through its own SDK,
+so check the [capability matrix](capability-matrix.md) before relying on a
+particular tool posture.
+
+For typed output and event examples, see the [runnable example
+index](../examples/README.md). The [recipes](recipes.md) explain result
+semantics, compatibility preflight, sessions, and MCP.

agent_runtime_kit-0.5.3/docs/recipes.md

@@ -0,0 +1,125 @@
+# Practical recipes
+
+These recipes use the public API. Start with the [quickstart](quickstart.md)
+and [runnable examples](../examples/README.md).
+
+## Handle results and errors
+
+`run()` can raise for invalid or unsupported inputs, missing runtimes, and
+deadlines. It can also return an `AgentResult` whose `finish_reason` is not
+`done` or whose `error` is set. Always check `is_success` before using output:
+
+```python
+result = await kit.run(
+    "claude",
+    goal="Summarize this repository",
+    permissions="strict",
+    filesystem="read-only",
+)
+if not result.is_success:
+    raise RuntimeError(result.error or result.finish_reason)
+print(result.output)
+```
+
+For `output_type=Summary`, `result.parsed` is a validated instance on a
+successful non-null result. A mismatched payload becomes a failed result.
+Use `result.parsed_output_available` to distinguish an absent structured
+payload from valid JSON `null`; both have `parsed_output is None`. Usage and
+cost fields are `None` when the provider does not report them, while reported
+zero stays zero. Built-in runtimes currently leave `artifacts` empty.
+
+## Separate preflight from setup
+
+Use `kit.validate_task(provider, task)` to list statically detectable
+unsupported fields without dispatching a task. Use
+`kit.availability_for(provider)` for a synchronous, package-only check. Use
+`await kit.readiness_for(provider)` for a bounded setup probe:
+
+```python
+from agent_runtime_kit import AgentTask, ReadinessStatus
+
+task = AgentTask(goal="Summarize this repository")
+report = kit.validate_task("codex", task)
+if not report.supported:
+    for issue in report.issues:
+        print(issue.field, issue.message)
+
+availability = kit.availability_for("codex")
+if availability.available:
+    readiness = await kit.readiness_for("codex")
+    if readiness.status is ReadinessStatus.READY_TO_ATTEMPT:
+        print("Setup detected; a task may be attempted")
+```
+
+These checks answer different questions. Static support does not prove that a
+package is installed. Package availability does not prove credentials or
+network access. `READY_TO_ATTEMPT` means setup was detected, not that a task
+will succeed. `INDETERMINATE` requires an application policy decision; it is
+not a positive readiness result. The [provider diagnostics](providers.md)
+describe safe probe behavior.
+
+## Request permissions explicitly
+
+```python
+result = await kit.run(
+    "claude",
+    goal="Summarize this repository",
+    permissions="strict",
+    filesystem="read-only",
+)
+```
+
+The default filesystem request is `workspace-write`, even under `strict`.
+Adapters map both settings to vendor controls; they are not a universal OS
+sandbox guarantee. `permissions.network` has no supported per-task mapping in
+the built-in adapters and is rejected. Tool allow/deny lists and approval
+behavior differ by provider. Read the [capability matrix](capability-matrix.md)
+before requesting a more permissive posture.
+
+`sdk_executions` is an informational task/event field, not a portable turn or
+spend cap. Only Claude maps `budget_usd`; Codex and Antigravity reject it.
+Use [deadlines and cancellation](task-control.md) to bound a task's duration.
+
+## Observe events
+
+`AgentKit.on()` registers a sync or async handler for normalized event names.
+Register before dispatch. Handler failures are swallowed so logging cannot
+break a run; send events to your own durable sink if they must be retained.
+
+```python
+@kit.on("agent.tool.completed")
+def log_tool(event):
+    print(event["summary"])
+```
+
+See `python -m examples.events` for a complete offline run. Events may contain
+redacted or truncated attributes; a tool audit is best-effort evidence of what
+the vendor reported, not proof that no other side effect occurred.
+
+## Resume a session when supported
+
+Pass `session_id` or `resume_from` on a task, but not both. Save a returned
+`result.session_id` if you need it later, and check session support for the
+chosen runtime before reuse. An omitted handle starts a task-isolated
+conversation; process reuse does not imply session reuse. Provider-specific
+session behavior is documented in [provider notes](providers.md).
+
+## Configure an MCP server where supported
+
+```python
+from agent_runtime_kit import AgentTask, McpServerConfig
+
+task = AgentTask(
+    goal="Use the local documentation server",
+    mcp_servers=(McpServerConfig(name="docs", command="my-docs-mcp"),),
+)
+report = kit.validate_task("claude", task)
+if not report.supported:
+    raise ValueError(report.issues)
+```
+
+Claude and Antigravity accept per-task stdio MCP servers; Codex rejects
+per-task MCP configuration. Antigravity does not accept per-server `env` values.
+The command starts only when a real task is dispatched. Choose and trust the
+server executable as you would any local process. See the [capability
+matrix](capability-matrix.md) for other differences.

{agent_runtime_kit-0.5.1 → agent_runtime_kit-0.5.3}/docs/sdk-evolution-agent.md

@@ -4,6 +4,15 @@ The SDK evolution agent is a local dogfood workflow for keeping
 agent-runtime-kit aligned with Claude Agent SDK, OpenAI Codex SDK, and Google
 Antigravity SDK as those upstream packages evolve.
 
+For a complete upgrade, invoke the repository's
+[`agent-runtime-kit-upgrade` skill](../.codex/skills/agent-runtime-kit-upgrade/SKILL.md).
+It collects evidence first, maps upstream implementation trends to the current
+integration, implements the necessary adapter/runtime changes with tests and
+docs, applies the compatible dependency update, and creates a verified regular
+pull request. Explicit report-only and local-only requests retain those limits.
+The CLI examples below describe the underlying runner; its report-only default
+and dependency-only implementation lane are stages within that broader skill.
+
 For the intended architecture, evidence contract, behavior probe strategy,
 changelog strategy, caveats, and alternatives, see
 [`docs/sdk-evolution-agent-design.md`](sdk-evolution-agent-design.md).
@@ -57,13 +66,26 @@ env -u UV_EXCLUDE_NEWER \
   uv run --locked --extra codex python -m examples.sdk_evolution_agent.auth ensure-codex
 ```
 
-Codex-backed SDK evolution runs explicitly choose `gpt-5.5` with
+Codex-backed SDK evolution runs default to `gpt-5.5` with
 `reasoning_effort=xhigh` for the AI stages that analyze direction, decide the
 update plan, and review the result. Dependency application and verification are
 deterministic. This model policy
 is applied only to `codex-agent-sdk`; Claude and Antigravity runs keep their
 provider-native model selection because `gpt-5.5` is not a valid model override
 for those adapters.
+Use `--model` and `--reasoning-effort` to select the requested model explicitly
+for every AI stage. For example, use `--model gpt-6-astra --reasoning-effort xhigh`.
+These options populate the first-class `AgentTask` fields and are recorded in
+`config.json`; unsupported provider values remain provider errors.
+
+If the locked Codex CLI cannot run the requested analysis model, the optional
+`--codex-bin /absolute/path/to/codex` selects an installed executable through
+the SDK's supported `CodexConfig.codex_bin`. It applies only to the analysis
+driver and is recorded separately in `config.json`. Exact baseline/candidate
+inspection and the SDK/CLI dependency coupling still use the published package
+versions. Omit this override for the required post-update run against the final
+locked SDK and bundled CLI. The override requires `--runtime codex-agent-sdk`
+and cannot be combined with an injected runtime or registry.
 Vendor runtimes also enable `reuse_process=True` for the multi-stage run, so
 compatible SDK subprocesses can stay warm across analysis/review stages and are
 closed by the CLI when the internally owned runtime exits. Codex reuses its
@@ -148,7 +170,15 @@ failures are retried. Candidate inspection writes the exact compatibility
 transition to `api_diffs.json` and executes the adapter contract against that
 same version. Independently, recent-release inspection fingerprints shipped
 files and Python AST definitions, compares adjacent releases, and writes the
-result to `implementation_diffs.json`. Source is never copied into the report;
+result to `implementation_diffs.json`. History also includes the exact locked
+baseline and candidate when they fall outside the latest three releases, so
+the changes between the installed baseline and the recent releases remain
+visible. Claude probes construct permission, budget, session, MCP and schema
+options; Codex probes construct configuration and validated thread/turn wire
+parameters, including permissions, reasoning effort and structured output.
+These checks complement real-adapter regression tests and live runtime checks;
+they do not establish behavior inside opaque executables.
+Source is never copied into the report;
 only paths, counts, sizes, and hashes are retained. Candidate inspection is
 opt-in because it executes freshly downloaded upstream code; historical
 inspection uses the same explicit consent. Without the flag, missing trend