Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,10 +57,10 @@ capabilities needed for real work.
|------------|---------|---------|-----------------|
| Python | >=3.10 | Package runtime | Claude Agent SDK, Codex SDK, and Google Antigravity all currently advertise Python 3.10+ compatibility. |
| Pydantic | 2.13.4 current; use >=2.12 | Public request/result validation where useful | Mature typed validation without forcing callers into framework-specific models. |
| claude-agent-sdk | 0.2.157 current | Claude runtime adapter | Official Agent SDK for Claude Code-style local agent execution. |
| openai-codex | 0.154.0 current | Codex runtime adapter | Official Python SDK for Codex app-server integration. |
| openai-codex-cli-bin | 0.154.0 current compatible | Codex runtime dependency | Exact runtime dependency selected by openai-codex 0.154.0; keep the SDK and CLI coupled. |
| google-antigravity | 0.1.17 current | Antigravity runtime adapter | Official Google Antigravity Python SDK for local agent harness integration. |
| claude-agent-sdk | 0.2.163 current | Claude runtime adapter | Official Agent SDK for Claude Code-style local agent execution. |
| openai-codex | 0.160.0 current | Codex runtime adapter | Official Python SDK for Codex app-server integration. |
| openai-codex-cli-bin | 0.160.0 current compatible | Codex runtime dependency | Exact runtime dependency selected by openai-codex 0.160.0; keep the SDK and CLI coupled. |
| google-antigravity | 0.1.20 current | Antigravity runtime adapter | Official Google Antigravity Python SDK for local agent harness integration. |
| anyio or asyncio | stdlib plus optional anyio | Async runtime compatibility | Vendor SDKs are async; the public API should be async-first. |
| OpenTelemetry API | 1.42.1 current | Optional event/trace integration | Mestre already normalizes agent events into span-event-shaped payloads; community users will expect observability hooks. |

Expand Down Expand Up @@ -125,10 +125,10 @@ capabilities needed for real work.

| Package | Current Version Checked | Python | Notes |
|---------|-------------------------|--------|-------|
| claude-agent-sdk | 0.2.157 | >=3.10 | Adapter-contract tests must detect option-surface drift. |
| openai-codex | 0.154.0 | >=3.10 | Pre-1.0 package; isolate Codex SDK API drift behind adapter boundaries. |
| openai-codex-cli-bin | 0.154.0 | >=3.10 | Exact runtime dependency for openai-codex 0.154.0. |
| google-antigravity | 0.1.17 | >=3.10 | Includes compiled runtime wheels; install from PyPI rather than source checkout. |
| claude-agent-sdk | 0.2.163 | >=3.10 | Adapter-contract tests must detect option-surface drift. |
| openai-codex | 0.160.0 | >=3.10 | Pre-1.0 package; isolate Codex SDK API drift behind adapter boundaries. |
| openai-codex-cli-bin | 0.160.0 | >=3.10 | Exact runtime dependency for openai-codex 0.160.0. |
| google-antigravity | 0.1.20 | >=3.10 | Includes compiled runtime wheels; install from PyPI rather than source checkout. |
| google-genai | 2.8.0 | >=3.10 | Not a core runtime adapter dependency unless Antigravity or future Google direct paths need it. |

## Sources
Expand Down
18 changes: 18 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,24 @@ 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).

## Unreleased

### Added

- 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`.

### Fixed

- 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
Expand Down
18 changes: 18 additions & 0 deletions docs/providers.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -233,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
Expand Down
49 changes: 49 additions & 0 deletions docs/sdk-upgrade-2026-10.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# October 2026 SDK integration review

The October 2 upgrade starts at `da3cf8a` and targets Claude Agent SDK
`0.2.163`, Codex SDK and its exactly coupled CLI `0.160.0`, and Antigravity
`0.1.20`. These are the latest stable PyPI releases observed that day. Keep
Python 3.10 support, provider extras, and the existing Codex `0.157.1` minimum
needed for named permission profiles; raise its excluding upper bound to
`<0.161`.

## Upstream changes and adapter decisions

| Observed upstream change | Impact and decision |
| --- | --- |
| Claude `0.2.157` to `0.2.163`: new `verbatim_prompts`, plus session-state handling and bounded background-subagent input lifetime. | Expose `ClaudeAgentRuntime(verbatim_prompts=True)` as an opt-in constructor option for composed goals. Require SDK support instead of silently dropping it. Preserve existing defaults because verbatim delivery also skips the initial attachment pass. Continue using SDK-owned `query()` and `ClaudeSDKClient` lifecycle management rather than duplicating the new run-end state machine. |
| Codex `0.157.1` to `0.160.0`: generated protocol adds history anchors, MCP server discovery filtering and error variants, and removes plugin UI models. | Already supported or outside scope: the adapter uses unchanged `AsyncThread.run`/thread APIs, preserves interrupted-turn error messages, and does not expose history pagination or plugin management. Keep native permission profiles, sandbox mapping, schemas, reuse and typed model/effort selection. Upgrade the SDK and its exact CLI dependency together. |
| Antigravity `0.1.20`: directory/search tools move from default collections to `deprecated()`; `schedule` joins the read-only/nondestructive collections. | Adapt explicit read-only allowlist validation to admit the three known legacy read-only tools that the SDK still supports. Keep SDK-owned default and deny-list collections; do not add legacy tools back to defaults or admit arbitrary deprecated write tools. Existing enum validation permits callers to explicitly select or deny `schedule`. |
| Antigravity policy auto-review, subagent model overrides and evaluation presets. | Outside this package's current task contract: permission modes already map to explicit capabilities and policies; the kit does not configure vendor subagents or benchmark orchestration. Do not switch callers to new policies or evaluation defaults implicitly. |
| Antigravity local event parsing tolerates unknown service tiers, handles policy denials and suppresses error-step text. | Already delegated to the SDK before the adapter consumes typed chunks. Continue normalizing token usage and stop reasons; do not duplicate the harness's parsing/policy machinery. |
| Bundled Claude CLI, Codex executables/resources and Antigravity harness change. | Artifact fingerprints establish distribution changes, not binary internals. Verify the final bundled Codex CLI through live structured tasks and keep live Claude/Antigravity execution distinct from local configuration probes. |

## Evidence and validation boundaries

The repository evolution runner collects exact baseline/candidate API and
configuration probes, recent-release Python definition/file diffs, upstream
release sources, resolver evidence, and direction/architecture/review gates.
All sixteen recent-release implementation snapshots and the four exact
baseline/candidate comparisons completed successfully before application.
Resolution, declarations, lockfile and compatibility manifest are updated
together by the runner's verified atomic transaction.

Regression coverage exercises both Claude dispatch paths, unsupported-SDK
refusal, and real SDK option construction. Antigravity tests exercise real SDK
explicit legacy tool allowlists, default preservation, and rejection of write
tools, including a hypothetical deprecated write tool. These configuration
checks do not contact providers or construct live Antigravity agents.

Official Antigravity sources did not provide a matching `0.1.20` release-note
entry during collection. Exact published wheel sources and executable
configuration probes establish the inspected changes; retain the release-note
coverage limit separately from compatibility findings.

Sources: [Claude SDK changelog](https://github.com/anthropics/claude-agent-sdk-python/blob/main/CHANGELOG.md),
[Codex SDK documentation](https://learn.chatgpt.com/docs/codex-sdk),
[Codex releases](https://github.com/openai/codex/releases),
[Antigravity SDK](https://github.com/google-antigravity/antigravity-sdk-python),
and the published [Claude](https://pypi.org/project/claude-agent-sdk/0.2.163/),
[Codex](https://pypi.org/project/openai-codex/0.160.0/),
[Codex CLI](https://pypi.org/project/openai-codex-cli-bin/0.160.0/), and
[Antigravity](https://pypi.org/project/google-antigravity/0.1.20/) distributions.
6 changes: 3 additions & 3 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -46,14 +46,14 @@ dependencies = ["jsonschema>=4.18,<5", "tomli>=2,<3; python_version < '3.11'"]
# already-installed users from a surprise vendor release. The sdk-evolution agent
# raises these deliberately after verifying a new version.
claude = ["claude-agent-sdk>=0.2.87,<0.3"]
# 0.157.1 is the tested SDK and CLI pair for native named profiles. Earlier
# 0.157.1 is the minimum SDK and CLI pair for native named profiles. Earlier
# bundled CLIs do not enforce every profile rule needed by restricted runtimes.
codex = ["openai-codex>=0.157.1,<0.158"]
codex = ["openai-codex>=0.157.1,<0.161"]
antigravity = ["google-antigravity>=0.1.2,<0.2"]
all = [
"claude-agent-sdk>=0.2.87,<0.3",
"google-antigravity>=0.1.2,<0.2",
"openai-codex>=0.157.1,<0.158",
"openai-codex>=0.157.1,<0.161",
]

[project.urls]
Expand Down
12 changes: 12 additions & 0 deletions src/agent_runtime_kit/adapters/antigravity.py
Original file line number Diff line number Diff line change
Expand Up @@ -988,6 +988,18 @@ def _reject_non_read_only_tools(kind: AgentRuntimeKind, tools: list[Any], builti
getattr(tool, "value", tool)
for tool in _read_only_tools(kind, "permissions.allowed_tools", builtin)
}
# 0.1.20 removes legacy directory/search tools from default collections,
# while Agent still classifies them as read-only when explicitly enabled.
# Keep defaults unchanged and admit only the known read-only legacy values;
# a future deprecated write tool must not widen this permission guard.
deprecated = getattr(builtin, "deprecated", None)
if callable(deprecated):
allowed.update(
getattr(tool, "value", tool)
for tool in deprecated()
if getattr(tool, "value", tool)
in {"list_directory", "search_directory", "find_file"}
)
for tool in tools:
value = getattr(tool, "value", tool)
if value not in allowed:
Expand Down
8 changes: 8 additions & 0 deletions src/agent_runtime_kit/adapters/claude.py
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,7 @@ def __init__(
default_model: str | None = None,
supported_models: tuple[str, ...] | None = None,
env: Mapping[str, str] | None = None,
verbatim_prompts: bool = False,
query_func: Any | None = None,
options_cls: Any | None = None,
client_cls: Any | None = None,
Expand All @@ -96,6 +97,7 @@ def __init__(
default_model, supported_models
)
self._env = dict(env) if env is not None else None
self._verbatim_prompts = verbatim_prompts
self._query_func = query_func
self._options_cls = options_cls
self._client_cls = client_cls
Expand Down Expand Up @@ -413,6 +415,8 @@ def _build_options(
setting_sources = metadata.get("setting_sources")
if isinstance(setting_sources, list):
kwargs["setting_sources"] = [str(item) for item in setting_sources]
if self._verbatim_prompts:
kwargs["verbatim_prompts"] = True
# Security posture must fail closed under vendor drift: the permission
# mode always, and the tool filters whenever the task requested any.
required = {"permission_mode": "permissions"}
Expand All @@ -422,6 +426,10 @@ def _build_options(
required["disallowed_tools"] = "permissions"
if task.budget_usd is not None:
required["max_budget_usd"] = "budget_usd"
if self._verbatim_prompts:
# An explicit request to disable prompt expansion must never be
# silently dropped by an older or drifted SDK.
required["verbatim_prompts"] = "verbatim_prompts"
supported, dropped = filter_supported_kwargs(
options_cls, kwargs, required=required, kind=self.kind
)
Expand Down
10 changes: 5 additions & 5 deletions src/agent_runtime_kit/compatibility.py
Original file line number Diff line number Diff line change
Expand Up @@ -66,17 +66,17 @@ def __post_init__(self) -> None:
package="claude-agent-sdk",
module="claude_agent_sdk",
version_specifier=">=0.2.87,<0.3",
tested_version="0.2.157",
tested_version="0.2.163",
),
RuntimeCompatibility(
kind=AgentRuntimeKind.CODEX_AGENT_SDK,
extra="codex",
package="openai-codex",
module="openai_codex",
version_specifier=">=0.157.1,<0.158",
tested_version="0.157.1",
version_specifier=">=0.157.1,<0.161",
tested_version="0.160.0",
tested_runtime_dependencies=(
PackageVersion(package="openai-codex-cli-bin", version="0.157.1"),
PackageVersion(package="openai-codex-cli-bin", version="0.160.0"),
),
),
RuntimeCompatibility(
Expand All @@ -85,7 +85,7 @@ def __post_init__(self) -> None:
package="google-antigravity",
module="google.antigravity",
version_specifier=">=0.1.2,<0.2",
tested_version="0.1.17",
tested_version="0.1.20",
),
)

Expand Down
60 changes: 60 additions & 0 deletions tests/test_antigravity_adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -1180,6 +1180,66 @@ async def test_antigravity_strict_honors_read_only_allow_list(tmp_path: Path) ->
assert config.kwargs["policies"] == []


@pytest.mark.asyncio
@pytest.mark.parametrize("tool", ["list_directory", "search_directory", "find_file"])
@pytest.mark.parametrize("mode", [PermissionMode.STRICT, PermissionMode.DEFAULT])
async def test_antigravity_explicit_legacy_read_only_tools_survive_default_removal(
tmp_path: Path, tool: str, mode: PermissionMode
) -> None:
class NewBuiltinTools(str, enum.Enum):
LIST_DIR = "list_directory"
SEARCH_DIR = "search_directory"
FIND_FILE = "find_file"
VIEW_FILE = "view_file"
EDIT_FILE = "edit_file"
FINISH = "finish"

@classmethod
def read_only(cls):
return [cls.VIEW_FILE, cls.FINISH]

@classmethod
def deprecated(cls):
# Include a hypothetical deprecated write tool to prove that only
# known read-only legacy tools are admitted by the adapter.
return [cls.LIST_DIR, cls.SEARCH_DIR, cls.FIND_FILE, cls.EDIT_FILE]

class NewTypes(FakeTypes):
BuiltinTools = NewBuiltinTools

runtime = AntigravityAgentRuntime(
api_key="key",
data_dir=tmp_path,
agent_cls=FakeAgent,
config_cls=FakeConfig,
types_module=NewTypes,
policy_module=FakePolicy,
)
permissions = PermissionProfile(mode=mode, filesystem=FilesystemAccess.READ_ONLY)
await runtime.run(AgentTask(goal="defaults", permissions=permissions))
assert FakeAgent.last_config.kwargs["capabilities"].enabled_tools == NewBuiltinTools.read_only()

await runtime.run(
AgentTask(
goal="explicit legacy tool",
permissions=PermissionProfile(
mode=mode, filesystem=FilesystemAccess.READ_ONLY, allowed_tools=(tool,)
),
)
)
assert FakeAgent.last_config.kwargs["capabilities"].enabled_tools == [NewBuiltinTools(tool)]

with pytest.raises(UnsupportedTaskInputError):
await runtime.run(
AgentTask(
goal="write tool",
permissions=PermissionProfile(
mode=mode, filesystem=FilesystemAccess.READ_ONLY, allowed_tools=("edit_file",)
),
)
)


@pytest.mark.asyncio
async def test_antigravity_read_only_allowlist_fails_closed_without_readonly_toolset(
tmp_path: Path,
Expand Down
Loading
Loading