feat(core): bound v2 tool output (#30999)

Author: kitlangton

CONTEXT.md

@@ -39,6 +39,12 @@ An expected temporary inability to observe a **Context Source** value; the runti
 **Safe Provider-Turn Boundary**:
 The point immediately before a provider call, after durable input promotion and any required tool settlement, where context changes may be admitted chronologically.
 
+**Model Tool Output**:
+The bounded projection of a Core-executed tool result persisted in Session history and replayed to the model. A tool may shape this projection semantically, but the Tool Registry enforces the final size limit.
+
+**Managed Tool Output File**:
+A temporary file created under OpenCode's shared tool-output directory to retain complete output that was too large for Session history.
+
 **Model Request Options**:
 Provider-semantic model settings selected from the Catalog and active Session variant before the LLM protocol adapter encodes them for a provider request.
 _Avoid_: Request body, wire options
@@ -96,6 +102,17 @@ Provider-neutral sampling and output controls, partitioned from provider semanti
 - A **Mid-Conversation System Message** lowers to the provider's native chronological instruction role when supported and to a wrapped chronological fallback otherwise.
 - When the effective aggregate instruction set changes, its **Mid-Conversation System Message** includes the complete current ordered set and supersedes the prior aggregate value; when no ambient instructions remain, the message states that previously loaded instructions no longer apply.
 - Ambient project instruction discovery honors `OPENCODE_DISABLE_PROJECT_CONFIG`; global instructions remain eligible.
+- Oversized textual **Model Tool Output** retains a bounded preview in Session history while its complete text moves to managed tool-output storage. Arbitrary structured-result size is a separate concern.
+- One tool settlement receives one aggregate textual limit, using the configured maximum lines or UTF-8 bytes, whichever is reached first. The limit is provider-independent; token pressure belongs to context assembly and compaction.
+- Generic truncation preserves the beginning and end of textual output. Tools may apply a more meaningful strategy before the Tool Registry enforces the final limit.
+- A truncated **Model Tool Output** identifies its complete text both in the bounded model-visible preview and as a typed managed output path. Managed output paths do not modify the tool's validated structured result.
+- A **Managed Tool Output File** is temporary and may expire after its retention period. The bounded **Model Tool Output**, not the file, is the durable replayable record.
+- Failure to retain a **Managed Tool Output File** does not change a successful tool operation into a failed one. The Session records an explicitly lossy bounded output without a path, while operators receive diagnostics for the storage failure.
+- Once a tool operation succeeds, bounding its **Model Tool Output** and publishing its one durable settlement form an interruption-safe completion region. Raw oversized success is never published before a later correction.
+- When a structured-only result would exceed the **Model Tool Output** limit, its validated structured value remains unchanged for Session consumers while model replay uses a bounded textual JSON preview and optional managed output path.
+- Existing tool-managed output paths survive generic bounding. A fallback file retains exactly the complete projected text received by the Tool Registry and never claims to reconstruct output already discarded by tool-specific shaping.
+- **Managed Tool Output Files** use globally unique names in one shared flat directory. Their absolute paths are readable and searchable by ordinary tools; other absolute paths remain outside Location-scoped filesystem authority.
+- Provider-executed tool results remain provider-native transcript facts outside generic Tool Registry bounding. Their context control requires provider-aware pruning or compaction because some providers require exact structured round-trip payloads.
 
 ## Example dialogue
 

packages/core/src/filesystem.ts

@@ -13,9 +13,10 @@ import { ProjectReference } from "./project-reference"
 import { NonNegativeInt, PositiveInt, RelativePath } from "./schema"
 import { Protected } from "./filesystem/protected"
 import { Ripgrep } from "./filesystem/ripgrep"
+import { ToolOutputStore } from "./tool-output-store"
 
 export const ReadInput = Schema.Struct({
-  path: RelativePath,
+  path: Schema.String,
   reference: Schema.NonEmptyString.pipe(Schema.optional),
 })
 export type ReadInput = typeof ReadInput.Type
@@ -65,7 +66,7 @@ export class ReadTarget extends Schema.Class<ReadTarget>("FileSystem.ReadTarget"
 }) {}
 
 export const ListInput = Schema.Struct({
-  path: RelativePath.pipe(Schema.optional),
+  path: Schema.String.pipe(Schema.optional),
   reference: Schema.NonEmptyString.pipe(Schema.optional),
 })
 export type ListInput = typeof ListInput.Type
@@ -181,6 +182,7 @@ export const layer = Layer.effect(
   Effect.gen(function* () {
     const fs = yield* FSUtil.Service
     const location = yield* Location.Service
+    const global = yield* Effect.serviceOption(Global.Service)
     const references = yield* ProjectReference.Service
     const ripgrep = yield* Ripgrep.Service
     const root = yield* fs.realPath(location.directory).pipe(Effect.orDie)
@@ -201,8 +203,21 @@ export const layer = Layer.effect(
       if (resolved.kind === "git") yield* references.ensurePath(resolved.path).pipe(Effect.orDie)
       return { directory: resolved.path, root: yield* fs.realPath(resolved.path).pipe(Effect.orDie) }
     })
-    const resolve = Effect.fnUntraced(function* (input?: RelativePath, reference?: string) {
-      if (input && path.isAbsolute(input)) return yield* Effect.die(new Error("Path must be relative to the location"))
+    const resolve = Effect.fnUntraced(function* (input?: string, reference?: string) {
+      const managed = path.join(
+        Option.match(global, { onNone: () => Global.Path.data, onSome: (value) => value.data }),
+        ToolOutputStore.MANAGED_DIRECTORY,
+      )
+      if (input && path.isAbsolute(input)) {
+        if (reference) return yield* Effect.die(new Error("Absolute paths cannot use a project reference"))
+        if (path.dirname(input) !== managed || !path.basename(input).startsWith("tool_"))
+          return yield* Effect.die(new Error("Absolute path is not managed tool output"))
+        const real = yield* fs.realPath(input).pipe(Effect.orDie)
+        const managedRoot = yield* fs.realPath(managed).pipe(Effect.orDie)
+        if (path.dirname(real) !== managedRoot || !path.basename(real).startsWith("tool_"))
+          return yield* Effect.die(new Error("Path escapes managed tool output"))
+        return { absolute: input, real, directory: managed, root: managedRoot }
+      }
       const selected = yield* select(reference)
       const absolute = path.resolve(selected.directory, input ?? ".")
       if (!FSUtil.contains(selected.directory, absolute))

packages/core/src/location-layer.ts

@@ -46,9 +46,8 @@ import { FetchHttpClient } from "effect/unstable/http"
 export class LocationServiceMap extends LayerMap.Service<LocationServiceMap>()("@opencode/example/LocationServiceMap", {
   lookup: (ref: Location.Ref) => {
     const location = Location.layer(ref)
-    const permissionsAndTools = ToolRegistry.layer.pipe(Layer.provideMerge(PermissionV2.locationLayer))
     const systemContext = SystemContextBuiltIns.locationLayer
-    const services = Layer.mergeAll(
+    const base = Layer.mergeAll(
       location,
       Policy.locationLayer,
       Config.locationLayer,
@@ -63,13 +62,18 @@ export class LocationServiceMap extends LayerMap.Service<LocationServiceMap>()("
       Pty.locationLayer,
       SkillV2.locationLayer,
       systemContext,
-      permissionsAndTools,
       LocationMutation.locationLayer.pipe(Layer.orDie),
     ).pipe(Layer.provideMerge(location))
+    const resources = ToolOutputStore.layer.pipe(Layer.provide(base))
+    const permissionsAndTools = ToolRegistry.layer.pipe(
+      Layer.provideMerge(PermissionV2.locationLayer),
+      Layer.provide(resources),
+      Layer.provide(base),
+    )
+    const services = Layer.mergeAll(base, resources, permissionsAndTools)
     const commits = FileMutation.locationLayer.pipe(Layer.provide(services))
     const searches = LocationSearch.layer.pipe(Layer.provide(Ripgrep.layer), Layer.provide(services))
     const skillGuidance = SkillGuidance.locationLayer.pipe(Layer.provide(services))
-    const resources = ToolOutputStore.layer.pipe(Layer.provide(services))
     const todos = SessionTodo.layer.pipe(Layer.provide(services))
     const questions = QuestionV2.locationLayer.pipe(Layer.provide(services))
     const builtInTools = BuiltInTools.locationLayer.pipe(

packages/core/src/location-search.ts

@@ -25,7 +25,7 @@ export const MAX_LINE_PREVIEW_LENGTH = 2_000
 export const ResultLimit = PositiveInt.check(Schema.isLessThanOrEqualTo(MAX_RESULT_LIMIT))
 
 const RootInput = {
-  path: RelativePath.pipe(Schema.optional),
+  path: Schema.String.pipe(Schema.optional),
   reference: Schema.NonEmptyString.pipe(Schema.optional),
 }
 

packages/core/src/session/event.ts

@@ -373,6 +373,7 @@ export namespace Tool {
       ...ToolBase,
       structured: ToolOutput.Structured,
       content: Schema.Array(ToolOutput.Content),
+      outputPaths: Schema.Array(Schema.String).pipe(Schema.optional),
       result: Schema.Unknown.pipe(Schema.optional),
       provider: Schema.Struct({
         executed: Schema.Boolean,

packages/core/src/session/message-updater.ts

@@ -308,6 +308,7 @@ export function update(adapter: Adapter, event: SessionEvent.Event) {
                 input: match.state.input,
                 structured: event.data.structured,
                 content: [...event.data.content],
+                outputPaths: event.data.outputPaths ? [...event.data.outputPaths] : [],
                 result: event.data.result,
               }),
             )

packages/core/src/session/message.ts

@@ -86,6 +86,7 @@ export class ToolStateCompleted extends Schema.Class<ToolStateCompleted>("Sessio
   input: Schema.Record(Schema.String, Schema.Unknown),
   attachments: SessionEvent.FileAttachment.pipe(Schema.Array, Schema.optional),
   content: ToolOutput.Content.pipe(Schema.Array),
+  outputPaths: SessionEvent.Tool.Success.data.fields.outputPaths,
   structured: ToolOutput.Structured,
   result: SessionEvent.Tool.Success.data.fields.result,
 }) {}

packages/core/src/session/runner/llm.ts

@@ -207,7 +207,8 @@ export const layer = Layer.effect(
         },
       })
       const withPublication = Semaphore.makeUnsafe(1).withPermit
-      const publish = (event: LLMEvent) => withPublication(publisher.publish(event))
+      const publish = (event: LLMEvent, outputPaths: ReadonlyArray<string> = []) =>
+        withPublication(publisher.publish(event, outputPaths))
       if (!(yield* SessionContextEpoch.current(db, session.id, agent.id, system.revision)))
         return yield* Effect.die(new RetryTurn(undefined))
       const providerStream = llm.stream(request).pipe(
@@ -216,26 +217,29 @@ export const layer = Layer.effect(
             yield* publish(event)
             if (event.type !== "tool-call" || event.providerExecuted) return
             needsContinuation = true
-            yield* tools.settle({ sessionID: session.id, agent: agent.id, call: event }).pipe(
-              Effect.catchCause((cause) => {
-                if (isQuestionRejected(cause)) return Effect.failCause(cause)
-                return Effect.succeed({
-                  result: { type: "error" as const, value: String(Cause.squash(cause)) },
-                  output: undefined,
-                })
-              }),
-              Effect.flatMap((settlement) =>
-                publish(
-                  LLMEvent.toolResult({
-                    id: event.id,
-                    name: event.name,
-                    result: settlement.result,
-                    output: settlement.output,
-                  }),
+            yield* Effect.uninterruptibleMask((restore) =>
+              restore(tools.settle({ sessionID: session.id, agent: agent.id, call: event })).pipe(
+                Effect.catchCause((cause) => {
+                  if (isQuestionRejected(cause) || Cause.hasInterrupts(cause)) return Effect.failCause(cause)
+                  return Effect.succeed({
+                    result: { type: "error" as const, value: String(Cause.squash(cause)) },
+                    output: undefined,
+                    outputPaths: [],
+                  })
+                }),
+                Effect.flatMap((settlement) =>
+                  publish(
+                    LLMEvent.toolResult({
+                      id: event.id,
+                      name: event.name,
+                      result: settlement.result,
+                      output: settlement.output,
+                    }),
+                    settlement.outputPaths ?? [],
+                  ),
                 ),
               ),
-              FiberSet.run(toolFibers),
-            )
+            ).pipe(FiberSet.run(toolFibers))
           }),
         ),
         Effect.ensuring(withPublication(publisher.flush())),

packages/core/src/session/runner/publish-llm-event.ts

@@ -218,7 +218,10 @@ export const createLLMEventPublisher = (events: EventV2.Interface, input: Input)
     }
   })
 
-  const publish = Effect.fn("SessionRunner.publishLLMEvent")(function* (event: LLMEvent) {
+  const publish = Effect.fn("SessionRunner.publishLLMEvent")(function* (
+    event: LLMEvent,
+    outputPaths: ReadonlyArray<string> = [],
+  ) {
     switch (event.type) {
       case "step-start":
         yield* startAssistant()
@@ -347,6 +350,7 @@ export const createLLMEventPublisher = (events: EventV2.Interface, input: Input)
           assistantMessageID: tool.assistantMessageID,
           callID: event.id,
           ...result,
+          outputPaths,
           result: event.result,
           provider,
         })