[AbirAbbas]

What this is

The desktop app now owns Workstreams: its store, pages, sources and the workstream agent's tools all live in codeaf-desk. The one thing the desk cannot do for itself is make the model call those tools, because the engine runs the model loop. This PR gives codeaf app the two generic pieces the desk needs for that, and nothing that knows what a workstream is.

• Client tools. A connected app attaches named sets of tools to a conversation. The model sees them after every built-in tool; each call goes to the app as an event and the app answers it.
• Conversation scope. An app can tell a conversation to be told only about its own work, instead of everything landed or running in the same folder.

It carries #2334, #2346, #2360, #2417 and #2462 from the closed integration PR #2306 (workstreams/main) onto dev. That PR could not merge: its base, app/v3, landed on dev in #2561 and #2597 left it out as unfinished.

Wire surface added

Kind	Name	Notes
hello feature	agents.client_tools, agents.client_tools.source	announced together when the engine serves client tools
hello feature	agents.client_tools.remote	sets reach a conversation another codeaf host holds
hello feature	agents.scope
method	agents.tools_set {agent, set, instructions?, deadline_ms?, tools[]}	replaces one named set whole; answers {agent, set, tools}
method	agents.tool_result {call, result | error}	exactly one of the two; answers {accepted}
method	agents.set_scope {id, scope}	project (default) or conversation; answers {id, scope}
event	agents.tool_call {agent, turn, call, turn_call, source_message_id?, set, name, args, deadline_ms}	sent only to the connection that set the tools

Limits: 4 sets and 64 tools per conversation, 32 tools per set, wait of 30 s by default and 1–120 s when given. A disconnect, the wait or the end of the turn answers the model with an error saying the outcome is unknown. Built-in tool names are refused and child tasks never receive client tools. The remote protocol version is unchanged; a holder from an older build still answers bad_scope.

docs/design/app-v3/PROTOCOL.md, docs/REMOTE.md and the chat manual (internal/manual/chat/client-tools.md, the scope section of tasks.md) are updated in the same change.

What was left out

• Everything workstream-specific. Client tools: a client attaches tools to a conversation; collection-held conversations are kept #2334 was written beside an engine workstream door (Config.Workstream, workstreamWithoutPage, appWorkstreamAgents, v3WorkstreamKeeps); none of it is here. git grep -i workstream finds nothing in the files this PR adds.
• The "collections keep blank conversations" half of Client tools: a client attaches tools to a conversation; collection-held conversations are kept #2334. dev already has it from A blank conversation a collection holds is kept, never resumed, and shown as live #2475, so dev's sweep and launch cleanup are untouched.
• collections.factory_job (App wire: announce collections.factory_job when collections hold Factory jobs #2468) and the Factory additions from Generic collections (factory_job refs) and client tools (integration branch; draft, do not merge) #2306. They are separate work.

How it was carried

Four commits, one per source change (#2346 and #2360 together), cherry-picked in order. Conflicts were in cmd/codeaf/app.go, cmd/codeaf/engine.go, internal/session/{inherit,questionconversation,session,sweep}.go, cmd/codeaf/chatv3_layout.go and internal/remote/{client,server}.go; each was resolved by keeping dev's side and adding only the client-tools lines. The 17 files this feature owns are byte-identical to their final state on workstreams/main (631c78a), and the per-file count of client-tool and scope identifiers matches that branch in all 49 files that mention them.

Checks

CI on 9c839e8: the required check, light gate, touched codeaf, touched rest, touched session and windows native tests all pass.

Built engine, no provider key (bin/codeaf app --home <scratch>): the hello lists agents.client_tools, agents.client_tools.source, agents.client_tools.remote and agents.scope. agents.tools_set and agents.set_scope for an unknown conversation answer not_found, a bad scope answers bad_params, and agents.tool_result for an unknown call answers {"accepted": false}; none answers unknown_method.

Local, macOS arm64:

Command	Result
make test-quick	pass
go test -count=1 ./internal/appwire ./internal/remote	pass
the 29 tests in internal/session/{client_tools,scope}_test.go	pass
the 31 tests in cmd/codeaf/{appclienttools,appclienttools_remote,appscope}_test.go	pass
make pr-ready	did not pass on this Mac, see below
make test-remote	not run: no Docker daemon on this machine

make pr-ready passed its light gate and the internal/appwire and internal/remote legs. The cmd/codeaf leg (8 shards) reported 15 failing tests, none in a file this PR touches. Run alone afterwards:

• 9 fail the same way on unmodified dev (ffeeb78) on this Mac: TestAppFactoryPlanFilesAnswer, TestFactoryCommandStepRetryAfterOutOfAttempts, TestFactoryMeasuredOnlyPublication, TestFactoryRetryActionsDoNotReportStopped, TestFactoryStepRetryWaitsForPreviousLeaseCleanup, TestFactoryWriteUsesJobBaseAcrossAttempts, TestMemoryPauseResumeAfterTrailingProgress, TestMemoryPauseRetainsPendingForResume, TestMemoryPausedJobLifecycle.
• 5 pass on this branch when run alone: TestC7R2ReopeningChatStopsPreviousDrive, TestDoctorFindsAndRepairsSyncAndEngineStoreSafely (3 of 3 after one failure), TestFactoryVerificationThroughTheRealStageConversation, TestHostedTakeBackReachesAcquireWithoutSharedUploadsOrReleaseDelay, TestProcessCloseJoinsTheUsageWriter.
• TestFactoryPersonStopInFlightWakeAndPersonChat/queued_person is intermittent on both trees here: 6 of 9 runs failed on this branch and 4 of 8 on dev, with the machine's load average between 30 and 40 from other suites.

The internal/session leg, run separately once the machine's suite lock was free (make test PKGS=./internal/session SHARDS=8 TEST_FLAGS='-count=1 -p 2'), reported 5 failing tests: TestACommandLookFailsOnAFailingPipeStage, TestBashBeltTruncationCapFollowsTheWindow, TestBashBeltTruncationWritesHeadTailAndPath, TestTheFixedPrefixStaysUnderItsBudget, TestWatchTickFailsOnAFailingPipeStage. All five fail with the same messages on unmodified dev on this Mac (exit status 141 from macOS bash 3.2 pipes; the fixed prefix reads 52502 bytes against a 52497 budget on both trees, so this change adds nothing to it).

So every local red is either red on dev on this Mac or intermittent on both trees, and the same selector is green in CI. The local make pr-ready therefore did not pass as a whole on this Mac; the PR is marked ready on the strength of CI and the comparison with dev above.

Changes after review

Three commits on top of 9c839e8 address the review. Every new test below failed before its fix and passes after it.

1. A client tool call's id now covers the whole call (f190820)

• Found: the call id sent to the app was built only from the conversation and the provider's tool-call id, so a provider that reused an id for another tool or other arguments (Kimi's name:index ids, rewind or compaction, a faulty server) got the earlier call's saved answer or joined its wait without the app ever seeing the new call, and a call with no provider id got ct_fresh_N from a counter that restarted at every launch, so the desk's 30-day answer table could replay an old answer after a restart; the remote holder path had the same defect.
• Changed: clientToolCallID in cmd/codeaf/appclienttools.go now hashes the agent, provider call id, set, tool name and exact argument bytes, each length-prefixed, and keeps the ct_ + 64-hex shape. A call with no provider id gets a random ct_ id from crypto/rand, and the counter is removed. A true redispatch of the same call still gets the same id and the saved answer. The call paragraph in PROTOCOL.md and the change entry are updated.
• Proof: TestClientToolsReusedProviderIDWithAnotherCallReachesTheApp (settled and pending subtests), TestClientToolsCallWithoutProviderIDNeverRepeatsAcrossLaunches (two separate engine launches), TestClientToolsRemoteReusedProviderIDWithOtherArgumentsIsANewCall, and an extended TestClientToolsSettledMemoryBoundAndExpiry. The existing replay and pending-join tests still pass unchanged.

2. Under conversation scope, the prompt and the tasks tool no longer promise other windows' work (5e5efce)

• Found: under conversation scope the engine already hid other windows' work from the <elsewhere> note and from task search, but the system prompt still said "OTHER codeaf WINDOWS ON THIS PROJECT ARE VISIBLE TO YOU" and the tasks tool description still said search includes other windows' live work, so the model was promised information it would never get.
• Changed: the page and the tasks description now follow the stored scope. Under conversation scope they say other windows' landed files and running work are hidden, so the model must not conclude that nothing else is running. A scope change applies from the next turn start in either direction, including to a tasks tool loaded later from the lean shelf. It costs one cold prompt prefix, like a placement change. The project-scope page and tools are byte-identical to before; the fixed prefix still measures 52502 bytes. internal/session/prompts/system.md keeps its project-scope line, and the conversation variant is swapped in at render time from internal/session/scope.go. PROTOCOL.md, internal/manual/chat/tasks.md and the change entry are updated.
• Proof: TestConversationScopeShapesWhatThePageAndTasksToolPromise checks the request the model actually receives through project, then conversation, then project again, then a reopened conversation-scope chat. TestConversationScopeReachesAShelvedTasksTool covers the lean profile.

3. Evaluated and fixed: a remote session swap drops the old conversation's tool sets (3ded075)

• Found: on a remote holder, one ClientToolHub serves the session across Session.New and Session.Open swaps and the swap never cleared it, so the replacement conversation inherited the joined app's tool sets, its calls went to the app under the old conversation id, and the app's answer was refused, leaving the model with client_timeout even though the app may already have acted.
• Changed: Session.swap (internal/remote/server.go) now calls a new ClientToolHub.forget before the new agent can be reached. forget drops every set and ends each pending call with a "turn ended" answer and a clientToolEnded frame, so the app stops waiting. It also makes the hub refuse later snapshots, with ErrJoinedGone, from a joined connection still on the old conversation. A following window can still attach to the new conversation. PROTOCOL.md, docs/REMOTE.md, internal/manual/chat/client-tools.md and the change entry are updated.
• Proof: TestClientToolsRemoteSessionSwapDropsTheOldConversationsSets (new and open subtests) checks that the hub is empty after the swap. It also checks that a call from the replacement answers client_unavailable without reaching the app, that the pending call ends and cancels the app handler, and that the old joined connection's snapshot is refused. The other TestClientToolsRemote* tests and the existing swap and join tests pass under -race.

All three review items were fixed. None was left unchanged.

🤖 Generated with Claude Code