Skip to content

Define and validate immutable tool-call progression - #8

Merged
LevinGuy merged 1 commit into
mainfrom
fix/tool-call-progression
Oct 5, 2026
Merged

LevinGuy merged 1 commit into
mainfrom
fix/tool-call-progression

Conversation

@LevinGuy

@LevinGuy LevinGuy commented Oct 5, 2026

Copy link
Copy Markdown
Contributor

A capture can now record partial tool arguments and a later capture can complete them without changing the original event or inventing a second invocation. Previously both validators rejected the second event as a duplicate call identity.

Closes #1.

Normative proposal / RFC

Use the existing event supersedes field for incomplete-call amendments. Preserve call, tool, actor, execution, and retry identities; retain the earlier event and its stream unchanged. Unknown/partial argument knowledge may advance, but completed calls cannot be amended through this mechanism. A retry requires a new call ID.

Selected histories fold one explicit amendment chain in branch order. Conflicting successors can live on separate branches; selecting both is invalid. A late amendment retains previously recorded decisions/results and never reopens a terminal invocation. Contexts select one typed call input per invocation.

An amendment requires its predecessor event locally so both validators can verify its identity fields. An external descriptor cannot substitute for that envelope. Unchanged external invocations can still receive late results through existing bindings.

Implementation and evidence

  • Update Python and TypeScript semantic validators with matching rules.
  • Add two synthetic captures retaining identical earlier events, resources, streams, and contexts, followed by completed arguments and a terminal result.
  • Add 29 shared positive/negative cases covering identity changes, progression, branch selection/conflicts, retries, late amendments, and external boundaries. Both suites also verify immutable evidence and one-call request projection.
  • Update semantic/stream rules, generated object documentation, conformance guidance, gap status, and recorded test results.

Alternatives and compatibility

Mutating the original call would violate immutable evidence. Allocating another invocation ID for argument completion would confuse completion with retry. External-only supersession lacks enough identity information to validate the relationship, so this proposal requires materializing the authentic predecessor instead.

No JSON fields, schema shape, or version identifiers change: these are inter-event semantic rules beyond JSON Schema. Existing ordinary single-event calls keep their representation. Older reference validators reject amended captures; implementations claiming the updated draft semantics need the new checks. Complete-call factual corrections are outside this incomplete-argument progression mechanism.

No new fetching, execution, credential transfer, or authorization behavior is introduced. Examples are synthetic and contain no private data; these checks provide no live-continuation or independent-interoperability evidence.

Validation

  • tests/check_schema.py: 27 checks passed.
  • tests/check_examples.py: 10 examples and 5 negative checks passed.
  • tests/check_continuation.py: 44 checks passed.
  • tests/check_reference.py: 93 checks passed.
  • npm run typecheck and npm test: typecheck and 120 tests passed.
  • tests/check_documentation.py: 124 objects, 136 object examples, and generated-document/link checks passed.
  • mkdocs build --strict and git diff --check: passed.

@LevinGuy LevinGuy added bug Something isn't working specification Normative semantics, schemas, or format contracts priority:P0 Must resolve before the capability or conformance claim stated in the issue labels Oct 5, 2026
@LevinGuy
LevinGuy merged commit 549a56a into main Oct 5, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working priority:P0 Must resolve before the capability or conformance claim stated in the issue specification Normative semantics, schemas, or format contracts

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[P0] Define immutable tool-call progression across captures

1 participant