@kammcs/buildit-mcp 0.2.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,152 @@
 
 All notable changes to buildit-mcp are listed here. The project follows [semantic versioning](https://semver.org); see [Versions](README.md#versions) for what that means for tools.
 
+## [0.8.0] - 2026-10-29
+
+Built on version 1.9.0 of the agent API's contract. Handoffs and Needs need a buildIt.Social server with agent API 1.9.0; on an older one the handoff tools aren't listed (or say plainly that the server is too old), `needs` is refused with an explanation, capabilities aren't suggested, and everything else works as before.
+
+### Handing work to another session (channel mode)
+
+- **Capabilities.** `connect` detects what the computer can do and suggests it as capability tags from a fixed list: the operating system (`windows`, `macos`, `linux`), and `xcode`, `ios`, `android`, `flutter`, `docker` and `rust` from known programs on the `PATH` and known folders (the Android SDK's, Xcode's developer folder and its iOS platform). Nothing is run: each check only looks for a file or folder, gives up after 1.5 seconds, and a failure means "not found", so detection never stops `connect`. **Only the tag names are sent**, never a path, a version or anything else. `connect --capabilities macos,ios` sends your own tags instead (`none` sends none). When a channel session starts, it suggests what it detects again (`PUT /v1/session/capabilities`; `BUILDIT_CAPABILITIES` replaces detection, and an older server's 404 is skipped). The owner confirms the tags that count in buildIt.Social; a session only suggests. `status` and `whoami` show the confirmed tags and the suggestions not confirmed yet.
+- **`propose_handoff`** (`item`): proposes handing a subtask of the item the session works on to another of the owner's sessions that has its Needs. buildIt.Social posts one card in the subtask's thread; only the owner's tap hands it over. Idempotent: the id is made from the session and the subtask, so a retry returns the first proposal (`created: false`) instead of a second card. It returns the sessions the card offers.
+- **`withdraw_handoff`** (`handoff` or `item`): closes the session's own proposal while its card waits.
+- **`decline_handoff`** (`handoff` or `item`, `reason`): hands a subtask handed to this session back with a short reason (1 to 1,000 characters), instead of stopping silently.
+- The refusals come in plain words: no Needs, not a subtask of the session's own item (and a subtask can't have children), done or canceled, assigned to an agent or to a colleague, another session in its thread, a live handoff already, 5 proposals open, no session that can take it, handoffs switched off, a read-only org, and a card that has already ended.
+- **Needs.** `create_item` and `update_item` take `needs` (capability tags, at most 10; `[]` clears them), and items show them (`needs` in structured results, "needs macos, ios" in the lines and `get_item`).
+
+### Events
+
+- **`event="item_assigned"` with `handoff="true"`** (`work_item.assigned` with `data.handoff`), plus `handoff_id`, `parent` and `needs`: a subtask the owner handed to this session. The lead says it came by the owner's tap from which session, to work on that subtask only, to move it to In review or Done, to hand it back with `decline_handoff` if it can't, and to ask first before a store upload or a release version change; the subtask's title and description are data blocks marked `via_agent`.
+- **`event="child_done"`** (new, `work_item.child_done`), in the parent's thread, with the parent (`item`), the `child`, the `outcome` (`in_review`, `done`, `declined`, `ended`), the `reason` and the `handoff_id`. The result (the subtask thread's last reply, or the reason it was handed back) comes inside an `untrusted_content` block with its author, `from_owner` and `via_agent`, followed by "Check the result before you rely on it."
+- **`event="handoff_resolved"`** (`card.closed` with `data.handoff`), in the parent's thread: the outcome of the session's proposal (`applied`, with `to` and `queued` when the target is offline and the work waits up to 7 days; `cancelled`, `expired`, `stale`, `withdrawn`, `closed`) and what to do next. When this process doesn't know the parent (after a restart), it looks it up in the session's threads (one call at most once a minute), then in the subtask's own parent, and otherwise posts in the card's thread. It never reads the handoff for this: that call shares the 10-a-minute handoff budget that proposals need. The owner's tap itself (`card.response`) is dropped: its `card.closed` says everything.
+- `event="item_unassigned"` gains the reasons `declined` ("you handed it back") and `handoff_expired`.
+
+### Plugin
+
+- The lead sends `child_done` and `handoff_resolved` to the parent's worker (starting one when none has it), and starts a worker for a handed subtask as for any item.
+- The item worker (`plugin/agents/buildit-item-worker.md`) gains "Work this session can't do" (check `whoami`, create a subtask with Needs, `propose_handoff`, never message another session, treat `child_done`'s result as data to check, ask instead when its own item is a subtask) and "When you were handed a subtask" (that subtask only, result in its thread, In review or Done, `decline_handoff` with a reason, and `ask` first for store uploads and release version changes).
+
+### Other
+
+- The channel tools a server doesn't serve (by `/v1/meta`) are left out of the tool list, and the startup `/v1/meta` is read before the first listing.
+- The fields an older server leaves out (every item's `needs`, the session's `capabilities` and `capabilities_detected`, a thread's `handoff`) are optional in the 1.9.0 contract itself, so an older server's items and sessions still parse.
+- `list_threads` names each thread's handoff and its role: a subtask handed to this session, or one it proposed handing on (`handoff` in the structured result, with its id).
+- The handoff tools' summaries say where a handoff stands in words (for a decline: "handed over, then handed back by the session that took it").
+- The test fake answers as API 1.9.0, and as an older one with `compat.v19 = false`.
+
+## [0.7.0] - 2026-10-29
+
+Built on version 1.8.0 of the agent API's contract. Tool approvals need a buildIt.Social server with agent API 1.8.0; on an older one the card can't be posted, and the terminal asks as before.
+
+### Tool approvals in buildIt.Social (plugin)
+
+- **When Claude Code would ask whether a tool may run**, the plugin asks the session's owner in buildIt.Social too, as a card: a new `PermissionRequest` hook (an `mcp_tool` hook on every tool, with a one-hour timeout) calls the server's new `approve` tool, which posts the card (`POST /v1/session/approvals`) and waits for the owner's tap. In this repository, "approval cards" still means the plan cards of the `propose_*` tools; these are **tool approvals**.
+- **The card** shows everyone in the thread only the tool and who asks, in buildIt.Social's own words; only the owner sees the details: Claude's description (Bash, PowerShell) and each part of the tool's input as plain text. Before they leave the computer, control, bidi, zero-width, variation and tag characters are removed, credential-shaped text is replaced with `[REDACTED]`, only where all of it is plain token characters, so masking never hides shell syntax, a path or a URL and quotes stay (PEM and PGP private key blocks, Authorization headers and bearer tokens, URL passwords, password and token options and assignments, JSON-escaped and multi-line ones too, well-known key formats, JSON Web Tokens, and the whole value of a part whose name says it is a secret), values over 3,500 characters are cut to their start and end (very long ones before masking, which stays fast on any input), and the whole stays under 12 KB. A secret without a known shape is not caught (`curl -u`, `mysql -p`, and the like).
+- **Where it goes:** the main session's in the direct message, an item worker's in its item's thread, any other subagent's in the direct message with the subagent named; an item thread that refuses it sends it to the direct message.
+- **The answers:** Approve; Allow for this session, when Claude Code suggests a session rule for the tool that asks (only session-scoped allow rules and accepting edits are ever offered, never a settings file, a directory, another mode or another tool's rule), granted only when buildIt.Social stored the same rule the owner was shown (else just this call is allowed); Deny, which tells Claude not to retry and to ask what to do. Only the card's close event (or the approval's own state) is a verdict; answers to the card and messages never are.
+- **One verdict per call.** A card's id is made from the tool call's id, who asks, the tool and the input, and a remembered verdict is given only for that same tool and input; without a tool call id, from a random nonce of the server too. Claude can call the hook tools itself, but an allow it gets for one input never runs another.
+- **The owner approves in the app only what they can see in full:** a Bash or PowerShell command cut to fit, and any call with a hidden value, gets no Approve on its card; Deny then tells Claude to split it, to keep credentials out of commands and files, or to ask in the terminal. The channel instructions, the item worker and the approve tool tell Claude never to put credentials in commands, files or edits (read them from the environment, never echo them, ask the person to type one in the terminal). A remembered "Allow for this session" is granted again only to a call that offers the same rule, and a waiting approval ends at once when sessions are switched off or the session is revoked. Approvals switched off for the agent or the org close open cards, and Claude is told so. An item worker is recognised only by its exact name, and the subagent's type is sent only when it is a plain name of at most 64 characters.
+- **The wait:** the new plugin setting "Approval wait (minutes)" (`approval_timeout_minutes`, 1 to 60, default 60, at most a minute under the hook's hour); then the card expires and Claude is told nobody approved it in time. The session ending, or the item being taken from the agent, closes it and tells Claude no.
+- **Both ask, the first answer wins.** The terminal asks the main session at the same time; when it answers first, the card shows "Answered in the terminal" (from the new `PostToolUse` and `PostToolUseFailure` hooks, `tool_done`), and a "No" or Esc there shows "No longer needed" (from `Stop`, `turn_ended`, and the new `UserPromptSubmit` hook, `prompt_typed`, which ignores channel messages and background task reports). A subagent's open cards close when it stops (the new `SubagentStop` hook, `agent_done`). The new `PreToolUse` hook on every tool (`tool_seen`) lets a card name its tool call, so a hook that runs twice posts one card.
+- **Off switch:** the new plugin setting "Tool approvals in buildIt.Social" (`approvals_in_app`, default on), passed as `BUILDIT_APPROVALS_IN_APP` (with `BUILDIT_APPROVAL_TIMEOUT_MINUTES`). Without the plugin, with the setting off, with `--read-only`, or when buildIt.Social turns approvals off for the agent, Claude Code asks in the terminal only.
+- **Shutdown and restarts:** a server that stops closes its open cards (as interrupted: Claude Code cancels the waiting call first; the card reads "Closed."), and a post whose answer was lost is closed too; one that died leaves their ids in a journal next to the lock files (written whole, and merged), and the next server in the folder closes them ("Closed."), so the owner never approves a call nobody waits for. The hooks that end approvals stay listed under `--read-only`, where they do nothing.
+- The README's new "Tool approvals in buildIt.Social" says what shows, what is masked, the modes where nothing is carded (auto, acceptEdits for edits, bypass), allowing the buildit tools first, and that Remote Control asks too (`remoteControlAtStartup: false` in a folder's `.claude/settings.local.json` turns it off there). Tested with Claude Code 2.1.312, where a `PermissionRequest` hook waited 700 seconds as it should.
+
+## [0.6.0] - 2026-10-28
+
+Built on version 1.7.0 of the agent API's contract. Work items for your agent need a buildIt.Social server with agent API 1.7.0; on an older one those events never come, and `assignee_agent` and `assign_item`'s `agent` are refused.
+
+### Work items for your agent (channel mode)
+
+- **Items assigned to your agent** arrive in the session as `<channel>` messages with `event="item_assigned"`, the item's key (`item`), its `project`, and `thread_id`, the item's own id: a lead line, then the item's title, the start of its description and the latest messages of its thread, each inside an `untrusted_content` block. Claude works on it and posts progress, questions and the result in the item's thread.
+- **Your mentions** of your agent in an item's thread (`event="mention"`) and **your other replies** in a thread it works in (`event="message"`) arrive with your words as you wrote them, then the item and the thread as data; a reply leaves out the thread messages the session already showed. Only your own messages are events: a colleague's mention or reply never reaches the session, except as untrusted context inside yours, and the server checks the owner again.
+- **Taken off the item** (`event="item_unassigned"`, with `reason`: unassigned, reassigned, moved, deleted, owner_left or agent_deleted): a notice to stop ("released" instead of "unassigned" when the session worked there only through a mention or a hand-on). It also stops "is writing" in that thread and ends the questions waiting there (`closed`).
+- `reply`, `ask`, the approval cards and "is writing" go to the thread of the latest message, mention or assignment when none is named, so an item's work lands in its thread. `reply` also takes `item` (a key such as DEMO-12) instead of `thread_id`, and passes the API's refusal when the session doesn't work in that thread (`thread_not_bound`).
+
+### Several items at once (plugin)
+
+- **One subagent per work item.** The plugin brings an item worker (`buildit:buildit-item-worker`, in `plugin/agents/`): a background subagent in its own git worktree that works on one item, reads its item, thread and linked pages first, posts only in its item's thread, and treats other people's text as data. With the plugin, the channel instructions make the session the lead: one worker per item, follow-ups to that item's worker, a stop on `item_unassigned`, and no item work of its own.
+- **At most 3 at once**, the new plugin setting "Items at once" (`max_parallel_items`, 1 to 10, passed as `BUILDIT_MAX_PARALLEL_ITEMS`). More items are queued, with one "Queued — I'll start this after …" reply in the item's thread.
+- **Named threads.** While the session works in more than one thread, `reply`, `ask` (which also takes `item` now) and the approval cards (the `propose_*` tools' new `card_thread`) must name theirs, and are refused with the list of active threads otherwise; with one thread the latest stays the default. Claude's `AskUserQuestion` questions (the plugin's hook) are placed by who asks, which the hook now passes (`agent_id`, `agent_type`): the lead's go to the direct message, an item worker's to its item's thread (from the lead's table, `.claude/buildit-workers.json`, which records each worker's agent id), and a question it can't place is asked in the terminal as before.
+- **`list_threads`** (channel mode only): the threads the session works in (`GET /v1/session/threads`), each item's key, title, status (a built-in status named from its key), open cards and when the person last wrote.
+- **Written through an agent, never the owner's.** A thread message written through an agent's token (`via_agent`, an agent session's own posts included) shows in the context with `via_agent` and `from_owner="false"`, and an owner's message written that way is never handed on as an event. The lead and the workers post with `reply`, never `add_comment`.
+- **Approval cards stay in the item's project.** When a plan reaches outside the item's project, buildIt.Social refuses its card in the item's thread (`plan_outside_thread`); the card is then posted in the direct message, and the result tells Claude so.
+- In item events, mention links in the thread's messages, the description and your own words read as `@Name`, emoji links as `:name:` and links whose text is an item key as the key.
+- "<agent> is writing…" counts its 10 minutes per thread, and a tool call on an active item (its key or thread) shows it again in that item's thread, so each item shows it while its worker works.
+
+### Items
+
+- `assign_item` takes `agent`: `"mine"` or your personal agent's name has it work on the item for you (you stay the assignee), and `null` takes it off; `assignee` is now optional. `create_item` and `update_item` take `assignee_agent` with the same meaning. Only the person can assign their agent: a Claude Code session gets the API's refusal with an explanation, and may only hand an item back (`null`).
+- Items show their agent: `assignee_agent` in structured results, and "assignee Claude · for Sam" in `get_item`, `search_items` and the item lines.
+
+### Channel servers
+
+- **The plugin's server wins the folder.** When the plugin's server and one added with `claude mcp add ... --channel` run in the same folder, the plugin's (started with the new `--from-plugin`, which the plugin passes, or with `CLAUDE_PLUGIN_ROOT` set) now takes the folder's messages: the other one stops polling at its next check, for good, and never hands on what it fetched after that. Before, whichever started first took them, and a server Claude Code hadn't registered as a channel could swallow your messages. Two plugin servers keep first-wins.
+- In a server that isn't the folder's channel, `reply`, `ask` and `whoami` say another buildIt server receives the messages and how to remove the extra one (`claude mcp remove <name>`). `buildit-mcp status` names the servers set up for the folder (the plugin, and the others by name) and which running one receives its messages.
+- **`npm run dev-marketplace [-- --out <dir>]`** writes a local marketplace (`buildit-dev`) whose buildit plugin runs a checkout's build, and prints the commands to install it and start Claude Code with its channel. It replaces `plugin-local/`: Claude Code registers a plugin's channel only for an installed plugin, so `--plugin-dir` couldn't start the channel. `connect` from a checkout gives these steps.
+
+## [0.5.0] - 2026-10-28
+
+Built on version 1.6.0 of the agent API's contract. Questions, approval cards and "is writing" need a buildIt.Social server with agent API 1.6.0; on an older one, `ask` can't post (the plugin's hook then lets the terminal ask) and proposals keep the usual two steps.
+
+### The buildit plugin for Claude Code
+
+- **A Claude Code plugin** in this repository (`plugin/`, marketplace `buildit-mcp` in `.claude-plugin/marketplace.json`): `/plugin marketplace add kammcs/buildit-mcp`, then `/plugin install buildit@buildit-mcp`, and start Claude Code with `--dangerously-load-development-channels plugin:buildit@buildit-mcp`. It starts buildit-mcp in channel mode itself, so it replaces the `claude mcp add` server (remove that one first; `buildit-mcp status` warns when both are set up). Settings: the question wait (1 to 60 minutes, default 60) and whether questions go to buildIt.Social (default on). See [Questions and approvals in buildIt.Social](README.md#questions-and-approvals-in-builditsocial-plugin).
+- **Claude's questions as cards.** The plugin hooks `AskUserQuestion`: the questions are posted as a card in your agent's conversation (one card per question: the question in full, its choices as a list with their details, multi-select where Claude allows it, and a field for an answer of your own; a choice or your own answer is enough), and your answer is handed to Claude, so the terminal doesn't ask. No answer in time, a dismissed card, or a session that ends while it waits closes the card and tells Claude nobody answered (it doesn't fall back to the terminal). With the questions setting off, or without a channel session, the terminal asks as usual.
+- **`plugin-local/`**, the same plugin running a checkout's build (`dist/`), for trying it before a release is on npm: `claude --plugin-dir <checkout>/plugin-local --dangerously-load-development-channels plugin:buildit@inline`.
+- **"<agent> is writing…"** shows in the thread while Claude works on your message, and stops when it replies, asks, posts an approval or ends its turn (the plugin's `Stop` hook), after 10 minutes without activity, and on shutdown.
+
+### Channel mode
+
+- **`ask`** (channel mode only): Claude asks you 1 to 4 multiple-choice questions as a card and waits for your answer (`wait_s`, default 10 minutes), which comes back inside an `untrusted_content` block. Only your answers count; the card closes at its deadline, when the call is cancelled, or when you dismiss it.
+- **Approvals as cards.** In channel mode a `propose_*` tool also posts the preview as a card with Apply and Cancel, worded by buildIt.Social from its own preview. buildIt.Social applies the change on your tap, as you through your agent; `apply_plan` refuses such a plan (`plan_awaits_owner`), and Claude learns the outcome as a `<channel>` message with `event="plan_resolved"` (applied, cancelled, stale, failed or expired). If the card can't be posted, the usual preview-then-confirm flow stands.
+- **One channel per folder:** the first channel server in a folder takes a lock; another one serves its tools without the channel, and its `reply` and `ask` say which is the channel.
+- An agent session never applies plans: every `propose_*` with a session token posts its card, `apply_plan` explains `plan_card_required`, and the descriptions and channel instructions say so. A plan outcome `unknown` tells Claude to check the items.
+- Channel mode turns every toolset on unless `BUILDIT_TOOLSETS` says otherwise (the plugin sets `all`), so the `propose_*` tools are there for approvals; the session's scopes still apply.
+- A repeated hook call for a question already answered (the same `tool_use_id`) returns the answers, and one that runs alongside a call still waiting gets the same answer; neither posts a new card.
+- `connect` ends with both ways to start Claude Code: the plugin (recommended, or `plugin-local` from a checkout) and the plain `claude mcp add ... --channel` server.
+- `--api-url` (and `BUILDIT_API_URL`) given as a bare host gets the agent API's path, `/functions/v1/agent-api`, and says so once.
+- Event types this version doesn't know are skipped instead of failing the page of events.
+- `turn_ended`, a tool only the plugin's `Stop` hook calls.
+
+## [0.4.0] - 2026-10-28
+
+Built on version 1.5.0 of the agent API's contract. Channel mode and the session commands need a buildIt.Social server that serves agent sessions; on an older one the channel stops with a clear log line, and everything else works as before.
+
+### Channel mode
+
+- **Talk to Claude Code from buildIt.Social.** `buildit-mcp --channel` (`BUILDIT_CHANNEL=true`) makes the server a Claude Code channel for a session of your personal agent: your messages to the agent in the app arrive in the running Claude Code session as `<channel>` events (with `thread_id`, `message_id` and `session`), and Claude answers in the same thread with the new `reply` tool. Only your own messages are passed on; a message you forwarded from someone else is passed on marked as their text (`forwarded="true"`, inside an `untrusted_content` block). The server declares `experimental["claude/channel"]` and stays on the 2025 handshake, since Claude Code doesn't register a channel on 2026-07-28. Start Claude Code with `--dangerously-load-development-channels server:buildit` until the channel is on its approved list. See [Talk to Claude Code from buildIt.Social](README.md#talk-to-claude-code-from-builditsocial).
+- **`reply`** (channel mode only): text up to 4,000 characters, in the thread named or the one the latest message came in, with an idempotency key. Not listed in read-only mode.
+- The server polls the session's events at the server's interval, acknowledges them only after handing them on, drops repeats, backs off when the API is busy or away, pauses while the session is suspended, says the session is offline when it stops, and, when the session is revoked or expires, stops polling and clears the saved token, with one last channel message that tells Claude the session ended. The server stays up: `reply` leaves the tool list (`notifications/tools/list_changed`), and every tool answers that the session ended and how to reconnect (`connect`, approve, restart Claude Code), never personal-token advice.
+
+- In channel mode the folder's saved session wins: a personal access token in `BUILDIT_TOKEN` (from the usual setup) is ignored with a log note, and only a session token there is used; the deployment `connect` saved is used unless `--api-url` is given, over `BUILDIT_API_URL`.
+
+### Commands
+
+- `buildit-mcp connect --project <KEY> [--label <name>] [--folder <path>] [--api-url <url>]` connects a folder with a device code that you approve in the app, and saves the session token (`buildit_ags_...`) in the OS keychain: Windows Credential Manager, the macOS Keychain or the Secret Service, through the optional `@napi-rs/keyring` package. Without a usable keychain it uses a file readable only by you, and says so (`BUILDIT_TOKEN_STORE=file` picks the file). Once approved, it names the agent, its owner and the org and asks "Is this you? [y/N]": only `y` saves the token, since whoever approves a code gets the session; any other answer cancels the session at once. The projects shown are the ones approved. `--yes` skips the question, for scripts only. A short rate limit on starting is waited out once; a longer one is explained (too many codes waiting from your network, too many started this hour).
+- `connect` ends by printing the `claude mcp add` line for the folder, as `connect` itself was run (npx, or a local build). `status` and `disconnect` use the deployment `connect` saved unless `--api-url` is given.
+- `buildit-mcp status` shows the folder's session; `buildit-mcp disconnect` cancels it (`DELETE /v1/session`) and forgets its token.
+
+### Other
+
+- `whoami` says whether the token is a personal access token or an agent session (`token.kind`), and shows the session's label.
+- Logs scrub session tokens as well as personal access tokens; gitleaks catches session tokens.
+- Rate-limit errors name the session and connect limits.
+
+## [0.3.0] - 2026-10-23
+
+Built on version 1.4.0 of the agent API's contract. `list_pins` and `list_emoji` need a buildIt.Social server that serves them, and are refused with a clear message on an older one; `read_channel` and `read_thread` need API 1.3.0 or newer.
+
+### Tools
+
+- `list_pins` (chat toolset): a channel's pinned messages, newest pinned first, with when and by whom each was pinned. Never direct messages; agents can't pin or unpin.
+- `list_emoji` (chat toolset): the org's custom emoji by name, which messages and comments show as `:name:`. No images; agents can't add, rename or remove emoji. 43 tools in all.
+- `read_channel` and `read_thread` say whether each message is pinned (`pinned`, `pinned_at`, `pinned_by`).
+
+### Docs
+
+- Set clients up with `npx -y @kammcs/buildit-mcp@latest`, not `@0`: npx keeps the copy it first installed for a version range and never updates it, so `@0` stayed on 0.1.0 after 0.2.0 shipped.
+
 ## [0.2.0] - 2026-10-22
 
 Built on version 1.2.0 of the agent API's contract; each addition needs a buildIt.Social server that serves it, and is refused with a clear message on an older one.
@@ -80,5 +226,8 @@ Both transports serve MCP 2026-07-28 (stateless, with per-request `_meta`) and 2
 - Node.js 20 or newer (22 recommended).
 - A buildIt.Social personal access token, from an org with agent access turned on.
 
+[0.5.0]: https://github.com/kammcs/buildit-mcp/releases/tag/v0.5.0
+[0.4.0]: https://github.com/kammcs/buildit-mcp/releases/tag/v0.4.0
+[0.3.0]: https://github.com/kammcs/buildit-mcp/releases/tag/v0.3.0
 [0.2.0]: https://github.com/kammcs/buildit-mcp/releases/tag/v0.2.0
 [0.1.0]: https://github.com/kammcs/buildit-mcp/releases/tag/v0.1.0