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: 16 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,22 @@ 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

### Changed

- Updated the tested Claude Agent SDK to `0.2.179`, Antigravity to `0.1.23`,
and the exactly coupled Codex SDK and CLI to `0.167.0`. Raised the Codex
upper bound to `<0.168` after inspecting the exact candidate versions.

### Fixed

- SDK evolution now collects official release notes for Claude's bundled CLI,
verifies its version against the inspected SDK distribution, and blocks on
incomplete or contradictory runtime evidence.
- Implementation snapshots distinguish a public class replaced by an alias
from a removed name, including in isolated candidate environments.

## 0.5.5 - 2026-10-22

### Changed
Expand Down
19 changes: 16 additions & 3 deletions docs/sdk-evolution-agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -173,18 +173,31 @@ files and Python AST definitions, compares adjacent releases, and writes the
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
visible. Module-level capitalized alias assignments are fingerprinted alongside
class and function definitions, so replacing a class with an alias is
distinguished from deleting the name. These are static source observations,
not proof that a conditional assignment is present at runtime. 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;
Implementation 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
evidence is reported as `no-transition` rather than being replaced with
dependency advice.

For a Claude SDK update, release evidence also covers its bundled Claude Code
CLI. The runner matches each SDK tag's CLI-version file against the fingerprint
of the exact inspected distribution, then records official CLI release notes
between the baseline and candidate. The SDK's own note status remains separate:
CLI notes do not turn an absent SDK changelog entry into a match. Missing or
contradictory version mappings, an incomplete release index, and missing CLI
release text block promotion. The CLI remains opaque even when its release
notes are available.

## Upstream Implementation Trends

`direction_analysis.json` is an implementation-trend report. It answers what
Expand Down
52 changes: 52 additions & 0 deletions docs/sdk-upgrade-2026-11-07.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# November 7 SDK integration review

This review starts at `32dbd8c` and compares the locked SDKs with independently
published candidates. It updates Claude Agent SDK `0.2.172` to `0.2.179`,
Codex SDK and its exactly required CLI `0.163.0` to `0.167.0`, and Antigravity
`0.1.22` to `0.1.23`. The Codex upper bound becomes `<0.168`; the other SDK
ranges already admit their candidates.

## Upstream changes and integration decisions

| Observed change | Existing behavior and decision |
| --- | --- |
| Claude's `HookMatcher` adds an `on_failure` option, and the bundled Claude Code CLI moves from `2.1.308` to `2.1.319`. The CLI release history includes fixes affecting non-interactive sessions, MCP, permissions, and failure reporting. | The adapter does not register SDK hook callbacks and continues to pass task permissions, MCP servers, sessions, and result messages to the SDK. Keep those mappings and the SDK-owned CLI behavior; do not claim hook support from this update. The SDK's `0.2.179` release itself contains no change notes. |
| Codex's generated app-server protocol adds lifecycle fields and image input/result variants. Its former `ImageGenerationThreadItem` class is replaced by an alias to `ResultThreadItem`; the name remains available. The handwritten Python client is unchanged. | The adapter does not depend on that generated class name. Its task, session, permission, and tool-audit mappings continue to consume the SDK's supported results. Preserve exact SDK/CLI coupling and best-effort audit coverage; do not infer binary internals from artifact fingerprints. |
| Antigravity adds workflow tool execution and custom instruction titles, and moves path and structure conversion helpers into shared modules. | The adapter passes its system prompt as a string and continues using `Agent.chat` and the SDK's configuration and policy interfaces. Workflow orchestration remains vendor-owned, although callers can enable its built-in workflow tool. The local workflow regression exercises nested tool filtering with the adapter's actual allow-list and deny-list configurations. |
| Claude Code release notes are published separately from the SDK, and a static class-definition scan can mistake a replacement alias for a removed name. | The evolution runner now verifies the bundled CLI version against the exact inspected SDK distribution, records the official CLI release interval separately from SDK notes, and blocks incomplete or contradictory evidence. Both snapshot paths record capitalized module-level aliases alongside definitions. These static observations do not prove runtime behavior. |

## Evidence and limits

The pre-update evidence includes all four exact baseline-to-candidate API diffs,
13 recent implementation snapshots, and behavior probes for each transition.
The three adapter-contract comparisons pass; the Codex CLI distribution probe
changes only its version details. The current resolver excludes Codex `0.167.0`
until the upper bound is widened, while the prospective resolver selects the
exact SDK/CLI pair. The Claude SDK changelog has no matching `0.2.179` entry;
separate official Claude Code releases cover the bundled CLI interval.

The Antigravity workflow test uses the real `0.1.23` native harness and a local
fake OpenAI-compatible model endpoint. A positive control creates a temporary
file when the adapter's selected tools permit it; the same nested call is
refused for both an allow-list excluding file creation and a deny-list naming
it. This is a local semantic check of those cases, not a live provider test or
a claim about all possible tools and policies.

Final-lock verification on Python 3.10 passed the lock check, Ruff, and mypy.
The core suite passed 587 tests with 27 skips; the all-extras suite passed 611
tests with three live-provider skips and 90.37% coverage. A separate live call
through the locked Codex SDK and bundled CLI verified structured output,
session resume, retained context, and process reuse. The post-update evolution
run also passed its review through that SDK/CLI pair without an executable
override.

Claude's bundled CLI, the Codex executable, and Antigravity's native harness
are opaque in the inspected distributions. API/configuration probes and source
fingerprints cannot establish all runtime behavior. Live Claude and Antigravity
provider calls were not run; the workflow check above uses the local harness and
a fake model endpoint.

Sources: [Claude SDK release](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.179),
[Claude Code CLI release](https://github.com/anthropics/claude-code/releases/tag/v2.1.319),
[Codex release](https://github.com/openai/codex/releases/tag/rust-v0.167.0),
and [Antigravity release notes](https://github.com/google-antigravity/antigravity-sdk-python/discussions/273).
4 changes: 3 additions & 1 deletion examples/sdk_evolution_agent/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -237,7 +237,9 @@ async def run_agent(
_progress("collecting release notes and executable behavior probes")
release_notes = [
to_jsonable(item)
for item in collect_release_notes(evidence.get("packages", []), update_versions)
for item in collect_release_notes(
evidence.get("packages", []), update_versions, snapshots=snapshots
)
]
behavior = to_jsonable(
collect_behavior_evidence(
Expand Down
23 changes: 23 additions & 0 deletions examples/sdk_evolution_agent/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,28 @@ class ImplementationDiff:
limitations: tuple[str, ...] = ()


@dataclass(frozen=True)
class BundledRuntimeRelease:
"""An official release note for a runtime bundled inside an SDK."""

version: str
url: str
notes: str


@dataclass(frozen=True)
class BundledRuntimeEvidence:
"""Provenance and release notes for an SDK's exact bundled runtime."""

name: str
from_version: str | None
to_version: str | None
status: str
sources: tuple[SourceRef, ...] = ()
releases: tuple[BundledRuntimeRelease, ...] = ()
unavailable_reason: str = ""


@dataclass(frozen=True)
class ReleaseNoteEvidence:
"""Release-note evidence collected for one package interval."""
Expand All @@ -164,6 +186,7 @@ class ReleaseNoteEvidence:
summaries: tuple[str, ...] = ()
checked_urls: tuple[str, ...] = ()
unavailable_reason: str = ""
bundled_runtime: BundledRuntimeEvidence | None = None


@dataclass(frozen=True)
Expand Down
195 changes: 194 additions & 1 deletion examples/sdk_evolution_agent/release_notes.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@

from __future__ import annotations

import ast
import gzip
import hashlib
import json
import os
import re
Expand All @@ -11,7 +13,15 @@
import urllib.request
from collections.abc import Callable, Mapping, Sequence

from examples.sdk_evolution_agent.models import ReleaseNoteEvidence, SourceRef
from packaging.version import Version

from examples.sdk_evolution_agent.models import (
ApiSnapshot,
BundledRuntimeEvidence,
BundledRuntimeRelease,
ReleaseNoteEvidence,
SourceRef,
)

ReleaseNoteFetcher = Callable[[str], str]

Expand Down Expand Up @@ -88,6 +98,7 @@ def collect_release_notes(
update_versions: Mapping[str, str],
*,
fetcher: ReleaseNoteFetcher | None = None,
snapshots: Sequence[ApiSnapshot] | None = None,
) -> tuple[ReleaseNoteEvidence, ...]:
"""Collect primary-source release-note evidence for update candidates."""

Expand Down Expand Up @@ -219,6 +230,11 @@ def collect_release_notes(
status = "unavailable"
unavailable_reason = "no release-note source configured"

bundled_runtime = None
if name == "claude-agent-sdk" and snapshots is not None:
bundled_runtime = _collect_claude_bundled_runtime(
from_version, to_version, snapshots=snapshots, fetcher=fetcher
)
evidence.append(
ReleaseNoteEvidence(
package=name,
Expand All @@ -229,11 +245,188 @@ def collect_release_notes(
summaries=tuple(_dedupe(summaries)[:8]),
checked_urls=tuple(checked_urls),
unavailable_reason=unavailable_reason,
bundled_runtime=bundled_runtime,
)
)
return tuple(evidence)


def _collect_claude_bundled_runtime(
from_version: str | None,
to_version: str,
*,
snapshots: Sequence[ApiSnapshot],
fetcher: ReleaseNoteFetcher,
) -> BundledRuntimeEvidence:
"""Resolve CLI versions from exact SDK snapshots, then collect their releases.

The upstream SDK tag is only accepted when its version file has
the same fingerprint as the inspected distribution. A release index or tag
that cannot be reconciled is evidence of a gap, not an empty changelog.
"""

sources: list[SourceRef] = []
versions: list[str] = []
try:
for sdk_version in (from_version, to_version):
if not sdk_version or not re.fullmatch(r"[0-9A-Za-z][0-9A-Za-z.+-]*", sdk_version):
raise ValueError(f"invalid or missing Claude SDK version: {sdk_version!r}")
snapshot = next(
(
item
for item in snapshots
if item.package == "claude-agent-sdk"
and item.version == sdk_version
and not item.import_error
),
None,
)
if snapshot is None:
raise ValueError(f"missing exact SDK snapshot for {sdk_version}")
version_file = next(
(
item
for item in snapshot.implementation_files
if item.path == "claude_agent_sdk/_cli_version.py"
),
None,
)
if version_file is None:
raise ValueError(f"missing bundled CLI version fingerprint for SDK {sdk_version}")
url = (
"https://raw.githubusercontent.com/anthropics/claude-agent-sdk-python/"
f"v{urllib.parse.quote(sdk_version, safe='')}/src/claude_agent_sdk/_cli_version.py"
)
_progress(f"checking bundled Claude CLI version from SDK {sdk_version}")
try:
content = fetcher(url)
digest = hashlib.sha256(content.encode("utf-8")).hexdigest()
if digest != version_file.sha256:
raise ValueError(
f"bundled CLI version fingerprint mismatch for SDK {sdk_version}"
)
cli_version = _claude_cli_version(content)
except Exception as exc:
sources.append(
SourceRef(
kind="sdk-runtime-version",
label="Claude SDK bundled CLI version",
url=url,
version=sdk_version,
available=False,
note=str(exc),
)
)
raise
sources.append(
SourceRef(
kind="sdk-runtime-version",
label="Claude SDK bundled CLI version",
url=url,
version=sdk_version,
note="Source fingerprint matches the inspected SDK distribution.",
)
)
versions.append(cli_version)

baseline, candidate = (Version(value) for value in versions)
if candidate < baseline:
raise ValueError("candidate bundled CLI version is older than the baseline")
if candidate == baseline:
return BundledRuntimeEvidence(
"claude-code", versions[0], versions[1], "not-needed", tuple(sources)
)

releases: dict[Version, BundledRuntimeRelease] = {}
covered_baseline = False
for page in range(1, 6):
url = (
"https://api.github.com/repos/anthropics/claude-code/releases"
f"?per_page=100&page={page}"
)
_progress(f"checking bundled Claude CLI release notes, page {page}")
try:
rows = json.loads(fetcher(url))
if not isinstance(rows, list):
raise ValueError("release index is not a list")
except Exception as exc:
sources.append(
SourceRef(
kind="release-index",
label="Claude Code releases",
url=url,
available=False,
note=str(exc),
)
)
raise
sources.append(SourceRef(kind="release-index", label="Claude Code releases", url=url))
for row in rows:
if not isinstance(row, Mapping):
raise ValueError("release index contains a malformed entry")
if row.get("draft") or row.get("prerelease"):
continue
tag = str(row.get("tag_name") or "")
if not re.fullmatch(r"v?\d+\.\d+\.\d+", tag):
continue
release_version = Version(tag.lstrip("v"))
if release_version <= baseline:
covered_baseline = True
if baseline < release_version <= candidate:
release_url = f"https://github.com/anthropics/claude-code/releases/tag/{tag}"
release = BundledRuntimeRelease(
version=str(release_version),
url=release_url,
notes=str(row.get("body") or "").strip(),
)
if release_version in releases and releases[release_version] != release:
raise ValueError(f"contradictory CLI releases for {release_version}")
releases[release_version] = release
if covered_baseline or len(rows) < 100:
covered_baseline = True
break

missing = [str(version) for version, release in releases.items() if not release.notes]
problems = []
if not covered_baseline:
problems.append("release-index pagination did not reach the baseline")
if candidate not in releases:
problems.append(f"candidate CLI release {candidate} not found")
if missing:
problems.append("release notes missing for " + ", ".join(sorted(missing)))
return BundledRuntimeEvidence(
name="claude-code",
from_version=versions[0],
to_version=versions[1],
status="incomplete" if problems else "found",
sources=tuple(sources),
releases=tuple(releases[key] for key in sorted(releases)),
unavailable_reason="; ".join(problems),
)
except Exception as exc:
return BundledRuntimeEvidence(
name="claude-code",
from_version=versions[0] if versions else None,
to_version=versions[1] if len(versions) > 1 else None,
status="unavailable",
sources=tuple(sources),
unavailable_reason=str(exc),
)


def _claude_cli_version(content: str) -> str:
tree = ast.parse(content)
for node in tree.body:
if isinstance(node, ast.Assign) and any(
isinstance(target, ast.Name) and target.id == "__cli_version__"
for target in node.targets
):
value = ast.literal_eval(node.value)
if isinstance(value, str) and re.fullmatch(r"\d+\.\d+\.\d+", value):
return value
raise ValueError("SDK bundled CLI version is missing or unsupported")


def fetch_url_text(url: str) -> str:
"""Fetch a release-note source as text."""

Expand Down
Loading
Loading