openAgent

1# V2 Schema Changelog
2 
3## 2026-06-26: Add Finite Session History
4 
5- Add `GET /api/session/:sessionID/history` and generated Promise, Effect, and legacy JavaScript client methods.
6- Page public durable Session events after an optional exclusive aggregate sequence, with an explicit `hasMore` exhaustion signal.
7- Keep aggregate gaps legal, cap pages at 100 events, and preserve the existing durable replay-and-tail `sessions.events()` stream unchanged.
8- Add no migration or durable-event version; this is a finite read API over the existing event manifest.
9 
10## 2026-06-22: Simplify Session Input Promotion
11 
12- Keep `session.next.prompt.admitted.1` as the durable, client-visible record of pending Session input.
13- Replace `session.next.prompt.promoted.1` with the existing `session.next.prompted.1` event when input becomes model-visible.
14- Preserve the prompt endpoint, admission receipt, idempotency, steer/queue ordering, and atomic user-message projection.
15- Reset experimental V2 events, projections, inputs, Context Epochs, and synchronized workspace state while preserving canonical V1 `session`, `message`, and `part` rows.
16 
17## 2026-06-22: Reset Unpublished Compaction Event
18 
19- Replace the unpublished `session.next.compaction.ended.1` payload with the current checkpoint payload and remove its legacy decoder.
20- Reset experimental events, sequences, Session inputs, projected Session messages, Context Epochs, synchronized workspace rows, and Session workspace links.
21- Preserve canonical V1 `session`, `message`, and `part` rows.
22 
23## 2026-06-22: Make Session Interruption Process-Local
24 
25- Remove the unprojected `session.next.interrupt.requested.1` event from the experimental durable Session event union and generated SDK.
26- No canonical V1 data requires migration; experimental V2 event history containing the retired event is disposable.
27 
28## 2026-06-05: Execute Automatic Session Compaction
29 
30- Trigger automatic compaction before provider turns using the complete estimated request and absolute model-aware headroom.
31- Preserve the existing structured summary contract and update prior summaries with newly compacted history.
32- Store token-bounded recent history as plain serialized text inside the checkpoint instead of replaying provider-native messages.
33- Keep compaction starts durable and progress deltas live-only; activate history cutover only from a durable completed summary.
34- Store the completed event with the current checkpoint payload containing stable message identity, reason, summary, and recent context.
35- Reload the replacement Context Epoch and continue the original pending turn after compaction.
36- Preserve full durable history; compaction changes only the active model representation.
37- Defer provider-overflow recovery, explicit manual compaction, and deterministic old tool-result pruning.
38 
39Record V2 database, durable-event, projected-message, HTTP, and generated SDK schema changes here. Each entry states why the contract changed and whether consumers or stored data need compatibility handling. Commit messages for schema-affecting changes should include the same summary.
40 
41This document covers meaningful contract changes introduced on the `feat/opencode-embedded-api` branch since its divergence from `origin/dev`. Mechanical file moves and internal refactors are omitted unless they changed stored data, replay behavior, public HTTP or SDK shapes, or model-facing tool contracts.
42 
43## 2026-06-04 Event-Sourced Session Input Cutover
44 
45Affected schema:
46 
47- `session_input`, `session_message`, `event`, `event_sequence`, and disposable workspace beta storage.
48- New synchronized `session.next.prompt.admitted.1` and `session.next.prompt.promoted.1` events.
49- Experimental `SessionV2.prompt(...)`, HTTP, and generated SDK admission receipt.
50 
51Change:
52 
53- Replace inbox-local admission sequence with event-sourced prompt admission and promotion sequences.
54- Give projected Session messages stable `msg_*` resource IDs distinct from `evt_*` creator event IDs.
55- Give every event that creates a projected transcript resource an explicit `msg_*` resource ID. Assistant steps propagate one `assistantMessageID` through assistant-owned events.
56- Reset incompatible unreleased beta event history, derived Session projections, workspace rows, and Session workspace links.
57 
58Compatibility:
59 
60- The reset preserves canonical V1 `session`, `message`, and `part` rows.
61- Existing synchronized workspaces are disposable beta state and are removed by the reset.
62- Before starting the new build, discard adapter-managed external workspace resources created by unreleased builds. The SQL migration cannot remove external resources through runtime adapters, and rediscovering retained resources after startup can replay incompatible beta history.
63- Exact prompt retries reconcile one stable `msg_*` identity when Session, prompt, and delivery mode match.
64 
65## Earlier Branch History
66 
67### Replayable Session Event Refinement And Cursor Stream
68 
69Affected schema:
70 
71- Existing synchronized `session.next.*` event family in `packages/core/src/session/event.ts`.
72- Existing projected V2 Session-message union in `packages/core/src/session/message.ts`.
73- New explicit durable-event union and internal replay cursor returned by `sessions.events({ sessionID, after? })`.
74 
75Change:
76 
77- Keep the existing Session lifecycle event family and projected-message union rather than introducing them in this branch.
78- Stop synchronizing text deltas, reasoning deltas, and tool-input deltas; keep them explicitly ephemeral.
79- Add an explicit durable-event union for replay-safe consumers.
80- Add replay-and-tail aggregate cursors backed by durable Session-event sequence.
81- Encode synchronized event payloads before writing JSON storage and decode them while replaying so schema transforms remain explicit at the durable boundary.
82 
83Reason:
84 
85- Embedded Session execution needs a reconnect-safe replay stream over the existing durable log and derived chronological read model.
86- Fragment streams are useful to connected renderers but must not advance durable cursors or inflate synchronized storage.
87 
88Compatibility:
89 
90- The `session.next.*` lifecycle event family predates this branch; this branch refines its experimental V2 durability and replay contracts.
91- Durable replay cursors are per-aggregate event sequences; ephemeral deltas are intentionally absent after reconnect.
92 
93### Durable Step Settlement Ownership
94 
95Affected schema:
96 
97- `session.next.step.ended` and `session.next.step.failed` synchronized event version `2`.
98 
99Change:
100 
101- Bind step settlement to an explicit assistant message ID.
102 
103Reason:
104 
105- Provider-local call identifiers can repeat across turns.
106 
107Compatibility:
108 
109- Step settlement uses synchronized event version `2` because the durable payload changed.
110 
111### Durable Session Input Inbox
112 
113Affected schema:
114 
115- New `session_input` table from `20260603141458_session_input_inbox.ts`.
116- Updated pending-input index from `20260603160727_jittery_ezekiel_stane.ts`.
117- New `SessionInput.Admitted` schema and `Prompted.delivery` field.
118- Prompt-admission conflict behavior in `SessionV2.prompt(...)`.
119 
120Change:
121 
122- Persist admitted prompts before projection with an autoincrement inbox sequence, unique message ID, Session ID, encoded prompt, `steer` or `queue` delivery mode, optional promoted event sequence, and creation time.
123- Index pending inputs by Session, promotion state, delivery mode, and admission sequence.
124 
125Reason:
126 
127- Prompt admission and model-visible promotion must be separate durable operations.
128- Steering must promote at safe provider-turn boundaries while queued prompts remain pending in FIFO order until continuation would otherwise end.
129 
130Compatibility:
131 
132- Database migration creates the inbox table and replaces its first pending index with a delivery-aware index.
133- Exact prompt retries are idempotent; reusing a message ID for different input fails.
134 
135### Durable Session Projection Order
136 
137Affected schema:
138 
139- `session_message.seq` from `20260603040000_session_message_projection_order.ts`.
140- Session-message and event indexes from `20260603001617_session_message_projection_indexes.ts`, `20260603040000_session_message_projection_order.ts`, and `20260603160727_jittery_ezekiel_stane.ts`.
141 
142Change:
143 
144- Reset pre-launch Session-message projections and add `session_message.seq` for newly projected synchronized events.
145- Add event aggregate-sequence and aggregate-type-sequence indexes.
146- Add Session-message sequence, type-sequence, and compatibility timestamp indexes.
147 
148Reason:
149 
150- Projected history, replay, compaction lookup, and pagination must follow durable aggregate order rather than timestamps or caller-generated IDs.
151- Runner and HTTP read paths need covering indexes for their concrete lookup shapes.
152 
153Compatibility:
154 
155- Pre-launch Session-message projections are disposable because historical versions could write them without durable creator events.
156- The migration resets those projections rather than inventing chronology or blocking startup.
157- The timestamp compatibility index remains for legacy or transitional query shapes.
158 
159### Structured Tool Registry And Canonical Output
160 
161Affected schema:
162 
163- Core-owned typed tool registry contract.
164- Canonical tool output content and structured settlement schemas.
165- Canonical tagged tool file sources in `@opencode-ai/llm`.
166- Durable tool called, progress, success, and failure events and projected assistant-tool states.
167 
168Change:
169 
170- Validate model input against each registered tool's parameter schema.
171- Validate handler success against each tool's success schema before optional pure model-output lowering.
172- Generate optional tool-definition output JSON Schema from typed success schemas.
173- Persist canonical structured output and content for running, completed, and failed tools.
174- Represent tool files explicitly as inline data, remote URL, or managed file URI sources rather than one ambiguous URI string.
175 
176Reason:
177 
178- Embedded tool execution needs one typed boundary between provider calls, local side effects, durable settlement, and replay.
179 
180Compatibility:
181 
182- These are additive experimental V2 runtime contracts.
183- Tool results are durably settled before provider continuation.
184- Legacy text, JSON, and inline-media results remain convertible; unresolved URL and file sources must be materialized or explicitly rejected before provider lowering.
185 
186### Managed Tool-Output Files
187 
188Affected schema:
189 
190- New optional managed `outputPath` and `outputPaths` fields on tool results and completed Session tool state.
191- Absolute managed output paths accepted by ordinary `read` and `grep` inputs.
192 
193Change:
194 
195- Spill oversized model-facing tool text into globally unique files under OpenCode's shared tool-output directory.
196- Include the absolute file path in the bounded preview so ordinary `read`, `grep`, and `bash` operations can inspect it.
197 
198Reason:
199 
200- Tool results need bounded model context without discarding the full output.
201- Filesystem resolution admits only direct generated `tool_*` files from the managed directory, while existing permissions whitelist that directory.
202 
203Compatibility:
204 
205- Managed output is retained for a bounded period and exposed as a normal host filesystem path.
206 
207### Location-Scoped Filesystem Read And Search Contracts
208 
209Affected schema:
210 
211- Core filesystem read, directory-list, root-resolution, and named-reference inputs.
212- `LocationSearch.FilesInput`, `LocationSearch.GrepInput`, and bounded result schemas.
213- `read`, `glob`, and `grep` tool parameters and success payloads.
214 
215Change:
216 
217- Add bounded file reads, paged directory listings, bounded glob results, and bounded grep matches with line previews.
218- Allow named project references for read-oriented operations.
219- Resolve and pin canonical approved search roots before traversal.
220- Exclude hidden path segments from broad V2 glob and grep discovery.
221 
222Reason:
223 
224- Embedded tools need deterministic bounds and a shared path-containment authority.
225- Broad search should not disclose hidden files implicitly.
226 
227Compatibility:
228 
229- These are additive V2 tool contracts.
230- Hidden-file discovery is intentionally narrower than an unconditional ripgrep `--hidden` traversal.
231 
232### Location Workspace Identity
233 
234Affected schema:
235 
236- `Location.Ref.workspaceID`.
237- V2 Location HTTP middleware routing.
238 
239Change:
240 
241- Brand optional Location workspace identity as `WorkspaceV2.ID` instead of an untyped string.
242- Preserve nested `location[workspace]` and workspace-header routing inputs while decoding them into the branded identity.
243 
244Reason:
245 
246- Location-scoped services and embedded routing need one typed workspace identity boundary.
247 
248Compatibility:
249 
250- Existing workspace strings remain accepted when they satisfy the workspace ID schema.
251- Generated OpenAPI reflects the workspace prefix constraint.
252 
253### Structured Mutation Authority And File Leaves
254 
255Affected schema:
256 
257- New `LocationMutation.ResolveInput`, planned target, external-directory authorization, and typed path errors.
258- New `write` and exact `edit` tool schemas.
259- New internal file-mutation commit service.
260 
261Change:
262 
263- Resolve relative mutation paths within the active Location.
264- Accept absolute internal paths and require explicit `external_directory` approval before leaf approval for external absolute paths.
265- Keep named references read-oriented and reject them for mutation.
266- Revalidate path authority immediately before write mechanics.
267 
268Reason:
269 
270- Mutation tools need explicit capability escalation and symlink/path-swap checks without pretending path APIs provide a syscall-level sandbox.
271 
272Compatibility:
273 
274- These are additive V2 mutation contracts.
275- Richer V1 fuzzy edit behavior remains intentionally deferred.
276 
277### V2 Permission Requests And Saved Rules
278 
279Affected schema:
280 
281- `PermissionV2.Request`, `AssertInput`, `ReplyInput`, source metadata, tagged errors, and lifecycle events.
282- V2 permission list, reply, and saved-rule HTTP routes and generated SDK schemas.
283 
284Change:
285 
286- Add Location-scoped pending permission requests with `once`, `always`, and `reject` replies.
287- Attach optional originating tool message and call IDs.
288- Preserve authored ordered rules and saved approvals as separate inputs to evaluation.
289- Establish action and resource conventions for `read`, `glob`, `grep`, `edit`, `external_directory`, `bash`, `todowrite`, and `webfetch` approvals.
290 
291Reason:
292 
293- Embedded tool calls need a Core-owned authorization boundary that can suspend and resume through HTTP.
294 
295Compatibility:
296 
297- These are additive experimental V2 contracts.
298- Policy authors should account for canonical resource forms; originating tool source metadata remains optional until every registry call carries its durable assistant owner.
299 
300### Initial Core V2 Built-In Tool Schemas
301 
302Affected schema:
303 
304- `read`, `glob`, `grep`, `write`, exact `edit`, `bash`, and `websearch` model-facing tool contracts.
305 
306Change:
307 
308- Add Core-owned Location-scoped built-ins with explicit parameter and success schemas.
309- Bound bash output and timeout input, search result counts and previews, read sizes, directory pages, and websearch result/context controls.
310 
311Reason:
312 
313- Embedded runner launch requires a minimal typed tool set without importing legacy application orchestration.
314 
315Compatibility:
316 
317- These are additive V2 built-ins.
318- Richer launch-follow-up leaves such as `apply_patch`, skill loading, task dispatch, and LSP remain separate slices.
319 
320### Bash Advisory Warnings
321 
322Affected schema:
323 
324- Optional `warnings` in the `bash` tool success payload.
325 
326Change:
327 
328- Return advisory warning strings when best-effort command-argument scanning detects external absolute paths; keep structured external `workdir` approval enforced.
329 
330Reason:
331 
332- A shell subprocess has host-user filesystem, process, and network authority. Token scanning cannot honestly provide containment.
333 
334Compatibility:
335 
336- Consumers rendering bash success should tolerate optional warning strings.
337 
338### V2 Session HTTP And Generated SDK Contracts
339 
340Affected schema:
341 
342- V2 Session list, prompt, context, message-list, compact, and wait HTTP routes.
343- V2 Location query routing fields.
344- Generated OpenAPI and JavaScript SDK schemas.
345 
346Change:
347 
348- Expose embedded Session creation and read-side behavior over the experimental HTTP API.
349- Accept optional prompt admission `id`, `delivery`, and `resume` fields so callers can request idempotency, steering or queue semantics, and durable admission without immediate execution.
350- Keep message cursors opaque and preserve configured Location routing through both legacy flat and nested `location[...]` query parameters in the V2 SDK client.
351 
352Reason:
353 
354- Remote and embedded consumers need one generated contract while Location middleware remains compatible with current server routing.
355 
356Compatibility:
357 
358- These are experimental V2 routes.
359- Prompt admission now returns the admitted user-shaped message and may return a conflict error when one message ID is reused for different input.
360- SDK Location GET rewriting preserves existing flat query behavior and adds nested compatibility parameters.
361 
362## 2026-06-03: Durable Session Message Pagination
363 
364Affected schema:
365 
366- Internal `SessionV2.messages()` cursor input.
367- Opaque cursor payload returned by `GET /api/session/:sessionID/message`.
368 
369Change:
370 
371- Remove wall-clock `time` from the message cursor payload.
372- Resolve the opaque cursor's projected message `id` to its stored `session_message.seq`.
373- Apply page boundaries and ordering with durable per-session `seq` rather than `time_created` plus `id`.
374 
375Reason:
376 
377- Projected V2 message chronology is defined by synchronized Session-event order.
378- Wall-clock timestamps may collide or move backwards, so they are not safe pagination boundaries.
379- The list endpoint must agree with replay and context loading, which already order by durable sequence.
380 
381Compatibility:
382 
383- No database migration is required. `session_message.seq` and its session-scoped index already exist.
384- The HTTP cursor remains opaque and existing cursors remain usable because they already carry the projected message `id`; older extra `time` data is ignored while decoding.
385- No OpenAPI or generated SDK schema changes are required for this pagination correction.
386 
387## 2026-06-03: Public Provider And Model Catalog DTOs
388 
389Affected schema:
390 
391- Responses from `GET /api/provider`, `GET /api/provider/:providerID`, and `GET /api/model`.
392- Generated `ProviderV2PublicInfo` and `ModelV2PublicInfo` SDK schemas.
393 
394Change:
395 
396- Replace internal catalog response schemas with explicit public DTOs.
397- Remove provider request headers and bodies, API settings, custom enablement data, model request overrides, and variant request overrides from public responses.
398 
399Reason:
400 
401- Internal catalog records may contain credentials or provider-specific request material and must not cross the public HTTP serialization boundary.
402 
403Compatibility:
404 
405- Public V2 catalog responses intentionally expose fewer fields.
406- Internal provider and model schemas remain available to the runtime.
407 
408## 2026-06-03: Durable Reasoning And Hosted Tool Replay Metadata
409 
410Affected schema:
411 
412- Durable `session.next.reasoning.started` and `session.next.reasoning.ended` events.
413- Durable `session.next.tool.success` and `session.next.tool.failed` events.
414- Projected assistant reasoning and settled tool message state.
415 
416Change:
417 
418- Add optional reasoning `providerMetadata`.
419- Add optional durable tool `result` and project it into settled tool message state.
420- Preserve projected tool-call metadata separately from optional settlement-result metadata.
421- Replay provider-native reasoning and tool metadata only when the historical assistant model matches the selected continuation model.
422 
423Reason:
424 
425- Provider continuation requires signed or encrypted reasoning metadata on later turns.
426- Provider-executed hosted tool results must survive projection so replay can keep hosted calls and results inline in assistant content.
427- Recovery settlement must not erase provider-native call metadata needed to reconstruct a valid continuation request.
428 
429Compatibility:
430 
431- Added durable-event fields are optional so previously recorded experimental events remain decodable.
432- Projected settled tool state gains model-facing result data when available.
433- Projected assistant tools gain optional result-side provider metadata; the existing metadata slot remains the backward-compatible call-side slot.
434- OpenAI Responses lowers reconstructed provider-executed hosted results to stored item references instead of rejecting assistant history.
435- Bedrock Converse signatures, Gemini `thoughtSignature`, and OpenAI-compatible Chat `reasoning_content` now round-trip through canonical continuation parts.
436 
437## 2026-06-03: Projected Assistant Ownership And Full-Value Parts
438 
439Affected schema:
440 
441- Projected assistant text parts.
442- Durable text and tool lifecycle boundaries.
443- Projected assistant tool ownership.
444 
445Change:
446 
447- Preserve stable IDs on projected assistant text parts.
448- Route durable tool projection updates through explicit owning assistant message IDs rather than provider-local call IDs alone.
449- Replay full-value text and tool-input end checkpoints while keeping fragment deltas ephemeral.
450 
451Reason:
452 
453- Provider-local tool call IDs may repeat across turns.
454- Durable projection reconstruction must not depend on ephemeral fragments that disappear after reconnect.
455 
456Compatibility:
457 
458- Earlier experimental projected assistant rows without stable text IDs are not assumed replay-compatible.
459- Current V2 histories reconstruct from durable full-value checkpoints.
460 
461## 2026-06-03: Location-Scoped V2 Questions
462 
463Affected schema:
464 
465- New `QuestionV2.*` domain schemas.
466- New `question.v2.asked`, `question.v2.replied`, and `question.v2.rejected` events.
467- New question list, reply, and reject HTTP routes and generated SDK schemas.
468 
469Change:
470 
471- Add schemas for pending requests, question options, ordered answers, and tool ownership metadata.
472- Add `GET /api/question/request`.
473- Add `POST /api/session/:sessionID/question/request/:requestID/reply`.
474- Add `POST /api/session/:sessionID/question/request/:requestID/reject`.
475 
476Reason:
477 
478- Embedded V2 tool execution needs a Location-owned pending-question service whose suspended replies can be settled through HTTP.
479 
480Compatibility:
481 
482- These are additive experimental V2 contracts.
483- No database migration is required because pending questions are intentionally in-memory Location state.
484 
485## 2026-06-03: Core-Owned Todo Update Event
486 
487Affected schema:
488 
489- Core-owned `SessionTodo.Info`.
490- Global `todo.updated` event registration.
491 
492Change:
493 
494- Register the todo update event from Core session-todo ownership and expose the existing todo item shape to the Core V2 tool.
495 
496Reason:
497 
498- Embedded V2 `todowrite` execution needs Core-owned persistence and update publication without importing legacy application orchestration.
499 
500Compatibility:
501 
502- The todo table and public todo update event shape are preserved.
503- No database migration is required.
504 
505## 2026-06-03: Added Core V2 Tool Schemas
506 
507Affected schema:
508 
509- New `todowrite` tool parameters and success payload.
510- New `question` tool parameters and success payload.
511- New `webfetch` tool parameters and success payload.
512 
513Change:
514 
515- Add a todo replacement-list tool using `SessionTodo.Info` items.
516- Add a question tool using ordered `QuestionV2.Prompt` values and ordered answer arrays.
517- Add an HTTP(S) fetch tool with explicit `text`, `markdown`, and `html` formats, bounded timeout input, and optional managed output resource metadata.
518 
519Reason:
520 
521- Embedded V2 execution needs Core-owned built-ins rather than imports from legacy application orchestration.
522- Explicit schemas keep model-facing definitions, runtime validation, and durable tool settlement aligned.
523 
524Compatibility:
525 
526- These are additive Location-scoped V2 built-ins.
527- No database migration or public HTTP API migration is required.
528 
529## 2026-06-03: Conditional File-Mutation Stale Error
530 
531Affected schema:
532 
533- New internal `FileMutation.StaleContentError` tagged error.
534 
535Change:
536 
537- Add a typed error carrying the mutation target path when an approved exact edit no longer matches the bytes at commit time.
538 
539Reason:
540 
541- V2 exact edits must fail rather than stale-clobber a concurrent cooperating write after permission approval.
542 
543Compatibility:
544 
545- This is an additive internal error contract.
546- No database, HTTP, or generated SDK schema changes are required.
547 
548## 2026-06-03: Provider Stream Watchdog Policy Deferred
549 
550Affected schema:
551 
552- No database, durable-event, HTTP, or generated SDK schema changes.
553- Internal Session-runner provider-stream policy.
554 
555Change:
556 
557- Do not impose a universal provider-stream inactivity or absolute timeout.
558- Remove the internal timeout error and hardcoded watchdog service.
559- Defer provider timeout, retry, watchdog, durable failure-reporting, and drain-chain-release policy to a configurable design slice.
560 
561Reason:
562 
563- V1 had no universal processor inactivity watchdog.
564- Providers and autonomous workloads have different runtime characteristics, so one hardcoded default is premature.
565 
566Compatibility:
567 
568- No migration or generated artifact regeneration is required.
569- Embedded runner callers do not receive a runner-defined provider-stream timeout error.
570 
571## 2026-06-03: Keyed Coalescing Durable Tail Signals
572 
573Affected schema:
574 
575- No database, durable-event, HTTP, or generated SDK schema changes.
576- Internal durable aggregate-tail wake delivery only.
577 
578Change:
579 
580- Replace the process-global unbounded aggregate-ID PubSub with one sliding-capacity-1 dirty signal per active tail and aggregate.
581- Subscribe and register the signal before historical SQLite replay, then remove it when the tail closes.
582- Re-query durable rows after each dirty edge and advance only by persisted aggregate sequence.
583 
584Reason:
585 
586- Wake notifications are advisory edges, not durable event payloads.
587- Slow consumers should not retain an unbounded number of redundant wake IDs when one SQLite query can recover every committed row after their cursor.
588- Per-tail signaling preserves independent cursors for multiple consumers of the same aggregate.
589 
590Compatibility:
591 
592- No migration, synchronized event version, OpenAPI, or SDK regeneration is required.
593- `sessions.events({ sessionID, after? })` remains a replay-and-tail stream of every durable event in aggregate sequence order.
594 
595## 2026-06-03: Sequential V2 Apply Patch Tool
596 
597Affected schema:
598 
599- New Core-owned `apply_patch` model-facing tool parameters and success payload.
600- New Core-owned pure patch hunk representation for add, update, and delete operations.
601 
602Change:
603 
604- Accept `{ patchText: string }` using the `*** Begin Patch` envelope.
605- Return ordered applied-operation records carrying `type`, canonical `target`, and permission-facing `resource`.
606- Resolve and approve every target before reading approved update/delete contents.
607- Preflight update/delete correctness before committing operations sequentially.
608- Report already-applied resources explicitly when a later commit fails.
609 
610Reason:
611 
612- Embedded V2 agents need reviewable multi-file edits without importing legacy application orchestration into Core.
613- Sequential semantics are small and honest: they avoid claiming rollback or transactionality that path-based filesystem commits do not provide.
614 
615Compatibility:
616 
617- This is an additive model-facing V2 tool contract.
618- Moves and atomic rollback are deliberately unsupported in the first slice and remain visible follow-ups.
619- No database migration, durable-event version, public HTTP, OpenAPI, or generated SDK change is required.
620 
621## 2026-06-03: Embedded Local-Tool Recovery Alignment
622 
623Affected schema:
624 
625- No database, durable-event, HTTP, or generated SDK schema changes.
626- Internal runner recovery and permission evaluation behavior only.
627 
628Change:
629 
630- Evaluate permissions through the default `build` agent when a Session omits an explicit agent, matching provider-turn execution.
631- Before assembling a provider request, durably fail local tools still projected as `running` from a previous process with the existing `session.next.tool.failed` shape and `Tool execution interrupted` message.
632 
633Reason:
634 
635- Agent-less embedded Sessions previously executed as `build` while evaluating an empty permission ruleset, so the first local tool could wait forever for an approval surface the local Discord proof did not expose.
636- A process lost while a local tool was running previously left a dangling tool call that made later provider continuation invalid. Recovery must settle the durable projection without replaying an abandoned side effect.
637 
638Compatibility:
639 
640- No migration, synchronized event version, OpenAPI, or SDK regeneration is required.
641- Existing experimental Session databases recover dangling local-tool projections on the next provider attempt.
642 
643## 2026-06-03: V2 Skill Tool
644 
645Affected schema:
646 
647- New Core-owned `skill` model-facing tool parameters and success payload.
648- Existing upstream `SkillV2` service remains the single Location-scoped skill registry.
649 
650Change:
651 
652- Accept `{ name: string }` for one skill selected from the upstream-discovered Location skill list.
653- Assert `skill` permission for the selected name.
654- Return V1-shaped `<skill_content name="...">` model output with the skill base directory and a bounded sampled supporting-file list.
655 
656Compatibility:
657 
658- This is an additive model-facing V2 tool contract.
659- No database migration, durable-event version, public HTTP, OpenAPI, or generated SDK change is required.
660 
661## 2026-06-03: Pre-PR V2 Safety Review
662 
663Affected schema:
664 
665- V2 OpenAPI request bodies preserve requiredness instead of inheriting legacy optional-body normalization.
666- Existing durable tool-failure and replay-owner schemas are reused without version changes.
667 
668Change:
669 
670- Fence replay envelopes whose aggregate ID differs from the decoded synchronized payload and persist owner claims when replay first adopts an existing unowned aggregate.
671- Settle abandoned local and provider-executed tools durably before continuation; hosted failures preserve inline provider-executed replay.
672- Give `apply_patch` add hunks create-only semantics, make sequential commits uninterruptible after preflight, and reject malformed patch grammar eagerly.
673- Wait for initial plugin boot before materializing the `skill` built-in, discover conventional config-root skill directories, and resolve current skills again during execution.
674- Sanitize provider and model public API URLs by stripping credentials, queries, and fragments.
675- Keep V1-like `webfetch` network semantics: approve the requested HTTP(S) URL, allow ordinary hostnames, and delegate redirects to the HTTP transport.
676- Keep V2 request bodies required in generated OpenAPI and SDK types.
677 
678Compatibility:
679 
680- No database migration is required.
681- Pre-launch `session.next.*` databases remain disposable experimental state rather than compatibility targets; reset experimental V2 data when upgrading across incompatible event-schema iterations.
682- V1 returns fetched images as attachments. The first Core V2 typed settlement remains text-only, so V2 continues to reject fetched images and other non-text files until attachment settlement is designed explicitly.
683 
684## 2026-06-03: Defer V2 Bash Background Execution
685 
686Affected schema:
687 
688- Core V2 model-facing `bash` tool parameters and success payload.
689 
690Change:
691 
692- Remove the optional `background` bash parameter and process-local background settlement shape from the shipped tool.
693- Retain the internal `BackgroundJob` prototype for a later integration slice.
694 
695Reason:
696 
697- The model has no registered observation or cancellation tool for background bash jobs, and process-local status is not a sufficient remote contract.
698 
699Compatibility:
700 
701- Foreground V2 bash execution is unchanged.
702- Reintroduce background bash only with durable status observation, completion delivery, and explicit cancellation semantics.
703 
704## 2026-06-18: Remove Bash Description Input
705 
706Affected schema:
707 
708- V1 and Core V2 model-facing `bash` tool parameters.
709 
710Change:
711 
712- Remove the V1 required and V2 optional `description` parameter.
713- Derive shell presentation from the command or a generic shell label instead of model-authored description metadata.
714 
715Compatibility:
716 
717- Existing persisted tool calls may still contain `description`, but new tool definitions no longer expose or require it.
718- Shell command execution behavior is unchanged.
719 
720## 2026-06-04: Add Durable Session Context Snapshots
721 
722Affected schema:
723 
724- Add `session_context_epoch` for one active immutable baseline string, structured JSON snapshot, and baseline sequence per Session.
725 
726Change:
727 
728- Lazily initialize one durable Context Epoch snapshot at the first safe provider-turn boundary.
729- Lower its exact baseline string through `LLMRequest.system` for every provider turn in the epoch.
730- Reuse the stored baseline verbatim after restart or producer changes instead of resampling privileged initial context.
731- Compare later observations against an overwriteable codec-encoded structured snapshot rather than rendered-text hashes.
732- Expose admitted chronological context as first-class `system` Session messages while keeping the active baseline in bounded context state.
733 
734Compatibility:
735 
736- The unpublished Context Epoch schema is consolidated into one database migration; baseline and structured snapshots are operational state rather than synchronized event history.
737- Existing experimental V2 Session databases remain disposable across incompatible pre-launch event-schema changes.
738- Chronological context updates, replacement epochs after compaction or model switches, project instructions, skills guidance, and plugin transforms remain follow-up slices.
739 
740## 2026-06-04: Admit Chronological Session Context Updates
741 
742Affected schema:
743 
744- Add synchronized `session.next.context.updated.1` Session events containing a durable System-message ID and only exact combined model-visible text.
745- Add `session_context_epoch.revision` for transactional structured-snapshot advancement.
746- Add the first-class `system` Session message projection for chronological context updates.
747 
748Change:
749 
750- Reconcile Location-scoped Context Sources at each safe provider-turn boundary using one coherent observation.
751- Keep the stored baseline immutable while admitting changed source renderings as chronological `Message.system(...)` history.
752- Advance the overwriteable structured snapshot atomically with the rendered System-message event.
753- Emit the previously stored model-meaningful removal rendering when a source is removed.
754- Reject chronological system updates that would split a local tool call from its result across provider protocols; use wrapped user fallback when Anthropic native system-update placement is unsupported.
755 
756Compatibility:
757 
758- The synchronized event log retains only text actually shown to the model, not internal structured snapshots.
759- Existing experimental V2 Session databases remain disposable across incompatible pre-launch event-schema changes.
760- Replacement epochs after compaction or model switches, skills guidance, and plugin-defined context remain follow-up slices.
761 
762## 2026-06-04: Replace Session Context Epochs Lazily
763 
764Affected schema:
765 
766- Add nullable `session_context_epoch.replacement_seq` for idempotent lazy replacement requests.
767 
768Change:
769 
770- Mark the active Context Epoch for replacement after a model switch or completed compaction projection.
771- Persist the triggering aggregate sequence so same-target replay cannot reopen an already-settled replacement.
772- Render and overwrite the fresh immutable baseline and structured snapshot lazily at the next safe provider-turn boundary.
773- Exclude chronological System messages from earlier epochs when assembling active provider history.
774 
775Compatibility:
776 
777- Baseline replacement is bounded operational state and does not add permanent synchronized events.
778- Existing experimental V2 Session databases remain disposable across incompatible pre-launch event-schema changes.
779- Compaction execution, skills guidance, and plugin-defined context remain follow-up slices.
780 
781## 2026-06-05: Register Ambient System Context Producers
782 
783Affected schema:
784 
785- No database schema changes.
786 
787Change:
788 
789- Replace the Session-specific context loader with a Location-scoped registry of stable-keyed scoped context producers.
790- Register environment/date and ambient instruction producers independently, then evaluate producers concurrently in stable contribution-key order.
791- Directly discover and read global plus upward project `AGENTS.md` files at each safe provider-turn boundary.
792- Preserve admitted instructions across transient scan/read failures and block first-epoch initialization while any context source is unavailable.
793- Retry Context Epoch preparation until stable after optimistic revision mismatches.
794- Clear the active Context Epoch when a Session moves so the destination initializes a complete baseline before promoting more input.
795- Fence Context Epoch initialization against the authoritative Session Location so a concurrent old-Location runner cannot recreate stale privileged context after a move.
796- Canonicalize ambient instruction traversal boundaries, honor `OPENCODE_DISABLE_PROJECT_CONFIG`, and make non-empty aggregate updates explicitly supersede previously loaded instructions.
797 
798Compatibility:
799 
800- Watcher-backed per-file `Refreshable` instruction observations, configured sources, nested discovery, and plugin-defined context remain follow-up slices.
801 
802## 2026-06-05: Admit Selected-Agent Skill Guidance
803 
804Affected schema:
805 
806- Add `session_context_epoch.agent` so each durable baseline records its owning effective agent.
807- No synchronized event, public HTTP API, or generated SDK schema changes.
808 
809Change:
810 
811- Compose selected-agent, permission-filtered available-skill guidance with Location-wide System Context before Context Epoch admission.
812- Keep skill bodies behind the existing permission-checked `skill` tool and remove the unfiltered skill list from its Location-wide definition.
813- Stop missing-skill errors from enumerating the unfiltered Location-wide skill catalog.
814- Bind local tool authorization and pending permission requests to the provider turn's effective agent.
815- Keep absolute skill locations out of available-skill guidance; expose body and location only through the permission-checked `skill` tool.
816- Request Context Epoch replacement after an agent switch, dynamically re-observe the effective agent during retries, and fence first-epoch creation against the authoritative effective agent.
817- Fence existing-epoch replacement against the authoritative effective agent and block cross-agent provider turns while replacement context is unavailable.
818- Group the System Context algebra, registry, and built-ins under `system-context/`; keep source producers and Context Epoch persistence with their owning Skill, instruction, and Session modules; rename projected conversation selection to Session History.
819- Add the canonical V1-to-V2 runtime-context parity checklist to `specs/v2/session.md`.
820 
821Compatibility:
822 
823- Existing Context Epoch rows backfill the default `build` agent and reconcile to another selected agent at the next safe provider-turn boundary.
824 
825## 2026-06-22: Simplify Session Context Rebaselining
826 
827Affected schema:
828 
829- Remove `session_context_epoch.agent`, `session_context_epoch.replacement_seq`, and `session_context_epoch.revision`.
830- No synchronized event, public HTTP API, or generated SDK schema changes.
831 
832Change:
833 
834- Sample the effective agent and model once for each provider turn; selection changes apply to the next turn.
835- Preserve the immutable baseline and admit ordinary System Context changes as chronological `ContextUpdated` messages.
836- Rebuild the baseline directly after completed compaction instead of maintaining pending replacement state.
837- Preserve the old baseline and its effective chronological updates while a post-compaction baseline cannot be rendered completely.
838- Rely on the process-local Session execution lane instead of optimistic concurrency state between Context Epoch writers.
839 
840Compatibility:
841 
842- Existing Context Epoch rows migrate in place by dropping the obsolete selection and pending-replacement columns.
843- Model and agent switches no longer discard earlier chronological System Context updates by forcing a new baseline.
844