fix(runner): skip tool calls SessionToolRunner does not own

A self-hosted managed-agents session is commonly serviced by two clients
at once: the SessionToolRunner inside the customer's sandbox (registered
with the file/shell tools) and the customer's app backend (handling the
agent's custom function tools). The Sessions API has a partial-fulfilment
contract: when a session pauses requires_action the pending tool-call ids
can mix both kinds, and each client must post results ONLY for the ids it
owns and leave the rest pending for the other client to fill.

Previously execute() answered any unregistered tool name in place with an
is_error "tool not implemented" result. In the split-client setup that
claims a tool_use_id the runner does not own: the server either rejects
the type-mismatched result or the model reads "not implemented" as the
tool output while the real result from the app backend arrives after the
agent already sampled. Either way the conversation is corrupted.

Now an unregistered tool name is skipped unconditionally: the runner
posts no result, does not mark the id answered, and leaves it pending for
its owner, while still yielding the DispatchedToolCall (Posted=false,
IsError=false, no result event built) so the caller can observe the
unowned dispatch. A skipped, unanswered id stays out of the reconcile
idle/end-turn accounting and is re-surfaced after a reconnect until its
owner answers it. The comma-ok registry lookup is kept, so an
unregistered name never dereferences a nil tool.

Consequence for the single-client case: when this runner is the only
watcher of a session, an unowned tool call now gets no result or error
from anyone, so the session can stall silently rather than receiving the
old graceful "not implemented" error. An opt-in strict/error-on-unknown
mode is explored separately in a stacked PR (see linked exploration
ticket).

Author: packyg

betasessiontoolrunner.go

@@ -144,10 +144,12 @@ type SessionToolRunnerOptions struct {
 // event (ToolUse.Input / CustomToolUse.Input) and the tool's output blocks on
 // the posted result (Result.Content / CustomResult.Content).
 //
-// IsError is true if the tool reported failure, the tool name was unknown, or
-// the tool exceeded its per-call timeout. Posted is orthogonal to IsError: it
-// reports whether the result event was successfully sent back to the session.
-// Posted=false means the agent will not see this result, regardless of IsError.
+// IsError is true if the tool reported failure or exceeded its per-call
+// timeout. Posted is orthogonal to IsError: it reports whether a result event
+// was successfully sent back to the session. Posted=false means the agent will
+// not see a result from this runner, regardless of IsError — either because
+// the send failed or because the tool name is not one this runner owns and the
+// runner deliberately posted nothing and left the id pending for its owner.
 type DispatchedToolCall struct {
 	// Custom reports whether this dispatch was triggered by an
 	// agent.custom_tool_use event (a user-defined function tool) rather than an
@@ -195,8 +197,10 @@ type DispatchedToolCall struct {
 	// agent as an error.
 	IsError bool
 
-	// Posted reports whether the result event reached the session. False on
-	// permanent 4xx or exhausted retries.
+	// Posted reports whether a result event for this call reached the session.
+	// False on a permanent 4xx or exhausted retries, and also false — with no
+	// result event ever built — for a tool name this runner does not own when
+	// it deliberately posts nothing and leaves the id pending for its owner.
 	Posted bool
 }
 
@@ -886,8 +890,18 @@ func (r *SessionToolRunner) execute(ctx context.Context, p pendingToolUse) Dispa
 	var blocks []BetaToolResultBlockParamContentUnion
 	tool, ok := r.byName[name]
 	if !ok {
-		call.IsError = true
-		blocks = textOnlyResult(fmt.Sprintf("tool %q not implemented", name))
+		// Skip (split-client partial fulfilment): a name this runner is not
+		// registered for belongs to the other client servicing this session
+		// (typically the customer's app backend handling custom tools). Post
+		// NO result, do not mark it answered, and leave the tool_use_id
+		// pending for its owner — claiming it would corrupt the conversation.
+		// Still yield the call so the caller can observe the unowned
+		// dispatch; nothing was sent, so Posted and IsError stay false and no
+		// result event is populated. The id remains unanswered, so reconcile
+		// keeps it out of the idle/end-turn accounting and re-surfaces it
+		// after a reconnect until its owner answers it.
+		log.Info("tool not owned by this runner; leaving the tool_use_id pending for its owner")
+		return call
 	} else {
 		// Derive the per-tool timeout from the runner ctx (not
 		// context.WithoutCancel) so cancelling the runner also aborts an

betasessiontoolrunner_test.go

@@ -420,29 +420,118 @@ func TestSessionToolRunner_ReconcileRetriesFailedPost(t *testing.T) {
 	require.NoError(t, r.Close())
 }
 
-func TestSessionToolRunner_UnknownTool(t *testing.T) {
+// TestSessionToolRunner_SkipsUnownedToolByDefault pins the default
+// split-client behavior: a tool-use event whose Name is not in the runner's
+// registry belongs to the other client servicing the session (e.g. the
+// customer's app backend handling custom tools). The runner must post NO
+// result for it, claim nothing, and leave the tool_use_id pending — while
+// still yielding the DispatchedToolCall so the caller can observe the unowned
+// dispatch (Posted=false, IsError=false, no result event populated). It must
+// not panic on the registry miss.
+func TestSessionToolRunner_SkipsUnownedToolByDefault(t *testing.T) {
 	server := newSessionEventsServer(t)
 	server.HandleStream = func(w http.ResponseWriter, r *http.Request) {
 		streamWriter(w, r, []string{
-			sseLine("agent.tool_use", toolUseEvt("evt_99", "nope", map[string]any{})),
+			sseLine("agent.tool_use", toolUseEvt("evt_99", "not_ours", map[string]any{})),
+			sseLine("agent.custom_tool_use", customToolUseEvt("cevt_99", "app_backend_tool", map[string]any{})),
 		}, true)
 	}
-	server.HandleSend = func(w http.ResponseWriter, r *http.Request) {
-		body, _ := io.ReadAll(r.Body)
-		require.Contains(t, string(body), `"is_error":true`)
-		w.Header().Set("Content-Type", "application/json")
-		_, _ = w.Write([]byte(sendOK()))
+	server.HandleSend = func(http.ResponseWriter, *http.Request) {
+		t.Fatal("runner must not post any result for a tool it does not own")
 	}
 
+	// The runner owns "echo" but neither streamed event is for it.
+	echo := &stubBetaTool{name: "echo"}
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()
-	r := newShortIdleRunner(t, ctx, server.Client(), nil, 500*time.Millisecond)
+	r := newShortIdleRunner(t, ctx, server.Client(), []BetaTool{echo}, 500*time.Millisecond)
 
-	require.True(t, r.Next())
+	seen := map[string]DispatchedToolCall{}
+	for range 2 {
+		require.True(t, r.Next(), "the unowned call must still be surfaced to the caller")
+		call := r.Current()
+		seen[call.ToolUseID] = call
+	}
+
+	builtin, ok := seen["evt_99"]
+	require.True(t, ok, "the unowned agent.tool_use must still be yielded")
+	require.Equal(t, "not_ours", builtin.Name)
+	require.False(t, builtin.Custom)
+	require.False(t, builtin.IsError, "a skipped call is not an error")
+	require.False(t, builtin.Posted, "nothing was sent for an unowned tool")
+	require.Equal(t, "evt_99", builtin.ToolUse.ID, "the triggering event is still surfaced")
+	require.Empty(t, builtin.Result.ToolUseID, "no user.tool_result was ever built")
+	require.Empty(t, dispatchedResultText(builtin))
+
+	custom, ok := seen["cevt_99"]
+	require.True(t, ok, "the unowned agent.custom_tool_use must still be yielded")
+	require.Equal(t, "app_backend_tool", custom.Name)
+	require.True(t, custom.Custom)
+	require.False(t, custom.IsError, "a skipped call is not an error")
+	require.False(t, custom.Posted, "nothing was sent for an unowned custom tool")
+	require.Equal(t, "cevt_99", custom.CustomToolUse.ID, "the triggering event is still surfaced")
+	require.Empty(t, custom.CustomResult.CustomToolUseID, "no user.custom_tool_result was ever built")
+	require.Empty(t, dispatchedResultText(custom))
+
+	require.Equal(t, int32(0), echo.runs.Load(), "no registered tool should have run")
+	require.NoError(t, r.Close())
+	require.NoError(t, r.Err(), "skipping an unowned tool is not a terminal error")
+}
+
+// TestSessionToolRunner_SkippedUnownedToolDoesNotTripIdle pins that a skipped
+// (unanswered) unowned tool_use stays out of the end-turn accounting:
+// reconcile sees history ending on an end_turn idle but with the unowned
+// tool_use still unanswered, so it must NOT arm the idle countdown — the
+// runner has not actually handled that call, its owner still has to.
+func TestSessionToolRunner_SkippedUnownedToolDoesNotTripIdle(t *testing.T) {
+	server := newSessionEventsServer(t)
+	server.HandleStream = func(w http.ResponseWriter, r *http.Request) {
+		streamWriter(w, r, nil, true) // no live events; reconcile drives the test
+	}
+	server.HandleList = func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		body, _ := json.Marshal(map[string]any{
+			"data": []any{
+				toolUseEvt("evt_pending", "not_ours", map[string]any{}),
+				idleEndTurnEvt("evt_idle"),
+			},
+			"first_id": "evt_pending", "has_more": false, "last_id": "evt_idle",
+		})
+		_, _ = w.Write(body)
+	}
+	server.HandleSend = func(http.ResponseWriter, *http.Request) {
+		t.Fatal("runner must not post any result for a tool it does not own")
+	}
+
+	// Bound the run: with a short MaxIdle, a wrongly-armed idle countdown
+	// would end the runner ~150ms in; a correct runner instead blocks until
+	// this ctx expires ~2s in. The gap makes the two outcomes unambiguous.
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer cancel()
+	r := newShortIdleRunner(t, ctx, server.Client(), nil, 150*time.Millisecond)
+
+	require.True(t, r.Next(), "reconcile must still surface the unowned call")
 	call := r.Current()
-	require.True(t, call.IsError)
-	require.Contains(t, dispatchedResultText(call), "not implemented")
-	require.True(t, call.Posted)
+	require.Equal(t, "evt_pending", call.ToolUseID)
+	require.False(t, call.Posted)
+	require.False(t, call.IsError)
+	require.Empty(t, call.Result.ToolUseID, "no result was built for the skipped call")
+
+	// The skipped tool_use is unanswered, so reconcile must keep it OUT of
+	// the end-turn accounting even though history ends on an end_turn idle.
+	// Single-goroutine: drain to termination and assert it was ctx expiry,
+	// not an idle timeout.
+	start := time.Now()
+	for r.Next() {
+		t.Fatalf("unexpected extra yield: %+v", r.Current())
+	}
+	elapsed := time.Since(start)
+
+	require.NotErrorIs(t, r.Err(), ErrIdleTimeout,
+		"runner falsely went idle on a skipped unowned tool_use")
+	require.GreaterOrEqual(t, elapsed, time.Second,
+		"runner ended after only %s — it idle-timed-out instead of staying up for the pending unowned call", elapsed)
+	require.NoError(t, r.Close())
 }
 
 func TestSessionToolRunner_SessionTerminatedEndsIteration(t *testing.T) {

examples/managed-agents-observe-tool-calls/main.go

@@ -364,18 +364,43 @@ func heartbeatLease(ctx context.Context, cancel context.CancelFunc, client anthr
 
 // printCall logs one observed tool call: name, input, error flag, and whether
 // the result posted back to the session.
+//
+// By default the runner only owns the tools it was registered with. A
+// self-hosted session is commonly serviced by two clients at once (this runner
+// for sandbox tools, the customer's app backend for custom tools); a tool-use
+// for a name this runner does not own is deliberately left pending for its
+// owner — it is yielded here with Posted=false, IsError=false and no result
+// event built, which is distinct from a result the runner built but failed to
+// send.
 func printCall(call anthropic.DispatchedToolCall) {
 	status := "ok"
-	if call.IsError {
+	switch {
+	case call.IsError:
 		status = "error"
+	case skippedUnowned(call):
+		status = "skipped (not owned by this runner; left pending for its owner)"
 	}
 	posted := ""
-	if !call.Posted {
+	if !call.Posted && !skippedUnowned(call) {
 		posted = " [result post failed]"
 	}
 	fmt.Printf("tool %s(%s) -> %s%s\n", call.Name, truncate(callInput(call), 120), status, posted)
 }
 
+// skippedUnowned reports whether the runner deliberately left this call for
+// another client to answer (the default split-client behavior): nothing was
+// posted and no result event was ever constructed. Distinct from a failed
+// post, where the runner built the result but the send did not land.
+func skippedUnowned(call anthropic.DispatchedToolCall) bool {
+	if call.Posted || call.IsError {
+		return false
+	}
+	if call.Custom {
+		return call.CustomResult.CustomToolUseID == ""
+	}
+	return call.Result.ToolUseID == ""
+}
+
 // callInput renders the raw tool input from the triggering event —
 // CustomToolUse.Input for a custom tool call, ToolUse.Input otherwise.
 func callInput(call anthropic.DispatchedToolCall) string {