feat: add task-scoped shared agent boards

[marius-kilocode]

What Problem This Solves

This is step 1 of #13673: give existing task agents a small shared communication channel. It is the foundation for Kilo Swarm, not the finished feature.

Background agents normally report their results when they finish. A useful discovery can arrive too late to help a parent or sibling that is still working. This PR adds an optional board where they can share that discovery during the task.

Each board belongs to one main session and its task descendants. It is not a global board for a repository, worktree, or unrelated sessions.

Why This Change Was Made

Start with the smallest useful communication primitive and observe how agents use it before adding a larger interface or coordination system.

The flow is:

1. An agent posts a note with board_post.
2. A running recipient can see a fixed activity notice on its next normal tool result.
3. The recipient calls board_read when the information is relevant. Only that explicit read returns the peer message bodies.
4. Agents continue their assigned work. Normal background-task completion still delivers final results to the parent.

Peer messages are not new user requests or approval. This revision removes the earlier automatic peer-content injection into user messages. Runtime notices contain fixed text, not peer-written instructions; actual notes remain tool-result data. HOLD and VETO are advisory, not locks or session controls.

The board stores ordered history, validates membership and recipients, deduplicates retried posts, and provides bounded reads with pagination. Background completion also preserves the current parent model and reasoning choice rather than restoring the child selection. The merge with current main retains its headless-drain behavior.

User Impact

• Off by default. Enable experimental.shared_agent_board in CLI configuration or Shared agent board in VS Code Experimental settings.
• Works through the shared CLI backend. Read-only agents can participate without gaining workspace-write permission; explicit board denials remain effective.
• Supports INFO, ASK, RESULT, HOLD, and VETO, directed to a participant or broadcast to the board.
• History survives follow-ups and restarts in the same session. A new root session gets a separate board.
• All participants can read board history. Recipient selection controls activity notices, not privacy.
• Posting does not wake, restart, cancel, or assign work to agents. A direct post to a task known to be inactive reports that it was stored only.

Message types and QoS

All five types use the same QoS: persistent board storage plus best-effort activity notices. None guarantees a read, reply, or action. Types describe meaning, not delivery priority or runtime control.

Type	Intended use	What it does not do
INFO	Share a relevant fact or discovery.	Does not dispatch new work automatically.
ASK	Request input from another participant.	Does not open a user question, block execution, or guarantee a reply.
RESULT	Share an intermediate finding or useful result.	Does not mark a task complete or replace its normal final result.
HOLD	Flag a dependency or temporary blocker. Follow with INFO when resolved.	Does not pause an agent, acquire a lock, or reserve resources.
VETO	Flag an objection or a reason not to proceed.	Does not cancel work, revoke permission, or override user instructions.

All peer content, including notes from main, remains untrusted coordination data. A type label never grants approval or expands the assigned scope.

Delivery guarantees and limits

Aspect	Current behavior
Post acknowledgement	A successful board_post confirms that the message is stored in the board database. It does not confirm recipient notification, reading, or execution.
Running recipient	With the feature enabled and board_read allowed, the runtime checks for addressed or broadcast activity when a normal tool returns. It can attach a fixed notice to that result. The model must still choose to call board_read. Posting does not interrupt an in-progress model response.
No further tool result	If the recipient finishes without another eligible tool result, it may never see a notice. There is no notification deadline or guaranteed eventual read. The stored note can still be read later while the board exists and access is allowed.
Idle or finished recipient	Posting never wakes or resumes the agent. A direct post warns when the target is a task known to be completed, failed, or cancelled and its session is idle. Absence of this warning is not proof of delivery or availability.
Broadcast	ALL makes activity eligible for notice to other participants. It does not check for an active audience; posting can succeed after every other agent has finished.
Notice delivery	Notices contain fixed runtime text, not peer message bodies. Multiple posts can be coalesced into one notice, and notices can repeat. This is not an exactly-once notification stream.
Reading and replies	Bodies are returned only by an explicit board_read. There are no per-recipient read receipts or acknowledgements, mandatory replies, automatic processing retries, or guaranteed handling. A reply_to link relates messages; it is not an acknowledgement protocol.
Ordering and retries	Messages are appended transactionally in per-board sequence order, and reads preserve that order. An identical retry with the same trusted sender/message/tool-call identity reuses the stored record; changed arguments under that identity are rejected. A new tool call can post the same text again. This is storage deduplication, not exactly-once processing.
Capacity and paging	The complete formatted message must fit within 4 KiB. A board accepts up to 1,000 messages and 2 MiB of message data; over-limit posts fail rather than silently evicting older notes. Reads default to 20 messages, allow up to 50, and have a 32 KiB response budget. Callers must follow the cursor when hasMore is true.
Lifetime and visibility	History survives continuation and backend restarts in the same database, subject to the board/root-session lifecycle. Any participant can read the shared history, including messages addressed to others. main and participant session IDs select the notice audience, not a private inbox.

Use the board for advisory coordination within authorized work. If an agent must start or resume, use the normal task/session controls rather than assuming that a board post will trigger it.

What this first step does not include

The following remain open in #13673:

• Readable cards instead of JSON-first tool output: Make Kilo Swarm messages readable in chat #13668.
• Visible incoming messages and a session-linked communication view: Follow Kilo Swarm message flow through existing sessions #13672.
• Useful member names and execution state, including broadcasts after all peers finish: Expose Kilo Swarm agent identity and execution state #13670.
• Removal of redundant activity notices after explicit reads: Keep Kilo Swarm activity notices consistent with reads #13671.
• The later Kilo Swarm rename: Introduce Kilo Swarm user-facing branding #13669.

There is no new scheduler, planner, automatic worker assignment, cross-session sharing, or board-management UI. In particular, V1 does not yet tell agents reliably which peers are still active.

Release dependency: mirror experimental.shared_agent_board in the Cloud configuration schema at apps/web/src/app/config.json/extras.ts before release. That companion change is outside this PR.

Evidence

Checks rerun after resolving the merge:

• 169 CLI tests passed, covering board storage, fixed notices, explicit reads, permissions, cancellation, parent model retention, native requests, and headless/nested-task draining.
• 5 core tests and 38 extension configuration tests passed.
• Full monorepo typecheck, root and extension lint, annotation checks, Effect facade guard, formatting, unused-export check, and extension marker check passed. Existing lint and compiler warnings remain.
• End-to-end drain tests used real CLI subprocesses with local HTTP/mock-provider servers. Board integration tests checked that notices stay in genuine tool results and peer bodies appear only after explicit reads.

Earlier live-agent checks confirmed useful peer exchange through explicit reads and stored-only posting to a completed task without restarting it. A false approval canary did not trigger edits in that check. These observations do not prove that every model will ignore all hostile peer text. No fresh authenticated-provider or visual UI run was performed for this merge.

Manual test

Enable the board and run two background task agents. Have one share a discovery while the other is working. Confirm that the recipient gets a fixed notice, reads the note through board_read, and that normal task completion preserves the parent model and reasoning choice. A direct note sent after a child finishes must not restart it.

Existing prototype tool cards, using synthetic data

These screenshots show the current generic cards, not the communication viewer or redesigned cards planned in the epic.

[kilo-code-bot]

Code Review Summary

Status: 1 Issue Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
packages/opencode/src/session/llm/native-request.ts	192	Native cache policy sniffs the last message for board XML and misses resume/last-step tails

Files Reviewed (55 files)

• packages/opencode/src/session/llm/native-request.ts - 1 issue
• packages/opencode/src/session/prompt.ts
• packages/opencode/src/kilocode/board/store.ts
• packages/opencode/src/kilocode/board/context.ts
• packages/opencode/src/kilocode/tool/board.ts
• packages/opencode/src/kilocode/tool/registry.ts
• packages/opencode/src/kilocode/tool/task.ts
• packages/opencode/src/kilocode/agent/index.ts
• packages/opencode/src/tool/task.ts
• packages/opencode/src/agent/agent.ts
• packages/core/src/kilocode/board/sql.ts
• packages/core/src/database/migration/20260828074139_kilocode_board.ts
• packages/core/src/v1/config/config.ts
• packages/kilo-vscode/webview-ui/src/components/settings/ExperimentalTab.tsx
• packages/opencode/test/kilocode/board/store.test.ts
• packages/opencode/test/kilocode/board-tools.test.ts
• packages/opencode/test/kilocode/board-context.test.ts
• packages/opencode/test/kilocode/board-live.test.ts
• packages/opencode/test/session/llm-native.test.ts
• .changeset/shared-agent-board.md
• plus config/SDK/migration-gen/i18n and remaining test files

Fix these issues in Kilo Cloud

---

_{Reviewed by grok-4.6 · Input: 253K · Output: 23K · Cached: 1.3M}

_{Review guidance: REVIEW.md from base branch main}

[WebReflection]

@marius-kilocode about this:

Native cache policy sniffs the last message for board XML and misses resume/last-step tails

it wasn't part of the PR so I have approved as the issue looks to be elsewhere - feel free to follow up or maybe fix that in here, thanks.

[marius-kilocode]

I think that is just outdated. All good.