agent-runtime-kit 0.5.2__tar.gz → 0.5.4__tar.gz

{agent_runtime_kit-0.5.2 → agent_runtime_kit-0.5.4}/CHANGELOG.md

@@ -5,6 +5,50 @@ 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.4 - 2026-10-18
+
+### Changed
+
+- Updated tested Claude Agent SDK to `0.2.168`, Google Antigravity SDK to
+  `0.1.22`, and the exactly coupled Codex SDK and CLI to `0.163.0`.
+- Raised the Codex SDK upper bound to `<0.164` after exact candidate inspection.
+- SDK evolution analysis defaults to `gpt-6.1-sol` at maximum reasoning effort
+  across AI stages, with the selected model and effort recorded in run artifacts.
+
+### Fixed
+
+- Antigravity permission lists preserve the deprecated `start_subagent` alias
+  after its rename to `invoke_subagent`.
+- Explicit Antigravity workflow tools enable the SDK's delegation gate,
+  including when an independent invocation tool is denied. Strict and read-only
+  tasks continue to refuse delegation tools.
+
+## 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

agent_runtime_kit-0.5.4/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: agent-runtime-kit
+Version: 0.5.4
+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.164,>=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.164,>=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.4/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.2 → agent_runtime_kit-0.5.4}/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
@@ -160,7 +171,13 @@ escalate beyond the sandbox), `DEFAULT`/`PERMISSIVE` → `auto_review`
 (escalations auto-adjudicated). Tool audits are parsed from `TurnResult.items`
 (command executions, MCP tool calls, dynamic tool calls, web searches), and a
 `TurnResult.status` of `failed`/`interrupted` maps to the matching
-`finish_reason`. `budget_usd`, `permissions.network`, `allowed_tools`,
+`finish_reason`. Audits are best effort: live checks with SDK/CLI `0.160.0`
+and `0.163.0` observed a nested Code Mode `exec` call in the session log that
+was absent from both `TurnResult.items` and the supported thread-read response, while a direct
+shell call produced normal command items. An empty `tool_calls` tuple therefore
+does not establish that no tools ran. The adapter uses the SDK item surface
+and does not reconstruct execution history from local transcript files.
+`budget_usd`, `permissions.network`, `allowed_tools`,
 `disallowed_tools`, and `mcp_servers` have no per-task SDK surface and are
 rejected with typed errors. The constructor defaults to
 `config_overrides=("features.plugins=false",)` so headless runs are
@@ -233,13 +250,31 @@ 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
 destructive tool. An explicit `allowed_tools` list is rejected if it names a
 non-read-only tool under a `READ_ONLY` filesystem or `STRICT` mode. An
-`allowed_tools` list containing `start_subagent` enables subagents in any mode;
-the approval policy still follows the mode (only `STRICT` omits `allow_all`).
+`allowed_tools` list containing a delegation tool enables the SDK's subagent
+gate when the filesystem and mode permit that tool; the approval policy still
+follows the mode.
+
+Antigravity 0.1.22 names the invocation tool `invoke_subagent` and retains
+`start_subagent` as a deprecated input alias. The adapter uses the installed
+SDK's enum coercion for allow/deny entries, preserving that alias while still
+rejecting unknown names. Both `invoke_subagent` and `run_workflow` require the
+SDK's subagent gate. Selecting either enables it; denying one keeps the other
+usable. To disable both forms of delegation on 0.1.22, deny both names or use an
+explicit allow-list containing neither. `READ_ONLY` and `STRICT` reject either
+tool, including the legacy alias. Older SDKs retain `start_subagent` support
+and reject names they do not provide.
 
 Session and app-data directories are written under
 `$XDG_CACHE_HOME/agent-runtime-kit` (default `~/.cache/agent-runtime-kit`,

agent_runtime_kit-0.5.4/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.4/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.2 → agent_runtime_kit-0.5.4}/docs/sdk-evolution-agent-design.md

@@ -194,9 +194,9 @@ that exact home, and mirrors the supported normal Codex login cache from
 ask for access tokens, or inspect unsupported credential stores.
 
 When `codex-agent-sdk` is selected for SDK update work, every AI-backed stage
-should run on `gpt-5.5` with `reasoning_effort=xhigh`. This is a Codex runtime
+should run on `gpt-6.1-sol` with `reasoning_effort=max`. This is a Codex runtime
 policy, not a portable metadata field: Claude and Antigravity runs should not
-receive a `gpt-5.5` model override.
+receive a `gpt-6.1-sol` model override.
 
 Package filters narrow evidence collection for debugging, but normal evolution
 runs should inspect all tracked packages:

{agent_runtime_kit-0.5.2 → agent_runtime_kit-0.5.4}/docs/sdk-evolution-agent.md

@@ -66,15 +66,15 @@ env -u UV_EXCLUDE_NEWER \
   uv run --locked --extra codex python -m examples.sdk_evolution_agent.auth ensure-codex
 ```
 
-Codex-backed SDK evolution runs default to `gpt-5.5` with
-`reasoning_effort=xhigh` for the AI stages that analyze direction, decide the
+Codex-backed SDK evolution runs default to `gpt-6.1-sol` with
+`reasoning_effort=max` 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
+provider-native model selection because `gpt-6.1-sol` 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`.
+for every AI stage. For example, use `--model gpt-6.1-sol --reasoning-effort max`.
 These options populate the first-class `AgentTask` fields and are recorded in
 `config.json`; unsupported provider values remain provider errors.
 

{agent_runtime_kit-0.5.2 → agent_runtime_kit-0.5.4}/docs/task-control.md

@@ -10,7 +10,10 @@ deadline at call time.
 from agent_runtime_kit import AgentKit, AgentTaskTimeoutError
 
 try:
-    result = await kit.run("codex", goal="Refactor the parser", timeout=30)
+    result = await kit.run(
+        "codex", goal="Inspect the parser", timeout=30,
+        permissions="strict", filesystem="read-only",
+    )
 except AgentTaskTimeoutError as exc:
     print(exc.task_id, exc.deadline)
 ```
@@ -25,23 +28,55 @@ that grace, the runtime instance is quarantined and rejects new runs rather than
 overlapping them; it becomes reusable when the detached cleanup finally settles.
 
 To cancel a task started through `AgentKit`, keep its task id and use the same
-runtime instance or cached kind:
+runtime instance or cached kind. Wait for its started event (or for an early
+completion) before calling `cancel()`; scheduling `kit.run()` with
+`asyncio.create_task()` does not guarantee that it has registered the run yet.
+This example makes a real provider call and may incur charges:
 
 ```python
 import asyncio
 
-task_id = "index-repository"
-running = asyncio.create_task(
-    kit.run("claude", goal="Index the repository", task_id=task_id)
-)
-receipt = await kit.cancel("claude", task_id)
+from agent_runtime_kit import AgentKit
+
+
+async def main() -> None:
+    task_id = "index-repository"
+    started = asyncio.Event()
+    async with AgentKit() as kit:
+
+        @kit.on("agent.task.started")
+        def on_started(event):
+            if event["attributes"]["task_id"] == task_id:
+                started.set()
+
+        running = asyncio.create_task(
+            kit.run(
+                "claude", goal="Index the repository", task_id=task_id,
+                permissions="strict", filesystem="read-only",
+            )
+        )
+        start_wait = asyncio.create_task(started.wait())
+        try:
+            done, _ = await asyncio.wait(
+                {running, start_wait}, return_when=asyncio.FIRST_COMPLETED
+            )
+            if running in done:
+                result = await running  # completed or failed before cancellation
+                print(result.finish_reason)
+                return
+            receipt = await kit.cancel("claude", task_id)
+            print(receipt.disposition)
+            try:
+                result = await running
+                print(result.finish_reason)  # it may finish before cancellation takes effect
+            except asyncio.CancelledError:
+                print("cancelled")
+        finally:
+            start_wait.cancel()
+            await asyncio.gather(start_wait, return_exceptions=True)
 
-try:
-    await running
-except asyncio.CancelledError:
-    pass
 
-print(receipt.disposition)
+asyncio.run(main())
 ```
 
 `cancel()` does not construct a runtime that has not already been cached, and